專案規劃頁（Project Planning）

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

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

變更紀錄：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）：

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

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

2. Use Case（索引）

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

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

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

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

4. 狀態機與前置條件

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

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

5. UI 設計

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

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

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

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

6. API 規格

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

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

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[]
• 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}）

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

[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/）

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

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

9. DB

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

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

compliance.project_audit_rounds — 稽核輪次主檔

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

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

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

10. 頁面邏輯與資料對應

載入時序：

進度卡計算：

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

11. 背景行為與外部依賴

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；改權限要通盤看。

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（本次拆分）