↑ 需求首頁 ⌂ 需求中心

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

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

§1

〇、起手語（直接複製給新 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 / 部署決策。

§2

一、當前 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 不同步狀態）
§3

二、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 部署決策
§4

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

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 需求）
§5

四、必讀文件索引

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）
§6

五、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
§7

六、行為決策反悔條件

決策 反悔條件 / 觸發點
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 需求
§8

七、開發環境 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 除非要動套件
§9

八、踩坑提醒

從本次 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 修
§10

九、本次 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）
§11

十、推薦明天起手 prompt

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

§12

文件版本

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