FR-051 實作計畫 — 規劃階段推進前置檢核

依 docs/features/FR-051-2607-planning-advance-prechecks/design.md。 跨 repo：BE（compliance-manager-be）+ FE（compliance-manager-fe）。E2E 後補（Phase 4 test-plan）。 只規劃不實作——本檔為 plan，user approve 後才進 Phase 5。

• DDD 層級：Route 不查 DB（本案不新增 route）；App/handler 層透過 domain service；新 count_incomplete_prep_jobs 只在 infra repo 寫 SQL。
• @transaction：checker 為 helper，不加 @transaction（caller advance_stage 已開 scope）；docstring 標「caller 須在 @transaction scope」。
• Repo session lazy：新 count 方法掛既有 grc_project_repo_impl（已 @property session / get_session()）。
• 權限：不新增權限碼；沿用 advance_stage 既有 manager/main_role + force=manager 守門。
• 前置條件：疊加在 launch_audit 既有前置（status=planning / living_ssp）之前，不改既有。
• Error code：不新增（走 warning，非 error）。i18n key 走 flow_engine.readiness.* 同族。
• 不重複造輪子：檢核 A reuse get_ap_dashboard 同 JOIN；檢核 B 用既有 BpmnUtils + ProjectParticipantDomainService。
• BE→FE i18n 同步：新增 3 語（en/tw/cn）warning key。
• 顯式 git add，禁 -am；不切 branch；push 等 user 明示。

BE：

1. 抽 1~2 份真實主流程模板 XML（DEV DB workflow_templates.xml 或資源庫），確認 userTask main_role 值域 == ParticipantRole 值（manager/auditor/reviewer/viewer）。
   • 若不符（存 stage 角色碼）→ 在 checker 加 normalize map，並在此 plan 補一列。
2. 讀 advance_stage line 366-378 halt 分支，確認 handler_result（含新增 reasons）原樣回 FE，無 schema 白名單過濾。
3. 確認 count_incomplete_prep_jobs 的「本輪 vs 專案」scope（design §8.2）——首輪按專案全部 in-scope prep-job，多輪列 follow-up。

輸出：Step 0 結論寫一段到本檔末「Step 0 查證結果」，再開工。

Task B1 — domain count 方法（檢核 A 資料源）〔≤0.5d〕

• infra/grc/repository/grc_project_repo_impl.py：新增 count_incomplete_prep_jobs(project_uid) -> int，reuse get_ap_dashboard 的 JOIN，COUNT(*) FILTER (WHERE je.status != COMPLETED AND je.type=USER)。
• domain/grc/service/grc_project_domain_service.py + repo interface：加對應 abstract + 委派。
• 驗：pytest 直接對 DEV 種子專案跑，比對 get_ap_dashboard 的 not_started+in_progress 一致。

Task B2 — PlanningReadinessChecker（新檔）〔0.5d〕

• 新 app/grc/service/planning_readiness_checker.py：

  class PlanningReadinessChecker:
      def __init__(self, grc_project_domain_service, project_participant_domain_service,
                   audit_round_domain_service, workflow_execution_domain_service): ...
      def check(self, round_uid, project_uid) -> list[dict]:
          """回 [{code, context}]；caller 須在 @transaction scope。fail-open：任一子檢查
          取不到資料 → skip 該項 + log warning，不阻推進。"""

  • 檢核 A：n = count_incomplete_prep_jobs(project_uid)；n>0 → append {"code":"planning_prep_jobs_incomplete","context":{"count":n}}。
  • 檢核 B：取本輪主流程 XML（audit_round → workflow_execution.workflow_template_xml）→ BpmnUtils(xml).jobs 收 main_role（split ","）去重 → required_roles；participant_roles = {p.role for p in participants}；missing = required - participant；非空 → append {"code":"planning_roles_unassigned","context":{"roles":sorted(missing)}}。
• DI：di_containers/ grc container 註冊 checker（注入上述 4 domain service），注入進 LaunchAuditOnCompleteHandler。
• 驗：unit test 三情境（都通過 / 只缺 job / 只缺角色 / 兩者皆缺）。

Task B3 — 掛進 LaunchAuditOnCompleteHandler〔0.25d〕

• app/grc/service/oscal_stage_handlers.py::LaunchAuditOnCompleteHandler：
  • __init__ 多注入 planning_readiness_checker。
  • execute：force = bool((ctx or {}).get("force"))；if not force: warnings = checker.check(round_uid, project_uid); if warnings: return {"warning":"planning_readiness","reasons":warnings}；否則照舊 launch_audit。
• ⚠️ 守住 design §7 前提（review 調整 2）：advance_stage 在 not force 時 precondition 先於 handler 跑（stage_advance_service.py:313-331）。planning 的 precondition RoundPrepTasksDoneCheck 必須維持 lenient（不能改嚴）——否則會在 handler warning 之前先硬擋，破壞「confirm 放行」語意。檢查全放 handler warning 層，precondition 一行都不動。
• 驗：advance_stage 整合 test — force=false 有 warning → 回 {"advanced":false, handler_result.reasons=[...]}、BPMN 未推進；force=true → 正常推進。注意 test 必 patch logger（memory feedback_test_logger_patch_db_handler）。

Task B4 — BE 端 i18n / 常數〔0.1d〕

• warning code 常數集中（如 common/enum 或 checker 內常數），確保與 FE i18n key 對得上。

Task F1 — useStageInfo 透出 reasons〔0.25d〕

• src/composables/useStageInfo.js::advance：BE handler_result.reasons 透到回傳 result.reasons（現只透 needsConfirmation/warningMessage）。

Task F2 — FlowPhaseBanner 聚合彌窗〔0.5d〕

• src/components/grc/FlowPhaseBanner.vue::doAdvance 的 needsConfirmation 分支（review 確認 :442-450 存在、accept 帶 force:true 重打）：
  • ⚠️ 必保留無-reasons fallback（review 調整 1）：新 warning shape 是 {"warning":"planning_readiness","reasons":[...]}，沒有 message key。F2 邏輯 =「result.reasons 有值 → 聚合渲染；否則走既有 warningMessage / default_message fallback」。不可只寫 reasons 分支——要保住其他 handler 未來回單句 warning（如既有 launch_audit incomplete_tasks 提示）的契約不被破壞。
  • reasons 有值時：逐條 map 成訊息（planning_prep_jobs_incomplete → t('lang.flow_engine.readiness.prep_jobs_incomplete', {count})；planning_roles_unassigned → t('...roles_unassigned', {roles: roles.map(r=>t('lang.grc_participants.role_'+r)).join('、')})）→ 換行/列表聚合成 message。
  • ConfirmDialog header/accept/reject 用 lang.flow_engine.readiness.confirm_*。
  • accept → doAdvance({...payload, force:true})（既有）。
• 兩頁自動涵蓋：ProjectPlanningView / ProjectAuditorOverview 都嵌 Banner，零額外改。

Task F3 — i18n key（3 語）〔0.15d〕

• src/config/locales/i18n/{en,tw,cn}/（對應 flow_engine 檔）新增：
  • flow_engine.readiness.prep_jobs_incomplete（還有 {count} 個規劃階段任務尚未完成）
  • flow_engine.readiness.roles_unassigned（流程需要「{roles}」角色，但專案參與人員尚未指派，流程可能無法進行）
  • flow_engine.readiness.confirm_header / confirm_accept（仍要推進）/ confirm_reject（取消）
• 確認 grc_participants.role_auditor / role_reviewer 等既有角色譯名存在（無則補）。

Step 0 查證
   ↓
B1(count) → B2(checker，依 B1) → B3(掛 handler，依 B2) → B4(BE i18n 常數)
   ↓（BE pytest 綠）
F1(useStageInfo) → F2(Banner 彌窗，依 F1) → F3(FE i18n)
   ↓
manual smoke（規劃頁 + 總覽頁，both）→ Phase 4 test-plan → E2E

• B1~B4 可先於 FE；FE F1→F2 有序，F3 可並行。
• 回滾：每 Task 一 commit，可獨立 revert（B3 是唯一改既有行為點，revert 即恢復無檢核）。

• BE pytest：checker 四情境 + advance 整合（force true/false）全綠。
• 規劃頁 & 總覽頁 manual smoke：缺 job / 缺角色 / 兩者 → 聚合彌窗正確列出；confirm 放行後正常推進；取消不變。
• 都通過時不跳彌窗（既有二次確認仍在）。
• i18n 三語無 raw key。

2026-07-21 首腦 review 已預驗銷掉三項中的兩項，Step 0 剩一項必做。

✅ 已預驗銷掉（不用重做）：

• Step 0-2 handler_result 透出鏈 ✅：advance_stage halt 分支（stage_advance_service.py:366-378）原樣回整個 handler_result；route 序列化 StageAdvanceResponseSchema.handler_result = fields.Dict(allow_none=True)（api/flow_engine/serializers/stage_advance.py:73），Dict 不濾 key → 新增 reasons 可原樣到 FE。
• force 從 ctx 讀 ✅：advance_stage 開頭已有 ctx.setdefault("force", force)，handler execute(ctx=ctx) 拿得到 → B3 寫法（force = bool(ctx.get("force"))）成立。
• FE 掛點 ✅：useStageInfo.js:67-73 / FlowPhaseBanner.vue:442-450 needsConfirmation 分支存在、accept 帶 force:true 重打 → F1/F2 落點正確。

✅ Step 0-1 main_role 值域（2026-07-21 已驗，live DEV DB）：

• seed 檔（scripts/sql/seeds/bpmn/builtin-*.bpmn）：main_role ∈ {manager, auditor, reviewer}。
• live DEV DB compliance.flow_templates.bpmn_xml（含專案 cloned 模板，11/12 模板有 main_role）distinct 值域 + 筆數：manager×21 / reviewer×11 / auditor×6。
• 結論：值域 == ParticipantRole（manager/auditor/reviewer），全部合法。viewer 從不作 main_role（合理，觀察者不驅動階段）→ checker 不需 normalize map，B2 檢核 B 直接 set 相減即可。

⏳ Step 0-3（設計已定，無需驗）：首輪按專案全量 prep-job，多輪情境列 follow-up。

→ Step 0 全數清空，可進 Phase 5 實作。