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

• 目標：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：

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

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

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

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。

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

# 在 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 入口）

# 密碼透過 ~/.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 簡化版」。

關鍵驗證點：

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

# 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

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

修法守則

• 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 Tracker 現況

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 太長（3 天 / 33 commits / design.md 5 版 / §16 8 條 / smoke 4 bug / 衍生 feature 混入）。

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

Spec 4 應該的切分：

回報並建議：

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 留下的）