# Spec 3「AP 套用流程」Handoff v3 — 任務收尾後接手指南

> **時間**：2026-05-13 完整 task arc 收尾結束
> **狀態**：**Spec 3 全部 ship-ready，等 user 自行 push + deploy；下一階段是 Phase 6 follow-up PR 排序**

---

## 〇、起手語（直接複製給新 session）

我要接手 Spec 3「AP 套用流程」task arc 收尾後的下階段工作。工作目錄：

- BE：`~/Projects/Billows/Audit-Manager/compliance-manager-be/`
- FE：`~/Projects/Billows/Audit-Manager/compliance-manager-fe/`
- 套件：`~/Projects/Jedicogy/module/jedi-python-package/jedi-flow-engine/`

三個 repo 同 branch：`feature/project-flow-engine-integrate`。

**Spec 3 本體已完整 ship-ready**（M1–M13 + Phase 6 review + summary 收尾全部完成）。下一階段是 **Phase 6 follow-up PR 排序執行** 或 **branch push / merge / 部署決策**。

---

## 一、當前 commit / branch 狀態

### BE repo（`compliance-manager-be`）
- HEAD: `b6f4eec` chore(deps): restore jedi-flow-engine pin 0.0.27 → 0.0.28
- Working tree: **clean**
- 27 個 commits 在 `ea8f573..HEAD`（Spec 3 全程 + dependency pin restore）
- **未 push origin**

### FE repo（`compliance-manager-fe`）
- HEAD: `695baad` tweak(spec3 M13): ApListView row buttons 對齊 AuditorOverview 三維度判斷
- Working tree: **clean**
- 6 個 commits 在 `6f6f30b..HEAD`
- **未 push origin**

### jedi-flow-engine 套件
- HEAD: `dd904ae` chore: bump 0.0.27 → 0.0.28
- Working tree: **clean**
- 5 個 commits 領先 origin（4 個 Spec 2 期間 + 1 個 bump）
- **未 push origin**
- **0.0.28 已上 Nexus**（poetry publish 成功）— 但 git branch 未 push（Nexus 跟 git 不同步狀態）

---

## 二、user 還沒做的事（外部 / 網路 / package 動作）

| 動作 | 命令 | 風險 |
|---|---|---|
| Push jedi-flow-engine | `cd ~/Projects/Jedicogy/module/jedi-python-package/jedi-flow-engine && git push origin feature/project-flow-engine-integrate` | 低 |
| BE `poetry update jedi-flow-engine` | `cd ~/Projects/Billows/Audit-Manager/compliance-manager-be && poetry update jedi-flow-engine` | 低（Nexus 已有 0.0.28） |
| Push BE branch | 同上 dir + `git push origin feature/project-flow-engine-integrate` | 低 |
| Push FE branch | 同上 dir + `git push origin feature/project-flow-engine-integrate` | 低 |
| 開 PR / merge / 部署 staging-prod | gh pr create 等 | user 部署決策 |

---

## 三、後續可做的工作（按優先排）

### Tier 1：Phase 6 follow-up 高優先 PR（建議短期內處理）

詳見 `docs/issues/pending/2026-05-13-spec3-phase-6-followups.md`：

| PR | 標題 | Priority | Spec |
|---|---|---|---|
| **PR1** | `_sync_project_status_to_completed` helper + terminal_close_ap 加權限檢查 | **High** | 一次清掉 Pattern 1+2 + Silent #1/#3/#6 |
| PR2 | launch_audit dead code 54 行刪除 | Medium | BE review #2 |
| PR3 | M12 completion_rate 補 unit test | Medium | BE review #1（hotfix `b979a71` 暴露 import smoke 不夠） |
| PR4 | FE default flow_template guard（master 軟刪 UX） | Medium | FE review #1 |

**PR1 是最高優先** — 揭露 3 個 OscalAuditService method 對 project.status 同步用 3 種寫法（PENDING 白名單 / IN_PROGRESS 白名單 / != COMPLETED 黑名單），terminal_close_ap 黑名單會強推 SUSPENDED/ARCHIVED → COMPLETED 破壞 archive 語意。

### Tier 2：Low / 中期

| PR | 標題 |
|---|---|
| PR5 | `_is_terminal_user_task` outcoming 空加 log warning |
| PR6 | `_extract_stage_codes` BPMN parse log context 補強 |
| PR7 | Comment patch（DTO 補 stage_codes / module docstring 拆 seeded vs runtime handler） |
| PR8 | FE size=100 隱性截斷 console.warn |
| PR-TD1 | flow_template payload `Optional[dict]` → dataclass |
| PR-TD2 | `StartProjectDto.flow_template_uid` 改必填 `str`（無 default） |
| PR-TD3 | `StageInfoDto` dataclass 形式化 |

### Tier 3：跨 repo / 可延後

| 項目 | 說明 |
|---|---|
| **M8** | Phase E 4 fixture bug + 3 Banner BDD scenario（`compliance-manager-test` repo）|
| Stage plugin 架構 | 已 analysis 不做，等觸發條件（新 stage 頻率 / 6-8 stage / SaaS 需求）|

---

## 四、必讀文件索引

### Spec 3 本體
- `docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/design.md` v3 — **必看 §16 Implementation Reality / Reconciliation**（含 9 條 plan 偏差 + 5 條 M9-M13 補丁 + strict/lenient 落地對照）
- `docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/implementation-plan.md` v1.1
- `docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/test-plan.md` v1
- `docs/features/FR-026-2605-project-flow-engine-integrate/03-ap-binding/handoff-v2.md` — 上一輪 handoff（v1.x → v2.1 plan 接手）
- 本檔 `handoff-v3.md` — 這次

### Phase 6 review（必看 master + 5 個別報告）
- `docs/review/2026-05-13-spec3-review.md` — **master summary** + 8 important concerns + 4 cross-cutting pattern
- `docs/review/2026-05-13-spec3-review-be-code.md`
- `docs/review/2026-05-13-spec3-review-fe-code.md`
- `docs/review/2026-05-13-spec3-review-silent-failures.md`
- `docs/review/2026-05-13-spec3-review-types.md`
- `docs/review/2026-05-13-spec3-review-comments.md`

### Follow-up tracker
- `docs/issues/pending/2026-05-13-spec3-phase-6-followups.md` — **11 個 PR 規劃**（PR1–PR8 + PR-TD1/2/3）

### Analysis 文件
- `docs/analysis/2026-05-13-terminal-stage-bpmn-driven-close.md` — M9 設計取捨（為何 寧包子 close、為何不選 close_round 直接呼叫等）
- `docs/analysis/2026-05-13-stage-plugin-architecture-thoughts.md` — plugin 架構討論（現階段不做）

### Changelogs
- 9 個 BE changelog（M1-M4 + M9-M12 各一筆）
- 3 個 FE changelog（M5+M6 / M10 / M13）

### Conversation history（gitignored）
- `docs/conversation-history/2026-05-13-spec3-ap-binding/SUMMARY.md` — 整 task arc 收尾報告
- 11 個 part-NN-of-11-*.md（M0–Phase 6 各 milestone 邊界）
- 也有 zip 在 `~/Desktop/spec3-conversation-2026-05-13.zip`（143 KB）

---

## 五、4 個 cross-cutting pattern（Phase 6 review 揭露）

接手後若要動 Spec 3 相關 code，注意這 4 條：

1. **`project.status` 同步條件三處不一致** — 任何新加「結案類」method 必須白名單 allowed_from（不要 `!= COMPLETED` 黑名單）
2. **權限檢查依賴 caller 約定** — 任何 OscalAuditService method 都要 `_check_participant_role`，TerminalCloseHandler 例外目前是純文件約定
3. **Untyped dict 蔓延** — 加新 payload 欄位前考慮升 dataclass / TypedDict（避免擴大此 anti-pattern）
4. **Lenient log context 不足** — BPMN 相關 lenient fallback 加 ID context 跟 exc_info=True 留 audit trail

---

## 六、行為決策反悔條件

| 決策 | 反悔條件 / 觸發點 |
|---|---|
| `terminal_close` 寧包子（不驗 POA&M / AR data） | 審計報告期末資料缺失 → 加 ar_data.completed_at sync |
| BPMN parse 失敗 lenient fallback `[]` | 出現「snapshot xml 壞」事故 → enrichment 改 `null` 區分 corruption vs 缺失 |
| AP closed → completion_rate 100% | spec 改變要拆「強制終止」vs「正常結案」狀態 → case 條件改 hardcode 比對 |
| Button label terminal 時覆寫「完成本輪」 | 全面 generic 化需求 → Phase 1 FE button config 一次處理 |
| Stage plugin 不做 | 新增 stage 頻率高 / 第 3 個 view 重複邏輯 / stage ≥ 6-8 / SaaS 需求 |

---

## 七、開發環境 reminders

| 項目 | 細節 |
|---|---|
| BE log | `log/app.log`（不是 stdout） |
| BE 重啟 | `pkill -9 -f main_socketio.py && python main_socketio.py > /dev/null 2>&1 &` |
| Dev DB | `192.168.50.188:25432 guidant_ai_dev`（不是 _stg），用 cmmgr 跑 migration（cm_app 受 RLS 擋） |
| Dev 帳號 | 手動 `blsadmin / Billows@123!`、pytest `blsit / Billows@123!` |
| BE test 跑法 | `PYTHONPATH=. pytest test/test_xxx.py -v`（test/ 沒 conftest，要 PYTHONPATH） |
| pyproject.toml | **目前 pin 0.0.28，不要再切回 path mode 除非要動套件** |

---

## 八、踩坑提醒

從本次 task arc 學到（也記在 memory）：

1. **改 BE service 後必重啟** — BE 沒 hot reload；commit 在 git 但 process 跑舊版會被「fix 沒生效」誤導
2. **SQL 寫前先 grep ORM `Mapped[]`** — DTO 名跟 ORM column 經常不一致（如 catalog_control_id vs control_id）
3. **Import smoke 對 method-body unresolved name 不敏感** — Class import 過 ≠ method 內 name 可解析（M12 hotfix `String` 漏掉就是這樣）
4. **Plan 跟現實會偏差** — 跨多日的 plan 開工前要 pre-flight verify 假設（method 名 / 路徑 / class 名），M0 grep 是必要的
5. **dev DB 既有壞資料要手動 SQL 修** — M11 fix 後新邏輯只 cover 新 case，既有受影響 row 要 user/dev 主動 SQL 修

---

## 九、本次 task arc 統計

| 維度 | 數字 |
|---|---|
| BE commits | 27 |
| FE commits | 6 |
| jedi-flow-engine commits | 5（領先 origin）|
| 新增 unit tests | 81 |
| Milestones | M0–M13（含 4 個 smoke 補丁 M9/M10/M11/M12）|
| Phase 6 review findings | 0 critical / 8 important / 15+ minor |
| 文件齊全度 | 100%（11 changelog + 2 analysis + 1 issue + 6 review + spec v3） |
| Conversation history parts | 11（gitignored）|

---

## 十、推薦明天起手 prompt

把第〇段「起手語」+ 第二段「user 還沒做的事」+ 第三段「後續可做的工作」貼到新 session，再說「先做 PR1」之類即可。

---

## 文件版本

| 版本 | 日期 | 變更 |
|---|---|---|
| v1 | 2026-05-13 | task arc 收尾 + ship-ready + 發版完成後的接手指南 |