GRC 多輪稽核架構變更 — 前端溝通規格書

日期：2026-03-24 狀態：Draft — 待前後端確認

目前系統假設「一個專案 = 一個 Assessment Plan（AP）」，所有 GRC API 都用 project_uid 去查唯一的一組控制項資料。

但實際業務需求是：一個專案會經歷多輪稽核（每年一次），每一輪都有自己獨立的控制項結構、任務、證據、稽核結果。所以需要改為「一個專案 = 多個 AP」，每個 AP 代表一輪稽核。

現在的流程

專案列表 → 點進專案 → 直接看到控制項群組 / 任務設定 / Dashboard

改後的流程

專案列表 → 點進專案 → 選擇稽核輪次（AP） → 看到該輪的控制項群組 / 任務 / 稽核結果
                         ↑
                    新增的一步：選擇 AP

前端進入專案後需要多一個「稽核輪次選擇」的步驟（或預設選最新的 AP）。

3.1 稽核輪次選擇

進入時機： 點進專案後、進入控制項列表前

資料來源： GET /grc/project/<project_uid>/assessment-plans/menu

回傳格式：

[
  {
    "uid": "ap-uuid-001",
    "name": "2025 年度稽核",
    "round_number": 1,
    "status": "closed",
    "created_at": "2025-03-15T00:00:00"
  },
  {
    "uid": "ap-uuid-002",
    "name": "2026 年度稽核",
    "round_number": 2,
    "status": "in_progress",
    "created_at": "2026-02-20T00:00:00"
  }
]

AP status 值：

建議 UI：

• 下拉選單 或 Tab 切換
• 預設選中 status 不是 closed 的那筆（最新進行中的）
• 如果全部 closed，選最新的（round_number 最大）
• closed 的 AP 進入後為唯讀模式

3.2 Phase 3 稽核頁面（未來 Stage 2 實作）

稽核人員專用介面，逐控制項寫入 verdict + findings。Phase 3 的前端規格會在 Stage 2 開始前另行提供。

3.3 POA&M 追蹤頁面（未來 Stage 3 實作）

矯正階段的追蹤總覽。Stage 3 開始前另行提供。

核心變更：URL 加入 ap/<ap_uid> 路徑段

所有需要查詢控制項結構的 API，URL 從：

/api/1.0/grc/project/<project_uid>/...

改為：

/api/1.0/grc/project/<project_uid>/ap/<ap_uid>/...

變更對照表

不變的 API

以下 API 不需要改，前端不用調整：

向下相容

過渡期間，如果 ap_uid 未帶，後端會自動 fallback 取該專案最新的 AP。但建議前端盡快遷移到新 URL。

5.1 AP 列表

GET /api/1.0/grc/project/<project_uid>/assessment-plans/menu

Response：

{
  "code": 1,
  "data": [
    {
      "uid": "string",
      "name": "string",
      "round_number": 1,
      "status": "active | auditing | remediation | closed",
      "created_at": "2025-03-15T00:00:00"
    }
  ]
}

現有路由結構（推測）

/grc/projects                              → 專案列表
/grc/project/:projectUid                   → 專案詳情
/grc/project/:projectUid/task-setup        → 任務設定
/grc/project/:projectUid/control-groups    → 控制項群組
/grc/project/:projectUid/control-group/:groupUid/controls  → 控制項
...

建議調整

/grc/projects                              → 專案列表（不變）
/grc/project/:projectUid                   → 專案詳情（不變）
/grc/project/:projectUid/rounds            → 稽核輪次列表（新增，或整合在專案詳情頁）
/grc/project/:projectUid/ap/:apUid/task-setup
/grc/project/:projectUid/ap/:apUid/control-groups
/grc/project/:projectUid/ap/:apUid/control-group/:groupUid/controls
/grc/project/:projectUid/ap/:apUid/control-group/:groupUid/control/:controlUid
...

關鍵：URL 中加入 ap/:apUid，讓每個頁面知道當前在看哪一輪稽核。

專案列表 — project.status

AP 輪次 — AP status（phase）

POA&M 狀態（Phase 4，未來實作）

AR Verdict（Phase 3，未來實作）

Stage 1 完成後前端可以先行遷移 URL，後續 Stage 2-4 會逐步提供新頁面的規格。

Stage 1 上線後，前端需要：

• 呼叫 AP 列表 API，在專案詳情頁 or 側邊欄顯示稽核輪次選擇
• 將選中的 apUid 存入路由 params 或狀態管理
• 更新以下頁面的 API 呼叫，URL 加入 /ap/{apUid}：
  • Task Setup 頁
  • Control Groups 列表頁
  • Control Group 詳情頁
  • Controls 列表頁
  • Control 詳情頁
  • Control + AO 詳情頁
  • AO 列表頁
  • Job 列表頁
  • Job 新增
  • Control Review（sign-off）
  • AO Review
• 確認以下頁面不需要改：
  • 專案列表 / 詳情 / 更新
  • My Jobs
  • Job 詳情 / 更新 / 刪除
  • Job Comment
  • Job Evidence
  • SSP 編輯
  • Dashboard

Q: 現有專案只有一個 AP，遷移後怎麼辦？ A: 不需要做資料遷移。AP 列表 API 會回傳該專案唯一的那筆 AP，前端選中它即可。向下相容邏輯也會自動 fallback。

Q: 選定 AP 後，AP 的 status 會影響哪些操作？ A: 後端會根據 AP status 限制操作權限（例如 closed 狀態不能新增 job、不能修改 review）。前端可以依據 AP status 決定是否顯示編輯按鈕。

Q: Dashboard 要不要也分 AP？ A: 第一階段 Dashboard 維持現有邏輯（自動取最新 AP），不需要帶 ap_uid。未來可能加 AP 篩選。

Q: My Jobs 頁面要不要顯示是哪一輪的任務？ A: My Jobs 回傳資料已包含 project_name，未來會加上 round_number 或 ap_name 欄位讓前端顯示。