詳細設計・データ定義・タスクサンプル

文書ID: DESIGN-014 / 版: 1.0 / 関連: REQ-014〜016、API-014、ADR-001 / 状態: 記入例・未承認

架空案件の設計例。型とSQLは説明用であり、自社DB・認証・運用制約で検証する必要があります。

工程定義

• 目的: 実装単位ごとに処理、データ、例外、整合性を定義する。
• 入力: 基本設計、API契約、権限ルール。
• AIの作業: 型・スキーマ・擬似コード・テスト条件・実装タスクを作成。
• 成果物: データ定義、処理仕様、契約テスト仕様、移行方針、要件対応タスク。
• 完了条件: 技術リードが排他・異常系・移行・復旧の整合性を確認。

1. データモデル

関係: expenses 1件 → approval_audit 0〜1件。多段階承認を採用する企業では、承認段階IDを追加して一意制約と状態モデルを再設計する。

2. 型定義例

type ExpenseStatus = 'submitted' | 'approved';
type ApprovalResult = {
  expenseId: string;
  status: 'approved';
  approvedBy: string;
};

3. 処理仕様

1. 認証を検証。不成立なら401。承認権限なしなら403 FORBIDDEN。
2. トランザクション開始。閲覧範囲内の申請を行ロック付きで取得。存在しなければ404。
3. applicant_idと実行者IDが同じなら403 SELF_APPROVALで終了。
4. statusがsubmitted以外なら409 ALREADY_PROCESSEDで終了。
5. approvedへ更新し、同じトランザクションで監査記録を作成。
6. コミット後に200を返す。保存失敗はロールバックし503 SAVE_FAILED。

同時要求は行ロックと状態再確認で制御する。再送された承認要求は409とし、クライアントは最新状態を再取得する。この例では同じ要求へ200を再返却する方式は採用しない。

4. 契約テスト定義

CT-014-01: 成功レスポンスにexpenseId、status、approvedByが存在し、statusはapproved。

CT-014-02: 自己承認の403レスポンスにcode=SELF_APPROVALを含み、DBは不変。

CT-014-03: 本文に他人のactorIdを入れても本人性の根拠に使われない。

5. 実装タスク・要件追跡

6. 移行・復旧設計

本例ではapproved_by、approved_atとapproval_auditを追加。既存データへの影響を検証環境で調査し、過去の承認者が不明な行を推測で補完しない。アプリ切戻し後も新しい監査記録を保持し、破壊的な列削除は別変更とする。

自社用確認欄

DB・分離レベル: {{DATABASE_POLICY}} / 部門別権限: {{AUTHORIZATION_POLICY}} / 過去データ移行: {{MIGRATION_POLICY}}

レビュー: {{TECH_OWNER}} / 判定: 未承認 / 指摘と対応: {{REVIEW_NOTES}}