合規框架 PDF 匯入兩階段化 — 原始需求與 brainstorm 紀錄

狀態：已精化為 design.md / api-spec.md / frontend-spec.md 精化日期：2026-05-03

以下為 Phase 0 白話需求 + Phase 1 brainstorm（共 8 題）紀錄，作為溯源參考。最新可執行 spec 請見 design.md。

§1

Phase 0 — 白話需求（使用者 2026-05-03 口述）

「目前合規框架，也有匯入的功能，但是是用 PDF，這邊也希望比照合規資源庫，匯入後還是可以逐條編輯修改再儲存。請你去分析匯入合規框架的前後端，這邊麻煩也給我計畫以及方案。URL 應該是在這 /compliance-framework/compliance-framework-version-manage，匯入版本的按鈕。」

白話拆解：

既有合規框架（Compliance Framework / Version）的匯入入口在 ComplianceFrameworkVersionManage.vue 列表頁的「匯入版本」按鈕
現況：點按鈕 → Dialog → 選 PDF → 一次寫入 catalog/profile/framework_version，沒有預覽 / 編輯機會
期望：比照 module_frame 既有的 SSP docx 兩階段流程（已上線於 /module-frame/import-docx），改為「上傳解析 → 預覽逐條編輯 → 確認儲存」三段
解析的範圍是「整本框架 catalog」（group / control / objectives 階層），不是 module_frame 的「使用者填寫的現況」

§2

Phase 1 — Brainstorm 紀錄（Q1–Q8）

#	議題	決策
Q1	版本基本資料（version / release_date / publish_status / parent_version_uid）由誰決定？	A — Step 1（上傳前）就填，跟現有 dialog 一樣，全部必填；Step 2 預覽只能編 catalog 內容
Q2	誰可以操作匯入版本？	C — 沿用 RBAC，BE 不再額外加角色檢查
Q3	parse_job 的可見性 / 隔離邊界	B — 同 tenant 共享，同事可接手繼續編輯（不做使用者隔離）
Q4	PDF parse 失敗時的行為	B — 寫 `parse_job` 帶 `status=failed` + `error_code/error_message`，FE 顯示錯誤頁 + 重新上傳；保留 7 天供 debug
Q5	進入「匯入版本」頁面看到什麼？	C — 預設進 Step 1 上傳頁，頁首 banner 顯示「目前有 N 筆未完成草稿（含 M 筆是您的）」可點開接手；TTL 7 天
Q6	兩使用者同時編輯同一 parse_job 的 confirm 衝突	A — Last-write-wins，靠 DB 唯一性約束擋真 race，使用情境不會密集到需要 lock
Q7	編輯粒度	B — Update + Delete（移除誤抓的 group/control/AO），不開 Create；control 可跨 group 搬家
Q8	jedi-oscal 套件改動範圍	A — 拆 `parse_pdf_to_dict()` 與 `import_from_dict()` 兩個 method；jedi-oscal 進版到 0.0.16

Out of scope（明確不做）：

Excel 匯入（保留現有單階段流程不動）
Per-control 評論 / review workflow
PDF OCR / 自動 parser type 偵測
多人協同 real-time 編輯（lock / heartbeat / WebSocket）
獨立的匯入歷史審計表（parse_job 7 天 audit trail 已足夠）

§3

對照表（現況 vs 目標）

面向	現況（單階段）	目標（兩階段）
入口	Dialog	路由 `/compliance-framework/import-version`
API	`POST /api/1.0/oscal-framework-version/import/<file_type>` 一次寫入	parse / get / confirm / delete 四端點
BE 中間表	無	`oscal.framework_parse_jobs`
FE 預覽	無，response 後 reload 列表	Splitter（左 PDF iframe / 右 TabView：Groups / Controls / AOs）
編輯能力	無	Update + Delete，跨 group 搬家允許
jedi-oscal API	`import_or_update_oscal_from_pdf` 一次完成	拆 `parse_pdf_to_dict` + `import_from_dict`

§4

對 module_frame SSP docx import 的 reuse pattern

可直接參考 / 複製的元件：

BE：oscal.ssp_docx_parse_jobs schema、SspDocxImportAppService 架構、Domain service / Repo pattern
FE：SspDocxImportPage.vue wizard 結構、SspDocxImportService.js 三段式 API、useSspDocxDraft LocalStorage composable
i18n：ssp-docx-import.json 的 step1/step2/parsing/expired 等鍵名規律