手冊首頁／專案與任務／專案管理功能群總覽

專案管理功能群總覽

本檔放「本功能群多個頁面共用的知識」：頁面地圖、稽核輪次狀態機、角色權限基調、核心資料模型。

各頁面 spec 引用本檔，只寫自己頁面的差異——改共用邏輯時改這裡一份。

1. 頁面地圖

頁面	FE route	用途一句話	spec
專案列表頁	`/project/projects`	專案清單、建立入口	✅ 專案列表頁
專案建立	`/project/projects/new`	三步精靈成立專案（clone 資源庫三件組）	✅ 專案建立
專案總覽頁	`/project/projects/:id/round/:roundUid`	單一專案儀表板、輪次切換與階段導覽中樞	✅ 專案總覽頁
專案規劃頁	`/project/projects/:id/round/:roundUid/planning`	planning 階段主工作區：SSP 現況 + 任務指派 + 程序書	✅ 專案規劃頁
稽核計畫填寫頁	`/project/projects/:id/round/:roundUid/ap-authoring`（屬稽核執行群）	audit_planning 階段：AP 行程 / 查核方法	→稽核執行群

頁面 × 階段對應：每個稽核輪次階段有一個「主場頁面」——

planning        → 專案規劃頁（本群）
audit_planning  → 稽核計畫填寫頁（稽核執行群）
auditing        → 稽核執行頁（稽核執行群）
remediation     → POA&M 頁（稽核執行群）
closed          → 各頁唯讀

2. 稽核輪次狀態機（本群與稽核執行群共用的核心）

模型：一個專案 = 一輪主稽核 + N 輪覆核（close-out）；輪次實體是 compliance.project_audit_rounds，狀態由綁定的 BPMN workflow（jedi-flow-engine）驅動。

稽核輪次狀態機：7 態與轉換動作（動作後的英文 = API endpoint，括號 = 允許角色）

轉換權限與前置條件（BE 強制，enforcement 在 app/grc/service/audit_round_app_service.py）：

轉換	誰能按	前置條件	失敗 error code
建立輪次 → planning	manager	專案有 living SSP	`GRC_ROUND_LIVING_SSP_MISSING`
啟動稽核 launch-audit → audit_planning	manager	status=planning、living_ssp_id 非空	`GRC_ROUND_PHASE_READONLY` 等
開始稽核 start-auditing → auditing	auditor（manager 可代行）	status=audit_planning、AP 已存在
結束本輪 close-round	manager	POA&M 全部 closed
啟動複驗 launch-reverify	auditor（manager 可代行）	status=pending_reverify

通用 phase guard：寫入 API 用 common/util/round_guard.py 的 assert_round_phase(round, {允許階段})，階段不符回 GRC_ROUND_PHASE_READONLY（412）。新增本群寫入 API 時必加。

3. 角色權限基調

角色是誰：

manager（專案負責人）——開專案、定範圍、指派任務，時機到了啟動稽核輪次。「身為 manager，我要規劃這輪稽核要涵蓋哪些控制項、指派誰負責，準備好就啟動稽核。」
auditor（稽核員）——規劃期可協助編修稽核計畫，主戰場在稽核執行群。「身為 auditor，我要在規劃期先看到專案範圍與 SSP 現況，為稍後的判定做準備。」
viewer（一般參與者，如受評方成員）——只能檢視進度。「身為 viewer，我要能查看目前規劃到哪，不需要編輯權限。」

專案層角色（compliance.project_participants.role）：manager / auditor / viewer（一般參與者）。

動作類型	manager	auditor	viewer
輪次生命週期（建立 / launch / close）	✓	✗	✗
稽核規劃寫入（AP / 任務指派）	✓（全域代行）	✓	✗
檢視	✓	✓	✓

manager 全域 override 慣例：BE 檢查 auditor 的地方一律允許 manager 代行（role not in ("auditor", "manager") 才拒絕）。

頁內三層遞進（專案規劃頁特有，FE 判定）：專案 manager → 控制群組 manager → 控制項 manager，任一層即可編輯該層以下內容；詳見專案規劃頁 §3。

4. 核心資料模型

專案管理核心資料模型（藍 = compliance 業務層、黃 = oscal 合規資料層）

living vs 凍結 SSP（本群最重要的概念）：

living SSP（project_extensions.living_ssp_id）＝專案「現在」的控制項實作狀態，專案規劃頁編輯的就是它
凍結快照（project_audit_rounds.ssp_id）＝ launch-audit 當下拍的快照，稽核後續階段（AP / AR）都基於快照，living 繼續演進不影響本輪稽核
讀控制項結構一律從 projects.uid → living_ssp_id → profile_imports → catalog_controls 解析（不要繞舊 v1 表）

5. 本群共用的已知坑