docs(spec): Sprint 0 期の Flyway 運用ルール明文化(V1.0.0 直接追記 + schema/Entity 1 PR ルール)

[win2cot]

背景

2026-05-24 に Sprint 0 N1〜N8 Issue(#83〜#90)の見直しを行った結果、以下 2 つの運用ルールが暗黙知のまま運用されている / されようとしていることが判明した:

1. Sprint 0 期は本番データ無しのため、新規 migration ファイル(V1.0.1__...sql 等)を作らず初期版 V1.0.0_NN__*.sql に直接追記しているが、これは明文化されていない。実態として db(flyway): V1.0.1 — tasks拡張 (tenant_id/visibility/priority/due_date/status enum 等) (N1) #83 (N1) / db(flyway): V1.0.2 — マルチテナント+補助6テーブル追加 (N2) #84 (N2) は新規ファイル作成を計画して起票されたが、最終的に V1.0.0 統合の判断で実装され、Issue 本文と現実が乖離した。
2. Flyway migration と JPA Entity の同時性は spring.jpa.hibernate.ddl-auto: validate の前提として必須だが、起票方針として明文化されていない。実際 N1 (db(flyway): V1.0.1 — tasks拡張 (tenant_id/visibility/priority/due_date/status enum 等) (N1) #83) と N3 (backend: Task.java を設計 v1.3 に合わせて拡張 (N3) #85) は「ペア実装」と本文に書きながら別 Issue として起票されており、同時マージが構造的に保証できない状態だった(今回は両方実装済のため実害なし)。

ADR-0006 §3.4 リファレンスも、users.version / deleted_at 追加について「新規 migration ファイル V1.x.x_NN__alter_users_add_version_deleted_at.sql 等」と記述しており、上記 (1) のルールと矛盾している。

やること

案 A: 設計規約 §(Flyway セクション、新設)に追記

docs/specs/設計規約.md に新セクション「Flyway マイグレーション運用」を追加し、以下 2 ルールを明文化:

ルール 1: Sprint 0 期は初期版直接追記

• Sprint 0 完了(2026-06-27)までは、スキーマ変更は 初期版 V1.0.0_NN__*.sql への直接追記 を基本とする。
• 新規 migration ファイル(V1.0.1__...sql 以降)の作成は MVP リリース後(2026-10 月下旬以降の本番運用開始時)から。
• 例外: 検証用 / Testcontainers seed / 開発時のロールバックパスが本質的に必要なケースは個別判断、ただし Issue / PR で明示。

ルール 2: Flyway migration と JPA Entity の同時 PR ルール

• スキーマ変更を伴う実装は、Flyway migration の DDL と JPA Entity / Domain クラスの修正を 1 PR で同時 commit する。
• 分割すると ddl-auto: validate で起動・CI が壊れる(片方だけ merge された中間状態でアプリ起動不能)。
• Issue 起票時も 1 Issue にまとめる(Schema 用 Issue / Entity 用 Issue の分離は禁止)。

案 B: 新規 ADR-0010 として起票

複数規約への影響(Issue 起票方針、PR 戦略、ddl-auto 設定との依存)があるため ADR レベルで記録する案。ADR 番号は docs/adr/0010-flyway-migration-policy-sprint0.md 想定(0007〜0009 は Phase 1 Setup 2 で予約済の番号を確認のうえ採番)。

判断: 規約への直接追記(案 A)で十分か、ADR 必要(案 B)かは本 Issue 着手時に判断。設計規約レベルの「運用ルール」であり ADR の「decision」とは性質が違うため、案 A 寄りが妥当と推察。

やること(成果物)

• 案 A or B の判断
• 設計規約 / ADR への記述追加
• ADR-0006 §3.4 リファレンス末尾(docs/adr/0006-keycloak-user-storage-spi.md)の「新規 migration ファイル V1.x.x_NN__alter_users_add_version_deleted_at.sql 等」を本ルール準拠の記述に修正
• docs/reviews/2026-05-10-scaffold-vs-design-gap-analysis.md § G-2 / G-3 へのクロスリファレンス追加(本ルールを参照)
• docs(spec)+impl: 既存usersテーブル記述補正 + ADR-0006 派生スコープ(users 列追加 + JPA + 匿名化 service)(N8) #90 (N8) の「やること B」記述が本ルール準拠であることを確認
• CI green、./gradlew :webapi:check 不要(doc only)

受入条件

• 規約 / ADR を merge 後、次の Sprint 0 着手前 Issue(docs(spec)+impl: 既存usersテーブル記述補正 + ADR-0006 派生スコープ(users 列追加 + JPA + 匿名化 service)(N8) #90 等)で「V1.0.0 直接追記」「Schema/Entity 1 PR」を引用できる状態
• 次回 Sprint 0 起票時(Phase 1 Sprint 0 = 2026-06-14 開始)に本ルールが Issue テンプレに反映されている

参照

• 本 Issue の起票根拠: 2026-05-24 N1〜N8 Issue 見直しレビュー(sprint0-N1-N8-rewrite-draft.md § 横断追加タスク 案 1)
• 関連 Issue: db(flyway): V1.0.1 — tasks拡張 (tenant_id/visibility/priority/due_date/status enum 等) (N1) #83 (N1) / db(flyway): V1.0.2 — マルチテナント+補助6テーブル追加 (N2) #84 (N2) / backend: Task.java を設計 v1.3 に合わせて拡張 (N3) #85 (N3) / docs(spec)+impl: 既存usersテーブル記述補正 + ADR-0006 派生スコープ(users 列追加 + JPA + 匿名化 service)(N8) #90 (N8) / 監査列(created_at / updated_at / created_by / updated_by)の Auditing 機構整備 #144(監査列 Auditing 機構整備)
• 関連 ADR: ADR-0006(Keycloak User Storage SPI)§3.4 リファレンス末尾
• 関連 doc: docs/specs/設計規約.md(追記先候補)/ docs/reviews/2026-05-10-scaffold-vs-design-gap-analysis.md