feat: 実績バー優先の実績連動設計（正規化/業務時間帯/シーケンス/稼働時間算出の明確化）

[Copilot]

---

name: DESIGN PR
about: 設計フェーズの設計差分を共有するためのテンプレートです（実装なし）。編集対象ファイルはIssue指示を参照。

概要（Summary）

このプルリクエストは 実績開始日/実績終了日/実績工数のバー優先連動仕様 の設計を行います。

項目	値
実装差分（ソースコード変更）	なし
編集対象ファイル	.github/copilot/plans/41-actuals-linkage-bar-priority-spec.md

---

背景・経緯（Context / Facts）

• トリガーとなった事象（Issue / PR / 指摘 / 要望 / 差分 等）：[DESIGN] タスクテーブル：実績開始日/実績終了日/実績工数の連動仕様（バー優先・矛盾ゼロ）
• 参照した情報・資料（URL/Doc/チケット/議事メモ等）：Issue 本文、.github/copilot/80-templates/implementation-plan.md
• 作業開始時点で確認できていた事実（観測/制約/前提）：バー優先、workHoursPerDay 未指定時は業務時間帯から算出（defaultBreakHours=1h）、業務時間帯 09:00〜18:00 既定（workdayStartTime/workdayEndTime で変更可能）、1人固定、稼働日カレンダー利用、datetime 内部表現

---

実行区分（AIが実行したこと／人間が追加で行うこと）

区分	タスク（何をする）	対象（どのサイト/システム）	実行場所（URL/画面/コマンド）	実行方法（どうやって）	入力（必要な情報）	出力（得られるもの/保存先）	証跡（ログ/URL/スクショ等）
AI	設計計画の作成	リポジトリ	.github/copilot/plans/41-actuals-linkage-bar-priority-spec.md	テンプレート準拠で記述	Issue 要件	設計計画ドキュメント	変更差分
AI	丸め境界の明文化	同上	同上	例示/境界ルールを追記	Issue 要件	0.25h 丸め仕様	変更差分
AI	正規化呼び出し/稼働時間パラメータの明確化	同上	同上	設計方針に追記	Issue 要件	呼び出しタイミング・workHoursPerDay 仕様	変更差分
AI	業務時間帯/繰り越し計算の明確化	同上	同上	設計方針に追記	Issue 要件	workdayStartTime/workdayEndTime と overflow 仕様	変更差分
AI	シーケンス図の追加	同上	同上	Mermaid を追記	Issue 要件	初期表示/編集/バー操作の流れ	変更差分
AI	実装予定ファイル一覧の整理	同上	同上	スコープ表に追記	Issue 要件	新規/修正対象一覧	変更差分
人間	設計レビュー	GitHub PR	PR 本文	レビュー	本 PR	レビューコメント	PR コメント

---

ADR（Architectural Decision Records）

ADR変更サマリ（インデックス）

ADR	状態（proposed/accepted/superseded）	何を決めたか（要約）	変更理由（事実/制約）	影響（設計としての結論）	根拠（Issue/議論/観測）
該当なし	n/a	ADR 追加なし	既存設計内で完結	影響なし	Issue 本文

---

設計の要点（Decision Summary）

• 結論1：SSOT は ActualStart/ActualEnd（バー優先）で統一する。
• 結論2：初期表示は 4 パターン補完で矛盾ゼロへ正規化する。
• 結論3：ActualEffortHours は Task.actualEffort（hours）を前提に round-half-up で正規化する。
• 結論4：正規化は tasks 受信時と編集確定時に呼び出す。
• 結論5：workHoursPerDay は指定可能、未指定時は workHoursPerDay = windowHours - defaultBreakHours で算出する。
• 結論6：workdayStartTime/workdayEndTime を導入し、overflow は分単位で繰り越す。
• 結論7：初期表示/編集確定/ガントバー操作のシーケンスを定義する。
• 結論8：windowHours が短い場合は休憩なしで windowHours を採用する。
• 結論9：ガントバー操作は User 起点でシーケンス図に明示する。

---

レビュー議題（Review Agenda）

議題（レビューしてほしい観点）	期待する結論（OK/要修正/要議論）	参照（章/ADR/見出し）	ステータス（未/OK/要対応）	根拠（Issue/ADR/観測）
SSOT と補完順序の妥当性	OK	設計方針 / 初期表示	未	Issue
0.25h 丸め境界の明確性	OK	設計方針 / テスト戦略	未	Issue
正規化呼び出しタイミングの妥当性	OK	設計方針	未	Issue
workHoursPerDay 既定値と算出方法	OK	設計方針	未	Issue
workdayStartTime/workdayEndTime と overflow の妥当性	OK	設計方針	未	Issue
シーケンス図の妥当性	OK	設計方針	未	Issue

---

仮定・不変条件（Assumptions / Invariants）

種別	前提/不変条件	変更可能性（固定/変動/未確定）	破ると何が壊れるか（影響）	根拠（Issue/ADR/観測）
assumption	workHoursPerDay 未指定時は windowHours と defaultBreakHours=1h から算出	固定	effort 換算が崩れる	Issue
assumption	業務時間帯は 09:00〜18:00 既定（ローカルタイム解釈）	固定	overflow 計算が崩れる	Issue
invariant	期間は [start, end)	固定	effort 再計算が不安定	Issue

---

合意境界（Decided vs Not Decided）

確定（Decided）

項目	決定内容（要約）	根拠（ADR#/該当見出し）
SSOT	ActualStart/ActualEnd 優先	設計方針
丸め	0.25h round-half-up	設計方針
業務時間帯	workdayStartTime/workdayEndTime を指定	設計方針
workHoursPerDay 算出	未指定時は windowHours から算出	設計方針

未確定（Not Decided）

項目	未確定の理由（事実/制約）	決め方（誰が/いつ/条件）	根拠
該当なし	決定済み	n/a	Issue

---

要件・成功条件（Requirements / Success Criteria）

種別	項目	成功条件（どうなればOKか）	根拠（Issue/ADR/議論/観測）
機能	初期表示の矛盾解消	4 パターン補完で整合	Issue
機能	編集時の自動更新	2 項目確定で残り更新	Issue
機能	稼働時間/日のパラメータ化	workHoursPerDay を指定でき、未指定時は業務時間帯から算出	Issue
機能	業務時間帯のパラメータ化	workdayStartTime/workdayEndTime を指定できる	Issue
機能	シーケンスの明文化	初期表示/編集/ガント操作の流れが明示される	Issue
非機能	丸めの一貫性	0.25h round-half-up で収束	Issue

---

製造スコープ（実装時に影響する機能・契約・運用）

影響するもの（In-Scope）

ユーザー影響/機能名	入口（画面/操作/API/Job）	変更タイプ（追加/変更/削除）	影響レベル（S/M/L）	互換性（破壊/非破壊/未確定）	具体的に変わること（1〜2行）	根拠（ADR#/該当見出し）
実績表示	Task Table 編集/表示	変更	M	非破壊	実績値がバー優先で正規化	設計方針
実績バー	Gantt 表示	変更	M	非破壊	effort 編集時に end が再算出	設計方針

影響しないもの（Out-of-Scope）

対象（機能/契約/運用）	影響しない理由（事実/制約）	根拠（ADR#/該当見出し）
予定値連動	本仕様の対象外	Issue

未確定（TBD）

論点（何が決まっていないか）	影響しそうな範囲	いつ/誰が決めるか（予定）	根拠
該当なし	n/a	n/a	Issue

---

互換性・移行（Compatibility / Migration）

対象（API/DB/設定/イベント/Job 等）	互換性（破壊/非破壊/未確定）	移行要否（Yes/No/TBD）	移行の要点（短く）	ロールバック方針（短く）	根拠（ADR#/該当見出し）
既存実績データ	非破壊	No	ロード時に effort を補正	正規化ロジックのリバート	設計方針

---

代替案とトレードオフ（Trade-offs）

判断テーマ	プランA	プランB	採用プラン	採用理由（事実/制約/評価軸）	不採用理由（トレードオフ）	根拠（Issue/ADR/測定/議論ログ）
SSOT	Start/End 優先	Effort 優先	A	バー一致を最優先	Effort 基準だとバー不整合	Issue

---

影響範囲（設計が示す影響と根拠）

影響対象	結論（影響あり/なし/未確定）	影響内容（何が変わる）	根拠（ADR/議論/観測）
アプリケーション挙動	影響あり	実績値の正規化	Issue
DB/データ互換性	影響なし	スキーマ変更なし	Issue
API/外部連携	影響なし	仕様内で完結	Issue
環境設定・デプロイ手順	影響なし	変更対象外	Issue
監視/アラート/運用	影響なし	新規運用なし	Issue
セキュリティ/権限/監査	影響なし	Secrets/PII 対象外	Issue
コスト（課金/性能/リソース）	影響なし	軽量計算	Issue

---

リスクと対策（Risk / Mitigation）

リスク	発生条件（いつ起きるか）	影響（S/M/L）	予防/緩和策（設計上の手当）	検知（ログ/監視/アラート）	残課題（Open Questionsへのリンク）	根拠
既存 effort の補正差分	ロード時	M	バー優先の明文化	設計レビュー	Open Questions なし	Issue

---

実装ガイド（実装担当へ渡す情報）

観点	記載内容（要点）	根拠（ADR/該当見出し等）
変更対象（モジュール/境界）	normalizeActuals / deriveEnd / deriveStart / recalcEffort	設計方針
I/F（入力/出力/契約）	editActualStart/end/effort + workHoursPerDay/workdayStartTime/workdayEndTime/calendarConfig → normalizeActuals	設計方針
データモデル/永続化	ActualStart/ActualEnd/ActualEffortHours	Issue
エラーハンドリング方針	無効値は欠落扱いで補完	設計方針
互換性/移行方針	既存データはロード時に補正	互換性・移行
テスト戦略（何をどう保証）	初期表示/編集/境界値/稼働日/業務時間帯/シーケンス	テスト戦略
ロールアウト/切替	正規化導入コミットのリバート	ロールアウト

---

サンプル実装（PR本文専用）

codingAgentが「手を動かしたい」欲をここに寄せます。サンプルコードはPR本文にのみ記載し、リポジトリにファイル追加しません。

サンプル実装の扱い（Sample Code Contract）

サンプル種別	目的（何のための例か）	実装PRへの取り込み方針（そのまま/要調整/参考のみ）	参照（ADR#/該当見出し）
型/DTO/Interface	未使用	参考のみ	設計方針
疑似コード	丸め規則の具体化	参考のみ	設計方針
SQL/DDL案	未使用	参考のみ	設計方針
設定例	未使用	参考のみ	設計方針

インターフェース / 型 / DTO（例）

疑似コード（例）

q = effort / 0.25
normalized = Math.floor(q + 0.5) * 0.25  // round-half-up

SQL / DDL（例）

設定例（例）

失敗パターン / 境界値（例）

分類	ケース	期待動作（設計上）	備考
boundary	effort=1.124	1.00 に丸め	round-half-up
boundary	effort=1.125	1.25 に丸め	round-half-up

---

“推論せず質問に落とす”ための質問票（ADR / Open Questions）

論点 / 質問	回答（事実のみ）	根拠（Issue/ADR/該当箇所）
このPRで「決定」扱いにしたいことは何か？（なければ空欄）	なし	Issue
未確定点（質問として列挙）	なし	Issue
追加で合意が必要な関係者/レビュー観点	なし	Issue
実装前に必要な調査/PoCはあるか？	なし	Issue
境界条件（曖昧さ）が残る箇所はどこか？	なし	Issue

---

実装TODO（次PRのタスク分割）

タスク（実装PRでやること）	オーナー（AI/人間/共同）	ブロッカー（未確定ならOpen Questionsへ）	受け入れ条件（Doneの定義）	参照（ADR/該当見出し）
正規化関数群の実装	AI	なし	仕様通りの計算が実装済	設計方針
UI 入力との接続	AI	なし	編集時の自動更新が動作	設計方針
回帰テスト追加	AI	なし	受け入れ条件のテストが通る	テスト戦略

---

レビューの観測ログ（何を見てレビューできるか）

対象	参照先（URL/パス/見出し）	目的（何を確認する）
設計計画	.github/copilot/plans/41-actuals-linkage-bar-priority-spec.md	仕様整合性

---

補足（Notes）

• なし

---

コードレビューフィードバック対応（Review Feedback Response）

このセクションは「追記」で管理します。

追記（今回分）

• フィードバック（要約）：workHoursPerDay 未指定時の算出ルールと actualEffort 命名整理　対応（何を変えた）：actualEffort=hours の明記、windowHours/defaultBreakHours による算出を追記　対象（見出し/ADR/Commit）：機能要件 / スコープ / fix: 実績工数の命名とテスト観点を整理　状態（対応済/保留/却下）：対応済
• フィードバック（要約）：クランプ/フォールバック/overflow/warnOnce のテスト観点追加　対応（何を変えた）：異常系テスト観点を追記　対象（見出し/ADR/Commit）：テスト戦略 / fix: 実績工数の命名とテスト観点を整理　状態（対応済/保留/却下）：対応済
• フィードバック（要約）：User 起点のガントバー操作シーケンス　対応（何を変えた）：User 参加者を追加しシーケンス図を修正　対象（見出し/ADR/Commit）：設計方針 / fix: シーケンス図の主体を修正　状態（対応済/保留/却下）：対応済

既存ログ（前回まで）

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[DESIGN] タスクテーブル：実績開始日/実績終了日/実績工数の連動仕様（バー優先・矛盾ゼロ）</issue_title>
<issue_description># [DESIGN] タスクテーブル：実績開始日/実績終了日/実績工数の連動仕様（バー優先・矛盾ゼロ）

依頼の要点（合意の前提）

タスクテーブルの以下3項目を「常に整合性が取れた状態」で連動させ、表示・編集のどのタイミングでも矛盾が残らない仕様に統一する。

• 実績開始日（ActualStart）
• 実績終了日（ActualEnd）
• 実績工数（ActualEffortHours：消化工数）

本仕様は バー優先とし、実績バー（期間）の見た目と一致することを最優先にする。すなわち、矛盾解決・初期表示・再計算のSSOT（一次情報）は (ActualStart, ActualEnd) とする。

---

成果物

• .github/copilot/80-templates/implementation-plan.md に準拠した plan ドキュメントを.github/copilot/plans/41-actuals-linkage-bar-priority-spec.mdを修正する。
• ファイル追加は、.github/copilot/plans/41-actuals-linkage-bar-priority-spec.mdのみとする。
• コード修正・他のファイルの追加・編集を禁止する！

---

背景 / 前提条件

利用者ロールと権限要件

• 利用者: ガントチャートを業務利用するエンドユーザー
• 権限: 特になし（UI入力・表示の整合性仕様）

実行環境

• React + TypeScript のガントチャートコンポーネントライブラリ
• Task Table（タスクテーブル）と Gantt 表示（バー/グリッド）の双方に実績が表示される前提

外部サービス / 依存

• 稼働日判定: カレンダー（祝日・非稼働日）により計算可能（既存機能）
• 割り当て人数: 1人固定
• 1日の稼働時間: 8時間固定
• 実績工数（消化工数）は「稼働時間の合計（hours）」として扱う

データ型の前提（確定）

• データ保存/内部計算は 「日付＋時間（datetime）」で取り扱えるものとする
• UI入力は基本「日付のみ」だが、API/パラメータとしては「日付＋時間（datetime）」指定も可能とする

ネットワーク要件

• なし

セキュリティ前提

• Secrets/PII を扱わない（値整合とUIのみ）

---

スコープ定義

In Scope

• 初期表示（ロード/再描画）時に、入力データの欠落値補完・矛盾解決（正規化）を行う
• 編集時（ユーザー操作）に、3項目のうち2項目が確定した時点で残り1項目を自動更新し、矛盾ゼロにする
• 矛盾解決ポリシーを「バー優先」で固定する（SSOTは ActualStart+ActualEnd）
• 実績工数（ActualEffortHours）入力後の「start固定・end自動算出」を仕様として固定する
• 計算単位/丸め/境界（含む・含まない）を仕様として明文化する（本Issueで確定）

Out of Scope

• 予定（Planned）値との自動連動（予定工数/予定終了日を実績入力で変更しない）
• 複数人割当、稼働時間の可変（8h固定以外）
• 実績の変更履歴UI・監査ログの整備（必要なら別Issue）
• 編集UX（インプレース編集/オーバーレイ等）の導入（本件は値整合仕様の固定）

---

用語定義

• 稼働時間: 祝日・非稼働日を除外した稼働日のみを対象に、1日=8時間として算出される時間
• 正規化（Normalize）: 3項目の矛盾を解消し、優先順位に基づいて値を補正する処理
• SSOT: 真実の一次情報として扱う値の組（本件では原則 ActualStart + ActualEnd）

---

仕様ブロック（最大ボリューム）

1. SSOT / 優先順位（バー優先）

• 原則: (ActualStart, ActualEnd) をSSOT とする（バー優先）
• ActualEffortHours は派生値であり、保存されていても SSOT と矛盾する場合は 再計算で補正する
• 例外（操作直後の扱い）:
  • ActualEffortHours を編集した直後は「ActualStart固定 + ActualEffortHoursから算出したActualEnd」を新しいSSOTとして採用する
    • 結果として SSOT（start/end）がバーと一致する＝バー優先が保たれる

---

2. 初期表示（ロード時）仕様

ロード/再描画の際は以下の優先順位で補完・矛盾解決を行い、表示上矛盾が残らない状態に正規化する。

(1) ActualStart と ActualEnd が両方存在する場合

• SSOTとして (ActualStart, ActualEnd) を採用
• ActualEffortHours は「ActualStart〜ActualEnd の稼働時間（8h/日換算）」で再計算し、表示値を補正
• 既に ActualEffortHours が保存されていても矛盾する場合は補正対象

(2) ActualStart と ActualEffortHours が存在し、ActualEnd が欠落/無効の場合

• ActualStart + ActualEffortHours を用いて ActualEnd を補完（start固定でend算出）
• 補完後は (ActualStart, ActualEnd) をSSOTとし、必要なら ActualEffortHours を再正規化（丸め等）

(3) ActualEnd と ActualEffortHours が存在し、ActualStart が欠落/無効の場合

• ActualEnd + ActualEffortHours を用いて ActualStart を補完（end固定でstart算出）
• 補完後は (ActualStart, ActualEnd) をSSOTとし、必要なら ActualEffortHours を再正規化

(4) 上記いずれにも該当しない場合

• 実績期間が確定できない状態として扱う
• 表示/入力（空欄/プレースホルダ/警告表示等）は既存UI方針に従う（本Issueでは挙動変更しない）

---

3. 編集時（ユーザー操作）仕様

共通ルール:

• 編集操作により3項目のうち 2項目が確定した時点で残り1項目を自動更新する
• 自動更新後は必ず「矛盾ゼロ（SSOTに整合）」状態にする

3.1 ActualStart（実績開始日）を編集した場合

• ActualStart を更新する
• ActualEnd が存在する場合:
  • ActualEndは動かさない（バー優先）
  • ActualEffortHours を ActualStart〜ActualEnd の稼働時間で再計算して更新
• ActualEnd が存在しない場合:
  • ActualStartのみでは期間が確定できないため、他項目の入力を待つ（自動補完はしない）

3.2 ActualEnd（実績終了日）を編集した場合

• ActualEnd を更新する（バー優先）
• ActualStart が存在する場合:
  • ActualEffortHours を ActualStart〜ActualEnd の稼働時間で再計算して更新
• ActualStart が存在しない場合:
  • 初期表示(3)と同等の補完規則（end + effort → start）に従って ActualStart を補完し、
  • 補完後、(ActualStart, ActualEnd) をSSOTとして ActualEffortHours を必要に応じて正規化

3.3 ActualEffortHours（実績工数/消化工数）を編集した場合（重要）

• ActualEffortHours を更新する（入力値として受け取る）
• ActualStart は固定し、ActualEnd を自動算出して動かす
  • ActualEnd = 「ActualStart から、稼働日計算に従って ActualEffortHours 分の稼働時間を加算した日時」
• 算出後の (ActualStart, ActualEnd) をSSOTとして採用し、必要に応じて ActualEffortHours を正規化
  • 目的: 丸め/境界の影響で表示値がブレないようにする

---

4. 矛盾解決（正規化）ポリシー

4.1 3項目すべてが存在し矛盾している場合

• 原則: (ActualStart, ActualEnd) を優先し、ActualEffortHours を補正（バー優先）
• ただし「ActualEffortHours 編集直後」は、その操作から算出されたActualEndを含む (ActualStart, ActualEnd) が最新SSOTである

4.2 無効値の扱い

• ActualStart/ActualEnd が欠落または無効（パース不能/範囲外等）の場合は「欠落」と同等扱いとし、
  • 初期表示の優先順位ルールに従って補完を試みる
  • 補完不能なら「実績未確定」として扱う（表示方針は既存に従う）

---

5. 計算単位・丸め・境界条件（本Issueで確定）

5.1 表現と粒度

• 内部データ型: datetime（日付＋時間）
• ActualEffortHours: hours（実数）として扱う
• 表示/保存時の正規化単位は 5.3 に従う

5.2 期間境界（含む/含まない）

• 期間は [ActualStart, ActualEnd) の半開区間（startは含む、endは含まない）とする
  • datetime での境界曖昧さを排除し、加算/差分計算を安定させる
• UI入力が「日付のみ」の場合の解釈:
  • ActualStart（日付）→ 当日 00:00 として扱う
  • ActualEnd（日付）→ 当日 00:00 として扱う（半開区間）
  • ※日付のみ入力で「日単位の期間」を表現したい場合の解釈（例: 最終日を含めたい場合に翌日00:00へ変換する等）は、既存UI仕様に従う（本Issueでは入力UXを変更しない）

5.3 丸め・正規化（確定）

• 正規化後の ActualEffortHours は、再計算結果に対して 15分単位（0.25h） で丸める
  • 丸め方式: 最も近い 0.25h に四捨五入（ties は上方向）
  • 例: 1.12h → 1.00h、1.13h → 1.25h、1.37h → 1.25h、1.38h → 1.50h
• 丸め後の ActualEffortHours と SSOT（ActualStart, ActualEnd）が乖離しないこと
  • 原則: SSOT（start...

• Fixes [DESIGN] タスクテーブル：実績開始日/実績終了日/実績工数の連動仕様（バー優先・矛盾ゼロ） #125

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[LevelCapTech]

@copilot 正規化ロジックがどのタイミングで・どのソースコードから、どのようにして呼ばれるのかが不透明です。このスレッドコメントを参照し、.github/copilot/plans/41-actuals-linkage-bar-priority-spec.mdファイルを修正してください。

PR本文は維持。既存本文の削除/置換は禁止。必要情報はPR本文末尾の ‘コードレビューフィードバック対応`の追記セクション’ に追記すること。

[Copilot]

@copilot 正規化ロジックがどのタイミングで・どのソースコードから、どのようにして呼ばれるのかが不透明です。このスレッドコメントを参照し、`....

正規化の呼び出しタイミングと workHoursPerDay の扱いを設計計画に追記しました。該当修正は 368d1d3 です。

[LevelCapTech]

@copilot apply changes based on the comments in this thread

.github/copilot/plans/41-actuals-linkage-bar-priority-spec.mdファイルを修正してください。
PR本文は維持。既存本文の削除/置換は禁止。必要情報はPR本文末尾の ‘コードレビューフィードバック対応`の追記セクション’ に追記すること。

[Copilot]

@copilot apply changes based on the comments in this thread

.github/copilot/plans/41-actuals-linkage...

レビューコメントの指摘に従い、シーケンス図の主体をUserに修正しました。対応コミットは a4e6fbe です。

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 6 comments.

[LevelCapTech]

@copilot apply changes based on the comments in this thread

.github/copilot/plans/41-actuals-linkage-bar-priority-spec.mdファイルを修正してください。
PR本文は維持。既存本文の削除/置換は禁止。必要情報はPR本文末尾の ‘コードレビューフィードバック対応`の追記セクション’ に追記すること。

[Copilot]

@copilot apply changes based on the comments in this thread

.github/copilot/plans/41-actuals-linkage...

レビューコメントの指摘に従い、actualEffortの命名整理と異常系テスト観点の追記を行いました。対応コミットは b87c2e7 です。

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.