# Spec 4 接手指南 v3（最終交接 — stg 部署 + smoke + bug fix 環節）

> **建立日期**：2026-05-15
> **撰寫**：raymond（透過 Claude Opus 4.7 session）
> **接手對象**：stg 部署執行者 + 後續 bug fix / BDD 階段
> **狀態**：spec 4 全範圍開發完成（BE / FE / 內部套件 / 文件齊全），等 stg deploy + smoke

---

## 一、本案脈絡（5 行掃完）

- **目標**：spec 4 在既有 stage_object / BPMN flow template 機制上新增 `review` 階段 + 範本方向性驗證 + 全 stage 共用留言
- **進度**：M0–M11 全部 ship（含衍生 flow-template editor feature）
- **branch**（BE / FE 同名）：`feature/project-flow-engine-review`（未 push）
- **設計文件**：`design.md` v1.5（§16.1–§16.8 reconciliation 完整）
- **完整 task arc summary**：`docs/conversation-history/2026-05-13-review-stage-and-flow-validation/SUMMARY.md`（gitignored 本地檔）

---

## 二、已完成範圍

### 主線 A — Spec 4 review stage + topology validator（M0–M11.3）

按 design.md / implementation-plan.md 完整 ship：

| Milestone | 範圍 |
|---|---|
| M0 | Pre-flight verification |
| M1 | `compliance.stage_objects` 加 4 欄方向性驗證 + seed review row |
| M2 | Domain entity / mapper / model 對應 |
| M3 | `BpmnTopologyValidator` 純函式 + 22 條 unit test |
| M4 | Builtin BPMN seed (`builtin-full-audit-with-review`) + 既有 `builtin-full-audit` reverse patch |
| M5 | Error code + FlowTemplate validator 整合 |
| M6 | `POST /flow-engine/flow-templates/validate` endpoint |
| M7 | `StageAdvanceRequestSchema` 加 decision/comment + ReviewDecisionHandler |
| M8 | `StageAdvanceService` 接 decision/comment + JobComment 整合 |
| M9 | Integration test（service mock + HTTP smoke）|
| M10 | FE Banner 雙按鈕 + ConfirmDialog comment + BPMN editor inline validator |
| M11.1 | dev manual smoke + 4 個 root cause bug fix |
| M11.3 | 10 條 changelog 齊全 |

### M11.1 dev smoke 撞到 + 修完的 4 個 root cause bug

| Bug | Commit | Fix |
|---|---|---|
| task_execution → review 提前改 AP.status='auditing' | `5fba3bf` | 拆 launch_audit / 加 submit_for_review，TaskExecutionHandler review-aware 分流 |
| 執行任務階段按鈕寫死「啟動稽核」| `1c8d08c` | stage_objects 加 entry_button_label_i18n，BE peek 下一個 stage 動態決定 button |
| 退回後 BPMN 走錯 → 走到稽核 | jedi-flow-engine `67e979f` (0.0.29) | `_fmt(str)` 改用單引號（Camunda FEEL 標準）|
| reviewer 角色 launch_audit 403 | `1c8d08c` | launch_audit 加 trusted_caller flag 跳過冗餘角色二次驗 |

### 主線 B — 衍生 flow-template BPMN editor feature

| 範圍 | Commit |
|---|---|
| flow_templates.status draft/published 狀態機 + publish/unpublish endpoint | BE `3ff38d9` |
| BPMN editor writeCamundaProp fix（modeling.updateModdleProperties）+ smart Gateway condition UI + Toolbar 發布按鈕 | FE `bef1cc4` |

> **教訓**（已寫進 `docs/claude/feature-development-workflow.md`）：這部分**該開新 spec 不該塞回 spec 4 branch**。後續 spec 遵守「衍生 feature 離開本 spec scope」規則。

---

## 三、最終 commit chain

### BE Repo（feature/project-flow-engine-review，**未 push**）

```
9625a8f docs(claude): feature-development-workflow 加 Spec Sizing 4 規則 + Phase 1 walkthrough
b95e8ac fix(deploy): verify SELECT 欄位名 sort_order → sort
88b608e chore(deploy): BPMN 整合 feature 單一 SQL 入口 — \ir 整合 6 個 migration
72f27e5 chore(deploy): spec 1+2+3 整合性部署 SQL（idempotent，stg/prod 用）
0613750 chore: bump jedi-flow-engine 0.0.28 → 0.0.29
c945c12 docs(spec4): design.md v1.5 — §16.4–§16.8 reconciliation
3ff38d9 feat(flow-template): draft/publish 狀態機 + unpublish + topology 規則放寬
1c8d08c fix(spec4): review stage 三 bug 修復 + multi-review 架構支援
5fba3bf fix(spec4-be): task_execution → review 不再提前改 AP.status='auditing'
5bb4754 docs(spec4): handoff-v2
... (M0–M9 commits 略，見 SUMMARY.md §2)
```

### FE Repo（同名 branch，**未 push**）

```
bef1cc4 feat(flow-template): BPMN editor writeCamundaProp fix + smart gateway + draft/publish UI
e65a626 fix(spec4-fe): review reject 成功 toast 區分「已退回」非「已推進」
50821bb tweak(spec4-fe): code review 反饋 — readonly guard / 空白範本跳過初始 validate / 移除 silent return
317c36b fix(spec4-fe): i18n key spread overwrite + 補 3 條 validator rule i18n
bdc6c59 feat(spec4-fe): review stage 雙按鈕 + BPMN editor inline validator
```

### 內部套件 jedi-flow-engine 0.0.29（已推 Nexus）

```
67e979f chore: bump 0.0.28 → 0.0.29
537ad2d fix: review fix H3+M2 — BPMN gateway no-match warning + sub_workflow missing raise
```

### Working tree 殘留（不入版控）

```
?? scripts/sql/spec3_phase6_pr1_audit_completed_projects.sql
```

→ spec 3 PR1 髒資料審計工具（純 SELECT + commented UPDATE template），stg/prod 部署時手動跑 audit query；不該入 spec 4 branch。

---

## 四、stg / prod 部署 — 接手者必做（按順序）

### Step 1 — Push BE + FE branch（互動命令）

```bash
# 在 terminal 互動跑（GitLab 認證需要互動 prompt）
cd ~/Projects/Billows/Audit-Manager/compliance-manager-be
git push origin feature/project-flow-engine-review

cd ~/Projects/Billows/Audit-Manager/compliance-manager-fe
git push origin feature/project-flow-engine-review
```

### Step 2 — Stg DB migration（單一 SQL 入口）

```bash
# 密碼透過 ~/.pgpass 或 PGPASSWORD env var（不寫進 SQL 檔）
PGPASSWORD='<stg_password>' \
  psql -h <stg_host> -p <stg_port> -U cmmgr -d <stg_db> \
       -v ON_ERROR_STOP=1 \
       -f scripts/sql/2026-05-15-bpmn-integration-deploy-all.sql
```

SQL 內建：
- 依序執行 6 個 idempotent migration（全 IF NOT EXISTS / ON CONFLICT 守門）
- 跑完印 verify SELECT（stage_objects 5 列 + builtin flow_templates 4 筆）
- 用 `\ir` relative include，從 BE repo root 跑可自動找到同目錄 SQL

### Step 3 — Stg `poetry install` + 重啟 BE / FE

- `pyproject.toml` 已 pin `jedi-flow-engine==0.0.29`（已推 Nexus）
- `poetry install` 會抓 0.0.29
- BE / FE 用 infra 既有 deploy pipeline 重啟

### Step 4 — Manual smoke 14 步

完整 checklist 見 SUMMARY.md §6.5（簡化版）；或本 session 對話末段「Stg Smoke Checklist 簡化版」。

關鍵驗證點：

| # | 步 | 預期 |
|---|---|---|
| 1 | task_execution 階段按鈕 | 「**送審**」（不是「啟動稽核」）|
| 2 | task_execution → review | AP.status **維持** active（不變 auditing）|
| 3 | Review 階段 banner | 「啟動稽核」+「退回」雙按鈕 |
| 4 | 「檢視稽核結果」按鈕 | review 階段**不該出現** |
| 5 | Reject + 留言 | BPMN 回 task_execution，toast「已退回審核」|
| 6 | Approve | BPMN 走到 audit，AP.status 變 auditing，「檢視稽核結果」按鈕出現 |
| 7 | Spec 2 回歸 | launch_new_round 切「完整稽核流程」（無 review）→ 走原本 4-stage |
| 8 | Flow-template editor | 建範本 = draft；違規 sequenceFlow 紅框；publish/unpublish；smart gateway condition 下拉；draft 範本不能用於新專案 |

### Step 5 — 額外手動 audit（按需）

```bash
# spec 3 PR1 髒資料審計（找被誤推到 COMPLETED 的 project）
psql -h <stg_host> -p <port> -U cmmgr -d <stg_db> \
     -f scripts/sql/spec3_phase6_pr1_audit_completed_projects.sql
# 純 SELECT 不破壞資料，看 Query 1+2 結果決定是否要跑 commented UPDATE template
```

---

## 五、Bug fix 環節注意事項

Smoke 撞到 bug 時：

### 排查順序

1. **先看 BE log**：`tail -f log/app.log | grep -iE "WARN|ERROR|advance_stage|review_decision|launch_audit|condition_param"`
2. **DevTools Network**：看 `/stage/advance` / `/validate` request payload + response（特別是 `error_code` 欄位）
3. **DB job_executions**：確認 BPMN 走向是不是預期 UserTask（SUMMARY.md §6 SQL）
4. **比對 design.md §16 reconciliation 條目**：8 條已詳列各種已知 trap

### 已知 caveat

| 項目 | 看哪 |
|---|---|
| jedi-common 吞掉 ValidationError msg | design §16.2 — FE 必須走 error_code i18n 不靠 msg |
| launch_audit 提前 / 不該動 status | design §16.3 — submit_for_review vs launch_audit 拆分 |
| Multi-review 串接 | design §16.4 — `_peek_next_stage_code_via_jobs` 穿越 Gateway default |
| Button label 寫死 | design §16.5 — `entry_button_label_i18n` 動態 |
| Gateway condition 引號 | design §16.6 — Camunda FEEL 單引號 |
| Topology 規則放寬 | design §16.7 — review 可接 review/planning/task_execution/audit |

### 修法守則

- BE 改 service 層 code 後**必須提醒 user 重啟 BE**（沒 hot reload）
- 改 jedi-* 套件走 poetry path dependency 先驗，user 明確指示才 bump version 發 Nexus
- 寫 SQL **必先 grep ORM `Mapped[]`** 對欄位名（本 session 踩過 `sort_order` vs `sort` 的雷，commit `b95e8ac`）
- explicit `git add <檔名>`，不 `-A` / `-am`

---

## 六、後續未做的 task（deferred / follow-up）

### Task Tracker 現況

| # | 主題 | 狀態 |
|---|---|---|
| 5 | M11.2 BDD scenario（compliance-manager-test repo）| ⏸️ deferred — 等 smoke 結束 + bug fix 跑完 |
| 8 | Follow-up：推進日誌 + 階段 comment 視圖 | 🟡 下個 spec 範圍 |

### M11.2 BDD（恢復時機：smoke 通過後）

- Repo：`~/Projects/Billows/Audit-Manager/compliance-manager-test`
- Branch：切同名 `feature/project-flow-engine-review`
- 寫 `features/flow-engine-review/review-stage.feature` + step definitions + page object
- Mirror 既有 banner BDD pattern
- 跑 `npm run test:bdd -- --tags @flow-engine-review`

### Follow-up #8 推進日誌 + 階段 comment（下個 spec）

需求：跨階段 timeline 可查「誰 / 何時 / 在哪個階段做了推進 / decision / comment」用來除錯。

階段留言（review approve/reject comment, M8 已寫進 `compliance.job_comments`）順便在這個視圖呈現。

**UI 位置 caveat**：
- ❌ 不放 AuditorOverview 的「Review」section（該 section 是 AP 輪次切換，語意不能混）
- ✅ 建議：FlowPhaseBanner 旁加 timeline icon / 或獨立 page

### 文件缺口（不擋 stg 但對外 handover 用）

- `docs/api/flow-engine/api-spec.md` + `design.md` 尚未同步 publish / unpublish / validate 三個新 endpoint
- FE `e65a626` (review reject toast 區分) 無獨立 changelog（屬 UI 文案小調可不補；或 `2026-05-15-tweak-fe-review-reject-toast.md`）
- 對話歷史 part-NN-of-NN-\*.md 拆 part 未做（按 SOP 該從 session JSONL 解析，但 SUMMARY.md 已產整合視圖；本地 markdown gitignored）

---

## 七、Spec 4 task arc retrospective（給後續 spec 借鑑）

**結論：spec 4 太長**（3 天 / 33 commits / design.md 5 版 / §16 8 條 / smoke 4 bug / 衍生 feature 混入）。

**4 條教訓已寫進 `docs/claude/feature-development-workflow.md`**（commit `9625a8f`）：

| 規則 | 重點 |
|---|---|
| 1 | 一個 spec = 一個 user-facing 完整情境（垂直切）— 判準：「先 ship 這個 spec，user 能不能拿來用？」|
| 2 | Design phase 強制做 user mental walkthrough — 寫 user 操作流程 + 狀態變化 + 按鈕條件 + 錯誤情境 |
| 3 | 衍生 feature 離開本 spec scope（不一定下階段立刻做，是 scope discipline 不是 prioritization）|
| 4 | 3 天時間盒 — 超過必拆 |

**Spec 4 應該的切分**：

| 假想 spec | Scope | 預估 |
|---|---|---|
| 4a Review stage core | schema 4 欄 + validator + ReviewDecisionHandler + builtin BPMN + FE banner 雙按鈕 + i18n | 2 天 |
| 4b Flow-template lifecycle | flow_templates.status 狀態機 + publish/unpublish + Editor toolbar | 1.5 天 |
| 4c BPMN editor enhancements | inline validator + smart gateway condition UI + writeCamundaProp fix | 1.5 天 |

---

## 八、文件清單（pointer）

| 文件 | 位置 |
|---|---|
| 整合 SUMMARY（含 commits / 改動範圍 / 行為差異 / deploy handover / smoke checklist）| `docs/conversation-history/2026-05-13-review-stage-and-flow-validation/SUMMARY.md`（gitignored）|
| Spec 4 design | `docs/features/FR-026-2605-project-flow-engine-integrate/04-review-stage-and-flow-validation/design.md` v1.5 |
| Spec 4 implementation plan | 同目錄 `implementation-plan.md` v1.1 |
| Handoff v1 / v2 / v3（本檔）| 同目錄 |
| Changelogs | `docs/changelog/2026-05-14-*` + `2026-05-15-*` 共 10 條 |
| Analysis | `docs/analysis/2026-05-15-review-stage-three-bugs.md` + `2026-05-15-flow-template-bpmn-editor-design.md` |
| Workflow SOP（4 規則 + walkthrough）| `docs/claude/feature-development-workflow.md`（commit `9625a8f`）|
| 部署單一 SQL 入口 | `scripts/sql/2026-05-15-bpmn-integration-deploy-all.sql` |
| Spec 3 髒資料 audit（local-only）| `scripts/sql/spec3_phase6_pr1_audit_completed_projects.sql` |

---

## 九、若 session 卡關 / 中斷

回報並建議：

1. **卡 stg DB migration 跑出錯** → 跑哪個 step 失敗、psql 印什麼錯；用 cmmgr 帳號（不是 cm_app）；確認 ~/.pgpass 設好
2. **stg BE 起來但 500** → 看 `log/app.log` 完整 traceback；確認 `jedi-flow-engine==0.0.29` 真的裝起來（`poetry show jedi-flow-engine`）
3. **smoke 撞到本 handoff 未列的 bug** → 對照 design.md §16 8 條 reconciliation；若仍無解，按 CLAUDE.md issue flow 開 `docs/issues/pending/<file>.md`
4. **想做 BDD 但 step / page object 不知 pattern** → 看 `compliance-manager-test` 既有 banner BDD（spec 2 / spec 3 留下的）

---

## 十、文件版本

| 版本 | 日期 | 變更 |
|---|---|---|
| v1 | 2026-05-14 | M0–M6 完成、M7 起手交接 |
| v2 | 2026-05-14 | M7–M9 完成、M10 起手交接（FE + 收尾）|
| v3 | 2026-05-15 | 最終交接 — spec 4 全 ship + 衍生 flow-template editor + retrospective 教訓；等 stg deploy + smoke + bug fix |