FR-038 OSCAL GRC 核心架構重設計 — 詳細需求分析

狀態：需求分析（Phase 0/1）· 待 user review 後進入設計/計畫 來源：draft-requirement.md + PM 教材 OSCAL_稽核生命週期_PM教材.html + 現況盤點（jedi-oscal / BE / FE / v2 schema） 撰寫日：2026-06-14

---

把現在「只套用 OSCAL 概念、底層大量自定義欄位、用 AP 兼當稽核輪次」的實作， 重寫成「正式 OSCAL v1.2.2 物件模型落地、三層 clone/snapshot 邊界清楚、稽核輪次獨立成 project_audit_rounds」的專業 OSCAL GRC 系統。 範圍橫跨三個 repo：jedi-oscal-v2（全新套件）+ 主專案 BE + 主專案 FE。

---

盤點現有 jedi-oscal 0.0.22 + 主專案後，確認以下結構性問題（這些是「重練」而非「重構」的理由）：

PM 教材 §市場定位：Phase 3（外部稽核員寫 AR/findings）是市場空白區，多數產品到此斷掉 —— 這正是本次重設計要補的核心價值。

---

依 PM 教材 §09「三層架構與 clone 邊界」，目標是把控制集分三層存放，每層邊界都做一次「複製並固定」，讓上游改動不波及下游進行中的工作：

第 1 層 · 合規框架（母版,很少改）
  catalog 母版 ── group→control→part(AO) 樹 · 永不硬刪 · 改版=新增 framework_version
  profile ── 從 catalog 挑控制 + 指向特定 framework_version
        │  解析 + clone（建立資源庫時）
        ▼
第 2 層 · 合規資源庫（公版範本,稽核顧問維護,共用）
  catalog 副本（已挑選、已固定）+ 公版 profile + 公版 SSP 範本
        │  專案成立 → clone（脫鉤公版）
        ▼
第 3 層 · 專案（這個專案自己的,可編輯）
  專案 catalog 副本 ★單一真相來源
  SSP / AP / AR / POA&M ── 全部 import 指向同一份控制副本,不互相複製
        │  啟動稽核 → snapshot（再凍結一份）
        ▼
  凍結的 SSP 快照 + 控制定義 ── 稽核判定的不變依據

四個 clone/snapshot 邊界（每個都是「複製並固定」）：

1. profile resolve → 資源庫 catalog 副本（建立資源庫時）
2. 資源庫三件組 → 專案三件組（專案成立時，脫鉤公版）
3. living SSP → 凍結 SSP 快照（每輪啟動稽核時）
4. （框架改版）= 新增 framework_version，不原地改舊版

鐵則（PM 教材明列地雷）：副本要存「內容」或指向「永不原地改的版本化控制」，不能只存 id 即時 join 回會變動的母表。這直接否定現有 P4 的 profile 做法。

---

3.1 jedi-oscal-v2 全新套件

• 新開資料夾 ~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal-v2/，不在舊 jedi-oscal 下改，進入 v2.0。
• 沿用的優良設計（從舊套件保留概念）：DDD 四層（domain/infra/app/ports）、parser adapter 工廠（CMMC/ISO/NIST 的 PDF/Excel 匯入）、mapper 雙向轉換、BaseRepositoryImpl 慣例。
• 重做的核心：model 完全按 v2 schema（見 3.2）落地，欄位 1:1 對齊 OSCAL v1.2.2，移除所有 P1 自定義欄位（產品專屬欄位改用 props JSONB 或主專案 mapping 表承接，遵守記憶 feedback_hybrid_soft_ref_asset_pattern / feedback_jedi_package_extraction_pattern）。
• 對外介面定位：user 要求「專業的第三方套件模式，因應各種情境讀寫資料給主專案」→ 套件提供 OSCAL 物件的 CRUD + 匯入匯出 + profile resolution + snapshot/clone primitive；主專案業務流程（輪次狀態機、權限、workflow）留在主專案。
• 開發期：走 poetry path dependency（feedback_jedi_package_dev_path_first），feature 完成才正式 bump + 推 Nexus（feedback_jedi_package_publish_flow）。

3.2 v2 schema 涵蓋度 + 必補缺口

docs/features/FR-037-2606-oscal-schema-gap-audit/oscal-catalog-and-roots-schema-v2.sql（42 表、~650 欄、逐欄中文 COMMENT）已是 OSCAL v1.2.2 七大 model 的高保真關聯式落地，AP/AR/POA&M 都已在內。對齊度極高。但落地前必須補三塊：

v2 schema 已知刻意取捨（非缺陷）：mapping model 裁剪不實作；AP 的 terms-and-conditions/assessment-subjects/assessment-assets/local-definitions 暫 deferred；深層宣告式 leaf 留 JSONB。這些可在後續迭代補。

3.3 新增 project_audit_rounds（輪次主檔，取代「AP 當輪次」）

這是本次最大的流程架構變更。輪次從「藏在 AP/AR 子表的 run_no」升級成獨立 first-class 物件：

id              BIGSERIAL PK
project_id      int NN  FK→compliance.projects
name            varchar(255) NN          -- 輪次名稱
round_no        int NN                    -- 輪次編號（1,2,3…）
round_type      enum NN                   -- initial / close-out(覆核) / surveillance(年度抽樣)  ← PM 教材 §08 round_type 分流
status          enum NN                   -- 7 態（見下方狀態機）
parent_round_id int NULL  FK→project_audit_rounds.id   -- 複驗的母輪；NOT NULL ⟺ round_type=close-out（initial/surveillance 為 NULL）
ssp_id          int NULL  FK→oscal.system_security_plans  -- 凍結快照,啟動稽核 SSP 鎖定時才填
ar_result_id    int NULL  FK→oscal.ar_results            -- 該輪對應的 AR result（D2：1 round ↔ 1 ar_results）
start_at / end_at        datetime
created_at / updated_at / created_user / updated_user

狀態機（Q4 定案 = 7 態 + 覆核開新 round）：

尚未開始
  ─[PM 建立輪次]──────────────▶ 專案規劃中    （受評方持續編 living SSP）
  ─[PM 啟動稽核, snapshot SSP]─▶ 稽核規劃中    （稽核員補 AP 草稿：subjects/行程/方法）
  ─[稽核員 開始稽核]──────────▶ 稽核進行中    （稽核員填 AO 全量判定 + finding + risk）
  ─[稽核員 AR 定版]──┬─ 無 not_met ─────────▶ 結案（直接過，無需整改）
                     └─ 有 not_met ─────────▶ 改善計劃中（系統自動生 POA&M）
  改善計劃中 ─[執行人員整改完 + 更新 living SSP]─▶ 待複驗
  待複驗 ─[稽核員 發起覆核]──▶ 自動開新 close-out round（稽核規劃中, parent_round_id=本輪）

• 「待複驗」獨立一態 encode PM 教材鐵則「受評方不能自宣告通過，要稽核員複驗」。
• 跨 round 結案連動：母輪停在「待複驗」；close-out round 定版確認那幾條 AO 過了 → 沿 parent_round_id 回頭關閉母輪 POA&M → 母輪轉「結案」。
• 角色：PM(manager) 管輪次/SSP/POA&M 規劃；執行人員做準備 job + 整改；稽核員(auditor) 寫 AP/填 AR/定版/發起覆核。

輪次 ↔︎ OSCAL 物件關係（決策 D2 已定 = OSCAL 官方做法）：

• 1 project → 1 living SSP（受評公司持續維護）
• 1 project → N audit_rounds（血緣用 parent_round_id 串：initial → close-out → close-out…；surveillance 另起）
• 每個 round 啟動稽核時 → snapshot living SSP 成凍結副本（填 ssp_id）
• 1 engagement → 1 AP + 1 AR（engagement = 一個 initial/surveillance 輪 + 其下所有 close-out 覆核輪）；reviewed-controls=完整適用集
  • initial / surveillance 起新 AP+AR；close-out 覆核沿用母輪 AP+AR（細節見 design.md §3 engagement 模型，已取代「1 project 1 AP」的早期表述）
• 每輪 = 一筆 ar_results，往後追加、舊的不改（PM 教材「在原 AR 後追加、第一次不改」）
• 覆核輪縮小範圍 = 該輪 ar_results 自帶 narrowed reviewed-controls（OSCAL-faithful，範圍從 parent_round_id 母輪的 not_met findings 推導），UI 呈現成「該輪的計畫」
• POA&M 用 FK 指回 AR 記錄，不複製（PM 教材「不要真的複製一份」）

---

4.1 合規框架（FE 不大改 / BE schema rename）

4.2 合規資源庫（核心語意調整：catalog + profile + ssp 三件組）

新定位：公版稽核範本，由稽核顧問針對各框架設計維護；客戶有需求時拿來成立專案。 由三個 OSCAL 物件組成：catalog（控制集副本）+ profile（baseline 定義）+ ssp（公用範本）。

新建資源庫流程：

1. 選一個 framework_versions → 把對應 catalog snapshot 一份給該資源庫（邊界①）
2. 依 profile 設定，決定哪些 control / AO 納入這份資源庫（profile resolve）
3. 提供匯入 SSP（docx/excel）功能 —— 沿用現有匯入 UI/流程，只把落地資料改用 v2 schema
4. （取代舊 MF defaults / template SSP 並存）→ 資源庫三件組就是專案的起點母版

4.3 專案成立（clone 資源庫三件組）

4.3b 任務執行 / workflow 引擎綁定（Q1 定案）

「任務執行 / My Jobs」= 受評公司「準備 SSP / 收證據」的工作（Phase 1-2，稽核前）。

• job 綁在 專案 SSP 的控制項上，專案成立時就建（clone 資源庫 workflow 設定），與 AP / 稽核輪次無關。
• 符合 PM 教材「合規工作八成在準備期、證據在 SSP 階段就備好；AP 裡一份證據都沒有」。
• workflow/job 引擎（jedi-flow-engine）保留，綁定點從「AP task」改為「專案 SSP 控制項」。
• 稽核員執行稽核（Phase 3）走 AR 判定流程，不走 job 引擎。
• 影響舊流程 P2：舊 project-start 為每個 AP task 建 workflow 的邏輯要改成「為 SSP 控制項建 workflow」，且移到專案成立階段。

4.4 SSP 維護 + 啟動稽核 snapshot（FE 不大改 / 語意收緊）

• 啟動稽核前：對專案 living SSP 持續編輯（受評公司）。
• PM 按「啟動稽核」→ 系統 snapshot 當前 SSP 定版（邊界③），填入該 project_audit_rounds.ssp_id，此後該快照不可改；living SSP 仍可繼續往前改（PM 教材「考試交卷」比喻）。
• UI 資料 → OSCAL 物件對應（user 明列，見 §5）。

4.5 AP 稽核計畫（全新，FE + BE 都要做）

現況：FE 只有 AP 列表、無編輯畫面；概念幾乎不存在。需全新設計。

依 PM 教材 §04，AP 回答四件事（只有①必填，②③④是稽核員臨場專業判斷可省略）：

關鍵設計：按「開始稽核」系統自動產一份 AP 草稿（標題+對著哪份 SSP 快照+查哪些控制都有現成資料），稽核員再補日期與抽查名單。PM 不用從白紙開始。

D3 已定：本期補 assessment-subjects（抽查名單，AP 核心 UX）相關表；assets（工具/團隊）後續。v2 schema 的 ap_reviewed_controls / ap_local_objectives / ap_assessment_activities / ap_tasks 已備，subjects 需補表。

4.6 AR 稽核結果（中改：控制項導覽 + AO 層全量判定矩陣 + 風險總結）

現況：逐「控制項」填 verdict。需補 PM 教材 §05 的三層鏈 + 總結，並把判定粒度下沉到 AO 層（Q3 定案 = OSCAL 官方做法）：

observation（看到什麼,好壞都記）→ finding（每個 in-scope AO 一筆 met/not_met/pending）→ risk（稽核員手動組,沒過的進整改）

4.7 POA&M 改善計劃（小改）

現況已完整（列表/詳情/狀態轉換/remediation）。依 PM 教材調整：

4.8 結案 / 二次稽核（覆核）

依 PM 教材 §07 完整流程：

1. 稽核員寫完第一次 AR（定版）→ 換手受評方
2. 系統自動把沒過的 finding 整理成 POA&M 空白卡（搬風險+佐證，FK 不複製）
3. PM 排整改計畫（拆步驟+日期+指派，180 天）
4. 執行人員整改（上傳證據+更新 living SSP）→ 狀態「待複驗」（不能自宣告通過）
5. 發起新 round（round_type=close-out）：重新 snapshot 當下 SSP（PM 教材標：沿用舊快照是 bug）→ 範圍縮小只查那幾條 → 在原 AR 後追加第二次 results
6. 全關閉 → 發證；CMMC 180 天逼近告警

結案判斷：所有該輪 POA&M closed → round 可結案。年度查核 = 再走一輪（round_type=surveillance）。

---

SoA 釐清（PM 教材 §02）：SoA 不是 SSP 之前的獨立步驟，而是 SSP 的一部分（每條控制旁標「適不適用+理由」）。要分清兩件事：「適不適用」（標不適用→不準備證據、跳過查驗、但不跳過審查理由、永遠不會變缺失）vs 「做了沒」（已完成/部分/規劃中/還沒做→標還沒做=缺口=會開不符合）。

---

與 user 判斷大致一致：合規框架→任務執行不大改；AP 全新、POA&M 小改。唯一修正：AR 從「小改」上修為「中改」——因 Q3 定案判定下沉到 AO 層（OSCAL 官方全量矩陣），畫面要從控制項展開到 AO。

---

---

依賴關係決定哪些能平行。第一波必須先收斂「契約」（schema + 套件介面 + API spec），契約定了之後三 repo 才能真正平行。

Wave 0（序列 · 契約收斂，~1-2 天）

• T0.1 schema 定稿：補 G1（framework 表）+ G3（audit_rounds）+ D1 schema name 決策 → 產出可執行 migration（dev 先套）
• T0.2 jedi-oscal-v2 套件骨架 + port 介面定稿：DDD 四層目錄、對外 service 簽章、snapshot/clone/resolve primitive 介面
• T0.3 API spec 定稿：AP / AR 總結 / POA&M / audit_rounds 的 api-spec.md（SA）

Wave 0 三項彼此相依（schema→套件→API），建議我序列做但快速，或 schema 先行、套件骨架與 API spec 平行。

Wave 1（高度平行 · 套件實作）

契約定稿後，jedi-oscal-v2 各 model 模組可完全平行（彼此無共享狀態）：

• A1 catalog/group/control/part(AO) + framework/version + profile resolution
• A2 SSP + 12 子表 + UI→OSCAL 落點 mapper
• A3 AP（reviewed-controls / subjects / tasks / methods）
• A4 AR（observation/finding 全量矩陣/risk）+ POA&M（item/milestone/deviation）
• A5 parser adapter 搬移 + 對齊新 catalog 結構（CMMC/ISO/NIST）

Wave 2（平行 · 主專案 BE）

套件 path-dep 可用後：

• B1 合規框架 + 資源庫 API 對齊新 schema（含 profile resolve、資源庫三件組 snapshot）
• B2 專案成立流程重寫（clone 三件組、AP/AR 延後建）
• B3 SSP 維護 + 啟動稽核 snapshot + audit_rounds 狀態機
• B4 AP 後端（草稿生成 + CRUD）
• B5 AR 後端（全量判定矩陣 + 風險總結）+ POA&M 小改 + 結案/覆核 round

Wave 3（平行 · 主專案 FE，可與 Wave 2 部分交疊）

• C1 AP 全新畫面
• C2 AR 總結層（判定矩陣 + 風險總結）
• C3 POA&M 小改（milestone/assignee/deviation/180 天/發起覆核）
• C4 輪次切換改接 audit_rounds
• （合規框架/資源庫/專案/規劃/任務 不大改，只 API 對齊驗證）

Wave 4（序列 · 整合驗證）

• 端到端走一次完整生命週期（精誠機械 CMMC L2 劇本）→ 套件正式發版 → 主專案 pin → schema rename（若 D1 選 a）

平行策略總結：Wave 0 是序列瓶頸（契約），務必先做完；Wave 1 套件模組可開 ~5 個 agent 平行；Wave 2/3 BE/FE 可交疊。我會用 subagent dispatch（顯式 git add、各 repo 分開 commit、不切 branch）。

---

這份是需求分析。請 user 針對 §7 決策清單（尤其 D1 schema 策略 / D2 輪次基數 / D3 AP 範圍 / D5 是否本期含 ISO）拍板後，我再進 Phase 1 brainstorm → Phase 3 寫 design.md + implementation-plan.md（含詳細 schema、API spec、平行任務拆解到可執行顆粒）。