FR-046 Phase 2 fan-out 接手 Handoff（2026-07-04）

這整件事要解決什麼：公司要把 Guidant AI 系統交付給客戶端，客戶請了外部顧問做架構評估。顧問需要一套正式技術文件（Word）來理解全系統並提出架構建議。目標是 6 份繁體中文正式文件（GAI-SD-01~06：系統架構 / API 全量規格 / 資料庫 / 權限安全 / jedi-* 內部套件 / 第三方授權清單），範圍涵蓋 BE + FE + jedi-* + 部署拓撲，jedi-* 完整揭露（顧問拿得到源碼）。

目標模型：內容寫成 markdown（唯一內容源，進版控），由共用 renderer（scripts/deliverables/render_docx.py）統一轉成專業排版 docx（封面「OOOO 版權所有」佔位 + 密等機密 + 統一樣式）。內容真相來源是 code / DB 程式化產生（route dump、information_schema、依賴 metadata），不抄舊文件 —— 舊的 docs/api/、docs/claude/database-schema.md 完整度不一，只能當敘述參考。最後由對帳 script 程式化驗證「文件數量 = 真實數量」。

本棒在大圖的位置：三階段中的第二段 —— Phase 1 管線已完成並通過 pilot 驗證；本棒做 Phase 2（route/DB inventory scripts + 5 份文件內容 fan-out）；Phase 3（對帳 + 一致性 review + build 全部）是下下棒。

冷接自檢 4 問（答不出來回去讀 design.md，別動手）：

1. 這套文件是給誰看的、用來幹嘛？（外部顧問、架構評估 → 決定寫作深度與語氣）
2. 為什麼內容 md 不能自己排版、endpoint 清單不能抄 docs/api/？（renderer 統一樣式；程式化對帳要求真相來源唯一）
3. conventions.md §D 的固定 heading pattern 是幹嘛的？（Phase 3 對帳 script 靠它計數，格式錯 = 對帳 FAIL）
4. 本棒完成後還剩什麼？（Phase 3：verify script、一致性 review、build 六份、user 最終驗收）

1. 🔒 先懂需求 gate：docs/features/FR-046-2607-client-delivery-docs/design.md 全讀（尤其 §1 決策表 / §4 真相來源 / §5 規範 / §7 驗收）
2. docs/交付文件/v1.8.0/conventions.md 全讀（撰寫規範憲法，§C md 子集 / §D 可解析標記 / §E meta.yaml）
3. docs/features/FR-046-2607-client-delivery-docs/implementation-plan.md 的「全域鐵則」+ Phase 2（Task 4~10）
4. docs/features/FR-046-2607-client-delivery-docs/tracker.md（進度控管表 — 每完成一個 task 必更新）
5. scripts/deliverables/render_docx.py 開頭 docstring（renderer 介面）+ scripts/deliverables/collect_licenses.py（collector 寫法範本）
6. pilot 成品參考：docs/交付文件/v1.8.0/src/doc-06-licenses/（五章 md 就是「合格內容源」的樣子）

• Phase 1 三個 task 全完成、pytest 3/3 綠、pilot docx build 成功、敏感資訊掃描 0。
• 產出物：docs/交付文件/v1.8.0/（conventions / glossary / 六個 meta.yaml 骨架 / doc-06 五章）+ scripts/deliverables/{render_docx,collect_licenses}.py + test/test_deliverables_renderer.py。
• docx 不 commit（在 working tree / 或重 build 即得），最終驗收後才 commit — plan Task 13。

1. 中文路徑要引號：docs/交付文件/ 所有 shell 命令加引號。
2. metadata License 欄會是字串 "UNKNOWN"：collector 判讀順序 License-Expression → License 短值 → classifier → 首行 → MANUAL_LICENSE 人工補值；新 collector 比照。
3. git 顯式 add 檔名、禁 -am / add -A：本 session 曾因 index 有別人 staged 的東西差點掃進 commit。
4. pathspec commit untracked 檔會失敗：先 git add <檔> 再 git commit -- <檔>。

1. Task 4 route dump：create_app(enable_socketio=False) 可避 eventlet；但 create_app() 尾端 init_scheduler() 會啟動 APScheduler —— dump 完要 explicit shutdown + sys.exit(0)（推測可行，待 verify：先跑一次看會不會卡住或打 DB）。
2. DOC-02 endpoint 總數未知（推測數百）：Task 4 Step 3 的 6 批均分要照實際統計，不要照模組數拆。
3. jedi- 套件的 route*（jedi-auth / jedi-survey 等自帶 blueprint）也會出現在 url_map —— 屬於系統 API 的一部分，要進 DOC-02，模組歸屬標套件名。

1. Pre-flight（§6）
2. 確認 pilot gate 已過（§7；user 沒點頭就停）
3. Task 4：collect_routes.py → out/routes.json + out/api_batches.json → 更新 tracker「Task 10 批次明細」表 → commit
4. Task 5：collect_db_schema.py → out/db_schema.json → 對帳表數 → commit
5. Task 6~9 並行 dispatch（模型：DOC-01/04/05 用 Opus、DOC-03 用 Sonnet）；Task 10 六批並行（Sonnet）。dispatch prompt 必含：conventions.md 全文 + 全域鐵則 + 章節骨架 + 真相來源 + 顯式 git add 指示（plan Task 6~10 表格照抄）
6. 每個 agent 完成後：抽查其 md 是否守 §C/§D → 跑 renderer build 確認能過 → commit → 更新 tracker
7. 全部完成 → 更新 tracker session 紀錄 → 寫下一棒（Phase 3）handoff

• 新增：scripts/deliverables/collect_routes.py、collect_db_schema.py、scripts/deliverables/out/{routes,api_batches,db_schema}.json
• 新增：docs/交付文件/v1.8.0/src/doc-0{1,2,3,4,5}-*/ 各章 md + 更新各 meta.yaml chapters + src/assets/*.dot
• 更新：docs/features/FR-046-2607-client-delivery-docs/tracker.md（每 task）
• 不碰：renderer（除非 user 對 pilot 排版有修改意見）、doc-06（已完成）
• 跨 repo 只讀不改：FE repo（DOC-01 FE 章）、~/Projects/Jedicogy/module/jedi-python-package/（DOC-05）—— 讀 FE 前先讀 FE CLAUDE.md

1. 上面 pre-flight 全綠。
2. 問 user：「pilot docx（GAI-SD-06）驗收過了嗎？排版有沒有要改的？」 — gate 沒過不得進 Phase 2。

• 不切 branch / 不 push（等 user 明示）
• subagent dispatch prompt 必加「顯式 git add 檔名、禁 -am」
• 敏感資訊鐵則（conventions §B）：內部 IP / 帳密 / Nexus URL 一律佔位符
• 禁晶晶體、禁「GRC 系統」、產品名 Guidant AI
• DB script 憑證讀 .env（DB_SECRET 是 JSON）
• changelog 收尾才 batch 寫（user 下令才做）
• tracker.md 每完成一個 task 就更新（user 指定的控管方式）

1. 更新 tracker（含 session 紀錄列）
2. 寫 Phase 3 handoff（比照本文件結構）
3. 一句話 status 給 user；changelog / SUMMARY / Notion 等收尾動作等 user 明確下令

• Phase 3 的對帳 script / 一致性 review / build 全部（下一棒）
• 封面公司名（維持「OOOO」佔位，user 說了才換）
• 把 docx commit 進版控（最終驗收後才做）
• 動 docs/api/ 舊文件（它們不是本案交付物）

（同日 main 上另有他人 / 前 session 的 b6ebf097 oscal v1 清理 commit，與本案無關。）

請讀 docs/features/FR-046-2607-client-delivery-docs/handoff/2026-07-04-phase2-fanout-handoff.md，
先完成「🧭 原始需求」的冷接自檢 4 問與 §0 讀序（design.md、conventions.md 必讀），
再跑 §6 pre-flight 與 §7 gate 確認（pilot 驗收已過），
然後照 §4 開工順位執行 Phase 2（Task 4~10），每完成一個 task 更新 tracker.md。