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

BookStack 骨格（章・WIPページ）自動生成ツール 要件定義書

1. 目的

BookStack において、本・章・ページの骨格（章および WIP ページ）を 手作業を排除して一括生成するための Python ツールを作成する。

本ツールは、一度きり使う YAML 定義を入力として、 既存構造を壊さず、安全側（新規作成のみ・既存はスキップ）で動作することを目的とする。

2. 対象スコープ

2.1 対象とする操作

  • ページの 新規作成
  • 章の 新規作成（存在しない場合のみ）

2.2 対象外とする操作

  • 既存ページ・章の更新
  • 既存ページ・章の削除
  • YAML と BookStack 状態の同期（YAML は使い捨て）

3. 前提条件・制約

  • BookStack の Book は 事前に作成済み

  • Book の特定は Book ID を直接指定

    • book_name は使用しない（重複回避のため）

  • Python 実行環境：

    • Python 3.13 以上

  • 使用可能ライブラリ：

    • requests
    • pytest

  • 実行環境：

    • Windows ローカル PC

4. 入力仕様（YAML）

4.1 基本方針

  • YAML は 1回限りの入力
  • 記載順が処理順となる
  • YAML 内でページの「章所属」または「本直下所属」を明示する

4.2 論理構造（概念）

  • Book（ID指定）

    • Chapters

      • Pages

    • Pages（Book 直下）

※ 実際の YAML 構造は別途定義するが、 「ページは章にも本にも直接紐づけられる」ことを前提とする。

5. 同一性判定ルール

5.1 Chapter の同一性

  • 対象 Book（ID 指定）内で
  • 章名完全一致
  • 一致する章が存在すればそれを使用
  • 存在しなければ新規作成

5.2 Page の同一性

5.2.1 章に紐づくページ

  • 対象 Chapter 内のページ一覧を取得
  • ページ名完全一致
  • 一致する場合は SKIP

5.2.2 本に直接紐づくページ

  • 対象 Book に紐づくページ一覧を取得
  • ページ名完全一致
  • 一致する場合は SKIP

6. ページ作成仕様

  • ページ作成は 新規作成のみ

  • 既存ページが存在する場合は SKIP

  • ページ本文：

    • Markdown

    • 固定文言（例：WIP）

    • HTML は使用しない

      • WYSIWYG → Markdown 切替を回避するため

7. エラー処理・リトライ方針

7.1 API エラー

  • 対象：

    • 通信エラー
    • 5xx 系
    • その他 requests が例外を投げるケース

  • 最大 3回リトライ

  • リトライ失敗時はエラーとして扱う

7.2 処理中断方針

  • エラー発生時：

    • 即時終了

  • 次回実行時：

    • 既存ページは SKIP されるため、自然復旧可能

8. CLI 仕様

8.1 実行ファイル名

create_skeleton.py

8.2 コマンド形式

python create_skeleton.py -i path/to/input.yaml

8.3 オプション

  • -i / --input

    • 入力 YAML ファイルパス

  • サブコマンド（apply / plan 等）は持たない

9. 出力仕様（標準出力）

  • 標準出力に処理結果を出力する
  • 出力内容例：
OK: ISO 26262 / 21434 とA-SPICEの役割分担
SKIP: A-SPICEを軸にした規格全体設計の考え方
ERROR: XXX（API error）
  • ID（Book / Chapter / Page）は出力しない

10. 認証・設定

  • BookStack API 接続情報は すべて環境変数で指定

例：

  • BOOKSTACK_BASE_URL

  • BOOKSTACK_TOKEN_ID

  • BOOKSTACK_TOKEN_SECRET

  • HTTP プロキシ対応は不要

11. テスト方針

11.1 テスト種別

  • pytest を使用

  • 以下を実施する：

    • ユニットテスト
    • 実 API 結合テスト

11.2 結合テスト前提

  • テスト専用 Book を用意する
  • 命名規約を定め、誤操作を防止する
  • 結合テストはローカル実行を前提とする

12. 将来拡張

  • 本ツールは WIP 骨格生成専用

  • 以下は対象外とする：

    • 本文ファイル分離
    • テンプレート展開
    • 差分更新・削除

13. 設計上の思想（非機能要件）

  • 安全側（破壊的操作をしない）
  • 再実行可能
  • 人間が YAML を読めば挙動が完全に予測できる
  • 属人作業を排除しつつ、ブラックボックス化しない
上に戻る