Stage 2：外部稽核（Phase 3）設計規格

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

目標

實作 GRC 合規管理系統的外部稽核流程（Phase 3），讓稽核員能逐控制項寫入稽核判定（verdict）與發現（findings），並在稽核結束時自動處理矯正流程。

範圍

• Phase 3 完整流程：launch_audit → 稽核員寫 verdict/findings → confirm_audit
• confirm_audit 自動產生 POA&M 記錄 + revert 失敗 AO 的 workflow
• AP status 擴充至 4 值生命週期
• 不包含：POA&M 前端追蹤頁面 / CRUD API（Stage 3）

設計決策摘要

Enum 變更（jedi-oscal）

移除 draft、completed、archived，最終 4 個值：

class AssessmentPlanStatus(StrEnum):
    ACTIVE = "active"           # Phase 1+2：任務指派 + 執行
    AUDITING = "auditing"       # Phase 3：外部稽核
    REMEDIATION = "remediation" # Phase 4：矯正
    CLOSED = "closed"           # 本輪結案

狀態轉換

active → auditing → remediation → closed
              ↘                      ↗
               ──── (全 pass) ──────

每個轉換 API 檢查當前 status 是否在合法的「從」狀態，不合法拋 PreconditionFailedError。

3.1 launch_audit — 啟動外部稽核

POST /api/1.0/grc/project/<project_uid>/ap/<ap_uid>/launch-audit

權限： auditor 或 project owner

Request body：

{
  "force": false
}

流程：

1. 驗證 AP status = active
2. 驗證呼叫者權限
3. 統計未完成 tasks（assessment_plan_tasks.status != "completed"）
4. 若有未完成 tasks 且 force = false → 回傳 warning，不執行
5. 若 force = true 或無未完成 tasks → 執行：
   • 查詢該 AP 是否已有 AR（start_oscal_project 會建立空白 AR）
   • 有現有 AR：在該 AR 下建立 assessment_result_datas（run_no=1）+ 初始化 assessment_result_controls（verdict = null）
   • 無現有 AR：建立 assessment_results（含 metadata + document）+ assessment_result_datas（run_no=1）+ 初始化 assessment_result_controls（verdict = null）
   • AP status → auditing

注意： start_oscal_project 已會建立空白 AR（只有 AR 本體，無 run 和 controls），因此 launch_audit 通常是在現有 AR 下新增 run + controls，而非重建 AR。

Warning response（force=false 且有未完成 tasks）：

{
  "code": 1,
  "data": {
    "can_launch": true,
    "warning": true,
    "incomplete_tasks": 5,
    "total_tasks": 20
  }
}

Success response：

{
  "code": 1,
  "data": {
    "ar_uid": "...",
    "status": "auditing",
    "incomplete_tasks": 5,
    "total_tasks": 20
  }
}

Service： app/project/service/oscal_audit_service.py → launch_audit(ap_uid, force, curr_user)

3.2 AR Controls 列表

POST /api/1.0/grc/project/<project_uid>/ap/<ap_uid>/ar/controls/list

權限： 所有專案參與者

Request body： 標準 RequestMetaSchema（pager + sort + filters）

Filters：

Response item：

{
  "ar_control_uid": "...",
  "control_id": "AC-1",
  "control_title": "Access Control Policy",
  "verdict": "fail",
  "confidence": 85,
  "findings_count": 2,
  "group_uid": "...",
  "group_name": "Access Control"
}

前端依 group_uid 分組建樹狀導航。

Service： app/grc/service/audit_service.py

3.3 AR Control 詳情

GET /api/1.0/grc/project/<project_uid>/ap/<ap_uid>/ar/control/<ar_control_uid>

權限： 所有專案參與者

Response：

{
  "data": {
    "ar_control_uid": "...",
    "control_id": "AC-1",
    "control_title": "Access Control Policy",
    "description": "...",
    "guidance": "...",
    "verdict": "fail",
    "confidence": 85,
    "rationale": "...",
    "remarks": "...",
    "group_uid": "...",
    "group_name": "Access Control",
    "ssp_implementation": {
      "implementation_status": "partial",
      "implementation_description": "..."
    },
    "findings": [
      {
        "uid": "...",
        "category": "deficiency",
        "severity": "high",
        "title": "...",
        "description": "...",
        "recommendation": "...",
        "ao_uid": "...",
        "ao_name": "..."
      }
    ],
    "assessment_objects": [
      {
        "ao_uid": "...",
        "ao_name": "...",
        "evidences": [
          {
            "uid": "...",
            "evidence_type": "file",
            "description": "...",
            "file_id": 123,
            "reference_url": null
          }
        ]
      }
    ]
  }
}

3.4 寫入 Verdict

PUT /api/1.0/grc/project/<project_uid>/ap/<ap_uid>/ar/control/<ar_control_uid>/verdict

權限： auditor

前置條件： AP status = auditing

Request body：

{
  "verdict": "pass | fail | partial | na",
  "confidence": 85,
  "rationale": "...",
  "remarks": "..."
}

Response： 更新後的 ar_control 資料

3.5 Finding CRUD

新增 Finding：

POST /api/1.0/grc/project/<project_uid>/ap/<ap_uid>/ar/control/<ar_control_uid>/findings

Request body：

{
  "category": "deficiency | observation | recommendation",
  "severity": "low | medium | high | critical",
  "title": "...",
  "description": "...",
  "recommendation": "...",
  "ao_uid": "..."
}

ao_uid 必填 — 指定哪個 AO 需要矯正。

新增 Finding response：

{
  "code": 1,
  "data": {
    "uid": "...",
    "category": "deficiency",
    "severity": "high",
    "title": "...",
    "description": "...",
    "recommendation": "...",
    "ao_uid": "...",
    "ao_name": "..."
  }
}

注意： Stage 2 期間 finding 可自由刪除（AP status = auditing）。Stage 3 實作 POA&M CRUD 後，應加檢查防止刪除已有 POA&M 關聯的 finding。

Finding 詳情 / 更新 / 刪除：

GET    /api/1.0/grc/project/<project_uid>/ap/<ap_uid>/ar/finding/<finding_uid>
PUT    /api/1.0/grc/project/<project_uid>/ap/<ap_uid>/ar/finding/<finding_uid>
DELETE /api/1.0/grc/project/<project_uid>/ap/<ap_uid>/ar/finding/<finding_uid>

權限： auditor（寫入），所有參與者（讀取）

前置條件： AP status = auditing（寫入操作）

3.6 confirm_audit — 確認稽核結案

POST /api/1.0/grc/project/<project_uid>/ap/<ap_uid>/confirm-audit

權限： auditor 或 project owner

前置驗證：

1. AP status = auditing
2. 所有 ar_controls 必須有 verdict（非 null）

驗證失敗 response（412）：

{
  "code": 0,
  "msg": "以下控制項尚未填寫 verdict",
  "data": {
    "missing_verdicts": [
      {"control_id": "AC-1", "control_title": "Access Control Policy"},
      {"control_id": "AC-2", "control_title": "Account Management"}
    ]
  }
}

執行流程：

1. 收集所有 ar_controls 的 verdict

2. 判定路徑：

   • 全部 pass 或 na → 直接結案路徑（步驟 4）
   • 任一 fail 或 partial → 矯正路徑（步驟 3）

3. 矯正路徑：

   • 設定 assessment_result_datas.completed_at = now()
   • 收集所有 findings 的 ao_uid（去重）
   • 對每個被點名的 AO：
     • ao_uid → assessment_plan_tasks → assessment_plan_task_workflow_execution_mapping → workflow_execution_id
     • 查詢該 workflow 的 job_executions，找到最新的 COMPLETED 或 PROCESSING job 作為 revert 起點
     • 查詢該 workflow BPMN 的第一個 USER job 作為 revert 目標
     • 呼叫 flow-engine revert_job(workflow_uid, current_job_id, first_job_id, ...)
     • 若 workflow 所有 jobs 皆為 TODO，跳過 revert（無需回退）
   • 為每個 finding 建立一筆 compliance.poams（status = open）
   • AP status → remediation

4. 直接結案路徑：

   • 設定 assessment_result_datas.completed_at = now()
   • AP status → closed

Success response：

{
  "code": 1,
  "data": {
    "outcome": "closed | remediation",
    "findings_count": 3,
    "reverted_ao_count": 2,
    "poam_count": 3
  }
}

Service： app/project/service/oscal_audit_service.py → confirm_audit(ap_uid, curr_user)

新增 / 修改檔案

jedi-oscal 套件（需更版）：

jedi-oscal DB migration：

-- verdict 改為 nullable
ALTER TABLE oscal.assessment_result_controls
    ALTER COLUMN verdict DROP NOT NULL;

-- finding 新增 ao_uid
ALTER TABLE oscal.assessment_result_findings
    ADD COLUMN ao_uid VARCHAR(36);

-- 現有 AP status 資料遷移
UPDATE oscal.assessment_plans SET status = 'active' WHERE status = 'draft';
UPDATE oscal.assessment_plans SET status = 'closed' WHERE status IN ('completed', 'archived');

主專案 — 編排層：

主專案 — GRC 稽核 CRUD：

主專案 — POA&M 基礎建設：

新增 Error Codes

# common/code/grc_error_code.py
GRC_NOT_AUDITOR              = ("使用者不具備稽核員角色", "GRC_403001")
GRC_AP_NOT_ACTIVE            = ("稽核計畫狀態不是進行中，無法啟動稽核", "GRC_412001")
GRC_AP_NOT_AUDITING          = ("稽核計畫不在稽核中狀態", "GRC_412002")
GRC_AR_VERDICT_INCOMPLETE    = ("尚有控制項未填寫稽核判定", "GRC_412003")
GRC_AR_NOT_FOUND             = ("稽核結果不存在", "GRC_404016")
GRC_AR_CONTROL_NOT_FOUND     = ("稽核控制項不存在", "GRC_404017")
GRC_AR_FINDING_NOT_FOUND     = ("稽核發現不存在", "GRC_404018")

CREATE TABLE compliance.poams (
    id                  SERIAL PRIMARY KEY,
    uid                 VARCHAR(36) NOT NULL DEFAULT gen_random_uuid(),
    assessment_plan_id  INTEGER NOT NULL,
    ar_finding_id       INTEGER NOT NULL,
    control_identifier  VARCHAR(50) NOT NULL,
    ao_uid              VARCHAR(36) NOT NULL,
    status              VARCHAR(30) NOT NULL DEFAULT 'open',
    closed_at           TIMESTAMP,
    tenant_id           INTEGER NOT NULL,
    org_unit_id         INTEGER,
    created_at          TIMESTAMP NOT NULL DEFAULT now(),
    updated_at          TIMESTAMP NOT NULL DEFAULT now(),
    created_user        VARCHAR(50),
    updated_user        VARCHAR(50)
);

CREATE UNIQUE INDEX uq_poams_uid ON compliance.poams (uid);
CREATE INDEX ix_poams_ap_id ON compliance.poams (assessment_plan_id);
CREATE INDEX ix_poams_status ON compliance.poams (status);
CREATE INDEX ix_poams_tenant ON compliance.poams (tenant_id);

Stage 2 只自動建立記錄，不提供前端 CRUD API（Stage 3 實作）。

新增 API 總覽

所有 URL 前綴：/api/1.0/grc

AP Status 變更

前端需更新 AP status 的 badge / 顯示映射。

前端頁面建議

1. 稽核總覽頁

進入條件： AP status = auditing（或 remediation / closed 為唯讀）

UI 結構：

• 上方：稽核進度統計（已填 verdict / 總數、pass / fail / partial / na 各幾項）
• 左側導航：依 control group 分組的樹狀結構（從 AR controls list 的 group_uid / group_name 前端分組）
  • 每個 group 可展開，顯示該 group 下的 controls
  • 每個 control 旁顯示 verdict badge（顏色區分）
• 右側內容區：選中某 control 後顯示審查表單（見下方）

2. 控制項審查頁（右側內容區）

唯讀資訊：

• 控制項基本資料（code、title、description、guidance）
• SSP implementation description
• 該控制項下所有 AO 的 job evidences 列表（來源為 job_evidences，透過 AO → workflow → job 鏈路查詢）

可編輯區域（AP status = auditing 且 role = auditor）：

• Verdict 表單：verdict（下拉）+ confidence（數字）+ rationale + remarks
• Findings 列表 + 新增按鈕
• Finding 表單：category（下拉）+ severity（下拉）+ title + description + recommendation + ao_uid（下拉，從該 control 的 AO 列表選）

3. AP status 對 UI 的影響

launch-audit 前端互動流程

點擊「啟動稽核」
  → POST launch-audit { force: false }
  → response.warning == true?
     → 是：顯示確認對話框
           「尚有 {incomplete_tasks}/{total_tasks} 項任務未完成，確定啟動外部稽核？」
           → 確定：POST launch-audit { force: true } → 成功，重新載入 AP 狀態
           → 取消：不動作
     → 否：直接成功，重新載入 AP 狀態

confirm-audit 前端互動流程

點擊「確認結案」
  → POST confirm-audit
  → response.code == 1?
     → outcome == "closed"：
        顯示成功訊息「稽核完成，所有控制項通過」
        AP 狀態更新為 closed
     → outcome == "remediation"：
        顯示訊息「{findings_count} 項發現需要矯正，{reverted_ao_count} 個評估物件已退回重做」
        AP 狀態更新為 remediation
  → response.code == 0（412）?
     → 顯示「以下控制項尚未填寫 verdict」+ missing_verdicts 列表

Verdict 顯示對照

Finding Category 顯示對照

Finding Severity 顯示對照

以下 API 不受 Stage 2 影響：

• Stage 1 所有已遷移的 API（control group / control / AO / job / task-setup / review）
• 專案列表 / 詳情 / 選單
• My Jobs / Job 詳情 / Job CRUD
• Job Comment / Job Evidence
• SSP 編輯
• Dashboard
• 參與者 CRUD

Stage 2 上線後，前端需要：

• 更新 AP status badge 映射（新增 auditing / remediation / closed，移除 draft / completed / archived）
• 在 AP status = active 時顯示「啟動稽核」按鈕
• 實作 launch-audit 二次確認流程（warning 對話框）
• 新增稽核總覽頁：
  • 左側樹狀導航（control group → controls，帶 verdict badge）
  • 上方進度統計
• 新增控制項審查頁（右側內容區）：
  • 唯讀區：控制項資訊 + SSP + evidences
  • Verdict 表單
  • Findings 列表 + CRUD
  • Finding 表單（含 ao_uid 下拉選擇）
• 在 AP status = auditing 且全部 verdict 已填時顯示「確認結案」按鈕
• 實作 confirm-audit 結果處理（closed vs remediation 兩種路徑）
• AP status = remediation / closed 時稽核頁面為唯讀模式