Spec 1 流程範本管理 — FE 接手文件

BE 狀態：完成，branch feature/project-flow-engine-integrate 適用 session：compliance-manager-fe repo 的 FE engineer

• 左側選單「流程範本管理」入口（受 RBAC flow_template.read 控制）
• 範本列表頁（DataTable + 「內建 / 自訂」filter + name 搜尋 + 分頁）
• 範本編輯頁（BPMN editor + UserTask 屬性面板：階段物件下拉 + 主要角色單選 + 完整 ExclusiveGateway 編輯支援）
• 範本預覽 Dialog（唯讀 BPMN renderer + UserTask 列表）
• 「複製為自訂」按鈕（builtin 範本可點，跳 Dialog 輸入新名稱）

Response envelope：{"status": true/false, "data": {...}}（注意：FE 既有 BaseService 應已處理；不是 {"code": 1}）

Decision C 鎖定（§八 開放問題）：v1 完整 Gateway 編輯

• 編輯器 palette 含：StartEvent / EndEvent / UserTask / ExclusiveGateway / SequenceFlow
• 不需要 ServiceTask / ParallelGateway / CallActivity（Spec 1 範圍）
• UserTask 屬性面板必欄：
  • 「階段物件」下拉 — 選項來自 GET /flow-engine/stage-objects，顯示 name（i18n resolved），值為 code，落到 BPMN extensionElements > camunda:properties > camunda:property[name=stage_object_code,value=<code>]
  • 「主要角色」單選 — manager / reviewer / auditor / viewer，落到 camunda:property[name=main_role,value=<role>]
• Gateway 屬性面板：
  • 「閘道名稱」必填
  • 兩個 outgoing flow 可分別編輯：name（如「有缺失」/「無缺失」）+ conditionExpression（${has_findings == true} 等簡單表達式）+ default flag
• 工具列：「儲存」/「另存為新範本」/「預覽」/「離開」按鈕；存檔前 client-side validate（必須有 StartEvent / EndEvent / >=1 UserTask；每個 UserTask 必須選階段物件）

內建 builtin 範本參考

3 個 builtin XML 在 BE repo scripts/sql/seeds/bpmn/builtin-*.bpmn，可作為 FE 編輯器渲染的對照範本：

• builtin-internal-check（簡單線性，2 UserTask）
• builtin-self-assessment（線性，3 UserTask）
• builtin-full-audit（含 ExclusiveGateway loop back：audit → Gateway →（有缺失）poam → audit /（無缺失）End）

i18n key：flow-template-manage — 在 FE src/config/locales/i18n/zh-tw/menu.json 與 en/menu.json 補：

{
  "flow-template-manage": "流程範本管理"
}

{
  "flow-template-manage": "Flow Template Management"
}

對應 FE route 在 src/router/index.js：路徑 /flow/template-manage（與 BE migration 一致），icon pi-sitemap。

需在 FE src/config/locales/errorCode.json（或對應檔案）補：

依 user 從 web-menu API 取得的 capabilities：

• flow_template.create 缺：列表頁的「新增 / 複製為自訂」按鈕 disable
• flow_template.update 缺：列表頁的「編輯」按鈕 disable（同時編輯頁打開時禁止存檔）
• flow_template.delete 缺：列表頁的「刪除」按鈕 disable

builtin 範本一律：編輯 / 刪除按鈕 disable，但「複製為自訂」可用；預覽永遠可用。

• DataTable cols：名稱 / 描述 / 內建 or 自訂 / 建立時間 / 更新時間 / 建立者（顯示 nickname created_user_name）/ 操作
• Filter：top bar 一個 ToggleButton group「全部 / 內建 / 自訂」（對應 query is_builtin undefined / true / false）
• Search：name 模糊搜尋輸入框（debounce 300ms）
• Pagination：頁碼 + size 切換（10 / 20 / 50）

注意：不要混淆兩種「範本」：

• 舊：workflow_templates table（jedi-flow-engine 套件提供）— AO-level 任務問卷流程，per-AO 綁定一個
• 新（本 Spec）：compliance.flow_templates table — project-level AP lifecycle 流程，per-AP 綁定一個（Spec 2/3 接手）

兩張表結構不共用、不繼承，不要試圖統一 service / repo。

• AP 套用範本（→ Spec 3 的 ProjectCreateView + ProjectApListView wizard）
• Stage 推進 runtime / Banner UI（→ Spec 2）
• 既有 5 個 view 改動（→ Spec 2）
• 階段物件 CRUD UI（→ 後續 spec，本 spec 只 seed 4 個 builtin）
• 範本「儲存草稿 vs 發佈」狀態（v1 不分）
• 範本分類 / tag（v1 不做）
• 跨 tenant 範本分享（v1 強制隔離）

10.1 BE 全部可測，10/10 場景通過

10.2 真實 response sample（直接照抄即可，FE 不用猜 schema）

GET /flow-engine/stage-objects （一筆樣本）：

{
  "status": true,
  "data": {
    "items": [
      {
        "uid": "d737b4b4-9225-4c14-8ba6-1a5cd80ffceb",
        "code": "planning",
        "name": "規劃",
        "kind": "routed",
        "route_pattern": "/project/projects/:projectUID/settings",
        "complete_button_label": "啟動專案",
        "complete_handler_key": "activate_project",
        "precondition_key": null,
        "default_main_roles": ["manager"],
        "is_builtin": true,
        "sort": 10
      }
      // ...(task_execution / audit / poam)
    ]
  }
}

GET /flow-engine/flow-templates 分頁列表：

{
  "status": true,
  "data": {
    "items": [
      {
        "uid": "da8c2b81-e628-44ee-9096-c3f0b542b61f",
        "name": "builtin-full-audit",
        "description": "完整稽核流程：規劃 → 執行 → 稽核 → 缺失改善 → 結案",
        "is_builtin": true,
        "bpmn_xml": null,    // 列表不帶 XML，呼 detail 才有
        "created_user": "system",
        "created_user_name": "系統",
        "updated_user": "system",
        "updated_user_name": "系統",
        "created_at": "2026-05-12T19:04:40.904716+08:00",
        "updated_at": "2026-05-12T19:04:40.904716+08:00"
      }
      // ...(builtin-internal-check / builtin-self-assessment)
    ],
    "total": 3,
    "page": 1,
    "size": 10
  }
}

GET /flow-engine/flow-templates/<uid> 詳情： schema 同上 list 單筆，但 bpmn_xml 欄位填滿完整 BPMN 2.0 XML 字串（builtin-full-audit ~3.8K chars）。

錯誤 envelope（builtin 守門）：

{
  "status": false,
  "msg": "內建範本不可編輯或刪除",
  "error_code": "GRC_403040"
}

10.3 開工前先讀（plan-vs-reality drift）

10.4 BE 啟動方式（zsh source .env 會炸 JSON 大括號）

.env 內 JWT_SECRET={ "jwt_secret": "..." } 之類 JSON 值的 { } 會被 zsh/bash 當特殊字元 parse 失敗。用 Python 載 env 是穩定方法：

# 在 BE repo 根目錄
lsof -i :8000 -t | xargs -r kill -9    # 殺舊 BE，nohup 可能留 orphan
python3 -c "
import os, subprocess
for line in open('.env'):
    line = line.strip()
    if not line or line.startswith('#'): continue
    if '=' in line:
        k, v = line.split('=', 1)
        os.environ[k] = v
subprocess.Popen(['poetry', 'run', 'python', 'main_app.py'],
                 stdout=open('/tmp/be.log', 'w'),
                 stderr=subprocess.STDOUT,
                 env=os.environ.copy())
"
sleep 10 && tail -3 /tmp/be.log
# 應看到 "Running on http://127.0.0.1:8000"

10.5 Known Gaps / Follow-ups（移交 FE session 接管）

10.6 一步到位的 FE 開發 checklist

[ ] 1. BE 跑起來確認 GET /flow-engine/stage-objects 回 4 個
[ ] 2. FE menu.json 加 flow-template-manage → 「流程範本管理」/ Flow Template Management
[ ] 3. FE router 加 /flow/template-manage 路由
[ ] 4. FE errorCode.json 加 6 個 GRC_4040xx / GRC_400040 / GRC_409030 訊息
[ ] 5. 列表頁：DataTable + 內建/自訂 ToggleButton filter + name 搜尋 + 分頁
[ ] 6. 「複製為自訂」Dialog：輸入新名稱 → POST .../duplicate
[ ] 7. 範本編輯頁：
       - 載入：GET .../<uid> 取 bpmn_xml
       - BPMN editor 含 ExclusiveGateway palette + UserTask 屬性面板（階段物件下拉 + 主要角色單選）
       - Gateway 屬性面板：name + outgoing flow 的 condition expression
       - 存檔：PUT 自訂 / POST 新建（FE 不可送 PUT 給 builtin — 編輯按鈕應 disable）
       - Client-side validate：必有 StartEvent / EndEvent / >=1 UserTask 含階段物件
[ ] 8. 預覽 Dialog：唯讀 BPMN renderer + UserTask 列表（顯示綁的階段名）
[ ] 9. 權限 disable 規則（§六）
[ ] 10. e2e 在 compliance-manager-test repo（另一 session）

10.7 Artifacts（FE 開發 reference）

• 3 份合法 BPMN reference XML：scripts/sql/seeds/bpmn/builtin-{full-audit,internal-check,self-assessment}.bpmn
• API SA：docs/api/flow-engine/api-spec.md Spec 1 段
• API SD：docs/api/flow-engine/design.md Spec 1 段
• Changelog：docs/changelog/2026-05-12-feat-flow-template-management.md
• Plan：docs/features/FR-026-2605-project-flow-engine-integrate/01-flow-template-management/implementation-plan.md