資源庫任務說明：設計定案

🔴 這份是設計決策，不是現況。 內文停在 2026-10-17 定稿當時，實作改動不回頭改寫這裡。

狀態：設計定案，待開卡派工｜討論稿：discussion.md｜雛形：prototype/index.html

檔案路徑與行號以 2026-10-17 為準，查不到時以函式名重新定位。路徑慣例：BE 路徑相對 compliance-manager-be/；FE 路徑相對 compliance-manager-fe/；pkg/<套件>/ 代表 ~/Projects/Jedicogy/module/jedi-python-package/<套件>/。

名詞：資源庫＝合規資源庫（compliance.module_frames），一本只給一個專案用；AO＝評估目標，每條控制項底下的檢查項目，鍵是 catalog_control_parts.part_id；範本流程圖＝每條 AO 配的一張 BPMN 圖（compliance.workflow_templates，uid 寫在 AO props 的 workflow-template-uid），預設一個方塊；範本預設任務＝那個方塊，資源庫階段「任務」指的就是它；任務＝compliance.job_executions 一列，有 name／description／guide；目前輪次＝專案最新一輪（第 1 輪或最新覆核輪）。

整案一句話：資源庫頁每條 AO 底下多一段「任務說明」，顧問填預設任務的名稱、描述、指南；啟動帶進任務、啟動後直接改任務；一份 Excel 兩邊共用；顧問不改流程。

依賴：2a 先建 helper，3a 的「寫圖」用同一支；3c（版型）不依賴後端可與 2a 同時派；3b 等 3a 與 3c；其餘可平行。

%%{init: {'theme':'base','themeVariables':{'primaryColor':'#E2F0F1','primaryTextColor':'#14201F','primaryBorderColor':'#0E7C86','secondaryColor':'#EEF2F3','secondaryTextColor':'#14201F','tertiaryColor':'#FBFCFC','tertiaryTextColor':'#14201F','lineColor':'#4A5A5C','textColor':'#14201F','mainBkg':'#E2F0F1','nodeBorder':'#0E7C86','nodeTextColor':'#14201F','edgeLabelBackground':'#FBFCFC','titleColor':'#14201F','clusterBkg':'#FBFCFC','clusterBorder':'#E4EAEB','actorBkg':'#E2F0F1','actorTextColor':'#14201F','actorBorder':'#0E7C86','actorLineColor':'#C7D1D2','signalColor':'#4A5A5C','signalTextColor':'#14201F','labelBoxBkgColor':'#EEF2F3','labelBoxBorderColor':'#C7D1D2','labelTextColor':'#14201F','loopTextColor':'#14201F','noteBkgColor':'#F6EBD5','noteTextColor':'#14201F','noteBorderColor':'#9C6B12','activationBkgColor':'#EEF2F3','activationBorderColor':'#C7D1D2','sequenceNumberColor':'#FFFFFF'}}}%%
flowchart LR
    subgraph B2[棒 2 啟動與覆核輪]
      A2a[2a helper＋啟動帶三欄] --> A2b[2b 覆核輪抄三欄]
    end
    subgraph B3[棒 3 資源庫頁]
      A3a[3a 讀寫 API] --> A3b[3b FE 區塊＋收入口]
    end
    subgraph B4[棒 4 Excel]
      A4a[4a 資源庫端匯出匯入] --> A4c[4c FE 對話框]
      A4a --> A4b[4b 專案端對齊]
    end
    A2a -.方塊屬性 helper.-> A3a
    A3a -.讀取 readmodel.-> A4a

資料落點

• 啟動前：三欄在範本流程圖第一個 userTask 方塊上。name 是方塊的 name 屬性；描述與指南是 <camunda:properties> 底下兩個 <camunda:property name="task_description" value="…"/>、name="task_guide"。
• 啟動後：三欄在任務列 job_executions.name／description／guide。
• 兩個落點之間只有一條單向流：啟動時從圖帶進任務列。啟動後改任務列不回寫圖。

方塊屬性 helper（2a 建，3a 共用）

新檔 app/flow_control/service/task_node_props.py，純函式、不碰 DB：

• read_first_task(xml) -> {node_id, name, description, guide} | None：用 BpmnUtils(xml).get_jobs() 取第一個 userTask（與 _first_user_task_id 同一個「第一個」），從 properties 取兩個屬性。
• write_first_task(xml, name, description, guide) -> xml：只改第一個 userTask 的 name 與那兩個屬性；不動方塊 id、線、其他屬性（含 job_execution_uid）；屬性值為空就把該屬性拿掉，<camunda:properties> 清到空要整段拿掉（空節點會讓 BpmnUtils 解析炸，見 flow_apply_to_tasks_service.py:_strip_uid 註解）。
• 實作手法照 flow_apply_to_tasks_service.py 用 xmltodict parse／unparse。

專案啟動帶三欄（2a）

prep_job_generation_service.py:generate() 專案啟動模式（reclone_from_props=False）：clone 完範本後 read_first_task(cloned.xml)，name 有值就用它當 label，否則維持 f"{cid} / {ao_part_id} 收證據"；description／guide 直接寫進 JobExecutionEntity。workflow_execution 的 name 維持原 label（它是流程實例名稱，不是任務名稱）。

覆核輪抄三欄（2b）

generate() 覆核輪模式不讀圖（上一輪的圖方塊名稱是上一輪 clone 當下的，PM 之後改的任務名稱不在圖上）。改在 reverify_inheritance_service.py:inherit_from_parent() 的 get_job_pairs 迴圈裡，每對新舊任務把舊任務的三欄 UPDATE 到新任務（infra 層加一支 clone_task_text_fields(pair)，與 clone_assignees 同形）。

資源庫 AO 任務說明 API（3a）

新 app/module_frame/service/ao_task_guidance_service.py（@transaction，守門見 D2）：

左樹計數（已填說明／任務數）由同一支 GET 的聚合版 GET /module-frame/<uid>/task-guidance/summary 回每條控制項 {code, filled, total}，一次 SQL／一次解析，不逐條打。

新 readmodel infra/readmodel/module_frame/ao_task_guidance_query.py：綁定資源庫 → 專案 id、目前輪次 id；按輪次撈 AO 任務（與 job_export_query.py 同一條 wecm 查法）。

資源庫頁區塊（3b）

新子元件 src/components/grc/module-frame/AoTaskGuidanceSection.vue，掛在 ModuleFrameTemplateEditView.vue AO 展開區「參考程序書」之後，一行 <AoTaskGuidanceSection :module-frame-uid :control-code :readonly="isVersionView || writeDisabled()" />。元件自己打 GET、三格 @change 累積、頁面儲存時 emit 批次 PUT。版本檢視（isVersionView）唯讀顯示三欄文字。

長相照雛形畫面 1：template 一張小卡；project 多張小卡＋上方流程帶，小卡右上角狀態徽章與指派人（唯讀）。刪掉 L1479～1487 的流程編輯器 <button> 與 openBpmnEditor（D6）。

Excel 契約（4a、4b）

共用 builder app/flow_control/service/task_guidance_workbook.py：

另一頁「填寫說明」（照 prototype/sample/make_sample_xlsx.py 的六條）。合併、列高、著色借 poam_workbook_export.py:_plan_sheet() 的寫法。

匯入三段：parse（回每列的新舊值與變更旗標、跳過清單）→ FE 預覽只標變更格 → confirm（只寫有變更且 key 對得到的列；D4 跳過不報錯）。資源庫端端點 POST /module-frame/<uid>/task-guidance/export、.../import/parse、.../import/confirm；守門同 3a。

專案端 job_import_service.py 改用共用 builder 產前九欄，_EXPORT_COLUMNS 加 description／guide，confirm_import 多把三欄傳進 update_job。job_export_query.py 回 description／guide。

權限與鎖

• 資源庫端三支寫入（PUT、import/confirm）：@require_capability("oscal.resource-library.update") ＋ service 內 verify_module_frame_exists_by_uid(uid, writable=True) ＋ assert_template_not_audit_locked。
• 資源庫端讀取：資源庫讀權（既有）。
• 專案端匯出匯入：維持既有專案 manager 守門。
• 稽核中（FR-139 鎖）資源庫頁三欄唯讀，與既有欄位一致。

1. DEV 建一本新資源庫（或用沒綁專案的既有庫），資源庫頁某控制項展開 AO，看到一張「任務說明」小卡、名稱「Evidence upload」、描述指南空白；AO 右邊沒有流程編輯器鈕。
2. 填三欄存檔、重整還在；另一條 AO 不受影響。左樹該控制項計數變 1/N。
3. 匯出任務說明 Excel，開檔：每 AO 一列、三欄黃底、第一列是剛填的；改另一條 AO 兩格匯回，預覽只標兩格、確認後畫面更新。
4. 用這本資源庫啟動專案：規劃頁該 AO 的任務名稱、描述、指南＝資源庫填的；沒填的 AO 任務名稱仍是「控制碼 / AO 收證據」。
5. PM 在專案規劃頁把一條 AO 流程改成三站；回資源庫頁同一條 AO 看到三張小卡、流程帶三格、狀態與指派人唯讀；改第二張的指南存檔，規劃頁該任務指南同步。
6. 資源庫匯出 Excel：那條 AO 三列、B～E 合併；專案規劃頁任務配置匯出長相一致且多指派、部門、設備欄。
7. 啟動覆核輪：新輪同一條 AO 的任務三欄＝上一輪。
8. 覆核輪送審鎖寫後資源庫頁三欄唯讀。