SSP 文件解析器 API 規格書

文件版本：1.0 撰寫日期：2026-04-30 文件性質：SA — API 介面契約 依據：raw-requirement/requirement.md + Phase 1 brainstorming 9 項決策

狀態：草稿，等使用者 review 簽字後才會撰寫 SD（design.md）

1.1 功能定位

SSP 文件解析器（SSP Docx Parser）讓使用者上傳 Word 格式的 System Security Plan（SSP），系統用純規則層抽取每個合規控制項的實作描述（implementation description）與評估目標（assessment objectives），自動填入 ssp_control_implementation / module_frame_control_defaults 等對應表，省去人工逐條 copy-paste。

1.2 v1 範圍

✅ 做：

• 純規則 + python-docx + regex + fuzzy match 解析 docx
• 抽取控制項實作描述、評估目標（(a)(b)(c) 表格第 2 欄）
• 抽取 SSP 整體 metadata 寫到 information_systems
• 三個入口（合規資源庫 Step 2 / Step 3 / 專案規劃端）共用同一套 API
• 三步驟 wizard：上傳 → 預覽編輯（含拖拉指派 + diff preview）→ 結果摘要
• 同步處理（5MB docx 預估 5 秒內）
• 失敗段落拖拉到任意控制項主述或特定 (a)(b)(c) objective
• 一份 docx 涉及單一 baseline / framework

❌ 不做（v2 候選）：

• LLM fallback（規則打不到時不自動猜，全靠拖拉）
• OSCAL JSON 匯出
• Leveraged External Systems table 結構化抽取
• 系統元件 / 軟體元件清單抽取
• 嵌入圖片抽取
• Rich text 格式保留（與既有 plain Textarea UI 一致）
• docx 範本下載
• 多 baseline 跨 framework 解析
• 中途離開後 resume（中途離開作廢）
• async / cron / worker queue

1.3 端點總覽

依優先順序：

4.1 POST /api/1.0/ssp-docx-imports/parse — 上傳 docx + 解析（同步）

• Route Class：SspDocxImportParseRoute
• 認證：JWT Required
• 權限：依 source_type 分支驗證
  • source_type = 'module_frame' → tenant admin OR manager
  • source_type = 'project_ssp' → project manager
• Request：multipart/form-data

• Response (200)（成功，parse job 創建並同步解析完成）：

{
  "status": true,
  "data": {
    "parse_uid": "uuid-string",
    "status": "awaiting_review",
    "summary": {
      "total_paragraphs": 273,
      "matched_controls_count": 22,
      "unmatched_paragraphs_count": 8,
      "missing_baseline_controls_count": 3,
      "framework_detected_id_pattern": "AC.L1-b.1.x",
      "warning_level": null
    }
  }
}

• Response (200)（PARTIAL warning，仍可繼續但需確認）：

{
  "status": true,
  "data": {
    "parse_uid": "uuid-string",
    "status": "awaiting_review",
    "summary": {
      "total_paragraphs": 273,
      "matched_controls_count": 8,
      "unmatched_paragraphs_count": 50,
      "missing_baseline_controls_count": 12,
      "warning_level": "partial",
      "warnings": [
        "規則命中率 < 50% — 建議檢查 framework 選擇是否正確",
        "Baseline 中 12/17 控制項在 docx 找不到對應描述"
      ]
    }
  }
}

• Response (422)（FATAL 失敗）：

{
  "status": false,
  "msg": "上傳的 docx 不包含任何可辨識的控制項 ID（GRC_422001）",
  "data": {
    "parse_uid": null,
    "fatal_reason": "no_control_id_found"
  }
}

• Error codes：
  • GRC_400005 上傳檔案不是 docx 格式
  • GRC_400006 上傳檔案超過大小限制（10MB）
  • GRC_400007 framework 必填
  • GRC_400008 source_type 必填且必須為 module_frame / project_ssp
  • GRC_400009 mode 為 full 時 source_type 必須為 module_frame
  • GRC_403002 無權限操作此 source_uid
  • GRC_404021 source_uid 對應的資源不存在
  • GRC_422001 docx 內無法辨識任何控制項 ID（FATAL）
  • GRC_422002 docx framework 偵測與使用者選擇不符（FATAL）
  • GRC_422003 docx 結構損壞 / 解析失敗

4.2 GET /api/1.0/ssp-docx-import/<parse_uid> — 取得 parse 結果（Step 1 用）

• Route Class：SspDocxImportRoute

• 認證：JWT Required

• 權限：建立此 parse job 的使用者本人 OR 同 source_uid 的有權使用者

• Path Parameters：

  • parse_uid — ssp_docx_parse_jobs.uid

• Response (200)（status=awaiting_review，給 Step 1 預覽 UI 用）：

{
  "status": true,
  "data": {
    "parse_uid": "uuid",
    "status": "awaiting_review",
    "source_type": "project_ssp",
    "source_uid": "ssp-uid",
    "framework": "cmmc-l1",
    "mode": "statement_only",
    "summary": {
      "total_paragraphs": 273,
      "matched_controls_count": 22,
      "unmatched_paragraphs_count": 8,
      "missing_baseline_controls_count": 3,
      "warning_level": null
    },
    "matched_controls": [
      {
        "control_id": "AC.L1-b.1.i",
        "control_name": "Authorized Access Control",
        "score": 0.95,
        "score_reason": "H3 標題完整 ID 命中",
        "current_implementation_description": "我們透過 AD 控制使用者群組...",
        "parsed_implementation_description": "我們透過 AD + Okta 控制使用者群組，並...",
        "default_action": "use_docx",
        "objectives": [
          {
            "objective_key": "a",
            "objective_text": "authorized users are identified",
            "current_description": "已透過 SOP-001 識別",
            "parsed_description": "已透過 SOP-001 識別並由 IT 部審核",
            "default_action": "use_docx"
          }
        ]
      }
    ],
    "unmatched_paragraphs": [
      {
        "paragraph_idx": 142,
        "text": "我們的安全事件處理由 SOC team 24x7 監控...",
        "context": {
          "preceding_h1": "Control Implementation",
          "preceding_h2": null,
          "preceding_h3": null
        },
        "rule_score": 0.45,
        "rule_guess_control_id": "IR.L2-...",
        "rule_guess_confidence": 0.45
      }
    ],
    "missing_baseline_controls": [
      {
        "control_id": "SC.L1-b.1.x",
        "control_name": "Boundary Protection",
        "reason": "baseline 中存在但 docx 沒提到"
      }
    ],
    "predicted_module_frame_controls": [
      // 僅在 mode=full 時提供 — D-Q5 β 預選清單，給 Step 2 勾選 UI
      { "control_id": "AC.L1-b.1.i", "preselected": true },
      { "control_id": "AC.L1-b.1.ii", "preselected": true }
    ],
    "created_at": "2026-04-30 10:00:00",
    "expires_at": "2026-04-30 11:00:00"
  }
}

• Response (200)（status=completed，已匯入完成的 job 查詢）：

{
  "status": true,
  "data": {
    "parse_uid": "uuid",
    "status": "completed",
    "import_summary": { "created": 22, "updated": 5, "skipped": 3 },
    "completed_at": "2026-04-30 10:05:00"
  }
}

• Response (200)（status=failed / expired）：

{
  "status": true,
  "data": {
    "parse_uid": "uuid",
    "status": "failed",
    "error_code": "GRC_422001",
    "error_message": "docx 內無法辨識任何控制項 ID"
  }
}

• Error codes：
  • GRC_404022 parse_uid 不存在
  • GRC_403003 無權限存取此 parse job

4.3 POST /api/1.0/ssp-docx-import/<parse_uid>/confirm — 確認匯入（Step 2）

• Route Class：SspDocxImportConfirmRoute

• 認證：JWT Required

• 權限：建立此 parse job 的使用者本人；且 status 必須為 awaiting_review

• Path Parameters：parse_uid

• Request Body：

{
  "decisions": [
    {
      "control_id": "AC.L1-b.1.i",
      "action": "use_docx | keep_current | skip",
      "objectives": [
        { "objective_key": "a", "action": "use_docx" },
        { "objective_key": "b", "action": "keep_current" }
      ]
    }
  ],
  "manual_assignments": [
    {
      "paragraph_idx": 142,
      "targets": [
        { "control_id": "IR.L2-x", "level": "implementation", "merge_action": "append" },
        { "control_id": "AC.L1-b.1.i", "level": "objective", "objective_key": "c", "merge_action": "replace" }
      ]
    }
  ],
  "skipped_paragraph_idxs": [85, 142, 200],
  "predicted_controls_user_selection": [
    "AC.L1-b.1.i", "AC.L1-b.1.ii", "AC.L1-b.1.iv"
    // 僅在 mode=full 時必填 — 使用者在 Step 1 微調過的最終控制項勾選清單
  ]
}

• Response (200)：

{
  "status": true,
  "data": {
    "parse_uid": "uuid",
    "status": "completed",
    "import_summary": {
      "created": 22,
      "updated": 5,
      "skipped": 3,
      "manual_assigned": 8,
      "manual_skipped": 3,
      "missing_left_blank": 3
    },
    "redirect_url": "/projects/<uid>/ssp/control-implementations"
  }
}

• Error codes：
  • GRC_404022 parse_uid 不存在
  • GRC_412009 parse job 狀態不是 awaiting_review，無法確認匯入
  • GRC_412010 parse job 已 expired
  • GRC_400010 decisions 缺漏（matched_controls 中有未決策的 control_id）
  • GRC_400011 predicted_controls_user_selection 缺漏（mode=full 時必填）

4.4 DELETE /api/1.0/ssp-docx-import/<parse_uid> — 放棄此次 parse job

• Route Class：SspDocxImportRoute

• 認證：JWT Required

• 權限：建立此 parse job 的使用者本人

• Response (200)：

{
  "status": true,
  "data": { "parse_uid": "uuid", "status": "discarded" }
}

• 副作用：MinIO 上的 file 同步刪除；DB row 軟刪除（is_active=False）。

• Error codes：

  • GRC_404022 parse_uid 不存在
  • GRC_412011 已完成的 job 無法再放棄（status=completed）

依 CLAUDE.md 命名規則 GRC_<HTTP狀態碼><3位序號>，序號接續既有 common/code/grc_error_code.py。

備註：

• 角色驗證在 app service 層透過 domain service（依 CLAUDE.md DDD 規範）
• project manager = project_participants.role == 'manager'
• tenant admin = users.is_admin == True
• auditor 角色不可進行任何 docx import 操作（F-Q3 α 嚴格）

7.1 入口 A1 — 合規資源庫新增 Step 2

• 位置：ModuleFrame.vue 編輯/新增 wizard 第 2 步（選控制項）
• 新增按鈕：「從 docx 匯入控制項」（與既有手動勾選並排）
• 點擊後開啟 SspDocxImportDialog 子 wizard
• mode = full，source_type = module_frame
• 子 wizard 完成後：使用者選定的控制項 ID 清單回傳父 wizard，父 wizard 跳轉至 Step 3

7.2 入口 A2 — 合規資源庫新增 Step 3

• 位置：ModuleFrame.vue 編輯/新增 wizard 第 3 步（填現況）
• 新增按鈕：「從 docx 匯入現況」（與既有手動填寫並排）
• mode = statement_only，source_type = module_frame
• 子 wizard 完成後：使用者選定的現況資料回傳父 wizard，父 wizard 顯示已填內容

7.3 入口 B — 專案規劃 SSP 控制項現況頁

• 位置：SSP 控制項現況頁，與既有「匯入 Excel」按鈕並排
• 新增按鈕：「匯入 docx」
• mode = statement_only，source_type = project_ssp
• 子 wizard 完成後：頁面 reload 顯示更新後的現況

7.4 共用：SspDocxImportDialog 三步驟

• Step 0 — 上傳：framework dropdown + FileUpload 元件 → 點「下一步」呼叫 POST /parse
• Step 1 — 預覽編輯（最複雜的 UI）：
  • 自動匹配清單（matched_controls）— diff preview + 每筆 keep/use_docx/skip
  • 待人工確認清單（unmatched_paragraphs）— 拖拉到任一控制項主述或 objective
  • Baseline 缺漏清單（missing_baseline_controls）— 純 warning 訊息
  • 批次操作 toolbar：全部使用 docx / 全部保留現有 / 只匯入空白項
  • PARTIAL warning banner（若有）
  • 拖拉到已有內容時跳 Conflict modal（append / replace 二選一）
• Step 2 — 結果：import_summary + 「完成」按鈕

這些 OPEN 不影響 SA 主結構，會在 SD（design.md）階段細化解決方案。

9.1 假設

• 既有 jedi-oscal 套件的 ssp_control_implementation / ssp_control_implementation_objective 現況可直接寫入（API 已存在）
• 既有 module_frame_control_defaults / module_frame_control_objective_defaults 表結構穩定
• information_systems + project_information_systems 的 CRUD service 已可呼叫
• python-docx 套件已存在（既有 docs/scripts 已使用）

9.2 風險

• R1：客戶提供的 docx 結構過於不規則 → 規則命中率 < 50% → 大量人工拖拉，使用者體驗差 → 觸發 PARTIAL warning，但 v1 沒有 LLM 救援，使用者可能放棄
• R2：information_systems 寫入 / merge 邏輯（OPEN-1）若沒 set 好，可能造成多 row 髒資料
• R3：5MB docx 同步解析超時：若實測超過 5 秒，前端 UX 受影響 → 需要在 SD 階段加 timeout 監控

• 原始白話需求：raw-requirement/requirement.md
• 客戶範例 docx：raw-requirement/reference/ASIA-CMMC-SSP-DRAFT-202604.docx
• 既有合規資源庫文件：docs/api/module-frame/
• 既有 SSP 控制項現況設計：api/oscal/serializers/ssp/ssp_control_implementation.py
• jedi-oscal 套件 SSP models：~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal/jedi_oscal/infra/model/ssp/
• jedi_information_system 套件：jedi_information_system/（主專案內）
• CLAUDE.md（DDD / 權限 / error code 規範）

Sign-off 區（Phase 2.1 結束時填寫）

簽完後進 Phase 2.2（design.md / SD 撰寫）。

跟 docx 匯入相關的編輯介面（編輯頁的「參與單位 / 人員」對話框）需要 BE 提供 CRUD endpoints 直接管理某個 module_frame 的 oscal_parties，不再透過 docx import 流程。

11.1 GET /module-frame/<uid>/parties

列出該 module_frame 連結的所有 parties。

Request：無 body

Response 200：

{
  "status": true,
  "data": [
    {
      "uid": "uuid",
      "party_type": "person | organization",
      "name": "Pan Pan",
      "role": "system-security-officer",
      "title": "Security Manager",
      "email_address": "bls.tech.pan@gmail.com",
      "telephone_number": null,
      "address": null,
      "matched_user_id": 23,
      "matched_org_unit_id": null,
      "matched_user_name": "Pan Pan",
      "matched_org_unit_name": null
    }
  ]
}

11.2 POST /module-frame/<uid>/parties

新增 party + 連結到該 module_frame。

Request body：

{
  "party_type": "person | organization",
  "name": "string",
  "role": "system-owner | ...",
  "title": "string?",
  "email_address": "string?",
  "telephone_number": "string?",
  "address": "string?",
  "matched_user_id": 23,
  "matched_org_unit_id": null
}

role 為 5 個固定 role 之一（responsible-organization / information-provider / information-receiver / system-owner / system-security-officer）。

11.3 PUT /module-frame/<uid>/parties/<party_uid>

編輯 party 內容 / 重新連結。party_type 與 name 不可改（保 dedupe key 穩定，re-import 時才能找到同一筆）。role 改變時自動 re-point responsible_party 連結。

11.4 DELETE /module-frame/<uid>/parties/<party_uid>

只移除「該 module_frame 跟此 party 的連結」（responsible_party row），party row 本身保留供其他 module_frame 重用。

11.5 Error codes

11.6 Confirm (/ssp-docx-import/<uid>/confirm) 新欄位

11.7 Parse 回傳新增欄位

GET /ssp-docx-import/<uid> 回傳的 parsed_result 多了：