feat: tasks.completed_at カラム新設(振り返り集計 + 本日完了件数の判定基盤)

[win2cot]

概要

PR #327(Issue #150)で確定した S-03 ダッシュボード「当日対応 + 振り返り」リスト (4) 今日やったこと セクション、および §3.3.3 数値カード「本日完了件数」の判定基盤として、tasks テーブルに completed_at TIMESTAMP NULL を新設する。

スコープ

DDL / マイグレーション

• tasks.completed_at TIMESTAMP NULL を追加(基本設計書 §4.2 タスクテーブル定義 / §4.4 CREATE TABLE 抜粋に反映)
• 複合インデックス (tenant_id, completed_at) を追加(振り返りクエリ + 数値カード集計の用途)
• Flyway マイグレーションスクリプト(V*_add_completed_at_to_tasks.sql)

Domain / Entity

• xyz.dgz48.tasks.webapi.task.domain.Task モデルに completed_at: OffsetDateTime? を追加(JST 全層統一方針に従う)
• JPA Entity(adapter.persistence)に対応カラムマッピング追加

UseCase / 業務ロジック

• ChangeTaskStatusUseCase(A-16):ステータス遷移時に completed_at を制御
  • 未完了 → 完了: completed_at = now() セット
  • 完了 → 未完了(再オープン): completed_at = NULL クリア
  • 完了 → 完了(同状態の再保存): 既存値維持(冪等性)
• UpdateTaskUseCase(A-14):completed_at は API リクエストから受け付けず、サーバ側で制御する(クライアントから書き換え不可)

DTO / API

• Task レスポンス DTO に completed_at を追加(OpenAPI スキーマ更新)
• リクエスト DTO には含めない(read-only)

集計 SQL

• リスト (4) 今日やったこと抽出条件: status = '完了' AND DATE(completed_at) = CURRENT_DATE AND (owner_id = :userId OR assignee_id = :userId)
• 数値カード「本日完了件数」: COUNT(*) WHERE status = '完了' AND DATE(completed_at) = CURRENT_DATE + 認可フィルタ通過

議論ポイント(本 Issue 本文で結論を出す。ADR は起票しない)

• completed_at 操作の SSOT 配置: 案 (A) @PrePersist / @PreUpdate でステータス変更を検知して隠蔽 vs 案 (B) UseCase で明示的にセットする
• 推奨は 案 (B) UseCase 明示セット:
  • ステートマシンの遷移ロジック(ChangeTaskStatusUseCase)に SSOT を集約する方が認可・監査ログとの整合が取りやすい
  • JPA ライフサイクルコールバックに業務ロジックを置くと、テストとデバッグが難しくなる
  • 既存設計規約と整合(Domain にロジック集約)
• 議論完了後、Issue 本文に結論を追記し、実装に進む

完了の定義(DoD)

• DDL + Flyway マイグレーションが merge 済み(Testcontainers MySQL 8.4 で確認)
• Domain / Entity / UseCase / DTO に completed_at が反映
• A-16 ステータス変更で completed_at が正しく制御される(完了遷移時セット、再オープン時クリア)
• OpenAPI Task スキーマに completed_at が追加(read-only として明示)
• 集計 SQL のテストケース(振り返りリスト + 数値カード本日完了件数)が green
• 議論ポイント(操作方式 (A) vs (B))の結論が本 Issue 本文に追記され、コード実装と整合

前提・依存

• blocks: 派生 D-A docs: 基本設計書 §3.3.1/§3.3.2/§3.3.3 を screen-flow.md v1.0 と同期 #328(基本設計書 §3.3 同期)。D-A の §3.3.3 改訂で「振り返りセクション」と数値カード「本日完了件数」を記述するには、本 Issue の completed_at DDL + Entity + UseCase が前提

関連

• 親 PR: feat(docs): 画面遷移図とサイトマップ初版を追加 (#150) #327(Issue 画面遷移図とサイトマップの初版作成 #150)/ screen-flow.md §6.1 派生 5
• ADR-0005(タスク認可 3 役割評価)
• 設計規約 §3 データベース / §8 命名規約
• JST 全層統一方針(memory project_jst_full_stack_unification、TIMESTAMP は Asia/Tokyo)

[win2cot]

実装完了 — PR #335

議論ポイント結論

案 (B) UseCase 明示セット を採用。ChangeTaskStatusUseCase に completed_at 制御ロジックを集約し、ステートマシン遷移の SSOT とした。

実装概要

層	変更内容
DDL	idx_tasks_tenant_completed (tenant_id, completed_at) を V1.0.0_01 に追加
Domain	Task.changeStatus() 追加(→DONE でセット / 再オープンでクリア / DONE→DONE 冪等)、TaskOwnershipException 新設
UseCase	ChangeTaskStatusUseCase 新設。参照権限(404) → 操作権限(403) → changeStatus() → save()
Persistence	TaskRepository.save() ポート追加、TaskJpaRepositoryAdapter 実装、TaskJpaEntity.updateStatus() 追加
API	PATCH /api/tasks/{id}/status を TaskController に追加、ChangeTaskStatusRequest DTO 新設
レスポンス	TaskResponse に completedAt(read-only、nullable)を追加
例外処理	TaskExceptionHandler に TaskOwnershipException → 403 ハンドラを追加
依存追加	spring-boot-starter-validation(@NotNull / @Valid 使用のため)

テスト

全レイヤのテストを追加し ./gradlew :webapi:check 全通過(Spotless / NullAway / JaCoCo 80% 達成)。

• TaskTest — changeStatus() 全ブランチ検証
• ChangeTaskStatusUseCaseTest — 404 / 403(view) / 403(ownership) / completedAt セット / クリア
• TaskControllerWebMvcTest — PATCH 200 / 404 / 403
• TaskJpaRepositoryAdapterTest — Testcontainers MySQL で save() の completedAt セット・クリアを確認

DoD チェック

• DDL + Flyway マイグレーション(Testcontainers MySQL 8.4 で確認)
• Domain / Entity / UseCase / DTO に completed_at が反映
• A-16 ステータス変更で completed_at が正しく制御される
• OpenAPI Task スキーマに completedAt が追加済み(read-only として定義済み)
• 議論ポイント(案 (B))の結論がコード実装と整合