ドキュメント定義マトリクス
| ドキュメント | 何を定義するか | 誰が使うか | 変更コスト | 最重要度 |
|---|---|---|---|---|
| 詳細API仕様書（OpenAPI 3.x） | エンドポイントURL・HTTPメソッド・リクエスト/レスポンスのスキーマ・エラーコード・認証要件 | FE（実装インプット）・BE（実装インプット）・QA（テスト設計） | 高 | ◎ 最重要 |
| 物理データモデル・DDL | テーブル定義・カラム・型・制約（NOT NULL/FK/UK）・デフォルト値 | BE（クエリ実装）・DBA（構築・チューニング） | 高 | ◎ 最重要 |
| インデックス設計書 | インデックス一覧・対象カラム・種別（単一/複合/部分）・設計根拠（対応クエリパターン） | DBA・BE | 高 | ◎ 最重要 |
| 共通コンポーネント仕様書 | 共通ライブラリのインターフェース・利用方法・制約・バージョン | FE・BE全員（依存する共通基盤） | 高 | ◎ 最重要 |
| 監視設計書（アラート定義） | 監視対象・アラート閾値・通知先・対応フロー | インフラ・運用チーム | 中 | ○ 重要 |
| 詳細画面設計書 | 画面レイアウト・状態遷移・入力バリデーション・エラー表示 | FE | 中 | ○ 重要 |
| コンポーネント仕様書（Storybook等） | UIコンポーネントの見た目・Props・状態パターン | FE | 中 | ○ 重要 |
| バックアップ・リストア方針 | バックアップ頻度・保持期間・リストア手順 | DBA・インフラ | 中 | ○ 重要 |
| コーディング規約・レビュー基準 | 命名規則・フォーマット・レビューの合否判断基準 | 全開発者 | 低 | ○ 重要 |
◎最重要ドキュメントの詳細
詳細API仕様書（OpenAPI 3.x）
何を定義するか：FEとBEの「契約書」として機能する。エンドポイントのURL・HTTPメソッド・リクエストボディ/クエリパラメータのスキーマ・レスポンスの構造・各フィールドの型と制約・認証方式（Bearer/Cookie等）・全エラーコードの定義。
⚠️ API仕様書の版がFEとBEで乖離すると開発が止まる
API仕様書は単一のソースオブトゥルースを維持しなければならない。FEとBEが別々にコピーを持つと版が乖離し、実装後に「レスポンスの構造が違う」が発生する。OpenAPIのYAML/JSONファイルをGit管理し、両者が同じファイルを参照する運用を徹底する。
物理データモデル・DDL
何を定義するか：論理ER図を物理レベルに落とし込む。テーブル名・カラム名・データ型・NOT NULL制約・外部キー制約・ユニーク制約・デフォルト値・コメント。DDLはそのままDBに流せる状態にする。
形骸化した場合の影響：BEがDDLを見ずにクエリを書き、実際のカラム名・型と乖離が生じる。テスト環境で動いていたコードが本番の本当のDDLで動かない。
インデックス設計書
何を定義するか：インデックスの一覧（テーブル名・カラム・種別）と、そのインデックスがどのクエリパターンのために設計されたかの根拠。根拠がないインデックス設計は後のチューニングで「このインデックスは本当に必要か」を判断できなくなる。
形骸化した場合の影響：BEがDDLを先に実装し、DBAが後からインデックスを追加しようとした際にアプリ側のクエリを全面修正する必要が生じる。インデックスはクエリパターンと同時に設計しなければならない。
OpenAPI仕様書に含めるべき項目
| 項目 | 必ず定義すること |
|---|---|
| エンドポイント | URL・HTTPメソッド・パスパラメータ・クエリパラメータ（型・必須/任意・説明） |
| リクエストボディ | スキーマ（全フィールドの型・必須/任意・バリデーション条件・例） |
| レスポンス | HTTPステータス別のレスポンススキーマ（200/400/401/403/404/500） |
| エラーコード | エラーコード一覧・意味・クライアント側での対処方針 |
| 認証 | 認証方式（Bearer/Cookie）・トークンの渡し方・認証失敗時の挙動 |
| 共通規約 | ページネーション方式・ソート・フィルタの共通パラメータ名 |
✅ 次のPARTへ