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

| 項目 | 內容 |
|------|------|
| 緣由 | Phase 1（管線 + pilot）完成，停在 pilot user gate；下一棒執行 Phase 2 內容 fan-out |
| Branch | `main`（本 feature 全程在 main，不切 branch） |
| 接手前必讀 | 本文件 §0 讀序 |
| 前置條件 | **🛑 pilot gate 必須先過**：user 開過 `GAI-SD-06-Third-Party-Licenses-v1.8.0.docx` 說 OK 才開工；user 若有排版修改意見 → 先改 renderer 重 build 重驗，再進 Phase 2 |
| 預估 | Phase 2 全部 task 約 1~2 個工作天（含並行 agent 等待） |

## 🧭 原始需求 / WHY（必讀，不懂不准開工）

**這整件事要解決什麼**：公司要把 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 最終驗收）

## §0 接手讀序（按順序）

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 就是「合格內容源」的樣子）

## §1 現況（非 bug，是進度狀態）

- 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。

## §2 前次教訓（別重蹈）

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 -- <檔>`。

## §3 已知風險 / 待驗證點（推測，開工時 verify）

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**，模組歸屬標套件名。

## §4 開工順位

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

## §5 該讀的檔案 / 預期改動範圍

- 新增：`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**

## §6 Pre-flight Command（必跑）

```bash
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
git branch --show-current          # 應為 main
git status --short                 # 應乾淨（或只有已知 untracked）
git log --oneline -6               # 應見 2779317c / 59d4c791 / 4f742b9e / 317c8890 / 08b5393d
poetry run pytest test/test_deliverables_renderer.py -q   # 3 passed
poetry run python scripts/deliverables/render_docx.py "docs/交付文件/v1.8.0/src/doc-06-licenses"  # ✅ Generated
```

## §7 Verify 前一棒確實完成（必跑 + 必問）

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

## §8 行為規範重要提醒

- 不切 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 指定的控管方式）

## §9 本棒收尾（Phase 2 完成後）

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

## §10 不在本期 scope（別順手做）

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

## §11 前次 session commits（未 push；push 等 user 明示）

| Commit | 內容 |
|--------|------|
| `08b5393d` | design.md + README FR 登記 |
| `317c8890` | implementation-plan.md（reviewer 兩輪 Approved） |
| `4f742b9e` | Phase1 Task1 — conventions + glossary + 骨架 + tracker |
| `59d4c791` | Phase1 Task2 — renderer（TDD 3 tests） |
| `2779317c` | Phase1 Task3 — GAI-SD-06 pilot（collector + 五章 + build 通過） |

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

## §12 給 fresh session 的超短 prompt

```
請讀 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。
```