Compliance Manager 稽核生命週期架構設計

本文件定義 compliance-manager 系統的四階段稽核流程，對齊 OSCAL 標準。 適用於 CLAUDE.md 或作為 Claude Code session 的上下文輸入。

系統遵循 OSCAL 三層架構（Control → Implementation → Assessment）， 實作為四階段專案生命週期，支援多輪稽核（audit round）的持續合規管理。

角色定義

Phase 1: 規劃（project.status = PENDING）

操作者：PM

1. PM 呼叫 start_oscal_project，系統執行：

   • 驗證專案名稱不重複
   • 取得 Profile（by profile_uid）
   • 建立空白 SSP（或取得既有 SSP）
   • 建立 Assessment Plan（AP）
   • 從 Profile snapshot：ap_groups → ap_controls → ap_tasks
   • 為每個 AP Task 建立定版 workflow + workflow_execution
   • 建立 audit_round（round_number=1, status=preparing）
   • 建立 Project + ProjectExtension
   • 建立 audit_systems、參與者、設備 mapping
   • 不建立 AR（AR 在 Phase 3 才建）

2. PM 編輯 SSP：

   • system_characteristics（系統名稱、邊界、FIPS 199 分類、部署架構）
   • 每個控制項的實作描述（描述公司目前如何符合該控制項）

3. PM 定義每個 ap_task 的 job：

   • 依據 SSP 描述，決定需要哪些佐證
   • 透過 workflow template 產生 job_executions
   • 例如 AC-2 可能需要：上傳 SOP、填帳號盤點問卷、上傳 AD 截圖、上傳停用記錄

4. PM 指派人員：

   • task_assignees：指定各 job 的執行人員
   • job_execution_org_units：對應部門
   • job_execution_devices：對應設備

5. PM 確認所有設定完成後，點擊「啟動專案」：

   • project.status → IN_PROGRESS
   • audit_round.status → in_progress
   • 所有被指派人員收到通知

Phase 2: 證據收集 + 內部審查（project.status = IN_PROGRESS）

操作者：執行人員 + 內部稽核人員

1. 執行人員收到通知，登入看到被指派的 job 清單
2. 逐一完成 job：
   • 上傳文件 → compliance.job_evidences
   • 填寫問卷 → compliance.job_execution_surveys
   • 留言討論 → compliance.job_execution_comments
3. Job 完成後 workflow 自動流轉至「待審查」節點
4. 內部稽核人員在 AO / Control 層級審閱：
   • 瀏覽每個 task 的 SSP 描述 + 所有證據
   • 通過 → 標記「內部通過」
   • 不通過 → 在 job_execution_comments 說明原因，將 job 退回執行人員
5. 退回的 job 由執行人員補件後重新提交
6. PM 在 dashboard 監控所有控制項的準備進度
7. PM 確認就緒後，點擊「啟動外部稽核」→ 觸發 launch_audit

Phase 3: 外部稽核（audit_round.status = auditing）

操作者：外部稽核人員

launch_audit 系統動作：

• 建立 assessment_results（此時才建 AR）
• 建立 assessment_result_controls（從 ap_controls 對應）
• 對 SSP 做 snapshot（凍結當前版本作為稽核基準）
• audit_round.status → auditing
• 外部稽核員帳號啟用

1. 外部稽核員看到快速瀏覽介面，每個控制項顯示：

   • SSP 實作描述（snapshot 版本）
   • 所有 job_evidences（準備期上傳的佐證）
   • 內部稽核的審查意見（job_execution_comments）
   • 關聯的設備和部門

2. 外部稽核員逐項審查，寫入 ar_findings：

   • satisfied：控制項實作符合要求
   • not-satisfied：記錄缺失原因

3. ar_evidences 引用 job_evidences（FK: job_evidence_id），不複製

   • 記錄「此 finding 基於哪些證據做出判定」
   • 同一份證據可被多個 finding 引用

4. 稽核員如需補充資料 → 系統產生新 job（evidence source=audit）

5. 完成所有審查後，PM 確認 AR → 進入矯正

Phase 4: 矯正與結案（audit_round.status = remediation）

操作者：PM + 執行人員 + 內部稽核人員

系統自動動作：

• 從每個 not-satisfied finding 建立 poams（status=open）
• audit_round.status → remediation

1. PM 填寫 POA&M 矯正計畫：

   • remediation_plan、assigned_to、due_date
   • 可設定 poam_milestones
   • 系統產生矯正 job → poam_job_mappings 關聯
   • poam.status → planned

2. 執行人員執行矯正：

   • 上傳矯正後的證據 → job_evidences（source=remediation）
   • poam.status → in_progress → verification

3. 內部稽核驗證矯正到位：

   • 通過 → poam.status → closed，更新 SSP 實作描述
   • 不通過 → 退回 in_progress，在 comments 說明

4. PM 確認所有 POA&M 都 closed 後結案：

   • audit_round.status → closed
   • project.status → COMPLETED

PM 點擊「開啟新一輪稽核」→ launch_new_round：

1. 建立新 audit_round（round_number++, status=preparing）
2. 基於最新 SSP（含上一輪矯正）重新 snapshot AP 結構
3. 為新 AP tasks 產生新的 workflow + job
4. 上一輪未 closed 的 POA&M 自動標記「本輪需複查」
5. project.status → PENDING 或直接 IN_PROGRESS
6. 每一輪的證據都是新的（時效性證據重新收集，制度性文件可引用上輪）
7. Round 1 所有歷史資料完整保留

新增 Table

oscal.audit_rounds

id                UUID PK
project_id        FK → projects
round_number      INTEGER (1, 2, 3...)
name              VARCHAR（例如「2025 年度稽核」）
status            VARCHAR: preparing / in_progress / auditing / remediation / closed
ssp_snapshot_id   FK → ssp (optional)
started_at        TIMESTAMPTZ
completed_at      TIMESTAMPTZ
created_at        TIMESTAMPTZ

oscal.poams

id                UUID PK
audit_round_id    FK → audit_rounds
finding_id        FK → assessment_result_findings
ap_task_id        FK → assessment_plan_tasks (冗餘但實用)
title             VARCHAR(500)
description       TEXT（從 finding 帶入）
remediation_plan  TEXT
risk_level        VARCHAR: high / medium / low
status            VARCHAR: open / planned / in_progress / verification / closed
assigned_to       FK → users
due_date          DATE
closed_at         TIMESTAMPTZ
closed_by         FK → users
created_at        TIMESTAMPTZ
updated_at        TIMESTAMPTZ
created_by        FK → users

oscal.poam_milestones

id              UUID PK
poam_id         FK → poams (CASCADE)
title           VARCHAR(500)
description     TEXT
sequence_order  INTEGER
due_date        DATE
status          VARCHAR: open / completed
completed_at    TIMESTAMPTZ
created_at      TIMESTAMPTZ

oscal.poam_job_mappings

id                UUID PK
poam_id           FK → poams (CASCADE)
job_execution_id  FK → compliance.job_executions
milestone_id      FK → poam_milestones (nullable)
created_at        TIMESTAMPTZ

修改既有 Table

oscal.assessment_plans — 加欄位

• audit_round_id FK → audit_rounds

oscal.assessment_results — 加欄位

• audit_round_id FK → audit_rounds

oscal.assessment_result_evidences — 改為引用

• job_evidence_id FK → compliance.job_evidences（引用而非複製）
• relevance_note TEXT（稽核員註記）

compliance.job_evidences — 加欄位

• source VARCHAR: preparation / audit / remediation

start_oscal_project 異動

修改步驟 4：原本「建立 AP + 空白 AR」→ 改為「只建 AP，不建 AR」 新增步驟：建立 audit_round（round_number=1, status=preparing） 其餘步驟不變

新增 Endpoint

launch_audit

• 前提：PM 確認 Phase 2 就緒
• 動作：建立 AR + ar_controls、SSP snapshot、audit_round.status → auditing

launch_new_round

• 前提：上一輪 audit_round.status = closed
• 動作：新 audit_round、重新 snapshot AP 結構、產生新 workflow + job

class ProjectStatus(StrEnum):
    PENDING = "pending"          # Phase 1: 規劃
    IN_PROGRESS = "in_progress"  # Phase 2-4: 執行中（細部用 audit_round.status 區分）
    COMPLETED = "completed"      # 本輪稽核結案
    SUSPENDED = "suspended"      # 暫停/延期
    ARCHIVED = "archived"        # 封存

Phase 2/3/4 的區分靠 audit_round.status，不靠 ProjectStatus。