範本匯入精靈（ModuleFrame Import — docx / excel）

功能群：合規框架與 SSP｜匯入三步式先讀 _overview §4、母頁 module-frame

事實基準：2026-07-05 從 FE / BE code 掃出；endpoint 對 routes.json、schema 對 db_schema.json、error code 開檔驗

1. 功能描述

範本匯入精靈是從 docx / excel 批次匯入合規資源庫（ModuleFrame）內容的精靈（5 條 route 合一 spec）。docx 走三步式（上傳 → 解決差異 → 預覽 / 確認）、excel 走 2 頁式（上傳頁 + 預覽頁）。兩者都是暫存 parse job，confirm 才寫 compliance.module_frames 與其樣板 SSP（見 module-frame、_overview §4）。

共用元件：docx 走 SspDocxImportPage.vue（src/components/grc/ssp-docx-import-v2/），由 mode（create / update-mf）+ source_type='module_frame' 參數化——同一元件也服務 SSP docx 匯入頁（見 project-ssp-import-docx）。

主要使用者：資源庫作者（管理員）。

角色速覽：資源庫作者（管理員）；scope=SYSTEM 公版 root 租戶維護。

1.1 功能總覽（本頁全部功能）

UC（§2）分兩條獨立管線展開：docx 三步式（UC-MFI-01，含解決差異步）、excel 2 頁式（UC-MFI-02，24h TTL parse job）——兩者暫存表 / 服務 / error code 家族各異，故分別成 UC。整包 / YAML 匯入（9）屬常規批次 CRUD，僅列 §6.1 不展開 UC。

2. Use Case

角色速覽：資源庫作者（管理員）；scope=SYSTEM 公版 root 租戶維護。

流程圖視覺慣例：菱形 = 判斷、橘底 = 例外 / 擋下、紅框 = 錯誤（標 error code）、綠框 = 成功終點、虛線 = 可選路徑。

UC-MFI-01 從 docx 匯入資源庫內容（三步式）

UC-MFI-02 從 excel 匯入資源庫內容（2 頁式）

3. 權限矩陣

本頁多為 JWT + 選單能力守門（無 platform-admin 限制，資源庫非全域資源）；細粒度前置以 error code 表達（§4）。

4. 狀態機與前置條件

匯入三步式見 _overview §4。error code：

5. UI 設計

版面骨架：

實機截圖（STG，亮色模式，2026-07-05，帳號 blsadmin）：

② docx 解決差異步驟、③ excel 預覽頁（8 表 + 未匹配徽章）截圖從缺：需實際上傳檔案觸發解析 job 才能進入 Step 2，屬寫入動作（會在 STG 建立 parse job / 暫存檔），不在本次唯讀截圖範圍內；待專案安排實測資料時再補。

狀態呈現：docx 用 SspDocxImportPage 分步；excel 上傳與預覽分屬兩 route（reload 可復原）；決策持久化在 Pinia store + localStorage。

6. API 規格

Envelope：成功 {"status": true, "data": …}、失敗 {"error_code": "…", "msg": "…"}。

6.1 總清單（本頁呼叫的全部 endpoint）

6.2 核心 endpoint

[POST] /ssp-docx-imports/parse

Request（multipart）：

Response data：{parse_uid, status}。出處：api/oscal/routes/ssp/ssp_docx_import_route.py::SspDocxImportParseRoute

[GET] /ssp-docx-import/{parse_uid} ・ [POST] .../confirm

GET 回 {status, parsed_result}（status ∈ awaiting_review / failed / confirmed）。confirm body：

confirm → 寫 module_frames + 樣板 SSP。出處：app/oscal/service/ssp_docx_import_app_service.py

[POST] /ssp-excel-imports/parse

Request（multipart）：

Response data：{parse_uid, status}；預覽 GET 回各表 row 資料 + 未匹配 / fuzzy 標記。出處：api/oscal/routes/ssp/ssp_excel_import_route.py

7. 前端檔案地圖（compliance-manager-fe/）

8. 後端檔案地圖（本頁核心鏈路）

DDD 提醒：匯入三步式（暫存 parse job → confirm 才落地）；source_type 驅動 confirm 寫入目標。

9. DB

9.1 資料表總清單

9.2 ER 圖

樣板 SSP 子表結構見 module-frame §9.2；本頁另寫暫存 ssp_docx_parse_jobs / ssp_excel_parse_jobs（confirm 後落地）。

9.3 核心表

oscal.ssp_docx_parse_jobs / ssp_excel_parse_jobs — 匯入解析暫存 job

共用結構：uid / status（awaiting_review / failed / confirmed）/ parsed_result（JSON）/ source_type / source_uid / created_at / created_user / org_unit_id。excel job 有 24h TTL（GRC_EXCEL_PARSE_JOB_TTL_EXPIRED）。

10. 頁面邏輯與資料對應

載入 / 儲存流程：docx 見 §2 UC-MFI-01（上傳 → (update) 解決差異 → 預覽 → confirm）；excel 見 UC-MFI-02（上傳頁 → 預覽頁 → confirm）。決策存 Pinia + localStorage，confirm 後清模組快取（避免 router.push 回去讀到 stale）。

關鍵欄位對應：

錯誤對應：見 §4 error code 表。

11. 背景行為與外部依賴

12. 邊界情況與已知坑

1. 共用元件 mode/source_type 參數化：SspDocxImportPage 同時服務資源庫（source_type=module_frame）與專案 SSP（source_type=project_ssp，見 project-ssp-import-docx）——改這元件兩頁都受影響
2. docx 三步 vs excel 兩頁：docx 有「解決差異」步（update-mf）；excel 無 diff 步、改用 2 route（上傳頁 + 預覽頁）
3. mode=full 僅 module_frame：docx mode=full 寫全欄位，只適用 module_frame 來源（否則 GRC_400009）；SSP 來源用 statement_only
4. excel parse job 24h TTL：過期 GRC_412014 需重新上傳；awaiting_review 才可 confirm（否則 GRC_412013）
5. 決策持久化 localStorage：中途離開可續，但跨裝置 / 清快取會丟決策
6. confirm 後清模組快取：避免 router.push 回資源庫讀到 stale（useModuleFrameParties 等）
7. 8 表 excel：basic / system_characteristic / components / leveraged / inventory / system_assets / parties / controls——各表獨立匹配決策

13. 開發與驗證

• 跑起來：BE python main_socketio.py（port 8000，log 在 log/app.log）；FE Vite dev server。BE 改 service code 必重啟
• 測試帳號：資源庫作者 / 管理員；密碼見 .env / 部署文件
• 導航路徑：範本管理 → 建立（docx / excel）或既有資源庫 → 匯入更新
• 前置資料：docx / excel 檔（可先下載樣板）；(create) 需框架版本
• E2E：compliance-manager-test/ repo；以 範本匯入 / module-frame-import 搜尋
• 相關文件：母頁 module-frame、SSP docx 匯入（共用元件）project-ssp-import-docx、匯入三步式 _overview §4