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

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

---

## 架構總覽

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

### 角色定義

| 角色 | 職責 |
|------|------|
| PM 專案主持人 | 建立專案、編輯 SSP、定義任務、指派人員、啟動稽核、管理 POA&M |
| 執行人員 | 依指派完成 job（上傳文件、填問卷、截圖等） |
| 內部稽核人員 | Phase 2 審閱證據、Phase 4 驗證矯正 |
| 外部稽核人員 | Phase 3 獨立審查、判定 satisfied/not-satisfied |

---

## 四階段流程

### 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

---

## 開啟新週期（Round 2+）

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

---

## OSCAL Model 對應

| 系統概念 | OSCAL Model | 說明 |
|---------|-------------|------|
| compliant_frameworks | Catalog | 控制項定義來源 |
| module_frames（合規資源庫） | Profile | 選取/裁剪的 baseline |
| SSP / system_characteristics | SSP | 系統安全計畫 |
| 元件定義（未來） | Component Definition | 預填控制項實作範本 |
| assessment_plan + ap_tasks | Assessment Plan | 檢查項目與任務 |
| assessment_results + ar_findings | Assessment Results | 稽核判定結果 |
| poams | POA&M | 矯正計畫與追蹤 |

## ProjectStatus 對應

```python
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。