FR-037 OSCAL 模型 × DB Schema required 欄位完整盤點

🗄️ 本 FR 已於 2026-06-14 ARCHIVED。 盤點後續演變成「全 OSCAL 關聯式 schema 重新設計」（單檔 45→42 表），方向已偏離本文件原本「只盤缺口、供下一輪動表」的定位。User 決定整個重來、不續作 FR-037，新一輪將另開 FR。本 session 成果（v2 schema + 審查報告）保留於本資料夾，收尾說明見 handoff/2026-06-14-FR037-ARCHIVE-SUMMARY.md。

定位：這是一份「缺口清單」，不是實作計畫。目的是把 OSCAL 5 個模型的 required 欄位與我們 oscal.* 表逐欄位對齊一次，讓未來動表時知道一次要補哪些。實作分期、哪些真要做、做到什麼 conformance 等級，留後續 implementation-plan 決策（見 §7）。

必填要分「一定必填」與「條件式必填」——差別決定要不要補。

Tier A：一定必填、完全沒有（沒表沒欄位）← 真正的硬缺口

Tier B：一定必填、欄位在但約束錯（nullable / 詞彙）← 改 DDL 或值域

Tier C：條件式必填（該 assembly 選填，一旦用就必填子欄位）← 看 conformance 目標

「一定必填且完全缺」只有 Tier A 3 條 + Tier B 6 條約束。Tier C 不啟用該功能就不算違規，做不做取決於產品 conformance 目標（見 §7）。

• 權威來源：JSON Schema 每個 object 的 "required": [...] 陣列就是 OSCAL 硬性 required 欄位。本盤點逐一抽出比對。
• 重要前提：本系統是 GRC 產品，採 OSCAL 的關聯式拆解（不是完整 OSCAL processor）。因此「OSCAL required 但我們沒有」分三種意義，務必區分：
  1. 約束倒置 / 詞彙不符（欄位在、但比 OSCAL 寬鬆或值域不對）→ 便宜、風險低、應先做。
  2. 整段 assembly 缺（沒表沒欄位）→ 要新增表，工程量視 assembly 大小。
  3. OSCAL optional 我們也沒有 → 不列為 required 缺口，僅在「非 required 缺口」註記。
• 嚴重度：🔴 阻擋有效 OSCAL 匯入/匯出　🟠 required 但可延後/可 mapper 補　🟡 fidelity 損失但不致命　✅ 已到位。

2.1 Catalog（oscal.catalogs → catalog_groups → catalog_controls → parts/parameters）

所有 OSCAL Catalog required 欄位都有對應欄位：

唯一要修的 required 級問題（約束倒置）：

• 🔴 catalog_control_parts.prose 是 NOT NULL，但 OSCAL part prose 是 optional。匯入「只有子 part 才有文字、自己無 prose 的結構性 part」會被我們的 NOT NULL 擋下。我們在這裡比 OSCAL 嚴，應放寬為 nullable。

非 required 缺口（fidelity，OSCAL optional，本輪不列入硬缺口）：

• props[] / links[] 在 control/group/part/param 都沒建模（800-53 大量靠 props 如 label/sort-id，目前被擠進 control_id/order_no 或丟失）。
• 子控制項（control enhancement）與巢狀 part 被攤平（catalog_controls/catalog_control_parts 無 self-FK）；group 倒是有 parent_group_id 可巢狀。
• parameter 的 constraints/guidelines/select/how-many/usage/class 沒建模；values 壓成單一 default_value。
• OSCAL token id（group/part）未存（只有內部隨機 uid），靠 OSCAL id 交叉連結（{{ insert: param }}、href="#id"）無法直接解析。
• group name 為 String(100)，OSCAL title 是 MarkupLine（可超長/含 markup）；現行框架（CMMC/ISO/800-53）group 標題都短，低風險。

catalog_control_assessments 是內部 AP 範本層，不是 OSCAL Catalog 構件，不列入 OSCAL 盤點。

2.2 Profile（oscal.profiles → profile_controls）

我們的 Profile 是「已解析的選取控制項清單」表示法——存了 import/include/exclude 的結果，丟掉了宣告規則。

要修的 required 級問題：

• 🟠 profile.imports 是 root required，目前無結構表示。現況 = 單一 catalog_id（FK，不可 null，比 OSCAL 嚴——OSCAL import.href 非 required）+ 扁平 profile_controls。匯出時必須保證 imports[] 非空。最小解：把 catalog_id + include=True 的列合成單一 import.include-controls.with-ids；正解：建 profile_imports 表支援多 catalog + include-all。

merge / modify / set-parameters / alters / matching pattern 全是 OSCAL optional，不列本輪 required 缺口，但這是我們 Profile 表示法最大的功能性落差（只知道選了哪些控制項，不知道怎麼選、怎麼客製）。

3.1 已到位

3.2 約束倒置 / 詞彙不符（便宜先做）

3.3 整段 required 結構缺失（FR-036 動表時最划算一次補）

3.4 其他註記

• import-profile 存 profile_id FK 而非 OSCAL href → 內部 OK，匯出靠 mapper 合成 href。
• responsible-role：control-implementation 上是單一自由文字 responsible_role，非 role-id 參照、非多值。
• ⚠️ 遷移風險：ssp_inventory_item_components（OscalSspInventoryItemComponent）仍 FK 到 legacy 表 oscal.ssp_system_implementation_items，與新的 ssp_inventory_implemented_components 並存（mid-migration）。動 inventory↔︎component join 前先確認哪張是 live。

4.1 Assessment Plan（oscal.assessment_plans → groups → controls → tasks）

我們的 AP 擴充（非 OSCAL）：assessment_plan_groups（鏡射 catalog group，OSCAL AP 無 group 概念）、assessment_task_controls（task↔︎control 直連 M:N，OSCAL 是透過 activity→step→reviewed-controls 間接關聯）。匯出時這兩層無 OSCAL 對應位置。

AP 本輪 required 缺口：🔴 task.type 詞彙占用；🟠 import-ssp.href 型別語意；🟠 reviewed-controls 攤平有損。其餘缺的都是 OSCAL AP root optional。

4.2 Assessment Results（oscal.assessment_results → datas → controls → findings/evidences）

severity/category/ao_uid/recommendation/confidence 是我們的擴充欄位（OSCAL finding 原生無 severity，通常放 prop）。

4.3 POA&M（compliance.poams 扁平單表 vs OSCAL plan-of-action-and-milestones）

OSCAL POA&M 是獨立模型（非 AR 一部分）：root required uuid/metadata/poam-items；poam-item required uuid/title/description。

status（open/in_progress/closed）是我們的擴充（OSCAL 用 prop）。

Metadata 4 個 root required（title/last-modified/version/oscal-version）全到位（oscal.oscal_metadatas）；prop/link/role/party/location/responsible-party 的 required 欄位也都有。但有幾個結構性大洞：

非 required（OSCAL optional）：party 的 email-addresses/telephone-numbers/addresses 都壓成單一純量（OSCAL 是陣列）；address 攤成自由 Text（丟 city/state/postal/country）；responsible-role 無專表（與 responsible-party link 混用）；prop.uuid/group、link.text、role.short-name、party external-ids/location-uuids/member-of-organizations、metadata.actions 皆未建模。

6.1 🔴 約束倒置 / 詞彙不符（欄位已在，最便宜，風險最低）

6.2 🔴/🟠 整段 required 結構缺失（要新增表）

6.3 import 類型欄位 — 解法

三個必填 import 都是 OSCAL 跨文件參照（href = URI 指向另一份 OSCAL 文件）：

關鍵事實：每張目標表都有 uid（UUID v4），所以 內部 id → 目標.uid 永遠可解析。據此分兩情境：

• 情境 1｜內部文件互參（我們自己產的 OSCAL）→ 零動表，純 mapper：匯出時 profile_id/ssp_id/assessment_plan_id → 查 目標.uid → 合成 href="#<uuid>"。內部 round-trip 不需新欄位。
• 情境 2｜匯入外部 OSCAL（target 不在我們 DB）→ 需 string href 欄位：int FK 存不了「我們沒有的文件」的 href（外部 URL 或對方 uuid）。要保真就得在三個 root 表加 import_href（String，存原始 href）+ optional import_remarks，否則來源在匯入即丟失。

順帶技術債：assessment_plans.ssp_id 現存 stringified int（memory feedback_ap_ssp_id_varchar_stringified_int）。VARCHAR(36) = UUID 長度，正好可改存 ssp.uid，語意直接貼 OSCAL href、匯出免查表——但屬 breaking 資料遷移，單獨評估。

結論：import 欄位有解、不一定要動表——只求內部 round-trip 走 mapper id→uid（0 動表）；要支援匯入外部文件 / 完整保真才加 import_href(+remarks)，並建議 ssp_id 改存 uuid。

1. 目標 conformance 等級：要做到完整 OSCAL round-trip（含 risk/observation/back-matter），還是只求內部資料完整 + 主要 required 欄位？這決定 §6.2 的 #16/#18 這種大結構做不做。
2. 分期：§6.1（約束/詞彙）可獨立先發一輪低風險 migration；§6.2 的 SSP 群（#8-13）建議與 FR-036 動 SSP 表族同期做（同一次動表）；AR 群（#14-17）+ back-matter（#18）規模大，宜獨立 phase。
3. 與 FR-036 的界線：FR-036 負責「MF defaults 折進樣板 SSP」；本 FR 負責「SSP 等表的 OSCAL 欄位補齊」。兩者都動 ssp_*，需協調動表順序避免互踩（建議 FR-036 結構先定，本 FR 的 SSP 欄位補在其上）。
4. jedi-oscal 發版：OSCAL ORM 全在 jedi-oscal，補欄位＝改套件 → 走 path-dependency dev、user 明示才發版（規範 feedback_jedi_package_dev_path_first）。
5. 三環境零丟失 migration：新增 NOT NULL 欄位要給 default 或先 nullable 回填再收緊；詞彙改值要資料轉換。dev→stg→poc 漸進。

• Schema：docs/reference/oscal_model_schemas/oscal_{catalog,profile,ssp,assessment-plan,assessment-results}_schema.json
• ORM：~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal/jedi_oscal/infra/model/{base,catalog,profile,ssp,ap,ar}/
• POA&M：compliance.poams（BE 主專案）
• NIST 概念頁：catalog / profile / ssp / assessment-plan / assessment-results（pages.nist.gov/OSCAL/learn/concepts/layer/）