Spec 4 接手指南 v2（M10 起手，FE + 收尾）

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

• 目標：spec 4 在既有 stage_object / BPMN flow template 機制上新增 review 階段 + 範本方向性驗證 + 全 stage 共用留言
• 進度：M0–M9 已完成（BE 全範圍 ship）；剩 M10 FE + M11 smoke/BDD/changelog 收尾
• branch（BE / FE / test 三 repo 都用同名）：feature/project-flow-engine-review
• 設計文件：docs/features/FR-026-2605-project-flow-engine-integrate/04-review-stage-and-flow-validation/design.md v1.3
• 實作計畫：同目錄 implementation-plan.md v1.1

Session 1（M0–M6）— 詳見 handoff-v1.md

DB schema + ORM mapping + BpmnTopologyValidator + builtin BPMN patch + POST /flow-engine/flow-templates/validate endpoint。

Session 2（M7–M9）— 本 session 產出

Session 2 重要決策軌跡（給 FE 接手時參考）

1. @validates_schema 訊息被 jedi-common 吞掉 → 業務驗證放 service 層：FE 從 /stage/advance 拿到 400 時 msg 是 generic「請求參數錯誤」，真實 error code 在 error_code 欄位（GRC_400061 / GRC_400062）。FE 顯示錯誤訊息時必須走 i18n by error_code，不要直接顯示 msg。詳見 design.md §16.2。

2. ReviewDecisionHandler silent default approve 已被 service 層先擋住：M9 test 已驗證 decision=null → GRC_400062；FE 送 advance 時若 stage 是 review 必須帶 decision，否則一定 400。

3. JobComment 寫入失敗不擋推進（M8 log enrichment fix）：BE 在 BPMN 推進成功後寫 JobComment 是 best-effort；如果寫失敗只 log warning + 帶 ap_uid / project_uid / user_id / template_job_id context，FE 在 success response 後不要假設 comment 一定寫進 DB。M11 manual smoke 需驗證 comment 列表確實顯示退回原因。

4. HTTP /validate endpoint 路徑：POST /api/1.0/flow-engine/flow-templates/validate（注意 /api/1.0 prefix；M9 test 已驗）。

M10 — FE：Banner approve/reject 雙按鈕 + ConfirmDialog comment + BPMN editor inline warning

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

切換指令：

cd ~/Projects/Billows/Audit-Manager/compliance-manager-fe
git fetch
git checkout feature/project-flow-engine-review 2>/dev/null || git checkout -b feature/project-flow-engine-review

⚠️ FE 檔名跟 plan 描述不完全一致，實際路徑（已驗）：

M10 sub-tasks：

1. M10.1 i18n keys — src/locales/zh-TW.json + en.json 加 flowEngine.validator.* + flowEngine.banner.review.*（design §10.4 / plan §M10.1）

2. M10.2 FlowPhaseBanner.vue review 階段加雙按鈕 + Dialog comment textarea

   • Submit / Reject 兩個 button
   • 共用同一個 Dialog，靠 rejectMode flag 切 placeholder + confirm-button disabled 條件
   • reject 必填 comment（trim 後不空）；approve comment 可選
   • 對 BE 送的 payload：{ decision: 'approve'|'reject', comment: '...' }
   • 詳細 template / setup code 見 plan §M10.2

3. M10.3 Service / API client — advanceStage(projectUid, apUid, payload) 支援 decision/comment

   • 必先 grep 找 stage advance 對應 service 檔（plan 寫的 FlowPhaseService.js 不存在）
   • endpoint：POST /project/<uid>/ap/<ap_uid>/stage/advance

4. M10.4 BPMN editor inline warning — FlowTemplateEditorView.vue 拖 sequenceFlow 時 debounce 500ms 呼叫 /flow-engine/flow-templates/validate

   • 用 lodash debounce
   • violations 從 envelope data.violations 取
   • /validate endpoint 一律回 200（valid + violations），不會 throw 400；FE 不需 catch error 走 fallback
   • violations[].sequence_flow_id 用來 highlight（紅色 outline）
   • 側邊欄渲染 warning list，violation reason 走 i18n key（M10.1 加的 flowEngine.validator.*）+ context interpolate
   • CSS：.djs-element.violation-marker .djs-visual > * { stroke: var(--danger-color, #dc3545) !important; }

5. M10.5 Palette 加 review UserTask 預設 stencil

   • 對齊既有 4 個 stage palette 模式
   • properties: { stage_object_code: 'review', main_role: 'reviewer' }

6. M10.6 FE smoke 3 項（要實際開瀏覽器 + BE 起來 + DB 有 spec 4 seed）

   • 建專案選「完整稽核流程（含審核）」→ review banner 顯示雙按鈕
   • BPMN editor 拖違規 sequenceFlow → 側邊欄出現 warning
   • reject 不填 comment → confirm 按鈕 disabled

7. M10.7 Commit FE

   • HEREDOC + Co-Authored-By: Claude Opus 4.7 (1M context)
   • explicit git add（不 -A / -am）

Commit msg 範本：見 plan §M10.7（line 2292）

M11 — Manual smoke + 跨 repo BDD + changelog（收尾）

三 repo 都要動：

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

M11.1 Manual smoke 6 步（design §12.2）— 需 user 操作瀏覽器，subagent 做不到：

1. 建專案選「完整稽核流程（含審核）」→ AP1 走 planning → task_execution → review
2. reviewer 在 review banner 按「退回」+ 寫退回原因 → 確認 BPMN 回 task_execution、JobComment 可見
3. PM 重新走 task_execution → review，reviewer 「送出審核」approve → 確認走到 audit
4. 走完 audit → 缺失 → poam → audit → 無缺失 → End
5. 同專案 launch_new_round 切回「完整稽核流程」（無 review）→ 確認 AP2 走原本 4-stage 流程，行為與 Spec 2 ship 一致
6. 範本管理頁拖 sequenceFlow 從 Gateway 指向 poam → 確認側邊欄即時警告 + 畫布紅框；強制存檔 → BE 回 400

M11.2 BDD scenario（compliance-manager-test repo）

• Feature file: features/flow-engine-review/review-stage.feature
• 對應 step definition + page object（mirror 既有 banner BDD pattern）
• 跑：npm run test:bdd -- --tags @flow-engine-review

M11.3 Changelog（BE + FE 各一份；test repo 不需 changelog）

• type: feat, breaking: false, modules: [flow-engine, grc]
• 結構見 plan §M11.3（line 2364）

M11.4 最終 summary（CLAUDE.md「做 summary」流程）

• 盤點 BE + FE + jedi-* + test 全 case commits
• 文件齊全度 audit：changelog / issue / analysis 缺什麼補什麼
• 對話紀錄歸檔到 docs/conversation-history/2026-05-13-review-stage-and-flow-validation/part-NN-of-NN-*.md（按 phase 拆 part）
• 產出 SUMMARY.md（含 commits 清單 / 改動範圍 / 行為差異 / 規範文件清單 / 已知 follow-up / 部署 handover）
• design.md §16 reconciliation 段：M10 + M11 期間若有偏離，追加新條目（目前 §16.1 + §16.2 已記）

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: 提醒可發問（特別是 FE 檔名 fallback）
• Your Job 步驟條列
• Report Format（Status / files / commit SHA / self-review）

CLAUDE.md 規範必貼（兩 repo 都要遵守）：

• commit 用 HEREDOC + Co-Authored-By: Claude Opus 4.7 (1M context)
• NEW commit 不用 amend（即使是 review fix）
• DO NOT push（user 還沒指示）
• explicit git add 檔名，不用 -A / -am（CLAUDE.md 反覆強調；BE working tree 有 2 個未追蹤 SQL 不該掃進）

POST /api/1.0/project//ap/<ap_uid>/stage/advance

Request body（M7 + M8 加的欄位）：

{
  "force": false,
  "decision": "approve" | "reject" | null,
  "comment": "...string..." | null,
  "ctx": {}
}

Response（success / failure 都用既有 envelope）：

• 200 success：{ "status": true, "data": { "advanced": true, "handler_result": {...}, "current_stage_info": {...} } }
• 400 業務驗證失敗：{ "status": false, "error_code": "GRC_400061" | "GRC_400062", "msg": "..." }（msg 是 generic「請求參數錯誤」，FE 必須用 error_code 走 i18n）

Error code 對照（FE 必加 i18n）：

非 review stage 送 decision → BE 不擋，靜默 ignore + log warning（不影響 FE）。

POST /api/1.0/flow-engine/flow-templates/validate

純驗證 endpoint，一律回 200：

Request:

{ "bpmn_xml": "<bpmn:definitions>...</bpmn:definitions>" }

Response:

{
  "status": true,
  "data": {
    "valid": true | false,
    "violations": [
      {
        "rule": "successor_not_allowed" | "start_stage_not_allowed" | "end_stage_not_allowed" | "unknown_stage_code" | "gateway_missing_condition" | "unreachable_node" | "no_end_path",
        "reason_i18n_key": "flowEngine.validator.successor_not_allowed",
        "context": {
          "sequence_flow_id": "Flow_xxx",       // 部分 rule 帶
          "source_stage": "audit",              // successor_not_allowed
          "target_stage": "poam",
          "stage": "poam",                      // start_/end_stage_not_allowed
          "code": "xxx",                        // unknown_stage_code
          "gateway_id": "Gateway_xxx",          // gateway_missing_condition
          "node_id": "Flow_xxx"                 // unreachable_node
        }
      }
    ]
  }
}

/validate 不會 throw 400/500（除非 BPMN 完全無法 parse）；FE 不需 catch error 走 fallback path，只要看 data.valid 與 data.violations 即可。

POST /api/1.0/flow-engine/flow-templates（create / update）

加上 topology 守門員。違規回 400 with error_code = GRC_400060，但 violations 細節不在 response（design §16.1 reconciliation：err.context 被 jedi-common 吞掉）。

FE 設計建議：存檔前先呼叫 /validate 拿 violations，UI 顯示；user 確認 OK 才送 create/update。若 BE 仍回 400（race condition / direct API call），FE 把 GRC_400060 對應到 generic「流程結構不合法，請開啟編輯器查看詳情」訊息。

BE 已 ship 範圍（M0–M9，不要再動）

compliance-manager-be/
├── 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 kwargs
├── app/flow_engine/
│   ├── service/flow_template_app_service.py   ← M5 validator integration
│   ├── service/stage_advance_service.py        ← M7+M8 加 decision/comment + JobComment
│   └── util/bpmn_topology_validator.py         ← M3 純 function
├── 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
│       └── builtin-full-audit-with-review.bpmn                ← M4 new
├── tests/test_bpmn_topology_validator.py       ← M3 22 條
├── tests/test_stage_advance_service_v4.py      ← M9 5 條 service-level mock
├── tests/test_flow_template_validate_endpoint.py ← M9 HTTP smoke
└── tests/fixtures/bpmn/invalid_start_to_poam.bpmn ← M9 fail-case fixture

FE 待做範圍（M10）

compliance-manager-fe/
├── src/locales/
│   ├── zh-TW.json                              ← M10.1 加 flowEngine.validator.* + banner.review.*
│   └── en.json                                 ← M10.1 對應
├── src/components/grc/FlowPhaseBanner.vue      ← M10.2 雙按鈕 + Dialog comment
├── src/views/flow-template/
│   ├── FlowTemplateEditorView.vue              ← M10.4 debounced /validate + violation outline
│   └── （palette 位置 implementer ls 確認）    ← M10.5 review UserTask stencil
└── src/service/?                                ← M10.3 advanceStage(decision/comment)
                                                    （路徑 implementer grep `advanceStage|stage/advance` 確認）

測試 repo 待做範圍（M11）

compliance-manager-test/
└── features/flow-engine-review/
    ├── review-stage.feature                    ← M11.2 BDD scenario
    └── （對應 step definition + page object）

回報 user 並建議：

1. 卡 FE component 結構 → 看既有 FlowPhaseBanner.vue 其他 stage 怎麼處理，mirror 模式
2. 卡 axios error envelope → 對齊 BE response 結構（envelope { status, error_code, msg, data }）
3. 卡 bpmn-js 事件 / canvas marker API → 看 FlowTemplateEditorView.vue 既有 commandStack 監聽，沿用既有 modeler 物件
4. design.md / plan.md 跟實作對不上 → 看 design.md §16 reconciliation 段，加新條目記偏差（v1.4 開頭）