Track B 前置分析報告

日期：2026-05-21 狀態：分析完成，待 raymond 確認決策點後開工 範圍：B1 ~ B6 六個 phase 的現況盤點、設計選項、疑問清單

已可直接利用

yaml_mapper 現有覆蓋範圍

結論：ssp_yaml_mapper.py 約完成了 55% 的 OSCAL SSP 序列化。B5 需在 jedi-oscal 裡補 4 個區塊：parties、statements（AO）、back-matter、部分 system-characteristics 欄位。

章節結構建議（從 CMMC SSP draft 推導）

封面 (Cover)
版本更新紀錄表 (Version History)
目錄 (TOC — Word auto field)
├── 1. 系統概述 (System Overview)
│   ├── 1.1 系統基本資料 (system-characteristics: name / abbreviation / description)
│   ├── 1.2 系統邊界 (authorization-boundary)
│   ├── 1.3 網路架構 (network-architecture)
│   └── 1.4 資料流 (data-flow)
├── 2. FIPS 199 安全分類 (Security Classification)
│   └── 機密性 / 完整性 / 可用性 + overall sensitivity
├── 3. 系統所有人與聯絡人 (Parties / Roles)
│   ├── 3.1 組織 (parties type=organization)
│   └── 3.2 人員 (parties type=person)
├── 4. 授權邊界系統元件 (System Implementation)
│   ├── 4.1 設備清單 (inventory-items / hardware)
│   ├── 4.2 資訊系統 / 元件 (components)
│   └── 4.3 外部利用服務 (leveraged-authorizations)
├── 5. 控制項實作說明 (Control Implementation)
│   └── 5.x <control_id>: description + status
│       └── 5.x.y <statement_id> (AO): description + status
└── 6. 附錄：參考程序書 (Back Matter / Reference Documents)

技術選型

建議：延用 CLAUDE.md 規範的 python-docx 手寫模式（不用 pandoc，跟既有 system-design DOCX 規範一致）。

generator 分兩層：

1. SspDocxGenerator（jedi-oscal 或主專案）— 純版面/結構，只知道 python-docx API
2. SspContentAssembler（主專案）— 組裝資料，產出 SspExportDataModel，傳給 generator

待決問題 B1-Q1

要不要讀真實的 .docx 樣板檔（template mode）vs 純 python-docx 程式碼生成？

建議選 B，與既有 system-design DOCX 模式一致，部署簡單。

問題核心

兩個來源的資料存放位置不同：

選項分析

選項 A：統一 SspExportDataModel 中間層（推薦）

@dataclass
class SspExportDataModel:
    # 來源識別
    source_type: Literal["module_frame", "ssp_version"]
    source_uid: str  # mf.uid 或 ssp_group_uid

    # 組裝後的欄位（格式一致）
    title: str
    version: str
    system_name: str
    system_name_short: Optional[str]
    description: str
    sensitivity_level: str
    authorization_boundary: Optional[str]
    # ... metadata 欄位

    parties: List[SspPartyExportItem]
    inventory_items: List[SspInventoryItemExportItem]
    components: List[SspComponentExportItem]
    leveraged_authorizations: List[SspLeveragedExportItem]
    control_implementations: List[SspControlImplExportItem]
    reference_documents: List[SspRefDocExportItem]

• 優點：Docx generator 和 OSCAL serializer 只依賴 SspExportDataModel，不知道來源差異
• 缺點：需要寫兩個 loader（MfSspContentLoader + SspVersionContentLoader）
• 這是 B2 的主要工作

選項 B：直接組裝 SystemSecurityPlanEntity

從 MF 資料「偽造」一個 SystemSecurityPlanEntity，讓現有 yaml_mapper 直接用。

• 優點：直接複用 yaml_mapper
• 缺點：SystemSecurityPlanEntity 是 DB ORM 對應的 entity，「偽造」會讓型別語義混亂；且 yaml_mapper 本身還有缺口需補

選項 C：在 yaml_mapper 加 MF 來源支援（jedi-oscal 層改）

在 SystemSecurityPlanYamlMapper 加一個 module_frame_to_dict(mf_data) 方法。

• 缺點：把業務邏輯（MF vs SSP）推進了套件層，不合適

結論：選 A，主專案定義 SspExportDataModel，兩個 loader 分別組裝。

待決問題 B2-Q1

SspExportDataModel 要放在哪一層？

• 放 domain/oscal/export/ — 純 domain dataclass，DDD 合規
• 放 app/oscal/service/export/ — 跟 loader 放在一起

建議放 domain/oscal/export/ssp_export_model.py，因為 Docx generator 和 OSCAL serializer 都可能在 jedi-oscal 層使用它。

待決問題 B2-Q2

MF 來源的 devices/info_systems 要從哪裡撈？

ModuleFrameSspResourcesService 是透過 MF 的 linked SSP 撈 ssp_system_implementation_items。 但如果一個 MF 沒做過 Excel 匯入（沒有 SSP shell），這裡會回傳空清單。

匯出時，MF 沒有 Excel 匯入過的設備應該怎麼處理？

• 選項 A：只匯有資料的，空清單正常（最小成本）
• 選項 B：提示 user「設備/系統資料尚未匯入」

Endpoint 設計

POST /api/1.0/module-frame/<uid>/export?format=docx
POST /api/1.0/projects/<project_uid>/ssp/<version_id>/export?format=docx|pdf|odt|json|xml|yaml

注意：format 放 query string（RESTful，不改 URL 路徑）。

回傳格式

Flask send_file + BytesIO，Content-Disposition 帶檔名：

# 範例
filename = f"SSP_{system_name}_{date.today().isoformat()}.docx"
return send_file(
    BytesIO(docx_bytes),
    mimetype="application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    as_attachment=True,
    download_name=filename,
)

待決問題 B3-Q1

兩個 endpoint 要放在哪個 Blueprint？

• 選項 A：api/oscal/routes/ssp_export_route.py（新 route，擴 oscal blueprint）
• 選項 B：api/module_frame/routes/mf_export_route.py（MF 端） + api/oscal/routes/ssp_export_route.py（SSP 版本端）

建議選 B，因為兩個 endpoint 的 URL 前綴不同（/module-frame vs /projects）。

技術選型問題

建議選 A（LibreOffice headless），指令：

libreoffice --headless --convert-to pdf --outdir /tmp /tmp/ssp.docx
libreoffice --headless --convert-to odt --outdir /tmp /tmp/ssp.docx

待決問題 B4-Q1

部署環境是否已安裝 LibreOffice？

這決定了 B4 是 1 天工作還是要先處理環境。 請 confirm：which libreoffice 在 prod/staging server 上的結果。

現有缺口清單（需補到 jedi-oscal）

缺口 1：AO statements 序列化

# 現況（ssp_yaml_mapper._control_implementation_to_dict）
r: Dict = {"control-id": str(control_id)}
# 只有 description + status + remarks
# ❌ 缺 ci.objectives → OSCAL statements[]

# 需補
if ci.objectives:
    r["statements"] = [
        {
            "statement-id": obj.statement_identifier,
            "uuid": _stringify_uuid(obj.uid),
            "description": obj.implementation_description or "",
            "remarks": obj.remarks,
        }
        for obj in ci.objectives
    ]

缺口 2：parties + responsible-parties 序列化

_metadata_to_dict 目前只輸出 title/version 等標量欄位。需補：

# MetadataEntity 已有 .parties[] (List[PartyEntity])
# 和 .responsible_parties[] (List[ResponsiblePartyEntity])

if metadata.parties:
    out["parties"] = [_party_to_dict(p) for p in metadata.parties]
if metadata.responsible_parties:
    out["responsible-parties"] = [_rp_to_dict(rp) for rp in metadata.responsible_parties]

缺口 3：back-matter 序列化（程序書）

OSCAL back-matter.resources[]：

back-matter:
  resources:
    - uuid: "..."
      title: "程序書名稱"
      rlinks:
        - href: "..."

SystemSecurityPlanEntity 目前沒有 reference_documents 屬性。 需要在 ssp_entity 加 relationship 或由 B2 的 assembler 填充。

缺口 4：system-characteristics 現有 DB 欄位限制

已確認 OscalSystemSecurityPlanSystemCharacteristic ORM 欄位實際清單：

結論：system-characteristics 的 B5 缺口比預期小 — DB 根本沒有這些欄位，無法序列化。 mapper 目前的 7 個欄位已涵蓋現有 DB 資料的全部。缺口 4 實際上不需要補。

若未來需要 CIA 分類和 network-architecture，那是另一個 feature（schema 擴充 + UI）。

OSCAL JSON / XML 的做法

XML 選項

OSCAL XML 根元素需要：

<system-security-plan xmlns="http://csrc.nist.gov/ns/oscal/1.0"
                       uuid="...">

建議選 C（xmltodict + namespace patch），成本低，足夠滿足結構正確性要求。若後續需要完整 schema validation 再改 B。

待決問題 B5-Q1

OSCAL 標準合規程度：要完整符合 OSCAL 1.1.x spec（含所有 required 欄位），還是「最大努力」輸出？

OSCAL 1.1.x 對 system-security-plan 的 required 欄位：

• uuid ✅
• metadata.title ✅
• metadata.last-modified ✅
• metadata.version ✅
• metadata.oscal-version ✅
• system-characteristics.system-id[] （我們有 system_identifier）
• system-characteristics.system-name ✅
• system-characteristics.description ✅
• system-characteristics.security-sensitivity-level ✅
• system-characteristics.status ✅
• system-implementation.components[]（at least 1 required） — 有資料時 ✅，空 MF 時 ❌
• control-implementation.implemented-requirements[].uuid ✅
• control-implementation.implemented-requirements[].control-id ✅

建議：「最大努力」— 輸出我們有的資料，缺少的 required 欄位補空字串或省略；加一個 _validate_oscal_completeness() 方法輸出 warning log 但不擋住匯出。

待決問題 B5-Q2

AO statements 資料路徑確認

ControlImplementationEntity.objectives 這個 list 是否在現有 SSP query 時有被 eager load？ 現有 yaml_mapper 呼叫端是哪裡？需要確認 caller 在 load SSP entity 時有無帶 objectives。

待決問題 B5-Q3

MF 來源的 control-implementation 資料路徑

MF 的控制項說明在 module_frame_control_defaults（不是 system_security_plan_control_implementations）。 OSCAL yaml_mapper 接 ControlImplementationEntity — 但 MF source 的資料型態是 ModuleFrameControlDefaultEntity。

B2 的 assembler 必須把 ModuleFrameControlDefaultEntity → ControlImplementationEntity（或 直接 map 到 SspControlImplExportItem dataclass）才能餵給 yaml_mapper。

這是 B2 最重要的轉換工作，需要確認兩個 entity 欄位對應關係。

入口位置（需確認 FE 現有頁面）

格式選項

[ docx ]  [ pdf ]  [ odt ]  [ OSCAL-JSON ]  [ OSCAL-XML ]  [ OSCAL-YAML ]

建議用 dialog + radio group，UX 一致，不用 6 個按鈕。

必須決策（阻 B1/B2 開工）

D3 補充：匯出 docx 不設計成 round-trip 匯入格式，優先做可讀交付物。round-trip 是未來獨立 feature。

可先開工、途中決策（不阻 B1）

B1（1~2 天）
  → 分析 CMMC reference docx 章節結構（需讀 .docx 內容）
  → 建 SspDocxGenerator 骨架 + 空殼輸出（封面/TOC/章節框架）

B2（2~3 天）  ← 最重要，其他都等這個
  → 定義 SspExportDataModel
  → MfSspContentLoader（MF 來源，7 個 service 聚合）
  → SspVersionContentLoader（SSP 版本來源，從 SSP entity）
  → SspDocxGenerator 填入真實資料

B3（0.5 天）  ← B2 完成後很快
  → 兩支 export endpoint + streaming response

B4（0.5~1 天，視 LibreOffice 環境）
  → LibreOffice headless subprocess wrapper

B5（2~3 天）  ← 平行於 B3/B4 可開
  → jedi-oscal yaml_mapper 補 4 個缺口
  → SspExportDataModel → ControlImplementationEntity 映射
  → JSON/XML 輸出方法

B6（1 天）  ← 等 B3/B4/B5 全部完成
  → FE 匯出按鈕 + dialog + 格式選擇

預估總工時：B1~B5 約 7~10 天（視 B4 環境複雜度），B6 FE 另外 1 天。

1. 讀 CMMC reference docx：用 python-docx 寫一個 dump 腳本，把所有 heading 列出來，確認章節結構（我沒辦法直接讀 .docx binary）
2. 確認 LibreOffice 環境：which libreoffice on dev server
3. 拍板 D1~D3：三個必要決策
4. 確認 ssp_system_characteristics DB schema：確認 CIA 三欄（confidentiality/integrity/availability）和 network-architecture/data-flow 是否存在

# dev DB 確認 schema 指令
psql -h 192.168.50.188 -p 25432 -U cmmgr -d guidant_ai_dev \
  -c "\d oscal.system_security_plans_system_characteristics"