# FR-047 功能 SPEC 量產 — Lane A 續跑交接（中繼 handoff）

| 項目 | 內容 |
|------|------|
| 緣由 | 連續作業模式跑 FR-047 頁面 spec 量產；本棒（Lane A ①）完成「專案管理群」7 頁後 context 快滿，中繼交棒 |
| Repo / branch | BE `compliance-manager-be`，current branch = **main**（**不切 branch、不 push**，照 CLAUDE.md） |
| 本棒完成 | 專案管理群 7 頁全數 ✅（commits `83fce5ac` / `f0c8cdef`）；tracker 已更新（`3b096628`） |
| 接手前必讀 | ① 本檔全部 → ② `docs/features/FR-047-2607-feature-spec-handbook/handoff/2026-07-05-mass-production-prompt.md` → ③ `writing-feature-specs` skill → ④ 範本 `docs/specs/v1.8.0/project-management/project-planning.md` + 本棒產出的 `project-list.md`（合格 Sonnet 樣貌） |
| 預估 | 剩餘 Lane ②~⑤ 約 15 頁 + 4 個 _overview；每頁 20~40 分鐘（Opus 自寫較久） |

---

## 🧭 原始需求 / WHY（先懂這個，再開工）

**這套手冊給誰、解決什麼**：`docs/specs/v1.8.0/` 是給**新手全端工程師**的功能 SPEC 手冊——痛點是「查一個功能會查到天荒地老」。解法：**一條 FE route = 一份 13 節 spec**，markdown 是唯一 living truth（HTML 站 / docx 都是 build 產物）。

**核心紀律一句話**：spec 是 living truth，每個事實從 code / DB **掃出來**，不憑記憶、不抄舊文件、不信探勘 agent 摘要的 schema 名。真相來源唯一：
- 表結構 / schema 名 / 欄位 → `scripts/deliverables/out/db_schema.json`
- endpoint 存在性 / path → `scripts/deliverables/out/routes.json`
- request / response 欄位 → marshmallow serializer + service 組裝碼（開檔逐條對）
- FE UI / 條件邏輯 → FE repo 實掃（`~/Projects/Billows/Audit-Manager/compliance-manager-fe/`）

**本棒在大圖的位置**：整個量產分 3 wave、9 群、47 條目。本棒完成「專案管理群」（Wave 1 第一群）。**平行有其他 session 在跑別的群**（#5 跑稽核執行群 = Lane B）——所以 tracker 是多 session 共寫，改前必重讀。

**本棒要續的 Lane 順序（user 指定，全屬 Lane A 連續作業）**：
- **② 合規框架與 SSP 群**（`compliance-framework/`）：先 `_overview`，再 6 頁
- **③ 問卷群**（`survey/`）：`_overview` + 3 頁
- **④ 報表與儀表板群**（`reporting/`）：`_overview` + 4 頁（`analysis` 🔍 先驗存廢）
- **⑤ 認證群**（`auth/`）：`_overview` + 登入（含 MFA OTP）+ 忘記/重設密碼

---

## §0 接手讀序（照順序，先懂需求再碰）

1. 🔒 **先懂需求硬 gate**：本檔「🧭 原始需求」+ mass-production-prompt.md（冷接自檢 3 問要答得出來）
2. 🔒 `writing-feature-specs` skill 全文（8 步流程 + 13 節模板 references/page-spec-template.md + 圖形化慣例）
3. 範本：`docs/specs/v1.8.0/project-management/project-planning.md`（pilot）+ `_overview.md`；本棒 `project-list.md`（Sonnet 合格樣貌）、`project-create.md`（Opus + BE bootstrap 時序圖法）
4. tracker：`docs/features/FR-047-2607-feature-spec-handbook/tracker.md`（認領頁面 / 看誰在寫什麼）
5. **本檔 §2 教訓**（血淚，務必讀——subagent 委派會 stall、schema drift、DB 連法）

**冷接自檢 4 問**（答不出回去讀）：
1. spec 的事實憑什麼可信？（答：三來源 dump + 開檔，不信 agent 摘要）
2. 為什麼不能派 subagent「寫完整頁 spec」交回就好？（答：見 §2.1，它們會 stall；只能派研究、md 自己寫）
3. schema 名寫 `grc.audit_rounds` 對不對？（答：錯，真相是 `compliance.project_audit_rounds`；一律查 db_schema.json）
4. 改 tracker 前要做什麼？（答：重讀，多 session 共寫）

---

## §1 現況（本棒完成什麼）

**專案管理群 `docs/specs/v1.8.0/project-management/` 7 頁全數 ✅**（+ _overview 早已完成）：

| 頁 | 檔 | 模型 | commit | 特別註記 |
|----|----|------|--------|---------|
| 專案列表 | project-list.md | Sonnet | `83fce5ac` | 可見性 vs 編輯權不對齊坑 |
| 專案建立 | project-create.md | Opus | `83fce5ac` | `POST /oscal-project/start` clone 三件組；atomic 核心 vs best-effort 尾段時序圖 |
| 專案總覽 | project-overview.md | Opus | `83fce5ac` | 三 route 變體；FE 生命週期常數指 legacy path 的 drift（§12） |
| 稽核輪次清單 | project-ap-list.md | Sonnet | `f0c8cdef` | 新增輪次 UI 旗標隱藏（BE 端點仍活） |
| 專案設定 | project-settings.md | Sonnet | `f0c8cdef` | ⚠️ PUT 無 BE 角色守門的安全缺口 vs verify-and-repair 嚴格 manager |
| 專案儀表板 | project-dashboard.md | Sonnet | `f0c8cdef` | 全域落地頁（非 per-project 總覽）；2 處已驗失效 UI |

**🔍 已解決**：`project-dashboard` 驗 live（`ui_routes.enable=1`，`/project/dashboard` 全域落地頁）保留；`project-task-setup` 驗**死**（FE 0 個 nav 進入點，功能 FR-038 併入規劃頁任務面板）→ tracker 除名。

每頁：13 節模板 + 3~5 張 `.dot`（`assets/` 下，前綴 `pl-`/`pc-`/`po-`/`pal-`/`ps-`/`pd-`）。全部 build ✅ / 敏感資訊 grep 0 / 「GRC 系統」0。§5 實機截圖一律留佔位 callout（截圖另有專責 session，STG 亮色模式）。

---

## §2 前次教訓（血淚，續跑必看）

### §2.1 ⚠️ subagent 委派「寫完整頁 spec」會 STALL — 不要這樣派
本棒派了 3 個 Sonnet subagent 各寫一頁 spec，結果**全部沒寫出 md 檔**：它們把工作再分包給 research 孫 agent，然後**idle 等孫 agent、不自己寫 md**。孫 agent 的**研究產出極好**（開檔驗證、file:line、schema 對 dump），但 parent 沒落地。
- **正確模式**：subagent 只派**研究**（用 `Explore` 或 general-purpose 明令「只回事實 manifest，不寫檔」），**md + dot 由主導 session 自己寫**。或直接自寫全部。
- 本棒後來救回 ap-list agent 已寫進 repo 的 4 張 dot（品質好、error code 正確），settings/dashboard 靠孫 agent 的研究報告自寫。
- **若仍要派寫檔**：prompt 必加「**禁止再 spawn subagent；自己 grep、自己 Write md 到指定路徑**」，並在交回後**自己 verify schema/endpoint + build** 才 commit。

### §2.2 schema drift — 一律查 db_schema.json
agent 摘要常寫錯 schema 前綴。本棒抓到的錯：`grc.audit_rounds`→實際 `compliance.project_audit_rounds`；`oscal.module_frames`→`compliance.module_frames`；`cloud_integration.drive_folder_mappings`→`public.drive_folder_mappings`；`auth.users`→`public.users`；`jedi_oscal.*`/`jedi_flow.*`→`oscal.*`/`compliance.*`；`public.workflow_executions`→`compliance.workflow_executions`。**view（`vw_*`）不在 dump**（dump 只收 table）→ 去 `scripts/sql/view/` 找定義，spec 標「(VIEW)」。

### §2.3 error code 開檔驗（別抄 agent）
本棒抓到 agent 把 manager 守門寫成 `GRC_403001`，實際 `GRC_NOT_MANAGER = GRC_403002`（`GRC_403001` 是 `GRC_NOT_AUDITOR`）。error code 在 `common/code/grc_error_code.py`，grep 確認。

### §2.4 DB 連法（.env source 會失敗）
`.env` 的 `DB_SECRET` 是 JSON，`source .env` 帶不進來。用 python regex 抓密碼：
```bash
PW=$(python3 -c "import re
for l in open('.env'):
    if l.startswith('DB_SECRET='):
        print(re.search(r'\"rds_master_password\"\s*:\s*\"([^\"]+)\"', l).group(1)); break")
PGPASSWORD=\"$PW\" psql -h 192.168.50.188 -p 25432 -U cmmgr -d guidant_ai_dev -tA -c \"SELECT ...\"
```
`public.ui_routes` 欄位是 `name / url / enable`（不是 path）；驗 route live 用 `enable=1`。

### §2.5 build 有時被別 session 的半成品擋
`render_html.py` 遇到缺 dot 會 `sys.exit` 硬停。曾被 session #3 的 `audit-execution/audit-review.md`（缺 `ar-ui-layout.dot`）擋（現已修）。若再遇：暫時把該壞 md 搬到 scratchpad → build 驗自己的頁 → 搬回。**別動別人的檔本身**。

### §2.6 tracker 多 session 共寫
#3/#4/#5/#6 都在改 tracker。**每次改前 Read 對應段**（Edit 會因 stale 失敗）。只改自己那幾列 + 統計 + Session 紀錄，別動別人的列。

### §2.7 FR-038 legacy 端點 drift（寫輪次 / 稽核相關頁會遇到）
FE `api.js` 有 `GRC_CLOSE_ROUND`/`GRC_LAUNCH_AUDIT` 組成 `/grc/project/:pid/ap/:apUid/...`，但**這些 path 不在現行 routes.json**——現行輪次生命週期在 `/audit-round/{roundUid}/...`。寫到相關頁在 §12 flag，別當 live endpoint。

---

## §3 每頁怎麼做（8 步 SOP 摘要，細節在 skill）

1. tracker 認領（標 🚧，改前重讀）
2. 該群 `_overview.md` 不存在先寫（頁面地圖 / 共用狀態機 / 角色基調 / 核心資料模型；範本 = project-management/_overview.md）
3. 事實蒐集三來源：FE 實掃 + BE 鏈路 + `db_schema.json`/`routes.json`
4. 寫 13 節 md（模板 references/page-spec-template.md）
5. 畫 `.dot` 進該群 `assets/`（前綴用頁面縮寫；`dot -Tsvg <f> -o /dev/null` 驗編譯；視覺語彙照既有 dot：主色 `#13294B`、accent `#B8873B`、判斷菱形 `#FFF6E5`、例外 `#FDEBD3`、錯誤 `#F8DCDC`、成功 `#D9E9DC`）
6. build：`python3 scripts/deliverables/render_html.py "docs/specs/v1.8.0"` 必 ✅
7. 自查：`grep -REn '192\.168\.|password\s*=|Billows@'`=0、`grep 'GRC 系統'`=0、內部連結不斷
8. 顯式 `git add <檔名>` commit（**禁 -am / add -A**）→ 重讀 tracker → 更新該頁狀態 / commit / 日期

**模型分工**：tracker 標 Sonnet 的頁可派 Sonnet subagent 寫（但見 §2.1 陷阱——建議只派研究、自己落 md）；標 Opus 的自己寫。

---

## §4 Lane ② 起步線索（合規框架與 SSP 群）

FE 路徑 `~/Projects/Billows/Audit-Manager/compliance-manager-fe/src/`。tracker Wave 2「合規框架與 SSP（compliance-framework/）」列的 6 頁：
- 合規框架管理（`compliance-framework-manage` / `version-manage`，Opus）
- 框架版本匯入 / 編輯（`compliance-framework-import-version` / `version-edit`，Sonnet）
- 範本管理 ModuleFrame（`module-frame` / `-items` / `-template-edit`，Opus）
- 範本匯入精靈 docx/excel（`module-frame-import-*` 5 條合一，Sonnet）
- SSP docx 匯入 / 更新（`project-ssp-import-docx`，Sonnet）
- BPMN 稽核範本管理（`flow-template-manage` / `-create` / `-edit`，Opus）

**已知 module-frame 端點**（routes.json 撈過，可信）：`GET /module-frame`（list）、`GET /module-frame/{uid}`、`.../components`、`.../control-defaults`、`.../objective-defaults`、`.../parties`、`.../inventory`、`.../leveraged`、`.../ssp-resources`、`.../system-characteristic`、`.../template-ssp`、`.../ssp-export`、`.../ssp-import-template`、`GET /module-frame/download/{template,yaml-template}` 等（增刪改各對應 POST/PUT/DELETE）。框架版本 / flow-template 端點自行 grep routes.json（pattern：`framework`、`flow-engine/flow-templates`）。ModuleFrame 領域知識 → 讀 `oscal-knowledge` skill + memory `reference_db_schema_module_frame`。`compliance.module_frames` 有 `_trans` 翻譯表（可翻譯欄位慣例見 `docs/claude/translatable-fields.md`）。

---

## §5 Pre-flight（開工必跑）

```bash
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
git branch --show-current          # 必須是 main；不對就停下問 user（不自己切）
git status --short                  # 確認自己要動的檔沒被別 session 佔
git log --oneline -5                # 對照本 handoff §1 commits
ls scripts/deliverables/out/{db_schema,routes}.json   # 事實 dump 在不在
python3 scripts/deliverables/render_html.py "docs/specs/v1.8.0" 2>&1 | tail -3  # 現況 build 是否已綠（別人的半成品可能擋，見 §2.5）
```

---

## §6 行為規範重要提醒（適用本量產）

- **不切 branch、不 push**（push 永遠等 user 明示）；**顯式 git add 檔名、禁 `-am`**
- 每頁**獨立 commit + 立刻更新 tracker**（改 tracker 前重讀）
- 每完成一個功能群，給 user 一句話回報然後**直接繼續**（不等驗收）
- §5 截圖一律留佔位 callout（截圖專責 session 另做）；一律**亮色模式**規格
- 憑證只寫「見 `.env` / 部署文件」，**絕不**把 IP / 密碼寫進 spec
- 不晶晶體、不用「GRC 系統」（用 Guidant AI / 合規稽核平台）、不用「速贏」
- 跨 repo 開 FE 前先讀 FE CLAUDE.md（646 行）；只讀不改 FE（spec 是掃 FE 現況，不動 FE code）
- **context 快滿時**：照本 SOP 在乾淨的群組邊界寫下一份中繼 handoff、更新 tracker 後停下

---

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

- 不修 code（發現的 bug / 安全缺口只寫進 spec §12，不動實作）——例：project-settings PUT 無角色守門是**記錄**不是修
- 不補 §5 實機截圖（專責 session）
- 不動別 session 正在寫的群（看 tracker 狀態 🚧 / Session 紀錄）
- 不重整別人已寫的頁

---

## §8 前次 session commits（origin 未 push，全在 local main）

```
3b096628 docs(FR-047): tracker — 專案管理群 7 頁全完成
f0c8cdef docs(FR-047): 專案管理群收尾三頁 — 輪次清單/設定/儀表板
83fce5ac docs(FR-047): 專案管理三頁 spec — 列表/建立/總覽
```
（更早的 pilot / 稽核執行群 commits 見 `git log`；本群相關的都已 commit，working tree 對本群乾淨。）

---

## §9 給 fresh session 的超短 prompt（user 複製貼）

```
接手 FR-047 功能 SPEC 量產（連續作業模式）。先讀
docs/features/FR-047-2607-feature-spec-handbook/handoff/2026-07-05-lane-a-continuation-handoff.md
全文（含 §2 教訓：subagent 委派會 stall、schema 一律查 db_schema.json、DB 連法、tracker 多 session 共寫），
答得出 §0 冷接自檢 4 問再開工。依 writing-feature-specs skill 8 步，
續跑 Lane ②合規框架與SSP群（先 _overview 再 6 頁）→ ③問卷 → ④報表（analysis 🔍先驗）→ ⑤認證。
每頁獨立 commit + 立刻更新 tracker（改前重讀）；每群完成給我一句話回報後直接繼續；
不切 branch、不 push、禁 -am；§5 截圖留佔位；context 快滿寫中繼 handoff 後停。
```

---

## §10 續跑進度更新（2026-07-05）

**✅ Lane ② 合規框架與 SSP 群：6 頁 + _overview 全數完成**（本 session #6 兩輪連續產出）：

| 頁 | 檔 | commit |
|----|----|--------|
| _overview | compliance-framework/_overview.md | `bba1e08d` |
| 合規框架管理（Opus） | compliance-framework-manage.md | `d5eddff9` |
| BPMN 稽核範本管理（Opus） | flow-template-manage.md | `ccfd588b` |
| 合規資源庫 ModuleFrame（Opus） | module-frame.md | `46a69ea3` |
| 框架版本匯入 / 編輯（Sonnet） | compliance-framework-import-version.md | `3fdcec1b` |
| 範本匯入精靈（Sonnet） | module-frame-import.md | `9a5bcbbe` |
| SSP docx 匯入（Sonnet） | project-ssp-import-docx.md | `9a5bcbbe` |

**下一棒起點 = Lane ③ 問卷群（survey/）** → 之後 ④ 報表群 → ⑤ 認證群。

**Lane ③ 問卷群線索**（`survey/`，tracker Wave 2）：
- 先寫 `_overview`（問卷 v2 資料模型：問卷範本 / snapshot / 填答；與稽核任務的關係——任務可掛問卷，見專案規劃頁 §6.4 surveys）。
- `survey-v2-manage`（Sonnet）：`views/survey/`（grep FE `survey-v2`）；`survey-v2-designer`（Opus，問卷設計器）；`survey-v2-fill / -preview`（Sonnet，填答 / 預覽）。
- 端點 grep `scripts/deliverables/out/routes.json` 的 `survey`；已知 `project-survey/*`（answers / histories / checkpoint / patch）在 `api.task_survey.routes`。表 grep `db_schema.json` `survey` schema（有獨立 `survey` schema：`survey.task_surveys` 等）+ `snapshot`。jedi-survey 套件（`~/Projects/Jedicogy/module/jedi-python-package/jedi-survey/`）。
- 領域知識：memory 搜 `survey`；問卷 snapshot 慣例見專案規劃頁 spec §11 / §6.4。

**Lane ④ 報表群（reporting/）**：`analysis` 頁先驗 `ui_routes.enable`（🔍）；`project-summary-report`（Opus，端點 `/project-summary-report*`，已在 routes.json）；`ai-dashboard`（Sonnet，`/ai-dashboard/*` + `/grc/dashboard/summary` 已在 dashboard 頁spec）；`customer-dashboard-editor`（Sonnet，動態儀表板模組）。

**Lane ⑤ 認證群（auth/）**：`login`+`otp-verify`（Opus，MFA OTP；端點 grep `login|otp|mfa|token`；jedi-auth + jedi-mfa 套件；memory `reference_dev_login`）；`forget-password`/`reset-password`（Sonnet，grep `password`）。**認證頁多為未登入態，§3 權限與其他頁不同（匿名可達）**，§5 截圖可能要登出態擷取。

**共用經驗（省時）**：三步匯入的 `parse→預覽→confirm` 模式已定型（見 `_overview §4` + `uc-cfi/mfi/ssi-01` dots 可參考）；envelope 成功 `{"status":true,"data":…}`；schema 一律查 db_schema.json（view 不在 dump，去 `scripts/sql/view/`）；error code 開檔驗。

**fresh session prompt（更新版，複製貼）**：
```
接手 FR-047 SPEC 量產（連續作業）。先讀 docs/features/FR-047-2607-feature-spec-handbook/handoff/2026-07-05-lane-a-continuation-handoff.md
全文（特別 §2 教訓 + §10 進度）。Lane ② 已完成；從 Lane ③問卷群（survey/，先 _overview 再 manage/designer/fill+preview）起，
→ ④報表群（analysis 🔍先驗）→ ⑤認證群（login+MFA / forget+reset，注意匿名態）。
依 writing-feature-specs skill 8 步；每頁獨立 commit + 改前重讀 tracker；schema 一律查 db_schema.json、
error code 開檔驗；不切 branch/不 push/禁 -am；§5 截圖留佔位；context 快滿寫中繼 handoff 後停。
```