專案規劃頁（Project Planning）

功能群：專案管理｜狀態機與共用概念先讀 功能群總覽

事實基準：2026-07-05 從 FE / BE code 掃出（FR-038 v2 round-based 架構）

變更紀錄： - 2026-09-19（FR-112）：任務可在本頁新增／刪除（一個 AO 可有多筆任務，新任務預設平行），任務區塊改 Master-Detail（籤列選一筆、右側單一表單）；「任務設定」進度卡改以任務為單位、三張卡皆可點開未設定清單並跳到該項；麵包屑改 PrimeVue Breadcrumb。行為與欄位全在 任務配置與啟動；本頁 hub 變動限於進度卡與左樹完成度判定（§10／§12 坑 9） - 2026-08-26（FR-067 驗收回饋，v1.16.0 後續補項，歸下版）：檢測任務分派列摘要與執行確認框的掃描目標改顯示「原始寫法＋BE 供的真實台數」（CM-1395），行為全在 任務配置與啟動（§5）；本頁作為 hub 無獨立變動 - 2026-08-25（FR-067.8）：檢測工具型任務改「每列自足」——任務層掃描參數區整塊移除（只留完成模式），整份參數搬進每個 Agent 分派列；行為與欄位全在 任務配置與啟動（§5「Agent 分派區塊」）；本頁作為 hub 無獨立變動 - 2026-08-25（FR-067）：檢測工具型任務新增「Agent 分派」設定（多台 agent 各掃各網段／各基準、per-列排程），任務卡 UI 與行為全在 任務配置與啟動（§5「Agent 分派區塊」）；本頁作為 hub 無獨立變動 - 2026-08-02（bugfix）：覆核輪左樹控制項母體改讀本輪 AP（收斂成母輪未通過控制），規劃階段即生效——此前 planning 期 ssp_id IS NULL、FE 退用 living SSP 打 control-tree，母體退回 living profile 全集，導覽因此顯示母輪全部控制項（1182034d，配合 167f578f / 9b2eae04 的 AP 端收斂；見 §6.2／§12 坑 8） - 2026-07-27（FR-056）：任務類型新增「檢測工具執行」（detection_tool）——選定工具 + 動態掃描參數 + 完成模式，詳見 任務配置與啟動；「開始執行任務」批次動作新增自動派 detection 任務首次掃描 - 2026-07-24（v1.10.0）：FR-052 Tab5「雲端整合」加顯示 gate（tenant drive 已連接才顯示，fail-closed，見 §4/§5）；Tab1 SSP 編輯（元件/外部授權/系統資產區）新增/編輯 dialog 補同名查重（CM-766，GRC_409037，見 §12）；批次匯入同批次去重擴及剩餘資料類型 - 2026-07-06 FR-047 — 本頁改造成 hub 導航頁；重功能拆出獨立子頁（現況編輯 / 任務配置 / 批次維護 / 基本資訊），階段推進橫幅抽成共用元件。

1. 功能描述

專案規劃頁是稽核輪次 planning 階段的主工作區：受評方在啟動稽核前，於此完成 SSP 現況說明與證據蒐集任務的準備。編輯的是專案的 living SSP（見 _overview §4）；launch-audit 推進後 SSP 凍結成快照，本頁轉唯讀。

本頁功能複雜、切成 6 個 Tab 與多組批次作業，故採 hub 模式：本頁描述版面骨架、區塊 inventory 與頁級共用底盤（左樹導覽、進度卡、載入鏈、共用 gate），每個重功能各自有 field-level 子頁（見 §1.1「詳述」欄）。快速定位「有幾塊、動哪塊碰哪支檔」看本頁；一個功能的逐欄細節開子頁。

主要使用者：專案經理（manager）、控制群組 / 控制項管理人、被指派填寫現況的人員。

角色速覽（完整定義與 manager 全域代行慣例見 _overview §3；流程圖中的「manager」皆指專案層 manager）：

角色	一句話
manager	專案經理 — 輪次生命週期與批次動作的擁有者，可代行 auditor 的規劃寫入
auditor	稽核員 — 稽核規劃與判定的執行者
viewer	一般參與者 — 只能檢視

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

#	功能	說明	位置	詳述（field-level 子頁）
1	控制項 / AO 現況編輯	逐項填實作狀態（5 種）+ 現況描述、備註，各自獨立儲存	Tab0 右面板	現況編輯
2	程序書上傳與關聯	上傳或從程序書池挑，關聯到控制項層 / AO 層	Tab0 右面板	現況編輯
3	樹導覽 / 搜尋 / 篩選	群組→控制項→AO 三層樹；關鍵字 + 完成度 / 狀態篩選；覆核輪控制項節點帶「上輪未通過」badge（v1.10.0 FR-053.1，prev_round_verdict==='not_met'）+ 右面板「上輪判定參照」區（prev_round_findings[]，讀母輪 AR）	Tab0 左樹	本頁 §5／§10／§12 坑 7
4	任務檢視與編輯	AO 證據蒐集任務逐欄配置（指派 / 部門 / 設備 / 問卷 / 檢測工具，v1.10.0 起 FR-056）；一個 AO 可有多筆任務，以籤列選一筆、右側顯示該筆表單	Tab0 AO 面板	任務配置與啟動
4a	新增 / 刪除任務	本頁直接開一筆任務（只填名稱即可存，後端自己在流程圖上掛成平行分支）；刪除帶確認。只在規劃期開放，且每個 AO 至少保留一筆	Tab0 AO 面板任務區塊	任務配置與啟動
5	快速配置	多選人員一鍵併入所有可編輯任務	Header 按鈕	任務配置與啟動
6	開始執行任務	PM 把已指派任務批次轉 PROCESSING + 通知；FR-056：一併自動派 detection_tool 任務首次掃描	Header 按鈕（限 PM）	任務配置與啟動
7	SSP 現況 Excel 匯出 / 匯入	三步驗證管線批次維護現況	批次維護選單	批次維護
8	任務配置 Excel 匯出 / 匯入	三步驗證管線批次維護任務指派	批次維護選單	批次維護
9	SSP 文件匯出	匯出正式文件（docx / pdf / odt / …）	批次維護選單	批次維護
10	三張進度卡	SSP 完成度 / 任務配置 / 證據蒐集進度；每張都可點開未設定清單，點一項直接跳到那個節點（與範本編輯頁共用同一組元件）	Header	本頁 §10
11	階段推進橫幅	輪次階段進度與前置、推進到下一階段	頁面頂部橫幅	FlowPhaseBanner
12	群組 / 控制項層參與人員	對群組 / 控制項節點指派管理人員（影響三層編輯權）	Tab0 Group / Control 面板	現況編輯
13	系統安全計畫（SSP）編輯	SSP 完整編輯（系統特性 / 單位人員 / 元件 / 授權 / 資產）；元件/外部授權/系統資產區手動新增/編輯已補同名查重（v1.10.0 CM-766，GRC_409037）	Tab1	系統安全計畫編輯器
14	專案基本資訊	名稱 / 描述 / 起訖日期（改名觸發 Drive 改名）	Tab2	基本資訊與參與人員
15	專案參與人員	專案層角色指派，全量覆寫、owner 保護	Tab3	基本資訊與參與人員
16	程序書池 / 雲端整合	程序書集中管理；Drive 等第三方整合設定；Tab5 僅 tenant drive 已連接（status===CONNECTED）時顯示，未連接直接隱藏（v1.10.0 FR-052，fail-closed）	Tab4 / Tab5	程序書池 / 專案雲端整合

本頁（hub）只細講左樹導覽（3）與進度卡（10） 這兩塊頁級功能；其餘每一列的逐欄規格（畫面欄位 / 逐支 API request-response / DB / 坑）都在「詳述」欄的子頁。§2 UC 為索引，指向子頁的核心流程。

2. Use Case（索引）

本頁的核心流程圖分散在各子頁；下表為 UC 索引：

UC	主題	在哪頁
UC-PP-01	填寫控制項 / AO 現況說明	現況編輯
UC-PP-05	上傳程序書並關聯到控制項 / AO	現況編輯
UC-PP-08	群組 / 控制項層參與人員管理	現況編輯
UC-TE-01 / UC-PP-02	AO 任務逐欄編輯 / 快速配置與開始執行	任務配置與啟動
UC-PP-03 / UC-PP-06 / UC-PP-07	SSP 現況匯入 / 任務配置匯入 / SSP 文件匯出	批次維護
UC-PP-09	編輯專案基本資訊與參與人員	基本資訊與參與人員
UC-PP-04	推進階段（FlowPhaseBanner）	FlowPhaseBanner

3. 權限矩陣（頁級速覽）

專案層角色基調見 _overview §3。本頁涉及的守門點速覽（細節在各子頁 §3）：

操作	FE 判定	BE 強制	詳述
讀樹 / 讀 SSP	參與者即可	require_participant（common/middleware/permission/ssp_permission.py）	—
寫現況 / 程序書	三層遞進 canEdit（專案 → 群組 → 控制項 mgr，ProjectPlanningView.vue:663-679）	require_manager	現況編輯 §3
任務更新 / 快速配置	同三層 canEdit	⚠️ 無角色守門（僅 JWT）	任務配置 §3
開始執行任務	isProjectManager	_check_manager → GRC_403002	任務配置 §3
節點參與人員	canManage*Participants	assert_project_manager → GRC_403002	現況編輯 §3
基本資訊 / 參與人員（Tab2/3）	canEdit	⚠️ 只做可見性檢查、無角色守門	基本資訊 §3
階段推進	banner user_can_advance	stage main_roles → GRC_403050	FlowPhaseBanner §3

⚠️ FE/BE 權限不對齊是本頁的共通議題：FE 三層遞進允許「群組 / 控制項 manager」編輯，但 BE 各寫入面守門粒度不一（現況 require_manager、任務無守門、Tab2/3 無守門）——改權限務必兩端一起看，各面細節見對應子頁 §12。

4. 狀態機與前置條件

輪次 7 態狀態機（含轉換圖）見 _overview §2。本頁相關的頁級 gate：

條件	效果	出處
apStatus === 'planning'	canEditSsp=true：SSP 表單可編、匯入按鈕可用	ProjectPlanningView.vue:75
apStatus !== 'planning'	唯讀 banner + 表單 disabled（launch-audit 後凍結）	同上
apStatus === 'closed'	全頁禁用（closed_banner）	同上
任務指派	planning 階段內都可編（不受 SSP 編輯狀態影響）	FE 行為
新增 / 刪除任務（FR-112）	當前輪（round_no 最大者）狀態必須是 planning；離開規劃期後按鈕停用、原因常駐顯示在任務區塊上方，後端同步擋下回 GRC_412054	FE taskMutationBlockedReason（ProjectPlanningView.vue:1467-1474）；BE job_service._assert_round_in_planning()
每個 AO 至少一筆任務（FR-112）	只剩一筆時刪除鈕停用（原因「查核項目至少要有一個任務」）；後端兩個入口都擋（規劃頁刪除 → 套件 FLOW_ENGINE_412003；流程圖存檔 diff 會刪到零 → 整筆存檔拒絕）	FE canDeleteTask(aoId)（同檔 :1483-1485）；BE repo.delete_job() / WorkflowXmlSyncService.sync()
基本資訊 / 參與人員	不受輪次階段限制（見 基本資訊 §4）	—
Tab5「雲端整合」顯示（v1.10.0）	tenant drive status==='CONNECTED' 才顯示該 tab，其餘狀態（EXPIRED/REVOKED/DISCONNECTED）或查詢失敗一律隱藏（fail-closed）	ProjectPlanningView.vue::loadDriveStatus()（driveConnected.value = s?.status === 'CONNECTED'），v-if="driveConnected" 包住 Tab5

⚠️ BE 寫入 phase guard：SSP 寫入本身無 phase 檢查（見各子頁坑）——唯讀是 FE 鎖的。

5. UI 設計

實機截圖（STG，亮色模式，2026-07-05；帳號 blsit，專案「回饋整合設定」）：

版面骨架（hub 導航圖：各區塊標代表性 API，彩色區塊可點跳對應子頁）：

六個 Tab 各自的內容與所屬 spec（本頁 hub 只細畫 Tab0 的頁級底盤；各區塊 field-level 見子頁）：

Tab	內容	詳細規格在哪
[0] 控制項實作	左樹導覽 + 右面板：現況編輯 / 任務配置 / 批次維護 / 節點參與人員	現況→現況編輯、任務→任務配置、批次→批次維護
[1] 系統安全計畫	SSP 完整編輯（系統特性、單位/人員、元件、授權、資產）	系統安全計畫編輯器（SspTabPanel.vue）
[2] 基本資訊	專案名稱 / 描述 / 起訖日期	基本資訊與參與人員（ProjectBasicInfoPanel.vue）
[3] 參與人員	專案層角色指派	基本資訊與參與人員（ProjectParticipantsPanel.vue）
[4] 程序書管理	程序書池集中管理	程序書池（DocumentPoolPanel.vue）
[5] 雲端整合	專案 Drive 資料夾驗證與修復	專案雲端整合（ProjectCloudIntegrationsPanel.vue）

左樹導覽（頁級功能 3）：群組 → 控制項 → AO 三層樹；關鍵字搜尋 + 完成度篩選（全部 / 已填 / 未填）與狀態篩選；節點帶完成度徽章。右面板依左樹選中節點型別切換（群組 / 控制項 / AO 面板）。狀態呈現：儲存中 per-項目 spinner（sspSaving / taskSavingSet）；無 socket，儲存後前端 state 更新；TabView 支援 ?tab=N 直鏈。

內容區頂部麵包屑：PrimeVue Breadcrumb（ProjectPlanningView.vue:2274），最多三層——群組代碼（點回群組面板）→ 控制項代碼（點回控制項面板）→ AO 名稱（不可點，末層即當前位置）。breadcrumbItems computed 在同檔 :1112-1122。全站 layout 已有一條全域麵包屑，頁內這條只表達左樹的當前位置。

AO 面板的任務區塊（Master-Detail，FR-112）：一個 AO 可掛多筆任務，版面是「上籤列、下表單」——籤列用 PrimeVue TabView（AoTaskSection.vue:213-224）一籤一筆（顯示狀態點／名稱／指派摘要／類型），只有選中那一筆的表單會 mount（AoTaskForm.vue，AoTaskSection.vue:225-241）。只有一筆任務時籤列不顯示、表單佔滿（showList 判 tasks.length > 1，AoTaskSection.vue:66）。區塊標題列右側是「新增任務」；刪除在表單內。選取狀態每個 AO 各記一筆，回到看過的 AO 會停在上次那筆；新增後自動選中新那筆並聚焦名稱欄；刪除後選相鄰一筆。任務排序依建立時間（BE ORDER BY je.created_at ASC, je.id ASC，ssp_control_implementation_query.py:77/113）。

任務區塊的提示條（常駐一行小字，不是 toast）：① 不能增減任務時顯示原因（凍結／無權限／唯讀，AoTaskSection.vue:171-173）；② 任務超過 20 筆時提示流程圖會不易閱讀（TASK_COUNT_HINT_THRESHOLD，ProjectPlanningView.vue:1465）——只是提示，不擋新增（不設硬上限）。

⚠️ 停用原因不可只掛 tooltip：停用的按鈕收不到 mouseenter，PrimeVue tooltip 永遠不會出現，使用者只看到按鈕按不下去、不知道為什麼。故原因一律常駐在提示條上，tooltip 只是附加。

6. API 規格

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

6.1 總清單（本頁呼叫的全部 endpoint）

分類	Method + Path	說明	完整規格
載入	POST /projects/{uid}/audit-rounds/list	輪次清單 → apStatus / sspUid	§6.2
載入	GET /ssp/{sspUid}/control-tree	三層樹 + 內嵌任務，一次載入 Tab0	§6.2
載入	GET /grc/project/{uid}/task-execution/progress	證據蒐集執行進度卡	§6.2
載入	GET /grc/project/{uid}、/org-units/menu・/users/menu・/surveys/menu、POST /devices	專案資料 + 四種下拉	GAI-SD-02
載入	GET /integrations/google-drive	v1.10.0 FR-052 新用途：Tab5「雲端整合」顯示 gate 的狀態來源（reuse 既有端點，零 BE 改動）——判 status==='CONNECTED'	專案雲端整合 §6
現況 / 程序書	GET/PUT .../control-implementation/{cid}・.../objective/{stmt}、.../reference-documents	現況編輯 / 程序書	現況編輯 §6
節點參與人員	POST/PUT/DELETE /control-group-participant・/project-control-participant	群組 / 控制項人員	現況編輯 §6
任務	PUT /grc/project/{uid}/job/{jobId}、POST .../start-task-execution	任務更新 / 開始執行	任務配置 §6
任務增刪（FR-112）	POST /grc/project/{uid}/assessment-object/{aoUid}/jobs、DELETE /grc/project/{uid}/job/{jobUid}	新增 / 刪除任務（兩者都只在規劃期放行）	任務配置 §6
批次	.../control-implementations/*・.../jobs/*・/ssp/{uid}/export	三步匯入 / 文件匯出	批次維護 §6
基本資訊	GET/PUT /grc/project/{uid}	Tab2/3 基本資訊 + 參與人員	基本資訊 §6
階段	GET/POST .../stage/info・.../stage/advance	階段推進	FlowPhaseBanner §6

6.2 載入類（hub 頁級）

[POST] /projects/{project_uid}/audit-rounds/list

輪次清單（頁面據此定位當前輪次 → apStatus / sspUid）。無 body。Response data（陣列，每項）：uid / name / round_no / round_type（initial·surveillance·close-out）/ status（7 態）/ parent_round_uid / ap_uid / ssp_uid（planning 期為 null 用 living）/ ar_result_id / poam_id / flow_template_snapshot_uid / workflow_execution_uid / start_at / end_at / created_at / created_user / created_user_name。出處：app/grc/service/audit_round_app_service.py:164-191（_to_dto）

[GET] /ssp/{ssp_uid}/control-tree

三層樹一次載入（含每個 AO 內嵌任務）。無 query。Response data.groups[] 各層節點：

• Group：id / code / name / total_controls / controls[]
• Control：id / uid / code / control_identifier / name / ssp_implementation_status / implementation_description / is_reviewed / reviewers[] / assessment_objects[] / prev_round_verdict（not_met/met/null，v1.10.0 FR-053.1，僅覆核輪有值）/ prev_round_findings[]（{title,severity,description,run_no}，同上）
• AO：id / uid / statement_identifier（_obj.N）/ title / ssp_implementation_status / ssp_implementation_description / is_reviewed / reviewers[] / workflow_template_uid / workflow_execution_uid / jobs[]（可多筆，依建立時間排序）
• Job：id / uid / name / description / guide / job_type / status / assignees[]（{uid, user_uid, name, user_name, user_login_name, is_approver, role}）/ departments[] / devices[] / surveys[]（{id, name, source_survey_uid, snapshot_uid, approval_required}）

名稱取圖上、其餘取 DB：name 以流程圖 userTask 的 name 為準（圖上改名要反映到規劃頁），查不到才 fallback job_executions.name；description / guide / job_type 一律讀 DB 欄位（ssp_control_implementation_service.py:511-515）。圖上那幾個同名 camunda 屬性是不再讀寫的殘留（見 任務配置 §12）。

出處：app/oscal/service/ssp_control_implementation_service.py:265-491（build_control_tree_by_ssp_id）

控制項母體怎麼決定（同一支 endpoint、三種母體，2026-08-02 補齊）：

輪次情境	母體來源
初始輪 / 持續監督輪（living SSP）	ProfileResolutionService.resolve 的 in-scope 全集
已凍結輪（round.ssp_id == 傳入 ssp_id）	本輪 AP reviewed_controls（FR-053 ⑥，鎖在 launch 當下的範圍）
覆核輪規劃階段（close-out + ssp_id IS NULL + 有 AP）	本輪 AP reviewed_controls（＝母輪未通過控制）；2026-08-02 新增 _is_planning_stage_reverify 分支

AP 缺 / 解析為空 → 防禦 fallback 回 profile resolve + log warning，不 500。 覆核輪範圍規則見 _overview §4。

[GET] /grc/project/{project_uid}/task-execution/progress

Response data：{total, completed, in_progress, not_started}（進度卡）。出處：api/grc/serializers/task_execution.py:11-17

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

檔案	角色	對應子頁
src/views/project/ProjectPlanningView.vue	主檢視（約 2,780 行；樹、面板、匯入匯出、快速配置、任務的建立／刪除／儲存與所有 API 呼叫都在此）	各 Tab0 子頁
src/components/grc/planning/AoTaskSection.vue	AO 任務區塊的殼：標題列＋新增鈕＋提示條＋TabView 籤列	任務配置
src/components/grc/planning/AoTaskForm.vue	選中那一筆任務的完整表單（原任務卡內容搬入）	任務配置
src/components/grc/planning/PlanningStatsBar.vue ＋ src/components/grc/StatCard.vue / UnfilledListOverlay.vue	三張進度卡與未設定清單浮層（與範本編輯頁共用）	本頁 §10
src/composables/usePlanningStats.js / usePlanningJump.js	進度卡的數字與未設定清單 / 點一項跳到該節點	本頁 §10
src/utils/detectionAssignmentParams.js	檢測任務分派列的參數組裝與比對（存檔擋門在父頁、渲染在表單，規則只有一份）	任務配置
src/assets/_planning-layout.scss	本頁與範本編輯頁共用的版型（面板、籤列接合、左樹分欄）	—
src/config/router/index.js:785-848	三條 route：project-planning（legacy）/ -ap / -round（v2 推薦）	—
src/components/grc/FlowPhaseBanner.vue	階段推進橫幅	FlowPhaseBanner
src/components/grc/ssp/SspTabPanel.vue	Tab1 SSP 編輯	SSP 編輯器
src/components/grc/project/ProjectBasicInfoPanel.vue / ProjectParticipantsPanel.vue	Tab2 / Tab3	基本資訊
src/components/grc/ParticipantsPanel.vue	節點參與人員 dialog	現況編輯
SspImportDialog / JobImportDialog	批次匯入 dialog	批次維護
src/service/SspService.js / menuStore.js	SSP API 包裝 / 下拉資料	—

8. 後端檔案地圖（本頁載入鏈）

鏈路	Route	App Service	底層
控制項樹	api/oscal/routes/ssp/ssp_control_implementation_route.py::SspControlTreeRoute	get_control_tree → build_control_tree_by_ssp_id（免權限核心，背景任務共用）	ProfileResolutionService.resolve + catalog repos + per-AO prep-job 反查
執行進度卡	同檔 TaskExecutionProgressRoute	get_prep_job_progress	沿 living SSP → catalog → workflow → job 鏈統計
輪次列表	api/grc/routes/（audit rounds）	audit_round_app_service.py::list_rounds	compliance.project_audit_rounds

DDD 提醒：各寫入 API 的鏈路與守門在對應子頁 §8；新增本頁 API 照層級走（route 不碰 DB、app service @transaction、寫入加角色檢查）——現況有數處沒守到（見各子頁 §12），別複製。

9. DB

9.1 資料表總清單（讀取鏈 + 寫入指向子頁）

表	讀/寫	說明	詳述
compliance.project_audit_rounds	讀	稽核輪次主檔（7 態、BPMN 綁定、凍結 SSP 指標）	§9.3
compliance.project_extensions	讀	living_ssp_id 是本頁編輯的 SSP 錨點	§9.3
compliance.projects / project_participants	讀 / 寫	專案主檔 / 參與者	基本資訊 §9.3
oscal.system_security_plans / profile_imports / catalog_*	讀	SSP → catalog 導航 + 控制結構	GAI-SD-03
oscal.ssp_implemented_requirements / ssp_statements / ssp_reference_documents	寫	現況 / 程序書	現況編輯 §9.3
compliance.job_executions + task_assignees / org_units / devices ・ survey.task_surveys	寫	任務 + 四關聯	任務配置 §9.3
compliance.control_group_participants / project_control_participants	寫	節點參與人員	現況編輯 §9.3
compliance.stage_objects	讀	階段行為定義	FlowPhaseBanner §9.3

9.3 核心表欄位（hub 頁級：輪次 + 錨點）

compliance.project_audit_rounds — 稽核輪次主檔

FR-038 核心實體：一專案多輪，每輪 launch-audit 時 snapshot living SSP。狀態機 7 態，覆核（close-out）開新輪以 parent_round_id 串回母輪。

欄位	型別	說明
uid	varchar(36)	對外識別碼
project_id	bigint	→ compliance.projects.id（soft ref）
round_no / name	int / varchar	輪次序號 / 名稱
round_type	varchar(20)	initial / close-out / surveillance
status	varchar(20)	7 態（見 _overview §2）
parent_round_id	bigint｜null	覆核母輪 self-FK；NOT NULL ⟺ close-out
assessment_plan_id / ssp_id	bigint｜null	本輪 AP / 凍結 SSP 快照
ar_result_id / poam_id	bigint｜null	稽核 / finalize 回填
flow_template_snapshot_uid / workflow_execution_uid	varchar(36)｜null	凍結 BPMN 範本 / main workflow

compliance.project_extensions — 專案擴展（1:1）

欄位	型別	說明
project_id	int	→ compliance.projects.id（1:1，CASCADE）
living_ssp_id	bigint｜null	專案 living SSP（soft ref）——本頁編輯的 SSP 錨點；profile / catalog 由 ssp.import_profile_id → profile_imports.source_catalog_id 導航
module_frame_id / owner_id	int｜null	啟動範本參考 / 專案負責人

各寫入表的欄位卡在對應子頁 §9.3（現況 / 任務 / 節點人員 / 基本資訊各自）。

10. 頁面邏輯與資料對應

載入時序：

進度卡計算：

進度卡	單位	分子 / 分母怎麼算	來源
現況說明	控制項	走訪樹的控制項，sspDescriptions[ctrl.id] 有值即算已填	sspStats（usePlanningStats.js:18-27）
任務設定	任務（FR-112 起，原為 AO）	Σ 各 AO 的任務數 / Σ 已指派人員的任務數（countTasks(ao)，ProjectPlanningView.vue:905-909）	taskStats（usePlanningStats.js:29-41）
證據蒐集	任務	BE 直接給，FE 不算	/task-execution/progress 的 {total, completed, in_progress, not_started}

「任務設定」為什麼改以任務為單位：平行多任務後，若分母是「有任務的 AO 數」，新增一筆空任務分母不動——畫面上看不出還有幾筆沒指派。改成數任務後與「證據蒐集」卡同一分母口徑。連帶「本輪無任務的 AO 不進分母」自然成立（0 筆任務貢獻 0）。

點卡片開未設定清單（三張卡皆可，UnfilledListOverlay）：浮層列出還沒設定的項目，點一項會展開左樹到該節點、選取它、捲動過去並閃一下（usePlanningJump.js:35-58），浮層隨即關閉（蓋在頁面上，留著會擋住剛跳到的那一項）。清單項目一律帶齊 groupId/controlId/aoId/taskId，跳轉端不必回頭反查樹。「誰算未設定」與「點了跳去哪」留在各呼叫端——三張卡判準不同（現況看 SSP 描述、任務設定看有無指派人、證據蒐集看任務狀態），下放到共用元件會讓它變成兩頁的聯集。

載入流程：輪次清單 → 定位當前輪次（apStatus / sspUid）→ control-tree 一次載入 Tab0 全資料（樹 + 內嵌任務）+ 進度卡並行。各子頁的儲存更新本地 state，不重拉樹（除匯入 confirm 後 fetchTree() 全重載）。

11. 背景行為與外部依賴

類型	內容
全站小改（v1.10.0）	輪次名稱雙語化：顯示端不再讀 DB name 欄（降級為 fallback），改由 FE useRoundName() composable 依 round_no+round_type 現場組 i18n 字串（src/composables/useRoundName.js），零 migration；錯誤 toast 全域去重（App.vue::handleAxiosError 1 秒視窗內同 error_code::message 只顯示一次，40 檔 147 處元件重複 toast 已收斂至此唯一出口）
Socket	本頁無 socket / 輪詢；資料更新靠操作後的 state 更新與手動重載
通知	「開始執行任務」→ 按人聚合送站內通知（見 任務配置 §11）
Drive 同步	專案改名 → best-effort（見 基本資訊 §11）
BPMN	任務由輪次綁定的 BPMN 範本 userTask 衍生；階段推進 = BPMN 引擎前進（見 FlowPhaseBanner）
jedi-* 套件	jedi-oscal-v2（SSP/catalog）、jedi-flow-engine（job/workflow）、jedi-survey（問卷）、jedi-auth（JWT）
系統參數	無 feature flag；BPMN 範本預設值來自 module_frames.audit_flow_template_uid

12. 邊界情況與已知坑（跨區塊）

各功能區塊的坑在對應子頁 §12；此處只留跨區塊 / 頁級的坑：

1. AO 識別碼 _obj.N、任務文案真相在 BPMN userTask、v1 表已 drop：見 _overview §5——影響現況與任務兩塊。
2. 無 socket 多人協作：多人同時編輯互相看不到；後儲存者覆蓋（props 整包 update）。客戶端多人協作要留意——跨所有 Tab0 編輯面。
3. 舊 route 相容：/ap/:apUid/planning 是 legacy，行為與 round route 有差（round 才有 stage banner 完整功能）；修 bug 先確認使用者走哪條 route 進來。
4. FE/BE 權限守門粒度不一（跨面）：現況 require_manager、任務無守門、Tab2/3 無守門——見 §3 與各子頁 §12；改權限要通盤看。
5. Tab5「雲端整合」顯示 gate 是純 FE 判斷（v1.10.0 FR-052）：BE 端零改動——reuse 既有 GET /integrations/google-drive（本就對全 JWT 開放，非新暴露），FE 判 status==='CONNECTED' 才渲染 tab。查詢失敗預設 driveConnected=false（fail-closed，寧可誤藏不誤顯示連不上的 tab）。若日後要改「未連接顯示但 disabled + 引導文案」需重新設計，目前是直接不渲染。
6. 元件/外部授權/系統資產同名查重（v1.10.0 CM-766）：手動新增/編輯 dialog（ComponentsLeveragedInventoryTab.vue，Tab1 SSP 編輯內嵌）補同名查重，撞名回 GRC_409037（「名稱重複，同一系統安全計畫內已有同名資料」）；無 FE 專屬處理，走全域 axios interceptor toast（見全站錯誤 toast 去重機制）。批次 Excel/docx 匯入的同批次去重已在此之前擴及所有資料類型，兩者是獨立防呆（批次去重防同批次內重複、本項防與既有資料撞名）。
7. 「上輪未通過」badge 只在覆核輪出現（v1.10.0 FR-053.1）：prev_round_verdict/prev_round_findings 由 BE build_control_tree_by_ssp_id 附加在 control-tree 回應的控制節點上，僅覆核輪（close-out + parent_round_id 有值）才會有值（讀母輪 AR：assessment_findings + finding_risks→risks.characterizations.severity）；初始輪 / 凍結輪 / living 非覆核輪一律 null/[]。同一 control-tree API 也被 專案總覽頁 呼叫，但該頁未渲染此 badge（見該頁 §12 坑 11）——要看上輪脈絡必須在本頁。
8. 覆核輪左樹只有「需複驗」那幾條，是預期行為（2026-08-02）：覆核輪的控制項母體＝母輪未通過控制（narrowed scope），規劃階段就已收斂，看不到母輪已通過的控制項是正確的（見 _overview §4）。三種母體來源見 §6.2。若覆核輪樹又出現母輪全集，先查兩件事：① 該輪 AP（ap_reviewed_controls）是不是被存行程時的 _backfill_scope_from_tasks 用行程聯集打回全集（→ 行程本身沒收斂，見 _overview §5 坑 5）② _frozen_round_control_scope 是否讀不到 AP 而 fallback 到 profile resolve（log 會有 warning）。
9. AO「已配置」＝底下每一筆任務都有指派人：aoHasAssignee() 用 every 不是 some（ProjectPlanningView.vue:886-892），備援路徑比 configured_job_count >= job_count。用 some 的症狀是新增的空任務被既有已指派那筆掩蓋——左樹綠勾與「任務設定」卡都看不出還有任務沒指派，且沒有任何錯誤訊息。此語意與 AO 完成判定（全部任務完成才算通過）同向。AO 卡的「未配置」標籤帶筆數（如 1/2 未配置），數的是 total - configured。
10. 新增／刪除任務的守門有兩層，錯誤碼刻意分開：「這一輪不能再動任務清單」是 GRC_412054，「這個任務不能退回」是既有的 GRC_412042——FE 規劃頁要能分辨兩者（按鈕與文案都不同），合成一碼會讓停用提示指錯地方。另有第三種：「查核項目至少要有一個任務」用套件的 FLOW_ENGINE_412003，不另開主專案碼（同一件事兩個碼會讓 FE 維護兩組 i18n key）。
11. 未儲存保護用「表單有沒有發出過變更」的旗標，不比對 JSON 快照：值的持有者是父頁的 taskMap，而流程圖編輯器存檔會觸發 refreshTasks 整份換掉——快照當場過期，使用者什麼都沒改也會被攔一次。

13. 開發與驗證

• 跑起來：BE python main_socketio.py（port 8000，log 在 log/app.log）；FE 在 compliance-manager-fe/ 起 Vite dev server。BE 改 service code 後必須重啟（無 hot reload）
• 測試帳號：dev 環境 blsadmin（密碼見 .env / 部署文件）
• 導航路徑：登入 → 專案列表 → 進專案 → 輪次（planning 狀態）→ 專案規劃
• 前置資料：專案需已綁 ModuleFrame（才有 living SSP 與 BPMN 範本）；沒有輪次先在總覽頁建立
• E2E：compliance-manager-test/（Cucumber + Playwright），以 專案規劃 / planning 搜尋
• 相關子頁：現況編輯 / 任務配置 / 批次維護 / 基本資訊 / FlowPhaseBanner；FR-038（v2 遷移）、FR-047（本次拆分）