02. 要件定義

機能要件

1. GAS バックエンド

1.1 Confluence API からのデータ取得

• 定期ポーリング: 指定された Confluence ページ配下の更新履歴を定期的に取得
• ページ単位の取得: 個別ページの内容を API 経由で取得
• 認証: Confluence Personal Access Token を使用した認証

1.2 HTML → Markdown 変換

• 自作変換ロジック: GAS のデプロイサイズ制約のため、外部ライブラリを使わず自作
• 変換対象の要素:
  • [Must] 見出し（h1-h6）
  • [Must] リスト（ul, ol）
  • [Must] テーブル
  • [Must] コードブロック
  • [Must] リンク
  • [Must] 画像（URL のみ）
  • [Want] その他基本的な装飾（太字、斜体など）
  • [Want] Confluence 独自記法（マクロ、ステータスラベル、パネルなど）
    • 実装が複雑なため、MVP では対応を見送り、Phase 2 以降で段階的に対応

1.3 Google Drive への保存

• ディレクトリ構造:
  • カテゴリ別フォルダ（例: “画面仕様書”、“施策A”、“施策B”）
  • 各カテゴリ配下はフラットにページを保存
• 保存内容:
  • Markdown ファイル本体
    • メタデータ（ページ ID、最終更新日時、タイトル、バージョンなど）は Markdown ファイルの frontmatter として保存
  • カテゴリ管理ファイル（_manifest.json）
    • 各カテゴリフォルダ内に配置
    • フォルダ内の全ページの一覧情報（ページ ID、バージョン、最終更新日時など）を記録
    • CLI が差分同期時に参照する

1.4 認証・アクセス制御連携

• Personal Access Token (PAT) の役割:
  • GAS 定期処理用 PAT: システム管理者（開発者）の PAT を GAS に設定し、定期ポーリングに使用
    • この PAT でアクセス可能なページのみ Google Drive に保存される
  • CLI ユーザー用 PAT: 各ユーザーが自身の PAT を CLI から送信
• アクセス制御の仕組み:
  • CLI からのリクエスト時、ユーザーの PAT で Confluence API にアクセスし、閲覧権限を検証
  • システム管理者 PAT でアクセス可能（= Google Drive に保存済み）かつユーザー PAT でアクセス可能なページのみ Markdown を返す
  • この仕組みにより、権限のないページへのアクセスを防ぎ、セキュリティに配慮
• レスポンス: 200 ステータスで閲覧可能なページのみ Markdown を返す

2. CLI ツール

2.1 ページ同期機能

• GAS への通信:
  • Personal Access Token を含む POST リクエスト
  • 単一ページまたは複数ページを指定（ページ ID、カテゴリ名など）
• ローカル保存:
  • レスポンスとして受け取った Markdown をローカルに保存
  • 既存ファイルがあれば上書き

2.2 マニフェスト管理

• ローカル状態の管理:
  • どのページを同期済みか
  • 最終同期日時
  • ページのバージョン情報
• 差分同期: マニフェストと Confluence の更新履歴を突き合わせて、更新が必要なページのみ同期

2.3 検索・フィルタリング

• ローカルにある Markdown ファイルの全文検索
• タグやカテゴリによるフィルタリング
• メタデータを活用した高度な検索

3. ローカル MCP サーバー（Phase 3 で実装）

• ローカルに保存された Markdown ファイルを AI エージェントに提供
• 検索・取得インターフェースの提供

非機能要件

1. パフォーマンス

• API リクエストの最小化:
  • Confluence サーバーへの負荷を抑える
  • キャッシュを有効活用
• 差分同期の効率化:
  • 更新されたページのみ処理
  • マニフェストによる高速な差分検出

2. スケーラビリティ

• GAS のデプロイサイズ制約:
  • 外部ライブラリの使用を最小限に
  • 自作ロジックで対応
• Google Drive の容量:
  • Markdown ファイルは軽量なので問題なし
  • 画像は URL 参照のみ

3. セキュリティ

• Personal Access Token の扱い:
  • システム管理者 PAT: GAS のスクリプトプロパティで管理（環境変数相当）
  • ユーザー PAT: ローカル環境変数や設定ファイル（~/.confluence-sync/config.json）で管理
  • CLI から GAS への通信は HTTPS
• Google Drive のアクセス権:
  • GAS からのみアクセス可能
  • ユーザーが直接 Google Drive にアクセスすることは想定しない
  • CLI は GAS API 経由でのみデータを取得

4. 保守性

• TypeScript による型安全性: CLI ツールは TypeScript で開発
• Biome によるコード品質: リント・フォーマット
• 明確なディレクトリ構造: コードの可読性・保守性

5. 拡張性

• MCP サーバーとの連携:
  • Phase 3 でスムーズに実装できる設計
  • ローカル Markdown ファイルを AI エージェントが活用可能に

制約条件

技術的制約

• GAS のデプロイサイズ上限
• Google Drive API のレート制限
• Confluence API のレート制限

組織的制約

• 事業部として専用サーバーを建てることはできない
• 大量リクエストによる Confluence サーバー負荷は NG
• Personal Access Token によるアクセス制御が必要

成功の定義

MVP（Phase 1-2）

• GAS が Confluence ページを取得し、Markdown に変換して Google Drive に保存できる
• CLI ツールで特定のページをローカルに同期できる
• マニフェストによる差分同期が機能する
• チームメンバーが問題なく利用できる

完成形（Phase 3）

• MCP サーバーが AI エージェントに情報を提供できる
• AI エージェントが社内ドキュメントを参照しながら作業できる
• チーム全体で最新情報が共有されている

今後詰める必要がある詳細

1. 差分同期の具体的な仕組み:

   • マニフェストのスキーマ
   • 更新検知のロジック
   • コンフリクト解決

2. 検索・フィルタリングの仕様:

   • 全文検索の実装方法
   • タグやメタデータの活用

3. エラーハンドリング:

   • API エラー時の挙動
   • リトライロジック
   • ユーザーへの通知

4. ユーザーエクスペリエンス:

   • CLI のコマンド体系
   • 進捗表示
   • ログ出力