---
title: "資源庫任務說明：顧問替每個任務寫名稱、描述、指南 — 討論稿 (FR-147)"
brand: "Guidant AI · **FR-147** 資源庫任務說明"
eyebrow: "FR-147 · 討論稿 · 2026-10-17"
h1: "資源庫任務說明"
subtitle: "顧問在合規資源庫替每條評估目標底下的每個任務寫名稱、描述、指南；專案啟動原封帶進任務；一份 Excel 兩邊共用"
lede: "顧問做完資源庫，想替每個任務先寫好「要做什麼、怎麼做」，讓之後做任務的人打開就看得懂。現在做不到，因為資源庫階段還沒有任務——任務是專案啟動後才長出來的；而且 PM 啟動後會改流程，一條評估目標可能變三個任務。本案讓資源庫頁在每條評估目標底下直接列任務（啟動前讀流程圖、啟動後讀專案現況），三欄可填，並給一份一列一任務、評估目標欄合併儲存格的 Excel 來回匯。方向與 D1～D4、D6 決策者已裁（2026-10-17）；雛形見 [prototype/index.html](prototype/index.html)。"
chips: [
  {text: "方向三點＋D1～D4、D6 已裁（2026-10-17）", kind: ok},
  {text: "雛形審過；顧問不改流程（D6）", kind: accent},
  {text: "不開新表、不動套件", kind: plain},
  {text: "任務產生只帶三欄，不改多節點", kind: plain}
]
footer: "FR-147 · 討論稿 · 2026-10-17 · 輸入：決策者 2026-10-17 需求與三點裁示、FR-139 收口時三條釐清 · 現況依據：程式碼行號與 DEV 資料（2026-10-17）· 沿革見 git log"
---

> 雛形審過、D1～D5 裁完後寫 design.md，本稿不再改寫。

**狀態**：討論稿（方向與 D1～D4、D6 已裁，雛形審過；D5 撤銷）　｜　**日期**：2026-10-17　｜　**雛形**：[prototype/index.html](prototype/index.html)　｜　**前作**：FR-139 收口時釐清三條（只給顧問名稱／描述／指南、任務不進版本、Excel 加兩欄兩邊共用）

路徑慣例：BE 路徑相對 `compliance-manager-be/`；FE 路徑相對 `compliance-manager-fe/`；`pkg/` 代表 `~/Projects/Jedicogy/module/jedi-python-package/<套件>/`。

名詞：**資源庫**＝合規資源庫（`compliance.module_frames`），顧問做的範本，一本資源庫只給一個專案用（FR-139 起）；**AO**＝評估目標，每條控制項底下的檢查項目；**流程圖**＝每條 AO 配一張 BPMN 圖（`workflow_templates`），圖上一個方塊（userTask）就是一個任務；**任務**＝`compliance.job_executions` 一列，專案啟動時從流程圖長出來，有 `name`／`description`／`guide` 三欄；**輪次**＝專案的第 1 輪與各覆核輪，每輪自己一批任務。

## 變更紀錄 {#changelog nav="變更紀錄"}

| 日期 | 變更 | 對應 |
|---|---|---|
| 2026-10-17 | 初稿：需求白話、三點裁示、現況盤點、方案、D1～D5、拆卡草案；雛形兩頁與範例 Excel | — |
| 2026-10-17 | 決策者審雛形 v3 後：版型改判——現行頁把一條控制項全部 AO 直向堆、AO 一多會爆，改比照稽核計畫頁左樹到 AO、右欄一次一條（D7，見 design.md）；雛形 v4 | D7 |
| 2026-10-17 | 決策者審雛形後：新增 D6（資源庫頁流程編輯器入口收掉，顧問不改流程），D5 撤銷（PM 在專案改方塊名是現況、與本案無關）；D1～D4、D6 全照建議裁定；棒 2 範圍縮為「三欄帶進任務＋覆核輪抄三欄」，不改多節點 | D6 |

---

## 分工概述（30 秒版） {#overview nav="概述"}

整案一句話：**資源庫頁每條 AO 底下列出任務，顧問替每個任務填名稱、描述、指南；啟動前每條 AO 固定一個預設任務、三欄存在範本流程圖的方塊上，顧問不改流程；啟動後直接寫專案任務、PM 改過流程就看到多個；一份 Excel 一列一任務、AO 欄合併，資源庫與專案兩邊共用。**

| 棒 | 做什麼 | 產出 | 完成怎麼判定（決策者親手做什麼、看到什麼） |
|---|---|---|---|
| **1 雛形** | 純前端假資料刻資源庫 AO 底下的任務說明段、匯出匯入對話框、Excel 長相，加一份範例 Excel | `prototype/` 兩頁＋`sample/*.xlsx` | 開雛形索引，切「尚未啟動／已啟動」各看一次，改三格存檔，走一次匯入預覽；用 Excel 開範例檔看合併儲存格 |
| **2 啟動與覆核輪帶三欄** | 任務產生時三欄從範本方塊帶進任務（名稱不再寫死「收證據」）；覆核輪從上一輪任務抄三欄 | BE 任務產生服務與覆核輪服務改動 | DEV 用一本填過三欄的資源庫啟動專案，規劃頁任務三欄就是資源庫填的；啟動覆核輪，新輪任務三欄跟上一輪一樣 |
| **3 資源庫頁任務說明** | 讀寫端點（啟動前讀圖、啟動後讀任務）、方塊屬性讀寫、資源庫頁新子元件、**收掉資源庫頁流程編輯器入口（D6）** | BE 新 service＋route；FE 新元件掛進資源庫頁、拿掉一顆鈕 | DEV 開一本沒啟動的資源庫，AO 底下看到一個任務、填三格存檔重整還在；用它啟動專案，規劃頁任務三欄就是剛填的；回資源庫頁看到的變成專案任務 |
| **4 Excel 兩邊共用** | 新匯出格式（AO 合併、加描述指南兩欄）；資源庫端匯出匯入；專案端既有匯入收兩欄 | BE 匯出匯入服務；FE 兩顆鈕與預覽 | 資源庫匯出開 Excel 看到一條 AO 三列合併；改兩格匯回預覽只標那兩格、確認後畫面更新；專案規劃頁匯出同樣長相 |

依賴：1 審過 → design.md 開 2、3、4 的卡 → 2、3、4 三棒碰的檔不同可平行；3 的「寫圖」與 2 的「讀圖帶三欄」要用同一支方塊屬性 helper，先由 2 建好。不動 jedi 套件、不開新表、不套 migration。

```{.mermaid cap="圖 1 — 四棒依賴"}
%%{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
    P[棒 1 雛形] --> R{決策者審＋裁 D1～D5}
    R --> D[design.md<br/>開 2、3、4 的卡]
    D --> B2[棒 2 啟動與覆核輪<br/>三欄帶進任務]
    D --> B3[棒 3 資源庫頁任務說明<br/>讀圖／讀任務、收流程入口]
    D --> B4[棒 4 Excel 兩邊共用<br/>AO 合併、加兩欄]
    B2 -.方塊屬性 helper.-> B3
```

---

## 需求 {#need nav="需求"}

### 決策者原話（2026-10-17）

- 要能讓顧問在合規資源庫這邊直接編輯任務的任務名稱、描述、指南。之前討論過但還沒做，卡在資源庫階段是沒有任務的。
- 任務會被 PM 異動流程。原本預設一個 AO 對一個任務；PM 啟動專案後改流程，例如變成「證據上傳 → 主管審核 → 顧問審核」，一個 AO 就三個任務。
- 情境：顧問先跟 PM 討論出基本版，公司內部定義了專案任務執行流程後，AO 逐一設定任務流程、產出不同任務；這時顧問在資源庫也要能對每個任務下名稱、描述、指南，讓使用者參考要怎麼做。
- Excel 要可以一 AO 對多行任務，參考改善計畫那邊前面合併儲存格的方式；每次匯出都要依照當時的現況。

### 裁示（2026-10-17，首腦複述後決策者點頭）

1. **資源庫頁啟動後看專案現況任務**，不是永遠只看範本圖。
2. **顧問在資源庫頁只改三欄文字；流程本身由 PM 在專案規劃頁處理**，或線下討論後由系統設定。
3. **Excel 一份格式兩邊共用**：專案規劃頁既有的任務配置匯出留著，資源庫頁新加同樣格式的匯出匯入，只差識別欄。
4. **顧問不改流程**（審雛形後追加）：資源庫階段每條 AO 固定一個範本預設任務，顧問只填那個任務的三欄；資源庫頁的流程編輯器入口收掉。決策者原話「我現在不想讓顧問有這麼大權限」。流程一律啟動後由 PM 在專案規劃頁改。

### 新畫面長什麼樣（對照雛形畫面 1、2）

- 資源庫「控制項與評估目標」頁，每條 AO 展開後在既有欄位（實作狀態、缺失、建議附件、參考程序書）之後**多一段「任務說明」**：啟動前固定一張小卡（範本預設任務）：名稱一行、描述與指南各一格。已啟動時列專案現況任務，PM 改過流程就多張小卡，右上角多任務狀態與指派人（唯讀），上方一條小流程帶顯示先後。
- 每條 AO 右邊既有的「流程編輯器」按鈕拿掉（D6）。
- 頁首多「匯出任務說明」「匯入任務說明」兩顆鈕；匯入有預覽，只標出有變更的格。
- 左樹每條控制項右邊顯示「已填說明／任務數」。

---

## 現況盤點：接入點 × 現況 × 本案動作 {#inventory nav="盤點"}

### ① 任務怎麼長出來

| 接入點 | 現況 | 本案動作 |
|---|---|---|
| 建資源庫初始化 AO 流程圖 `app/oscal/service/resource_library_app_service.py:_init_ao_workflows()`（L269） | 每條 AO 用 `Camunda7BpmnGenerator` 產一張圖，只有一個方塊「Evidence upload」，圖的 uid 寫進 `catalog_control_parts.props` 的 `workflow-template-uid`。DEV 有 67,079 條 AO 帶這個 | 不動。預設那個方塊就是「範本預設任務」，三欄留空待顧問填 |
| 專案啟動長任務 `app/flow_control/service/prep_job_generation_service.py:generate()`（L122） | 每條 AO clone 一份圖，**只解析第一個 userTask**（`_first_user_task_id` L103，註解自承「其餘靜默漏建」），任務名稱寫死「控制碼 / AO 收證據」，描述指南不帶 | 名稱改從方塊取、描述指南從方塊屬性帶（棒 2）；**仍只認第一個方塊**——D6 後資源庫圖永遠一個方塊，多節點留給未來真實需求 |
| 覆核輪長任務 同一支，`reclone_from_props=True` | 從上一輪的圖再 clone，同樣只配第一個方塊、名稱寫死 | 從上一輪任務列抄三欄（棒 2） |
| 覆核輪承襲 `app/flow_control/service/reverify_inheritance_service.py:inherit_from_parent()`（L40） | 抄指派、部門、設備、證據、問卷，**不抄三欄**；新舊任務配對查詢 `get_job_pairs` 已有 | 配對結果多抄三欄（棒 2） |
| 編輯器存檔長任務 `app/flow_control/service/workflow_xml_sync_service.py:sync()`（L64） | 三向比對：圖上沒編號的方塊建新任務、沒在圖上的任務刪掉。**資源庫頁的流程編輯器存檔時查不到流程實例，回 None 只存圖** | 資源庫頁入口收掉後顧問碰不到這條（D6）；服務本身不動 |
| 套用到其他任務 `app/flow_control/service/flow_apply_to_tasks_service.py`（FR-139 T-17） | 以來源圖為底換到其他 AO，走同一支三向比對 | 不動。它換圖不動任務層欄位，三欄留在目標任務上 |

DEV 資料：有任務的 AO 59,942 條是一個任務、80 條是多任務（最多 3 個）；65,037 筆任務只有 9 筆填了指南、11 筆填了描述。

### ② 三欄位在哪

| 接入點 | 現況 | 本案動作 |
|---|---|---|
| 任務表 `pkg/jedi-flow-engine/jedi_flow_engine/infra/models/job_execution.py` | `name`（L29）、`description`（L30）、`guide`（L34）本來就有 | 不動 |
| 專案規劃頁改三欄 `app/flow_control/service/job_service.py:update_job()`（L331） | 收 `name`／`description`／`guide`，守 project manager | 不動；資源庫頁啟動後寫三欄另開一支只開三欄、守資源庫編輯權（棒 3） |
| FE 任務表單 `src/components/grc/planning/AoTaskForm.vue`（L395～420） | 三格已存在 | 資源庫頁新元件照這三格的樣子刻（棒 3） |
| 流程圖節點 | 方塊只有名稱；任務編號是用 camunda 屬性 `job_execution_uid` 掛在方塊上（`BpmnUtils.inject_job_execution_uid`） | 描述、指南用同一招掛成兩個 camunda 屬性（棒 3；D1） |

### ③ 資源庫頁與專案的關係

| 接入點 | 現況 | 本案動作 |
|---|---|---|
| 一對一 `app/project/service/project_start_app_service.py:_assert_never_bound()`（L165）、`infra/readmodel/oscal/resource_library_binding_query.py` | FR-139 起一本資源庫終身只給一個專案；`ever_bound`／`has_live_project` 已有 | 棒 3 用它判「讀圖還是讀任務」 |
| 資源庫寫入守門 `domain/module_frame/service/module_frame_domain_service.py:verify_module_frame_exists_by_uid(writable=True)`（L79）、`assert_template_not_audit_locked`（L98） | 寫 `oscal.*` 都走它；稽核中鎖寫 | 三欄讀寫端點照走（棒 3） |
| 複製資源庫 `app/module_frame/service/resource_library_copy_service.py:_copy_ao_workflows()`（L102） | 連 AO 流程圖一起 clone | 不動。三欄在圖上，複製免費帶走 |
| FE 資源庫頁 `src/views/module_frame/ModuleFrameTemplateEditView.vue` | 1,954 行，已超標；AO 展開區在 L1496～ | 新區塊**一律新開子元件**，原檔只加一行掛載（棒 3） |

### ④ Excel

| 接入點 | 現況 | 本案動作 |
|---|---|---|
| 專案任務配置匯出匯入 `app/flow_control/service/job_import_service.py`（546 行） | 十欄：job_uid（隱藏）、群組、識別碼、控制項名稱、AO、任務名稱、類型、指派、部門、設備；一任務一列、AO 欄重複印不合併；匯入只寫類型、指派、部門、設備 | 匯出加描述、指南兩欄＋AO 合併；匯入多收三欄文字（棒 4） |
| 匯出查詢 `infra/readmodel/tasks/job_export_query.py:get_export_data()`（L85） | 按輪次撈 wecm × 任務，已回 `job_name`，沒回 description／guide | 加兩欄（棒 4） |
| 改善計畫匯出 `app/flow_control/service/poam_workbook_export.py:_plan_sheet()`（L131～205） | AO 多列、前幾欄 `merge_cells`、列高平分、灰底唯讀黃底可改 | 合併與著色寫法直接借（棒 4） |
| 資源庫端匯出匯入 | 沒有 | 新增；啟動前讀圖、啟動後走專案那套（棒 4） |

---

## 方案：任務資訊放流程圖，啟動時整張圖長任務 {#design nav="方案"}

### 資料落點（一句話）

**啟動前**每條 AO 固定一個範本預設任務，三欄住在那張流程圖的方塊上（名稱＝方塊名稱，描述與指南＝方塊的兩個 camunda 屬性）；**啟動後**三欄住在專案任務列上，與規劃頁同一份。沒有第三個地方。

### 端到端

```{.mermaid cap="圖 2 — 三欄從資源庫到任務的流向"}
%%{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 TB
    subgraph 啟動前
      L[資源庫頁 AO 任務說明<br/>顧問填三欄] -->|寫方塊名稱＋兩個屬性| G[AO 流程圖<br/>workflow_templates.xml]
      X1[資源庫 Excel 匯入] --> G
      G --> X2[資源庫 Excel 匯出]
    end
    G -->|專案啟動：每個方塊各建一筆<br/>三欄帶進任務列| J[專案任務<br/>job_executions]
    subgraph 啟動後
      J --> L2[資源庫頁 AO 任務說明<br/>改三欄直接寫任務]
      J --> P[專案規劃頁任務表單<br/>PM 改流程、改全部欄位]
      J --> X3[專案與資源庫 Excel<br/>同一份格式]
      J -->|覆核輪：新舊任務配對抄三欄| J2[覆核輪任務]
    end
```

### 讀寫規則

- **資源庫頁讀**：資源庫沒綁過專案 → 解析每條 AO 的圖取那一個方塊，三欄從方塊取（圖上若有多個方塊只列第一個，與啟動行為一致）；綁了專案 → 讀該專案**目前輪次**的任務列（wecm 按 round_id，與任務配置匯出同一條查法）。回傳形狀一樣，前端不分。
- **資源庫頁寫**：啟動前改圖（只改方塊名稱與兩個屬性，不動線、不增刪方塊；走倉儲雙寫主表與翻譯列，與任務產生那支同一個坑）；啟動後走一支只開三欄的更新，守「資源庫可寫」與稽核鎖，不要求專案 manager。
- **啟動**：任務產生維持只認第一個方塊，但 `name`／`description`／`guide` 改從方塊帶（名稱沒填時退回現在的「控制碼 / AO 收證據」）。
- **覆核輪**：三欄改從上一輪配對到的任務列抄，不再寫死「收證據」。
- **Excel**：匯出讀當下來源（圖或任務列），一列一任務、AO 前幾欄合併、順序欄、三欄黃底；匯入只寫三欄，識別欄啟動前「AO 編號｜方塊編號」、啟動後任務編號；專案規劃頁既有匯出匯入加同兩欄、改合併。

### 不做

- 任務不進資源庫版本（FR-139 收口已裁）。
- 顧問在資源庫頁不改流程、不增刪任務、不改指派與期限；資源庫頁流程編輯器入口收掉（D6）。
- PM 在專案規劃頁改方塊名稱與任務列名稱的關係維持現況（兩邊各自、不同步），與本案無關（原 D5，撤銷）。
- 啟動時「整張圖每個方塊都長任務」不做：D6 後資源庫圖永遠一個方塊，現況「只認第一個」就夠；資源庫編輯器既有的多方塊圖（若有）啟動行為不變。
- 既有「一資源庫多專案」舊資料：資源庫頁遇到多個專案退回只讀圖、三欄可填但只影響未來（實際上 FR-139 後不會再有新的）。
- 任務型別、週期、工具參數不進 Excel 三欄之外的範圍。

---

## 已裁 D1～D4、D6 {#decisions nav="已裁"}

2026-10-17 決策者審雛形後全照建議裁定；D5 撤銷。

::: {.callout .decided}
**D1 啟動前三欄存哪裡：流程圖方塊上（建議）vs 另開一張表**

- **甲：存流程圖方塊上**。名稱就是方塊名稱，描述與指南掛成方塊的兩個 camunda 屬性，跟現在掛任務編號同一招。資源庫的流程編輯器改方塊名稱、增刪方塊，任務說明自動跟著；複製資源庫免費帶走；不開新表、不套 migration。
- **乙：另開一張「AO 任務說明」表**，以 AO 編號＋方塊編號當鍵。查詢直接 SQL 不用解析 XML，但顧問在編輯器刪了方塊、表上那列還在，要另寫清理；複製資源庫要多抄一張表；要 migration 與 RLS。

[**裁定**：甲。乙的「兩份真相」正是 FR-139 一路在收斂的病；解析 XML 的成本已有 `BpmnUtils` 承擔，資源庫頁一次只開一條控制項，量不大。]{.rec}
:::

::: {.callout .decided}
**D2 啟動後顧問在資源庫頁改三欄，寫入守門用哪一把**

- **甲：資源庫編輯權**（`oscal.resource-library.update` ＋ `writable=True` 歸屬守門 ＋ 稽核鎖），不要求是專案 manager。
- **乙：要求同時是該專案 manager**，等於把資源庫頁當專案規劃頁的捷徑。

[**裁定**：甲。決策者裁示第 2 點是「流程權限給 PM、顧問只改三欄文字」，顧問通常不是專案成員；三欄是說明文字不是稽核範圍，風險低。端點只開這三欄，其他欄位仍走專案規劃頁。]{.rec}
:::

::: {.callout .decided}
**D3 資源庫頁啟動後讀哪一輪的任務**

- **甲：目前輪次**（最新一輪）。覆核輪一啟動，資源庫頁看到的就是新輪任務。
- **乙：第 1 輪固定**。

[**裁定**：甲，與任務配置匯出、規劃頁同一條「目前輪次」查法。覆核輪從上一輪抄三欄後（棒 2），顧問接著改的是新輪，舊輪任務已進稽核不該再動。]{.rec}
:::

::: {.callout .decided}
**D4 Excel 匯入是否允許「對不到」的列報錯整份退回**

- **甲：對不到的列跳過、其餘照寫**，預覽列出跳過幾列（與既有任務配置匯入一致）。
- **乙：有一列對不到整份退回**。

[**裁定**：甲，兩邊匯入行為一致，顧問匯入時任務數常已被 PM 改過，整份退回會讓檔案永遠匯不進去。]{.rec}
:::

::: {.callout .decided}
**D6 資源庫頁的流程編輯器入口收掉，顧問不改流程**

每條 AO 右邊「流程編輯器」按鈕拿掉。資源庫階段每條 AO 固定一個範本預設任務，顧問只填它的三欄；流程一律啟動後由 PM 在專案規劃頁改。

**為什麼**：決策者 2026-10-17 審雛形後裁「不想讓顧問有這麼大權限」。附帶效益：現況那顆按鈕設了也白設（啟動只認第一個方塊，其餘靜默消失）；拿掉後資源庫階段永遠一 AO 一任務，畫面、Excel、啟動邏輯都不必處理多方塊，棒 2 範圍縮一半。

**被排除**：留著按鈕並把啟動改成整張圖都長任務——權限方向與決策者相反，且要動啟動與覆核輪共用的核心。
:::

---

## 拆卡草案 {#cards nav="拆卡"}

design.md 定案後一次建完。三棒可平行；棒 2 先建方塊屬性 helper 給棒 3 共用。

| 棒 | 卡 | 做什麼 | 碰哪裡 | 依賴 | 驗收 |
|---|---|---|---|---|---|
| 1 | 雛形 | 兩頁雛形＋範例 Excel | `prototype/` | — | 決策者點過 |
| 2 | 2a | 任務產生三欄從方塊帶（名稱沒填退回現在的「收證據」）；方塊屬性讀寫 helper 新檔 | `prep_job_generation_service.py`（282 行，只改 label 與三欄來源）、`task_node_props.py` 新檔 | design | DEV 用填過三欄的資源庫啟動專案，規劃頁任務三欄＝資源庫填的；沒填的資源庫啟動行為不變 |
| 2 | 2b | 覆核輪承襲三欄 | `reverify_inheritance_service.py`、配對查詢 | 2a | 啟動覆核輪，新輪任務三欄＝上一輪 |
| 3 | 3a | 資源庫 AO 任務說明讀寫端點：綁定判斷、讀圖／讀任務、寫圖（雙寫）／寫任務三欄；守門走資源庫編輯權＋稽核鎖 | 新 `app/module_frame/service/ao_task_guidance_service.py`、route、readmodel | 2a 的 helper | API 啟動前後各讀寫一次一致 |
| 3 | 3b | 資源庫頁「任務說明」子元件（任務小卡三格；已啟動多卡帶流程帶）、左樹計數、兩顆鈕殼、**拿掉 AO 的流程編輯器按鈕（D6）** | FE 新元件，`ModuleFrameTemplateEditView.vue` 只加掛載與刪一顆鈕 | 3a | 照雛形畫面 1 操作一遍；AO 右邊沒有流程編輯器鈕 |
| 4 | 4a | 任務說明 Excel 匯出（AO 合併、順序、三欄黃底、填寫說明頁）與匯入 parse／confirm，資源庫與專案共用一支 builder | 新 `task_guidance_workbook.py`（借 `poam_workbook_export.py` 合併寫法）、`job_export_query.py` 加兩欄 | 3a | 資源庫匯出開檔看合併；改兩格匯回預覽與確認 |
| 4 | 4b | 專案規劃頁既有任務配置匯出匯入改合併＋收描述指南兩欄 | `job_import_service.py`（546 行，加欄要注意不往裡塞） | 4a | 專案匯出同長相；匯回三欄寫進任務 |
| 4 | 4c | FE：資源庫頁匯出匯入對話框與預覽（只標變更格） | FE | 3b、4a | 照雛形匯入預覽 |

---

## 坑與陷阱總表 {#pitfalls nav="坑"}

| 坑 | 在哪 | 怎麼避 |
|---|---|---|
| 圖的 XML 是可翻譯欄位，只寫主表編輯器看不到 | `prep_job_generation_service.py` L262 註解、`_job_repo.write_template_xml` | 寫圖一律走倉儲雙寫 |
| 資源庫頁寫方塊屬性時不可動到 `job_execution_uid` 或方塊 id | `workflow_xml_sync_service.py` L94 三向比對 | helper 只改 name 與兩個自家屬性，其他原樣保留；清屬性清到空就整段拿掉 |
| 資源庫頁走「資源庫入口」才會觸發資源庫側行為 | FR-139 T-24 教訓 | 驗收用資源庫頁的端點，不拿專案端點頂 |
| `ModuleFrameTemplateEditView.vue` 超標 | 1,954 行 | 新區塊必開子元件，原檔只加一行 |
| 空的 `<camunda:properties/>` 會讓解析炸 | `flow_apply_to_tasks_service.py:_strip_uid` 註解 | 清屬性清到空就把整段拿掉 |
| 改 service 後共用 BE 跑舊程式 | 2026-10-15 教訓 | 驗收前先重啟 |