terada_life
目次

詳細設計について

概要

詳細設計（内部設計）は、基本設計の成果物をもとに、実装可能なレベルまで設計を落とし込むフェーズ。開発者が「どうコードを書くか」を判断できる粒度で記述する。

内容

詳細設計の目的

  • 基本設計で定義した機能を、実装レベルの仕様に分解する
  • 開発者がドキュメントを見てコードを書ける状態にする
  • テスト設計の基盤を提供する（テストケースの元ネタになる）

詳細設計で作成する主な成果物

1. クラス設計書

モジュールやクラスの構造・責務・依存関係を定義する。

  • クラス図
    • クラス名、属性（フィールド）、操作（メソッド）
    • アクセス修飾子（public / private / protected）
    • クラス間の関連（継承、実装、集約、依存）
  • 責務の定義
    • 各クラスが担う役割を1〜2文で記述する（単一責任の原則）
    • 例: UserService — ユーザーのCRUD操作とビジネスルールの検証を担当
  • 依存関係
    • DI（依存性注入）で注入するインターフェースと実装クラスの対応表
    • レイヤー間の依存方向（Controller → Service → Repository）
  • ディレクトリ構成
    • モジュール分割後のファイル配置（パス）を記載する

2. シーケンス図

ユースケース単位の処理の流れをオブジェクト間のメッセージとして時系列で表現する。

  • 記載内容
    • アクター（ユーザー、外部システム）とオブジェクト（Controller、Service、Repository、外部API）
    • メッセージの方向と内容（メソッド呼び出し、HTTPリクエスト）
    • 戻り値・レスポンスの内容
    • 条件分岐（alt）、ループ（loop）、並行処理（par）
  • 作成対象
    • 主要なユースケースごとに作成する（全メソッドに対して作る必要はない）
    • 特に複数オブジェクトが連携する処理、外部API呼び出しを含む処理を優先する
  • 例: ユーザー登録のシーケンス
    • ユーザー → Controller: POST /api/users
    • Controller → Service: createUser(dto)
    • Service → Repository: findByEmail(email) → 重複チェック
    • Service → Repository: save(user)
    • Service → MailService: sendVerificationEmail(user)
    • Controller → ユーザー: 201 Created

3. データベース物理設計

論理設計をもとに、実際のDBMSに合わせた物理的なテーブル定義を行う。

  • テーブル定義書（テーブルごとに作成）

    • テーブル物理名・論理名

    • カラム一覧: 物理名、論理名、データ型（VARCHAR(255)等）、NOT NULL制約、デフォルト値、備考

    • 主キー、外部キー、ユニーク制約

    • 例:

      物理名論理名型NOT NULLデフォルト備考
      idIDUUIDYESgen_random_uuid()PK
      emailメールアドレスVARCHAR(255)YES-UNIQUE
      name氏名VARCHAR(100)YES--
      statusステータスSMALLINTYES00:仮登録 1:本登録
      created_at作成日時TIMESTAMPTZYESnow()-
      updated_at更新日時TIMESTAMPTZYESnow()-

  • インデックス定義

    • インデックス名、対象カラム、種別（B-Tree / GIN / GiSTなど）、目的
    • 検索パターン（WHERE句、JOIN条件）に基づいて設計する

  • マイグレーション方針

    • マイグレーションツール（Prisma Migrate、Flyway等）の指定
    • 既存データの移行方針、ダウンタイムの有無

4. API詳細設計

基本設計のエンドポイント一覧をもとに、各APIの詳細仕様を定義する。

  • エンドポイント詳細（APIごとに作成）

    • メソッド、パス、概要、認証方式

    • リクエストヘッダー（Authorization、Content-Type等）

    • パスパラメータ、クエリパラメータの型と制約

    • リクエストボディのフィールド定義:

      フィールド型必須バリデーション説明
      emailstringYESメール形式、255文字以内メールアドレス
      passwordstringYES8文字以上、英数記号混在パスワード

    • レスポンスボディ（正常系）: フィールド名、型、説明

    • エラーレスポンス一覧:

      HTTPステータスエラーコード条件メッセージ
      400VALIDATION_ERRORバリデーション失敗入力値が不正です
      409DUPLICATE_EMAILメールアドレス重複このメールアドレスは既に使用されています
      500INTERNAL_ERRORサーバー内部エラーシステムエラーが発生しました

  • 認証・認可の詳細

    • トークンの検証フロー（JWT検証、セッション確認など）
    • 権限チェックのロジック（ロールベース、リソースオーナーチェック）

5. 処理フロー図

各機能の処理ロジックをフローチャートやアクティビティ図で視覚的に表現する。

  • 記載内容
    • 処理の開始・終了
    • 条件分岐（if/else）とその判定条件
    • ループ処理とその終了条件
    • 外部API呼び出し、DB操作のタイミング
    • エラー発生ポイントと例外処理の流れ
    • トランザクション境界（どこからどこまでを1トランザクションとするか）
  • 作成対象
    • 複雑なビジネスロジック（条件分岐が3つ以上、ループを含む処理）
    • 複数テーブルを跨ぐトランザクション処理
    • 外部システム連携を含む処理

6. 状態遷移図

ステータスを持つエンティティについて、状態の変化とそのトリガーを定義する。

  • 記載内容
    • 状態の一覧（状態名、状態値、説明）
    • 遷移の一覧（遷移元 → 遷移先、トリガー、実行条件）
    • 不正な遷移（許可されない状態変化を明示）
  • 例: 注文ステータス
    • 作成済(0) → 支払い待ち(1): 注文確定ボタン押下
    • 支払い待ち(1) → 支払い済(2): 決済API成功コールバック
    • 支払い済(2) → 発送済(3): 管理者が発送処理実行
    • 発送済(3) → 完了(4): 配送完了通知受信
    • 支払い待ち(1) → キャンセル(9): 24時間未決済 or ユーザーキャンセル
  • ポイント
    • 「この状態からこの状態には遷移できない」という制約も明記する
    • 状態遷移時に実行する副作用（メール送信、ログ記録など）も記載する

7. バッチ詳細設計

バッチ処理ごとに、処理ステップ・エラーハンドリング・リカバリ方針を定義する。

  • 処理フロー
    • ステップごとの処理内容（データ取得 → 加工 → 書き込み → 通知）
    • 各ステップの入出力データ
    • チャンクサイズ（一度に処理する件数）
  • エラーハンドリング
    • リトライ方針（回数、間隔、バックオフ戦略）
    • スキップ方針（エラーレコードをスキップして継続するか、全体を中断するか）
    • エラー通知先（Slack、メール、監視ツール）
  • 排他制御・冪等性
    • 多重実行の防止方法（ロック、フラグ管理）
    • 途中失敗からの再実行時に二重処理が起きない設計（冪等性の担保方法）
  • ログ出力
    • 処理件数（成功/失敗/スキップ）のサマリー出力
    • エラー発生時の詳細ログ（対象レコード、エラー内容）

8. 単体テスト仕様書

詳細設計に基づいて、各モジュールのテスト観点とテストケースを定義する。

  • 記載内容

    • テストID、テスト対象（クラス名・メソッド名）、テスト観点
    • 事前条件（テストデータの状態）
    • 入力値
    • 期待される出力値・振る舞い
    • テスト区分（正常系 / 異常系 / 境界値）

  • 例:

    テストID対象観点入力期待結果区分
    UT-001UserService.createUser正常登録有効なemail, passwordUserオブジェクトが返る正常系
    UT-002UserService.createUserメール重複既存のemailDuplicateEmailError異常系
    UT-003UserService.createUserパスワード短すぎ7文字のpasswordValidationError境界値

  • カバレッジ方針

    • C0（命令網羅）/ C1（分岐網羅）/ C2（条件網羅）のどのレベルを目標とするか
    • テスト対象外とするもの（フレームワーク生成コード、外部ライブラリ等）

詳細設計で意識すべきポイント

  1. 実装者が迷わない粒度で書く — 曖昧な表現を排除し、具体的な型・値・条件を明記する
  2. 命名規則を統一する — 変数名、関数名、テーブル名の命名規約をドキュメントで定義する
  3. エラーハンドリングを明確にする — 正常系だけでなく、異常系・境界値の振る舞いを定義する
  4. 設計パターンを適用する — ストラテジー、ファクトリーなど適切なデザインパターンを活用する
  5. テスタビリティを考慮する — テストしやすい構造（依存性注入、インターフェース分離）を意識する

基本設計との違い

観点基本設計詳細設計
視点システム全体モジュール・関数単位
問いどう実現するか？（概要）どうコードに落とすか？（具体）
対象者ステークホルダー全般開発者・テスター
粒度機能単位クラス・メソッド単位
DB設計論理設計（ER図）物理設計（DDL、インデックス）

詳細設計の進め方（一般的なフロー）

  1. 基本設計書のレビュー・確認
  2. モジュール分割・クラス設計
  3. 処理ロジックの定義（フローチャート、シーケンス図）
  4. データベース物理設計（テーブル定義書作成）
  5. API詳細仕様の定義（型、バリデーション、エラーコード）
  6. 状態遷移の定義
  7. エラーハンドリング方針の策定
  8. 単体テスト仕様の作成
  9. レビュー・承認

詳細設計のアンチパターン

  • 設計書がコードの写経になる — ロジックを自然言語で冗長に書くのではなく、図や表で構造を示す
  • 過度に細かすぎる — 実装の自由度を奪うレベルまで書くとメンテコストが膨大になる
  • 基本設計との整合性が取れていない — 基本設計の変更が詳細設計に反映されていないと事故のもと
  • 非機能要件が抜けている — パフォーマンス要件やセキュリティ対策が詳細設計に落ちていない

参考資料

  • IPA「システム開発の基礎」
  • 「はじめての設計をやり抜くための本」（技術評論社）

メタデータ

  • ステータス: レビュー中
  • タグ: 設計, 詳細設計, 内部設計, システム開発
  • 作成日時: 2026/04/08
  • 更新日時: 2026/04/08