基本設計・ADR・API契約サンプル
文書ID: ARCH-001 / 版: 1.0 / 関連: REQ-014〜016 / 状態: 記入例・未承認
架空案件の設計文稿です。構成とAPIは設計例であり、稼働するシステムや検証済み契約の提供ではありません。
工程定義
- 目的: 要件に対応する構成、画面、外部契約、設計判断を定義する。
- 入力: 承認済み要件、既存システム、非機能目標。
- AIの作業: 構成候補と画面案を生成し、要件・制約との整合を検証。
- 成果物: 構成図、画面遷移、プロトタイプ仕様、ADR、API契約。
- 完了条件: 設計責任者が構成・契約・主要なトレードオフを承認。
1. 構成と境界
利用者ブラウザ → Web UI → 承認API → SQL DB（経費申請・承認監査記録）。承認APIは社内認証基盤の認証情報を検証する。業務権限はサーバー側で評価し、DB更新は承認APIに限定する。
外部境界: 認証基盤との接続。会計システムへの連携は対象外。ログにはパスワードやトークンを含めない。
2. 画面遷移・プロトタイプ仕様
| 画面ID | 表示内容 | 操作・遷移 | 確認観点 |
|---|---|---|---|
| UI-01 一覧 | 申請番号、申請者、金額、状態 | E100を選択しUI-02へ | 閲覧権限の範囲内だけ表示 |
| UI-02 詳細 | 明細、申請者、承認状況 | 承認を選び確認ダイアログ | 自己申請では承認不可の理由を表示 |
| UI-03 結果 | 承認結果と処理日時 | 一覧へ戻る | 失敗時は状態を成功表示にしない |
試作時の確認依頼文例: 「U001とU002の画面を切り替え、自己承認不可の理由と成功後の状態が理解できるか確認してください。」
試作URL・版: {{PROTOTYPE_REFERENCE}}（未作成）。動くプロトタイプはこの仕様から実装し、業務担当者と確認する。
3. ADR-001：承認と監査記録の一体保存
- 背景: 承認済みだが追跡記録がない状態を避けたい。
- 選択: 承認更新と監査記録INSERTを同一DBトランザクションで実行する。
- 代替: 非同期で監査記録を作る方式。後続障害時に一時的な記録欠落があり、今回の範囲では採用しない。
- 結果: 保存失敗時は全体をロールバック。DBへの依存とトランザクション時間を測定する。
- 関連要件: REQ-016。決定者・日付: 未承認。
4. API-014 契約
- メソッド・パス: POST /api/expenses/{expenseId}/approve
- 認証: 検証済みの利用者IDをサーバーで取得。リクエスト本文から承認者IDを採用しない。
- 入力: expenseIdは既存の申請ID。本文は不要。
- 成功: 200、JSON例 {"expenseId":"E100","status":"approved","approvedBy":"U002"}
| HTTP | code | 条件 | 更新 |
|---|---|---|---|
| 401 | UNAUTHENTICATED | 認証なし・無効 | なし |
| 403 | FORBIDDEN | 承認権限なし | なし |
| 403 | SELF_APPROVAL | 自己申請の承認 | なし |
| 404 | NOT_FOUND | 閲覧可能な対象なし | なし |
| 409 | ALREADY_PROCESSED | 状態が申請済みでない | なし |
| 503 | SAVE_FAILED | DB更新・監査保存失敗 | 全体をロールバック |
エラー本文の例: {"code":"SELF_APPROVAL","message":"自分の申請は承認できません"}
5. 自社への適用
{{TECH_STACK}}、認証方式、画面用語、承認範囲、接続先、エラー契約を差し替える。契約変更は詳細設計と結合テストへ通知し、ADRに理由を残す。
構成レビュー: {{TECH_OWNER}} / 未承認。要件・画面・APIの対応確認: {{REVIEW_NOTES}}