2026-05-22 finalized — 全 26 題小決策已 resolve；design / plan 文件全 spec-ready。 Sonnet 接手用：把下面 ``` 框內的 prompt 完整貼上即可開工。
你正在接手 SSP 在專案內直接編輯 — Phase C 的實作。
## 必讀文件清單（按順序讀）
1. CLAUDE.md（專案行為規範，已自動載入）
2. docs/features/FR-011.3-2605-ssp-edit-in-project/README.md（tracker）
3. docs/features/FR-011.3-2605-ssp-edit-in-project/analysis.md（完整設計分析，含 Project↔SSP 對應、可行性、影響面）
4. docs/features/FR-011.3-2605-ssp-edit-in-project/open-decisions.md（26 題決策表 — 已 finalized）
5. 接著按執行順序讀對應 design + plan：
- design-C1.md + implementation-plan-C1.md
- design-C8.md + implementation-plan-C8.md
- design-C7.md + implementation-plan-C7.md
- design-C2.md + implementation-plan-C2.md
- design-C3.md + implementation-plan-C3.md（重型，兩階段）
- design-C4.md + implementation-plan-C4.md
- design-C6.md + implementation-plan-C6.md
- design-C5.md + implementation-plan-C5.md
## 執行順序
[Batch 1 — 基礎 master data 準備]
C1 (OSCAL 角色 seed) → C8 (_ROLE_LABEL_MAP cleanup)
可平行進行（不互依賴）
C1 注意：要 seed 兩個 table — system_menus + oscal_roles（決策 C3-D5）
[Batch 2 — SSP-scoped endpoints 補齊]
C2.1 (basic CRUD: party / ssp-resources / system-characteristic / current-ssp-uid)
依賴 C1 (角色 dropdown 要 master data)
11 個 endpoint，建議分 4~5 個 commit
[Batch 3 — 受評範圍遷移 PR1（重點 refactor）]
C3.PR1 (service derived + 410 endpoint + backfill SQL)
+ C4 (專案 CRUD schema 拿掉 audit_systems/devices)
**必須同 PR / 同 release** — 不可分開 ship
C3 注意：410 response 用 GrcErrorCode pattern (GRC_410001 / GRC_410002)，
FE 用 error_code 查 i18n（決策 C3-D4）
Ship 後：DBA 跑 backfill SQL，進入 1 週觀察期
[觀察期 — 監控 mapping 表無新 INSERT]
跑 daily SQL 確認 mapping 表 row count 不增加
[Batch 4 — UI ship]
C2.2 (Excel import + leveraged endpoints)
+ C5 (FE SSP tab UI) — 部分依賴 C2.1，C2.2 ship 後 leveraged section 才完整可動
+ C6 (FE 拿掉專案表單受評範圍 section)
並行進行（不同 repo）
[Batch 5 — C7 06_外部利用恢復]
C7 (sheet_definitions + parser 兩行修改)
獨立，可任何時候做
注意：TEMPLATE_VERSION v2.0.0 → v2.1.0（決策 C7-D1）
[Batch 6 — 觀察期結束後 C3 PR2]
C3.PR2 (DROP TABLE + 拆 stack)
前提：1 週觀察期內 mapping 表 0 新 INSERT，無 regression
Point of no return — DROP 後無法簡單 rollback
## 每完成一個 phase 必做
1. **commit**：每個 phase 內分 T1, T2, T3... 各別 commit（不要批量塞一個 commit）
2. **changelog**：依 CLAUDE.md 規範寫進 docs/changelog/
3. **更新 README tracker**：把對應 phase 行的「狀態」+「ship commit」欄位填上
4. **smoke test**：design + plan 內列的測試規格全跑過
5. **不要自己決定架構**：plan 內有 [pre-flight verify] 標記要先動，遇到 design 沒覆蓋的情境 → 停下問人類
## 何時該停下問人類（不要自己拍板）
- pre-flight verify 結果跟 design 假設不符（method 改名 / DTO shape 不一致 / 資料量超出預期）
- 修改觸及 design 沒覆蓋的新檔案
- 跨 phase 影響擴大（例：改 C2 service 撞到 C3 的 derived 邏輯）
- 任何 pre-flight 跑 SQL 結果異常（mapping 表 row count 對不上 / 沒 active AP 的 project 數異常多）
- C3 PR2 是 point of no return — DROP TABLE 前必驗證觀察期穩定
## 重點 CLAUDE.md 規範提醒
- **DDD 層級嚴格規範**：route 不直接呼叫 DB；app service 用 @transaction；repo 用 lazy session
- **新增 endpoint 必須加權限檢查**（C2 用 require_ssp_manager）
- **變更紀錄**：每個 phase 完成都要寫 changelog
- **不自動 commit**：階段性 commit 可直接做，重大決策（架構衝突 / breaking change）才停下問
- **改 BE service 層 code 後必提醒 user 重啟**：BE 沒 hot reload
- **可翻譯欄位 update() 必傳 locale**（不太會撞到，但提醒）
- **晶晶體禁止**：動詞 / 連接詞用中文，技術專有名詞保留英文
- **Error code 一律用 GrcErrorCode + FE i18n**（C3-D4 強調的專案規範）
## 跨 repo 工作
| Repo | 路徑 | 涉及 phase |
|------|------|-----------|
| BE | ~/Projects/Billows/Audit-Manager/compliance-manager-be/ | C1, C2, C3, C4, C7, C8 |
| FE | ~/Projects/Billows/Audit-Manager/compliance-manager-fe/ | C5, C6（+ C1 i18n） |
| jedi-oscal（套件）| ~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal/ | 不預期動到 |
| 測試 | ~/Projects/Billows/Audit-Manager/compliance-manager-test/ | 各 phase 完工後寫 cucumber e2e |
## Branch
沿用 feature/ssp-import-export-phase2（或目前的 phase3 — 依 user 確認）
若 user 偏好可開新 branch feature/ssp-edit-in-project
## 預估總工時
- BE：8~10 天（C1 + C2 + C3 PR1 + C3 PR2 + C4 + C7 + C8）
- FE：5~6 天（C5 + C6 + C1 i18n）
- Test：2 天（cucumber + smoke）
- 觀察期：1 週（不 active 工作，只 daily monitoring）
總體曆時 3~4 週。
## 開工第一步
1. 先讀 README.md + analysis.md 對齊脈絡（5 分鐘）
2. 讀 open-decisions.md 確認所有決策（3 分鐘）
3. 從 C1 開工：讀 design-C1.md + implementation-plan-C1.md，跑 pre-flight 驗證
4. 跑 SQL migration → smoke test → commit + changelog → 更新 README tracker
5. C1 ship 後 user 確認再進 C8 / C2
過程中遇到任何 design 沒覆蓋的情境 → 停下問 user，不要自己決定。當 Sonnet 開工後：