仕様設計手順

1. 入力仕様の確定（YAML → ドメイン）

• YAML スキーマの確定（キー、型、必須/任意）

• 処理順が意味を持つことの明文化

• 不正入力の扱い（エラーにする条件）の洗い出し

• ドメインデータクラス定義

  • Book 単位
  • Chapter 単位

• ドメインレベルでのバリデーション仕様決定

  • 必須チェック
  • 重複チェック
  • 型チェック

---

2. 同一性判定ルールの具体化

• Book 直下ページの同一性判定方法
• Chapter の同一性判定方法
• Chapter 配下ページの同一性判定方法
• SKIP 条件の明文化（いつ・何を・どう判断して SKIP するか）

---

3. 処理フロー設計（ユースケース）

• 全体の処理順を疑似コードで固定

  • YAML 読み込み
  • Book 直下ページ処理
  • Chapter 処理
  • Chapter 配下ページ処理

• エラー発生時の即時終了ルール

• API リトライ適用範囲の明確化

• 標準出力に出すイベント種別（OK / SKIP / ERROR）

---

4. API 境界設計（インフラ層）

• BookStack API の使用エンドポイント整理

• クライアントクラスの責務定義

  • 一覧取得系
  • 作成系

• API レスポンスの最小利用フィールド定義（id / name）

• リトライロジックの配置（クライアント側）

---

5. エラーモデル設計

• 入力エラー（YAML / バリデーション）
• API エラー（通信・HTTP）
• 想定外エラー
• どこで捕まえて、どこで終了するかの境界決定

---

6. CLI 設計

• 引数仕様（-i）
• 例外時の終了コード方針
• 標準出力フォーマット確定
• ログと標準出力の役割分離（必要最小限）

---

7. テスト設計

• ユニットテスト対象の切り出し

  • ドメインデータクラス
  • バリデーション

• ユースケースの振る舞いテスト（APIモック）

• 実 API 結合テストの範囲・前提整理

• テスト用 Book の運用ルール決定

---

8. 実装順序の確定（作業計画）

• dataclass → validate
• ユースケース骨格
• API クライアント
• CLI
• テスト

---

補足（今回の設計思想に合うポイント）

• 状態を持たない（YAML使い捨て）
• 破壊操作をしない
• 再実行で安全に復旧できる
• 順序がそのまま意味を持つ