Spec 3：AP 套用流程

狀態：v2 — brainstorm 收斂後完整版，待 review 整體脈絡：../README.md 依賴：Spec 1（已 ship）/ Spec 2（已 ship）

建立新 AP 時 user 可挑選流程範本；AP 建立同時 snapshot clone 該範本 BPMN 到該 AP 專屬的 workflow_execution。後續範本被改 / 刪不影響進行中 AP；多 AP 之間流程獨立運作；未來可開放「中途調整 AP 自己的流程」也不會污染兄弟 AP 或 master。

審核 Spec 2 落地時發現的重要事實：

• start_oscal_project:487 已呼叫 _bind_main_workflow_to_ap → 第一輪 AP 有 snapshot + assessment_plan_extensions + main workflow_execution
• launch_new_round 從未呼叫該 helper → 後續輪 AP 沒綁 main workflow，Banner 找不到 stage → 推進按鈕永遠 disabled

→ Spec 3 不只是「加 dropdown + 把 hardcode 換成 parameter」，還要把 main workflow snapshot 整段 helper 邏輯接上 launch_new_round。

這同時是 Phase E launchProjectViaUi / launchAuditViaUi 系列 fixture 撞 disabled button 的潛在根因（fixture 是新一輪 flow 上跑的）。

來源：requirement.md §「想法（粗略）」§3

1. 建專案時 user 選流程範本，帶到自動建立的第一輪 AP
2. 稽核計畫頁建新一輪 AP 時 user 選流程範本（default 帶最新一輪 master）
3. AP 建立同時 snapshot clone 範本 BPMN 到該 AP 專屬 workflow_execution
4. 後續範本被修改 / 刪除不影響進行中 AP（snapshot 不可變）
5. 多 AP 之間流程互不影響（snapshot per-AP）

In scope

• BE start_oscal_project 簽章加 flow_template_uid: str (required)
• BE launch_new_round 簽章加 flow_template_uid: str (required) + 補做 main workflow snapshot
• BE _bind_main_workflow_to_ap 改為接 flow_template_uid 必填（拔 default lookup）
• BE 拔除 FlowTemplateDomainService.DEFAULT_MAIN_WORKFLOW_TEMPLATE_NAME / get_default_main_workflow_template()
• BE AP 詳情 API 補回 flow_template enrichment（snapshot uid / master uid / master name）
• BE error code 整理：刪 GRC_FLOW_MAIN_TEMPLATE_NOT_FOUND（412022）；reuse 既有 GRC_FLOW_TEMPLATE_NOT_FOUND（404027）
• FE ProjectCreateView 加流程範本 dropdown + 預覽 Dialog
• FE ProjectApListView「新增稽核計畫」Dialog 加流程範本 dropdown + default 帶值邏輯
• FE i18n（zh-tw / en）

Out of scope

• 範本管理 UI（→ Spec 1，已 ship）
• Stage 推進 runtime（→ Spec 2，已 ship）
• 中途調整 AP 流程 UI（未來 spec）
• Overview shell 化重構（Banner 已在 Spec 2 掛好）
• Stage progress bar 互動跳轉（v1 純預覽，Spec 2 已處理）
• 範本按合規資源庫過濾（Q1 YAGNI）
• 跨 tenant 範本共享（v1 純 tenant 隔離；RLS 自動處理）

兩處共用同一個「流程範本 dropdown + 📋 詳細選擇」UX，預覽元件 reuse Spec 1 FlowTemplatePreviewDialog.vue。

建專案 / 建後續輪 AP（任一入口）
  ↓ (使用者選範本 uid)
flow_template_uid (UUID, required) ──┐
                                     ▼
start_oscal_project / launch_new_round
                                     │
                                     ▼
_bind_main_workflow_to_ap(ap, project_uid, flow_template_uid, curr_user)
                                     │
                ┌────────────────────┴────────────────────┐
                ▼                                         ▼
  FlowTemplateDomainService                  GRC_FLOW_TEMPLATE_NOT_FOUND
    .get_by_uid(flow_template_uid)           （uid 不存在 / is_active=false）
                │
                ▼
  master (FlowTemplateEntity)
                │
                ▼
  WorkflowTemplateSnapshotService.clone_master_as_snapshot(
    master_uid=master.uid,
    master_name=master.name,
    xml=master.bpmn_xml,
    description=master.description,
    curr_user=curr_user,
  )
                │
                ▼
  snapshot (engine `public.workflow_templates`，per-AP immutable）
                │
                ▼
  workflow_execution_service.start_workflow_execution(template_id=snapshot.id, ...)
                │
                ▼
  main_wf (engine `workflow_executions`)
                │
                ▼
  ap_extension_domain_service.upsert(
    assessment_plan_id=ap.id,
    workflow_execution_uid=main_wf.uid,
    flow_template_snapshot_uid=snapshot.uid,
    curr_user=curr_user,
  )
                │
                ▼
  assessment_plan_extensions row written
                │
                ▼
  AP 詳情 API enrichment ◀── 從 ext 反查 snapshot → 反查 master → 三段組合回傳

9.1 OscalProjectService.start_oscal_project

@transaction
def start_oscal_project(
    self,
    project_name,
    ...既有參數...,
    flow_template_uid: str,         # 新增，必填
    curr_user: str = None,
    locale: str = None,
) -> Project:
    ...既有 21 個 step 不動...

    # Step 22 改造：把 flow_template_uid 顯式傳入
    self._bind_main_workflow_to_ap(
        ap=ap,
        project_uid=str(project.uid),
        flow_template_uid=flow_template_uid,
        curr_user=curr_user,
    )
    return project

9.2 OscalProjectService.launch_new_round

@transaction
def launch_new_round(
    self,
    project_uid: str,
    user_id: int,
    title: str,
    flow_template_uid: str,         # 新增，必填
    start_date=None, end_date=None,
    curr_user: str = None,
    locale: str = None,
) -> dict:
    ...既有 step 1–9 不動（含 sub-workflow per-task clone，跟 main 不衝突）...

    # 新增 step 10：補做 main workflow snapshot（Spec 2 的 gap）
    self._bind_main_workflow_to_ap(
        ap=ap,
        project_uid=str(project_entity.uid),
        flow_template_uid=flow_template_uid,
        curr_user=curr_user,
    )

    return {...既有...}

9.3 _bind_main_workflow_to_ap 改造

def _bind_main_workflow_to_ap(
    self,
    ap,
    project_uid: str,
    flow_template_uid: str,         # 新增，必填
    curr_user: str,
) -> None:
    """Spec 3 — 接 caller 指定的 flow_template_uid，clone 一份 per-AP 凍結 snapshot
    到 engine 表，啟動 workflow_execution，寫 assessment_plan_extensions。

    Caller 已開 @transaction scope，本 helper 不再加。
    """
    if (self._flow_template_domain_service is None
            or self._ap_extension_domain_service is None
            or self._workflow_template_snapshot_service is None):
        raise PreconditionFailedError(GrcErrorCode.GRC_FLOW_TEMPLATE_NOT_FOUND)

    master = self._flow_template_domain_service.get_by_uid(flow_template_uid)
    if master is None or not master.is_active:
        raise NotFound(GrcErrorCode.GRC_FLOW_TEMPLATE_NOT_FOUND)

    snapshot = self._workflow_template_snapshot_service.clone_master_as_snapshot(
        master_uid=str(master.uid),
        master_name=master.name,
        xml=master.bpmn_xml,
        description=master.description,
        curr_user=curr_user,
    )
    main_wf = self.workflow_execution_service.start_workflow_execution(
        template_id=snapshot.id,
        name=f"AP-{ap.uid}-main",
        params={"ap_uid": str(ap.uid), "project_uid": project_uid},
        created_user=curr_user,
        description=f"AP main workflow for {ap.title}",
    )
    self._ap_extension_domain_service.upsert(
        assessment_plan_id=ap.id,
        workflow_execution_uid=str(main_wf.uid),
        flow_template_snapshot_uid=str(snapshot.uid),
        curr_user=curr_user,
    )

9.4 拔除 Spec 2 過渡 hardcode

domain/flow_engine/service/flow_template_domain_service.py：

# 全部移除
# DEFAULT_MAIN_WORKFLOW_TEMPLATE_NAME = "完整稽核流程"
# def get_default_main_workflow_template(self) -> Optional[FlowTemplateEntity]: ...

IFlowTemplateRepo.get_builtin_by_name() — grep 確認無其他 caller 即刪。

9.5 Route schema 改動

9.6 AP enrichment（list + detail）

兩個 endpoint 都要回 flow_template enrichment：

• GET /grc/project/<uid>/aps（列表）— FE default 帶值靠這個，必須有
• GET /grc/project/<uid>/aps/<apUid>（詳情）— FE 顯示「目前用的範本」靠這個

Response 加欄位：

{
  ...既有欄位...,
  "flow_template": {
    "snapshot_uid":     "engine-snapshot-uid",
    "master_uid":       "compliance-master-uid",
    "master_name":      "完整稽核流程",
    "is_master_active": true
  }
}

Enrichment path（app service 層）：

1. 取 assessment_plan_extensions by assessment_plan_id → flow_template_snapshot_uid
2. 用 snapshot uid 取 engine workflow_templates row → source_template_uid
3. 用 master uid 取 compliance.flow_templates row → name + is_active

Enrichment 行為（lenient）：若任一段缺失（舊資料 ext 不存在 / master 已硬刪等 edge case），flow_template 回 null，不擋 API 回應。is_master_active=false 代表 master 已軟刪但 snapshot 仍正常運作（這 AP 還能跑完現有 lifecycle）。

對比 — 建立路徑（strict，見 §十一）：建 AP 時 master.is_active=False 直接 404 拒絕。語意：「進行中 AP 容忍 master 被刪、但新 AP 不能選已刪的 master」。

列表 enrichment 效能考量：列表 enrichment 會 N+1 — N AP × 3 段 query。實作要用 batch query：一次取所有 ext rows → 一次 batch 取 snapshot rows → 一次 batch 取 master rows，三段 dict join 完拼 response。

9.6.1 取代既有 workflow_template_uid 欄位（注意：清掉 §906）

launch_new_round 既有程式碼（line 906–924）對 task 動態 setattr task.workflow_template_uid — 那是 sub-workflow per-task 的 template uid，跟本 spec 加的 main workflow flow_template 是不同層級。保留，不衝突。但 §9.6 enrichment 必須清楚標 flow_template 是 main workflow（AP 級別），跟 task-level sub-workflow 分開不混淆。

9.7 Error code

10.1 ProjectCreateView.vue

加在「基本資訊」step（建議 Step 0 末尾）：

基本資訊
├── 專案名稱 *
├── 描述
├── 合規資源庫 *
├── 第一輪稽核計畫流程範本 *    ← 新增
│   ├── <Dropdown
│   │     v-model="form.flowTemplateUid"
│   │     :options="flowTemplates"
│   │     optionLabel="name"
│   │     optionValue="uid"
│   │     :loading="loading"
│   │     :class="{'p-invalid': v$.flowTemplateUid.$error}" />
│   └── <Button text size="small" @click="openPreview">📋 詳細選擇</Button>
└── ...

10.2 ProjectApListView.vue 新增稽核計畫 Dialog

新增稽核計畫
├── 計畫名稱 *
├── 起訖日期
├── 流程範本 *                  ← 新增
│   ├── <Dropdown ... v-model="form.flowTemplateUid" />
│   └── <Button text>📋 詳細選擇</Button>
└── ...

Default 帶值（依賴 §9.6 — AP 列表 API 必須含 flow_template enrichment）：

const defaultFlowTemplateUid = computed(() => {
  // apList 排序：最新一輪在 [0]（既有排序慣例，新 spec 不改）
  // 依賴 GET /grc/project/<uid>/aps 回 flow_template enrichment
  const latest = props.apList?.[0]
  return latest?.flow_template?.master_uid ?? null
})

watch(() => props.visible, (v) => {
  if (v) form.value.flowTemplateUid = defaultFlowTemplateUid.value
})

注意： 若 §9.6 列表 enrichment 未實作，dropdown default 會永遠 null，user 每次都要重選。列表 enrichment 是 dropdown UX 的硬依賴，不能延後到 v2 補。

10.3 預覽 Dialog reuse

<FlowTemplatePreviewDialog
  v-model:visible="previewVisible"
  :template-uid="form.flowTemplateUid"
/>

Spec 1 已 ship src/views/flow-template/components/FlowTemplatePreviewDialog.vue — input 是 master uid，內部自己拉 detail + render BPMN + 列階段清單。

10.4 Service / API client

src/service/FlowTemplateService.js（Spec 1 已有 list / detail），新增方法可直接 reuse。

10.5 i18n

zh-tw：

project:
  flowTemplate:
    label: 流程範本
    firstRoundLabel: 第一輪稽核計畫流程範本
    placeholder: 請選擇流程範本
    detailBtn: 詳細選擇
    requiredError: 請選擇流程範本
    inheritedHint: 預設沿用上一輪稽核計畫的流程範本

en 對應 key 一併補。

12.1 BE pytest

順手補 Spec 2 carry-forward test gap（同 commit 或鄰近 commit）：

• WorkflowTemplateSnapshotService — clone 行為 unit test
• StageAdvanceService — stage 推進 path unit test
• oscal_stage_preconditions — precondition function 個別 unit test
• oscal_stage_handlers — handler 個別 unit test
• AssessmentPlanExtensionRepoImpl — upsert / 查詢 unit test

12.2 FE E2E（compliance-manager-test）

留到 Spec 3 BE+FE 都 ship 後 — 跟 Phase E 4 fixture bug 一起重做：

• 修 ProjectCreatePage.addFourParticipantsWithRoles（適配 wizard step 數變化 + 新增範本 dropdown）
• 修 launchProjectViaUi / launchAuditViaUi / launchRemediationViaUi
• 重寫 Spec 2 Banner 3 個 scenario（adapt 新範本選擇 UI）

12.3 Manual smoke（必過項）

□ 建專案選範本 A「完整稽核流程」→ 第一輪 AP1
  └ Banner 顯示 stage = 規劃 → 推進按鈕作用 → status preparing→active
  └ 連續推完 4 個 stage 到 closed
□ 同專案 launch_new_round 選範本 B「自我評估稽核」（少 poam）
  └ AP2 snapshot uid 跟 AP1 不同
  └ Banner stage 組合對應 B 的 BPMN（規劃→執行→稽核→closed，跳 poam）
  └ 推到 audit 完成後直接 closed
□ DB 驗：
  - assessment_plan_extensions 兩列，flow_template_snapshot_uid 不同
  - public.workflow_templates 兩列 snapshot row，source_template_uid 對應 A/B master
  - 兩個 workflow_execution 互不影響
□ Smoke 通不過 → 根因落 Spec 2 stage_advance_service / oscal_stage_handlers
  → 此時補 Spec 2 carry-forward 5 service test gap 是必做（不再延後）

M3/M4 順序理由：M4 改 _bind_main_workflow_to_ap + 拔 get_default_main_workflow_template 會影響 StageAdvanceService / WorkflowTemplateSnapshotService 等 carry-forward 服務。先 M3 補測試，再做 M4 改動，M4 出 regression 時 test 立刻 fail，不會拖到 M7 smoke 才發現。

v1 列的 5 個 open questions 全部 resolved（見 §二）。

v2 沒有新增 open question — 進入 Phase 3 implementation-plan.md 階段。

Phase 5 實作 + M7 smoke + Phase 6 review 後，下列為實作偏離 v2.1 plan 的條目。記錄目的：給未來讀者保留決策軌跡，不是補救。

16.1 Plan 偏差

16.2 M7 smoke 發現的 Spec 2 carry-forward bug（M9–M13）

16.3 §11 strict-vs-lenient 行為對比實際落地

16.4 v3 已知 follow-up（不影響 ship）

整理自 Phase 6 review docs/issues/pending/2026-05-13-spec3-phase-6-followups.md：

16.5 Spec plugin 化討論

User Phase 5 + smoke 收尾後提出「stage 物件能否 plugin 化」討論，當前不做，紀錄在 docs/analysis/2026-05-13-stage-plugin-architecture-thoughts.md。3 個 phase（FE button config / StagePlugin 整合 / auto-discovery）+ 觸發條件已記錄。