Spec 4 接手指南 v1（M7 起手）

建立日期：2026-05-14 撰寫：raymond（透過 Claude Opus 4.7 session 1） 接手對象：新 session 的開發者 / Claude 執行策略：subagent-driven-development（每 milestone 1 implementer + 1 spec reviewer + 1 code reviewer）

• 目標：spec 4 在既有 stage_object / BPMN flow template 機制上新增 review 階段 + 範本方向性驗證 + 全 stage 共用留言
• 進度：M0–M6 已完成（BE validator 路徑全通）；M7–M11 待做
• branch：feature/project-flow-engine-review（HEAD = 1befd7f 之後）
• 設計文件：docs/features/FR-026-2605-project-flow-engine-integrate/04-review-stage-and-flow-validation/design.md v1.2
• 實作計畫：同目錄 implementation-plan.md v1.1

重要決策軌跡（M0–M6 期間累積）

1. M3 reverse edge 識別：extension property reverse=true 為 primary，嚴格 anchored regex ^\s*\$\{\s*[A-Za-z_]\w*\s*==\s*['\"]reject['\"]\s*\}\s*$ 為 fallback。fullmatch + 大小寫敏感。
2. M3 reachability：forward-only BFS（reverse edge 不計入路徑），seed 從所有 StartEvent。
3. M5 find_all 改為 list_active()：app service 不直接構造 query entity，走 domain service 既有 list_active() 入口（DDD-clean）。
4. M5 err.context 是 dead-data：jedi_common.handler 目前不序列化 exception attribute。violations 細節透過 /validate endpoint（M6）surfacing；create/update 400 只當守門員。details 在 design.md §16.1 reconciliation 已紀錄。
5. M6 routing order：/validate 靜態路徑明示排在 /<string:uid> 動態之前，避免 URL collision。
6. M6 schema/route 命名：FlowTemplateValidate*Schema / FlowTemplateValidateRoute — 對齊 sibling verb-based naming（M6 review 後 rename 過）。
7. M4 自訂範本 backfill scan = 0：dev DB 上沒有 user duplicate 自 builtin-full-audit 的範本含未 patch Flow_poam_audit，所以 backfill update 0 列；user 環境若有可能要重跑 dry-run。

環境狀態

• BE 跑在 port 8002（不是 8000，env config 決定）
• DB: 192.168.50.188:25432/guidant_ai_dev，cmmgr 密碼 jedi@123!（migration 一律 cmmgr，cm_app 被 RLS 擋）
• BE 啟動方式（避開 .env 直接 source 卡 escape）：

  lsof -ti :8000 2>/dev/null | xargs kill -9 2>/dev/null
  lsof -ti :8002 2>/dev/null | xargs kill -9 2>/dev/null
  sleep 1
  nohup python3 -c "from dotenv import load_dotenv; load_dotenv('.env'); import runpy; runpy.run_path('main_socketio.py', run_name='__main__')" > /tmp/be.log 2>&1 &
  sleep 10
  lsof -nP -iTCP -sTCP:LISTEN 2>/dev/null | grep python

• Login API（注意 dev schema）：POST /api/1.0/login body = {"username": "blsadmin", "password": "Billows@123!", "cf_turnstile_token": "XXXX.DUMMY.TOKEN.XXXX"}，回 data.access_token（不是 token）
• 測試帳號：blsadmin / Billows@123!（manual）；blsit / Billows@123!（pytest）

M7 — StageAdvanceRequestSchema + ReviewDecisionHandler

目標：schema 加 decision/comment 欄位 + 寫新 handler 註冊到 stage_registry。

Files:

• Modify: api/flow_engine/serializers/stage_advance.py — 加 decision (Str, OneOf approve/reject) + comment (Str) + @validates_schema 強制 reject 必填 comment
• Modify: app/grc/service/oscal_stage_handlers.py — 加 ReviewDecisionHandler class（key=review_decision，純 dispatch decision 不動 AP.status）
• Modify: di_containers/grc/grc_containers.py — import + Factory + register_stage_hooks_to_registry 加 registry.register_handler(grc_container.review_decision_handler())

詳細範本程式碼見 implementation-plan.md §M7.1–M7.4。

Commit msg: feat(spec4-M7): StageAdvance schema + ReviewDecisionHandler

M8 — StageAdvanceService 接 decision/comment + JobComment wiring

目標：service 接 decision/comment 參數；推進 BPMN 後寫 GRC JobComment；review stage 走特殊 condition_param。

Files:

• Modify: app/flow_engine/service/stage_advance_service.py：
  • advance_stage signature 加 decision: Optional[str] = None, comment: Optional[str] = None
  • 非 review stage 送 decision → log warning + pop ctx["decision"]（design §6.1）
  • _build_condition_param 加 review 分支 {"decision": "approve"|"reject"}
  • 推進 BPMN 後寫 JobComment：先查 JobExecution by template_job_id 拿 uid (UUID)，再傳給 JobCommentService.add_comment(job_uid=str(job_exec.uid), ...)
  • __init__ 加 job_comment_service dependency
• Modify: api/flow_engine/routes/stage_advance_route.py — 在 service.advance_stage(...) call 加 decision=body.get("decision"), comment=body.get("comment") kwargs；不動既有 ctx build 邏輯（保留 user_ctx.nickname 取得方式）
• Modify: di_containers/grc/grc_containers.py — stage_advance_service Factory 加 job_comment_service=job_comment_service

Critical fix 細節：原 design v1 寫 job_uid=curr_job_template.id（BPMN element id）會 silent fail；M5 spec reviewer 抓到並修進 design v1.1 §8.2。正解：

job_exec = self._job_execution_domain_service.get_job_execution(
    JobExecutionQueryEntity(
        workflow_execution_id=wf_ctx["workflow_execution_id"],
        template_job_id=curr_job_template.id,
    )
)
if job_exec is None:
    logger.warning("JobExecution not found ... skip JobComment")
else:
    self._job_comment_service.add_comment(
        job_uid=str(job_exec.uid),  # ← UUID
        content=comment.strip(),
        user_id=user_id,
        author_nickname=ctx.get("user_nickname") or curr_user,
    )

詳細 plan: implementation-plan.md §M8.1–M8.6。

Commit msg: feat(spec4-M8): StageAdvanceService 接 decision/comment + JobComment 整合

M9 — BE integration test

目標：寫 4–6 條 integration test 覆蓋 decision/comment + validate endpoint。

Files:

• Create: tests/test_stage_advance_v4.py
• Create: tests/fixtures/bpmn/invalid_start_to_poam.bpmn（inline XML，內容見 plan）

注意：implementation-plan.md §M9 提示 seed_review_ap / seed_planning_ap fixture 不易在 dev DB 上重現；若卡關可退而用 service-level unit test with mock — 對齊 Spec 3 §16.1 條 3 的 deferral pattern。重點不是 100% integration coverage，是核心路徑被測過。

Commit msg: test(spec4-M9): StageAdvance decision/comment integration tests

M10 — FE Banner + BPMN editor inline warning（跨 repo）

目標：FE 接 review approve/reject 雙按鈕 + ConfirmDialog comment textarea + editor 拖 sequenceFlow 時呼叫 /validate debounce。

Repo：~/Projects/Billows/Audit-Manager/compliance-manager-fe

Files:

• Modify: src/locales/zh-TW.json + src/locales/en.json — 加 keys（見 design §10.4）
• Modify: src/components/grc/FlowPhaseBanner.vue（沒有 banner/ 子層）— 加 review 雙按鈕 + Dialog comment textarea（同一 Dialog 共用所有 stage，靠 rejectMode flag 切換 placeholder 與 disabled 條件）
• Modify: src/service/FlowPhaseService.js（或對應 stage advance service）— advanceStage 支援 decision/comment
• Modify: src/views/flow-template/FlowTemplateEditView.vue — 加 debounced validateBpmn call + violation 紅 outline + side-panel warning list
• Modify: src/views/flow-template/components/BpmnPaletteProvider.js（或 palette config）— 加 review UserTask 預設 stencil
• New CSS: .violation-marker 紅色 stroke

詳細 plan: implementation-plan.md §M10.1–M10.7。

Commit msg: feat(spec4-fe): Banner approve/reject + BPMN editor inline warning（FE repo 自己 commit）

🛑 強烈建議 M10 開新 session（FE 跟 BE context 不要混；Vue/PrimeVue/bpmn-js 技術棧不同）

M11 — Manual smoke + BDD + changelog

目標：完整 e2e 跑通 + 寫 BDD scenario + BE/FE 各一份 changelog 收尾。

Repos：

• BE: docs/changelog/2026-05-14-feat-review-stage-flow-validator.md
• FE: 同名 changelog（FE repo）
• Test: ~/Projects/Billows/Audit-Manager/compliance-manager-test — 新 BDD scenario

Manual smoke 6 步（design §12.2）— 需要 browser 操作，subagent 做不到，必須 user 手動或 controller 帶著做。

subagent-driven-development SOP：

1. 每個 milestone 一個 implementer subagent（餵完整 task text + context；不讓 subagent 自己讀 plan）
2. Spec compliance reviewer subagent（驗實作對齊 spec）
3. Code quality reviewer subagent（驗實作品質）
4. 若 reviewer flag issue → 同 implementer 修 → re-review → 完成才標 milestone done

每個 implementer prompt 必含：

• Task description full text
• Context（working dir / branch / dependencies）
• Files (Create / Modify) 明確路徑
• Before You Begin: 提醒可發問
• Your Job 步驟條列
• Report Format（Status / files / commit SHA / self-review）

CLAUDE.md 規範必貼：

• commit 用 HEREDOC + Co-Authored-By: Claude Opus 4.7 (1M context)
• NEW commit 不用 amend（即使是 review fix）
• DO NOT push（user 還沒指示）
• SQL migration 用 cmmgr 不用 cm_app
• BE restart 必 kill -9（不是 pkill）

核心改動位置

compliance-manager-be/
├── app/flow_engine/
│   ├── service/flow_template_app_service.py   ← M5 加 validator integration
│   ├── service/stage_advance_service.py        ← M8 目標：加 decision/comment
│   └── util/bpmn_topology_validator.py         ← M3 純 function
├── api/flow_engine/
│   ├── serializers/flow_template.py            ← M6 加 validate schemas
│   ├── serializers/stage_advance.py            ← M7 目標：加 decision/comment
│   ├── routes/flow_template_route.py           ← M6 加 validate endpoint
│   └── routes/stage_advance_route.py           ← M8 目標：傳 decision/comment
├── app/grc/service/oscal_stage_handlers.py     ← M7 目標：加 ReviewDecisionHandler
├── di_containers/
│   ├── flow_engine/flow_template_containers.py ← M5 wired stage_object_domain_service
│   └── grc/grc_containers.py                   ← M7/M8 目標：wire review_decision_handler + job_comment_service
├── domain/flow_engine/entity/stage_object_entity.py  ← M2 加 4 欄
├── infra/flow_engine/
│   ├── models/stage_object.py                  ← M2 加 4 欄
│   └── mapper/stage_object_mapper.py           ← M2 加 4 欄 mapping
├── common/code/grc_error_code.py               ← M5 加 GRC_400060/061/062
├── scripts/sql/
│   ├── 2026-05-14-spec4-stage-objects-rules-and-review.sql   ← M1 migration
│   ├── 2026-05-14-spec4-builtin-flow-templates.sql           ← M4 migration
│   └── seeds/bpmn/
│       ├── builtin-full-audit.bpmn                            ← M4 patched reverse
│       └── builtin-full-audit-with-review.bpmn                ← M4 new
└── tests/test_bpmn_topology_validator.py       ← M3 unit tests (22 條)

Spec 1/2/3 既有檔（不要動，了解即可）

• app/flow_engine/service/workflow_execution_service.py:complete_main_workflow_job — M8 advance_stage 內部呼叫的 BPMN 推進方法
• app/grc/service/job_comment_service.py:add_comment(job_uid, content, user_id, author_nickname) — M8 寫 JobComment 入口（job_uid 是 UUID 不是 BPMN element id）
• infra/grc/repository/grc_job_comment_repo_impl.py:30 — filter JobExecution.uid == job_uid 驗證點

回報 user 並建議：

1. 卡 BE 啟動 → 看 log/app.log + /tmp/be*.log
2. 卡 subagent 一直跑不過 → 退到 inline 自己做（更快）
3. 卡 DB migration → 確認用 cmmgr，密碼 jedi@123!
4. design.md / plan.md 跟實作對不上 → 看 design.md §16 reconciliation 段，加新條目記偏差