メインコンテンツへスキップ

BookStackページ自動生成スクリプト 実装計画（WBS）

はじめに

本ページでは、添付された 要件定義書・YAML定義書・ソフトウェア仕様 を前提として、 BookStack の本・章・ページ骨格を自動生成する Python スクリプトを実装するための 作業分解構造（WBS） を示す。

ここでの WBS は、

  • 実装順がそのまま理解できること
  • 設計済み仕様（責務分割・fail-fast・安全側）と整合していること
  • BookStack 上の記事として「後から見返しても実装の全体像が即座に把握できる」こと

を目的としている。

全体フェーズ構成

  • フェーズ0：事前整理・方針固定
  • フェーズ1：基盤実装（CLI / ロギング / エラー枠組み）
  • フェーズ2：入力（YAML → ドメイン）
  • フェーズ3：ドメイン検証（バリデーション）
  • フェーズ4：BookStack API クライアント
  • フェーズ5：同一性判定ロジック
  • フェーズ6：ユースケース（処理フロー本体）
  • フェーズ7：標準出力レポート
  • フェーズ8：テスト実装
  • フェーズ9：結合確認・仕上げ

フェーズ0：事前整理・設計前提の固定

  • 仕様ドキュメントの読み合わせ

    • 要件定義書のスコープ・非スコープ確認
    • YAML定義書の処理順・同一性ルール確認
    • ソフトウェア仕様の責務分割・fail-fast 方針確認

  • 実装言語・環境の確定

    • Python 3.13 以上
    • 使用ライブラリ（requests / pytest のみ）

  • ディレクトリ構成の確定

    • bookstack_skeleton/ 配下の責務分割を最終決定

このフェーズで「仕様の解釈」を終わらせることで、以降の実装で仕様ブレを起こさない

フェーズ1：CLI・基盤処理の実装

1.1 CLI エントリポイント

  • create_skeleton.py 作成
  • -i / --input 引数の定義
  • 入力ファイル存在チェック
  • 終了コード規約の実装（0 / 1 / 2）

1.2 環境変数チェック

  • BOOKSTACK_BASE_URL
  • BOOKSTACK_TOKEN_ID
  • BOOKSTACK_TOKEN_SECRET
  • 未設定時は入力エラーとして即時終了

認証情報を標準出力・ログに一切出さないことをここで厳格に固定する

フェーズ2：YAML ローダ（入力 → ドメイン変換）

2.1 YAML 読み込み処理

  • YAML ファイルのロード
  • パース失敗時の入力エラー化

2.2 正規化処理

  • pages / chapters / chapters[].pages の欠損を空リストに正規化

  • 文字列項目の前後 trim

    • wip_markdown
    • ページ名
    • 章名

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

  • BookInput
  • ChapterInput
  • API 概念を含まない純粋データ構造

YAML 構造とドメイン構造の 1対1対応 を守ることで、後段ロジックが単純化される

フェーズ3：ドメインバリデーション

3.1 必須・型チェック

  • book_id の存在・型
  • wip_markdown の空文字禁止
  • list / string 型チェック

3.2 重複チェック

  • Book直下 pages 内の重複
  • chapters 内の章名重複
  • 同一章内 pages の重複

3.3 エラー集約

  • 複数エラーをまとめて返却
  • API を一切呼ばずに終了

API を叩く前にすべての入力不正を潰すことで、安全側・再実行可能性が担保される

フェーズ4：BookStack API クライアント

4.1 クライアント基盤

  • 認証ヘッダ付与
  • ベースURL正規化（末尾 / トリム）
  • HTTP 通信ラッパ

4.2 一覧取得 API

  • GET /api/books/{book_id}
  • Book直下ページ・章・章配下ページの最小情報取得

4.3 作成 API

  • 章作成（POST /api/chapters）
  • ページ作成（POST /api/pages）

4.4 リトライ制御

  • 対象：ネットワーク例外 / 429 / 5xx
  • 非対象：4xx（429除く）
  • リトライ上限固定

POST の多重実行リスクを意識し、冪等性はユースケース側の同一性判定で担保する

フェーズ5：同一性判定ロジック

5.1 判定対象の整理

  • Book直下ページ
  • Chapter
  • Chapter 配下ページ

5.2 判定関数実装

  • 完全一致（name）
  • 判定結果に SKIP reason を付与

5.3 API 非依存の純粋ロジック化

  • 必要情報は引数で受け取る
  • クライアント呼び出しは禁止

同一性判定を 独立モジュールに切り出すことで、仕様変更耐性が高くなる

フェーズ6：ユースケース（処理フロー本体）

6.1 事前取得

  • Book 全体構造の一括取得
  • 同一性判定用データ保持

6.2 Book直下ページ処理

  • YAML 記載順で処理
  • SKIP / CREATE の意思決定

6.3 Chapter 処理

  • 章の存在確認
  • 新規作成 or 既存利用

6.4 Chapter 配下ページ処理

  • 章ごとにページ処理
  • YAML 記載順厳守

YAML を読めば挙動が完全に予測できるという思想を、ここでコードとして固定する

フェーズ7：標準出力レポート

7.1 出力フォーマット固定

  • OK
  • SKIP
  • ERROR

7.2 スコープ表現

  • Book直下ページ
  • 章名 / ページ名

7.3 ログとの完全分離

  • stdout：結果のみ
  • stderr：詳細ログ

フェーズ8：テスト実装

8.1 ユニットテスト

  • loader
  • validator
  • identity
  • reporter

8.2 API クライアントテスト

  • 通信失敗時の挙動
  • リトライ回数確認

8.3 ユースケーステスト

  • SKIP / CREATE 分岐
  • 処理順の保証

フェーズ9：結合確認・仕上げ

  • テスト用 Book を用いた実行確認
  • 再実行時の自然復旧確認
  • README / BookStack 記事としての体裁最終調整

この WBS に沿って実装すれば、 安全・再実行可能・ブラックボックス化しない という設計思想を崩さずに完成できる

上に戻る