AO 任務配置與啟動（Task Config）

功能群：專案管理｜上層見 專案規劃頁（本頁＝其 Tab0「控制項實作」的 AO 任務配置，規劃頁功能總覽第 4／5／6 項）

事實基準：2026-07-06 從 FE / BE code 掃出；表結構對 db_schema.json、endpoint 對 routes.json、欄位對 marshmallow serializer + service 組裝碼逐條核｜變更紀錄：2026-07-06 FR-047 從 project-planning.md 拆出並納入快速配置 / 開始執行

1. 功能描述

AO 任務（prep-job）是「為每個控制項評估目標（AO）蒐集證據」的工作項。本頁涵蓋任務域的三件事：①單一任務逐欄配置（inline 編輯）、②快速配置（一鍵把多位人員批次併入所有可編輯任務）、③開始執行（PM 把已指派任務批次轉 PROCESSING 並通知）。

規劃頁 Tab0 的左樹選到某個 AO 後，右面板下方列出該 AO 的任務卡；每張卡片直接 inline 編輯（非獨立 Dialog）：任務名稱 / 描述 / 指南、任務類型（一般 general / 問卷 survey）、指派人員（可標審核人）、部門、設備、問卷（可標審批要求）。儲存以 PUT job 一次寫回，關聯欄位採 full-replace 語意（送 [] 清空、省略 = 不動）。快速配置與開始執行是 Header 的批次動作：前者 FE 端逐一 PUT 合併、後者呼叫專屬 start-task-execution endpoint。

任務真相來自範本 BPMN 的 userTask（見規劃頁背景）；儲存時 BE 會在同一 transaction 同步回寫 BPMN userTask，讓 BPMN 編輯器與規劃頁兩端一致。與 SSP 編輯不同，任務指派不受 SSP 凍結影響，只要輪次在 planning 階段、使用者對該節點有三層遞進的 manager 權即可編。

主要使用者：對該控制節點有 manager 權者（專案 / 群組 / 控制項任一層 manager）。

角色速覽（完整定義見 _overview §3）：

1.1 功能總覽（本頁全部功能）

UC（§2）展開兩條核心路徑：UC-TE-01（單一任務逐欄 inline 編輯，含 M2M / 審核人坑）與 UC-PP-02（快速配置 → 開始執行的批次流）。快速配置 ⚠️ 有清空關聯的坑（見 §12）。

2. Use Case

角色速覽（同 §1）。流程圖視覺慣例：菱形 = 判斷、橘底 = 例外/擋下、紅框 = 錯誤（標 error code）、綠框 = 成功終點、虛線 = 可選路徑。

UC-TE-01 編輯 AO 任務

UC-PP-02 快速配置與開始執行

3. 權限矩陣

⚠️ FE / BE 權限不對齊：FE 用三層遞進的 canEdit 擋按鈕，但 PUT job route 層只有 JWT 登入、無任何角色檢查——任一登入者繞過 FE 直接打 API 都能改任務指派。與規劃頁 §3 / §12 記載的同一 finding。唯有「開始執行」有 BE manager 守門（GRC_403002）。

4. 狀態機與前置條件

承接輪次階段 gate（見 規劃頁 §4）：

5. UI 設計

版面骨架（Header 批次動作 + AO 任務卡 inline 編輯，含 survey 型條件層 + 代表性 API）：

📸 截圖待補（亮色模式）：AO 面板 + 任務卡展開（general 型）taskedit-general.png、survey 型（含問卷 + 審批 + 審核人 switch）taskedit-survey.png。（規劃頁 §5 已有 planning-ao-tasks.png 概覽可參考）

任務卡 inline 表單（ProjectPlanningView.vue Panel 卡片，無獨立 Dialog）。欄位：

FE 別名坑：指派人員的審核旗標，FE 早期送 is_admin，serializer AssigneeInputSchema 以 @post_load coalesce 進 is_approver（api/grc/serializers/job.py:105-114）。新資料一律 is_approver。

狀態呈現：無 socket；儲存中 per-任務 spinner（taskSavingSet Set）；儲存後前端 state 更新（不整頁重載）。

6. API 規格

Envelope：成功 {"status": true, "data": …}、失敗 {"error_code": "…", "msg": "…"}。

6.1 總清單

批次啟動 POST /grc/project/{uid}/start-task-execution 屬規劃頁功能 6，見 規劃頁 §6.4。

6.2 核心 endpoint

[PUT] /grc/project/{project_uid}/job/{job_uid}

任務更新。全部欄位選填（load_default=None）；關聯陣列 full-replace（送 [] 清空、null/省略 = 不動）。Request（JobUpdateRequestSchema，Meta.unknown=EXCLUDE）：

{
  "name": "訪談紀錄蒐集",
  "description": "…",
  "guide": "…",
  "job_type": "survey",
  "control_uid": null,
  "assignees": [{ "uid": "<user uid>", "is_approver": true }],
  "department_uids": ["<org_unit uid>"],
  "device_uids": ["<device uid>"],
  "surveys": [{ "uid": "<survey uid>", "approval_required": true }]
}

出處：request api/grc/serializers/job.py:128-151、route api/grc/routes/job_route.py:100-136、service app/grc/service/job_service.py（update_job + _reconcile_task_surveys:228）

Response data（JobResponseSchema，形狀同 control-tree 的 Job 節點）：

出處：api/grc/serializers/job.py:128-157（JobUpdateResponseSchema → JobResponseSchema）

6.3 批次動作

快速配置（無專屬 endpoint，FE 逐一 PUT）

FE-only 編排：多選人員（來源 = 專案參與人員）→ 迴圈所有可編輯（canEditCtrl）控制項底下的任務 → 每個 job 把選取人員 additive 併入既有指派（已存在者跳過）→ 逐一 PUT job。⚠️ 每筆 PUT 送 department_uids: [] / device_uids: [] / surveys: []——因 full-replace 語意，會清空該任務既有的部門 / 設備 / 問卷關聯（見 §12 坑）。出處：ProjectPlanningView.vue:executeQuickConfig:1192-1230。

[POST] /grc/project/{project_uid}/start-task-execution

無 body。把該專案「已指派且 TODO」的 prep-job 批次轉 PROCESSING 並發站內通知。限專案 manager（_check_manager，否則 GRC_403002）；idempotent 可重按。Response data：{"activated_count": int}（實際轉 PROCESSING 的任務數）。出處：service app/grc/service/task_execution_service.py（_check_manager:8-17、start_task_execution:22-30）、serializer api/grc/serializers/task_execution.py:5-8。

7. 前端檔案地圖（compliance-manager-fe/）

8. 後端檔案地圖（本頁核心鏈路）

⚠️ DDD 提醒：PUT job route 層無角色守門（別比照為權限典範）；問卷關聯跨到 survey schema 的 task_surveys（非 compliance.job_execution_surveys），維護留意 schema 邊界。

9. DB

9.1 資料表總清單（本頁讀寫的全部表）

9.2 ER 圖

9.3 核心表欄位（取自 DEV DB dump，含 DB comment）

compliance.job_executions — 任務本體

compliance.task_assignees — 指派人員

compliance.job_execution_org_units / job_execution_devices — 部門 / 設備關聯

survey.task_surveys — 問卷關聯（跨 schema）

⚠️ schema 註：問卷關聯在 survey schema 的 task_surveys（job_service._reconcile_task_surveys 管理），不是 compliance.job_execution_surveys（那是另一張簡單映射表，本更新路徑不寫）。欄位一律取自 db_schema.json。

10. 頁面邏輯與資料對應

任務隨 control-tree 一次載入（內嵌於 AO 節點）。欄位對應：

儲存流程：saveTask 先 client 檢查「survey 有審批要求但無審核人 → toast warn 不送」（ProjectPlanningView.vue:918-923）→ PUT → 前端 state 更新。錯誤對應：GRC_404005（任務不存在）/ GRC_409033（問卷已有填答無法移除）→ toast。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. PUT job 無 BE 角色守門：route 僅 @jwt_required()，FE 靠三層 canEdit 擋；繞過 FE 直打 API 任一登入者都能改任務指派（與規劃頁 §12 同一 finding）。
2. 審核人檢查只在 FE：「survey 有審批要求則至少一審核人」只在 saveTask 前 client 檢查（toast 不送），BE 無此驗證——直打 API 可存出「有審批要求卻無審核人」的任務。
3. 問卷關聯跨 schema、非直覺：任務問卷走 survey.task_surveys（_reconcile_task_surveys），不是 compliance.job_execution_surveys；後者是另一映射表，本路徑不動。
4. surveys[].approval_required 送 null 保留既有值：SurveyInputSchema 的 approval_required load_default=None——BPMN 編輯器同步問卷時不帶此欄（無此 UI），送 null → _reconcile_task_surveys 保留既有審批旗標，不誤蓋規劃頁設定；規劃頁顯式送 True/False 行為不變。
5. is_admin → is_approver 別名：FE 早期送 is_admin，serializer @post_load coalesce 進 is_approver；下游只讀 is_approver。
6. 關聯 full-replace 語意：assignees/department_uids/device_uids/surveys 送 [] 清空、null/省略不動；部門 / 設備關聯是全刪重建（reconcile）。
7. 問卷已有填答不可移除：移除已有答案的問卷 evidence → GRC_409033（GRC_SURVEY_HAS_ANSWERS）。
8. ⚠️ 快速配置會清空部門 / 設備 / 問卷關聯：executeQuickConfig 對每個 job 只 additive 合併指派人員，但送 department_uids: [] / device_uids: [] / surveys: []——因 full-replace 語意（[]＝清空），會把該任務既有的部門 / 設備 / 問卷關聯一併清掉。若已配置這些關聯，用快速配置補人員前要留意會被清空（ProjectPlanningView.vue:1218）。
9. survey × device 笛卡爾積：任務掛多問卷多設備時 survey.task_surveys 列數會乘開（每問卷 × 每設備一列），指派前想清楚資料量。
10. date-only 顯示 08:00 陷阱：任務時間相關欄位 BE 慣例吐 YYYY-MM-DDTHH:MM:00 無 tz，前端 date-only 顯示要留意時區偏移（見 _overview 時區慣例）。

13. 開發與驗證

• 跑起來：起 BE + FE；登入見 .env / 部署文件測試帳號（需該節點 manager；開始執行需專案 manager）
• 導航：規劃頁 Tab0 → 左樹選 AO → 右面板任務卡展開編輯；快速配置 / 開始執行在 Header
• 前置資料：需 AP=planning 的專案 + 至少一個控制項有 AO 任務；備 user / org_unit / device / survey master 測四關聯；切 survey 型測問卷 + 審批 + 審核人 switch 連動；測快速配置後檢查部門/設備是否被清空（坑 8）
• 相關：現況編輯 / 程序書見 現況編輯；批次匯入見 批次維護；任務真相＝範本 BPMN userTask；問卷設計見 survey 功能群