Module Frame Template Defaults — 設計文件

狀態： Design — 待實作 建立日期： 2026-04-25 作者： raymond + Claude Code (brainstorming session)

1.1 背景

目前合規資源庫（module_frames）只存「基本資訊 + OSCAL Profile 包裝 + BPMN 工作流」。每次啟動專案後，使用者必須在 ProjectPlanning 介面為每個控制項與評估目標（AO）逐一填寫現況說明（implementation_description）與程序書（reference documents），每個專案都重複一次。

1.2 目標

把「現況說明 + 程序書」抽成 module_frame 層的模板預設值：

• 模板維運者一次設好預設內容
• 啟動專案時自動帶入新建的 SSP（snapshot 模式）
• 大幅減少每個新專案的填寫工作量
• 為將來 OSCAL Component Definition 標準匯出鋪路

1.3 不在本次範圍

詳見「§9 Out of scope」。最重要的是：

• 不做 SSP-per-round / SSP 版本控制 / AR snapshot
• 不做 template → SSP re-sync 機制
• 不做 i18n 翻譯表（v1 純 TEXT 欄位）

3.1 新增 4 張表（compliance schema）

3.1.1 compliance.module_frame_control_defaults

控制項層預設值，對應 OSCAL Component Definition 的 implemented-requirements，啟動時對拷至 SSP oscal.system_security_plan_control_implementations。

CREATE TABLE compliance.module_frame_control_defaults (
    id                          SERIAL PRIMARY KEY,
    uid                         UUID DEFAULT gen_random_uuid() NOT NULL UNIQUE,
    module_frame_id             INTEGER NOT NULL
        REFERENCES public.module_frames(id) ON DELETE CASCADE,
    control_identifier          VARCHAR(100) NOT NULL,           -- e.g. AC.L1-3.1.1
    implementation_status       VARCHAR(30) DEFAULT 'unknown',   -- 預設值
    implementation_description  TEXT,                             -- 現況說明預設文字
    responsible_role            VARCHAR(100),                     -- 負責角色預設
    control_origination         VARCHAR(50) DEFAULT 'organization',
    remarks                     TEXT,
    created_at                  TIMESTAMPTZ DEFAULT now() NOT NULL,
    updated_at                  TIMESTAMPTZ DEFAULT now() NOT NULL,
    created_user                VARCHAR(50),
    updated_user                VARCHAR(50),
    CONSTRAINT uq_mfcd_module_frame_control UNIQUE (module_frame_id, control_identifier)
);
CREATE INDEX ix_mfcd_module_frame_id ON compliance.module_frame_control_defaults (module_frame_id);

行為：

• Lazy 預填：建立 module_frame 時不預先 INSERT。使用者第一次編輯某 control 時才 upsert 一筆 row。
• 軟刪除靠 module_frames 的 is_delete flag + JOIN 過濾；hard delete 走 ON DELETE CASCADE。

3.1.2 compliance.module_frame_control_objective_defaults

AO（Assessment Objective）層預設值，對應 SSP oscal.ssp_control_implementation_objectives。

CREATE TABLE compliance.module_frame_control_objective_defaults (
    id                          SERIAL PRIMARY KEY,
    uid                         UUID DEFAULT gen_random_uuid() NOT NULL UNIQUE,
    module_frame_id             INTEGER NOT NULL
        REFERENCES public.module_frames(id) ON DELETE CASCADE,
    control_default_id          INTEGER NOT NULL
        REFERENCES compliance.module_frame_control_defaults(id) ON DELETE CASCADE,
    control_identifier          VARCHAR(100) NOT NULL,
    statement_identifier        VARCHAR(100) NOT NULL,            -- = catalog_control_assessment.uid
    implementation_status       VARCHAR(50),
    implementation_description  TEXT,
    remarks                     TEXT,
    created_at                  TIMESTAMPTZ DEFAULT now() NOT NULL,
    updated_at                  TIMESTAMPTZ DEFAULT now() NOT NULL,
    created_user                VARCHAR(50),
    updated_user                VARCHAR(50),
    CONSTRAINT uq_mfcod_ctrl_default_stmt UNIQUE (control_default_id, statement_identifier)
);
CREATE INDEX ix_mfcod_module_frame_id ON compliance.module_frame_control_objective_defaults (module_frame_id);
CREATE INDEX ix_mfcod_control_default_id ON compliance.module_frame_control_objective_defaults (control_default_id);

statement_identifier 設計：

• 模板層存 catalog_control_assessments.uid（OSCAL catalog 層級的 stable key）
• SSP 端 ssp_control_implementation_objectives.statement_identifier 存 assessment_plan_tasks.uid（執行期生成）
• 啟動專案對拷時透過 join 解析：module_frame_control_objective_defaults → catalog_control_assessments → assessment_plan_tasks → ssp_control_implementation_objectives

Soft FK 規範（按 CLAUDE.md 跨 schema 慣例）：

• statement_identifier 是 catalog_control_assessments.uid 的字串 soft reference（無 SQLAlchemy FK constraint，跨 schema）
• API 層 PUT 時驗證該 ccai uid 屬於模板的 profile（profile.controls 的 catalog_control_assessments 集合內），失敗回 MODULE_FRAME_CONTROL_NOT_IN_PROFILE
• 若 catalog 後續刪除/變更該 ccai → 模板資料變孤兒，UI 顯示「目標已被 catalog 移除」並提供「移除預設值」按鈕

denormalized module_frame_id：

• 此表同時存 module_frame_id (FK) 和 control_default_id (FK)，後者可推導前者
• 故意 denormalize 理由：
  1. 大量 query「列出某模板所有 AO defaults」可省一次 JOIN
  2. RLS / tenant 過濾可直接 filter 此表（不必 JOIN module_frames）
• 一致性靠：API 層只讓使用者選 control_default，module_frame_id 由 service 層自動填入（不接受 client 傳值）

3.1.3 compliance.module_frame_reference_documents

程序書池（per-module_frame），對應 SSP oscal.ssp_reference_documents。

CREATE TABLE compliance.module_frame_reference_documents (
    id                  SERIAL PRIMARY KEY,
    uid                 VARCHAR(36) DEFAULT gen_random_uuid() NOT NULL UNIQUE,
    module_frame_id     INTEGER NOT NULL
        REFERENCES public.module_frames(id) ON DELETE CASCADE,
    file_id             INTEGER NOT NULL,                          -- jedi-file-upload tenant 內 file
    title               VARCHAR(255),
    description         TEXT,
    created_at          TIMESTAMPTZ DEFAULT now() NOT NULL,
    updated_at          TIMESTAMPTZ DEFAULT now() NOT NULL,
    created_user        VARCHAR(50),
    updated_user        VARCHAR(50)
);
CREATE INDEX ix_mfrd_module_frame_id ON compliance.module_frame_reference_documents (module_frame_id);
CREATE INDEX ix_mfrd_file_id ON compliance.module_frame_reference_documents (file_id);

Scope 說明：

• 程序書 row 是 per-module_frame
• 但底層 file_id 是 tenant-scoped（jedi-file-upload 既有設計），故同 tenant 內不同模板可挑同一份檔案重用（FE 從既有檔案池選即可）

3.1.4 compliance.module_frame_reference_document_mappings

多對多，讓同一份程序書可掛多個 control / objective default。

CREATE TABLE compliance.module_frame_reference_document_mappings (
    id                          SERIAL PRIMARY KEY,
    reference_document_id       INTEGER NOT NULL
        REFERENCES compliance.module_frame_reference_documents(id) ON DELETE CASCADE,
    context_type                VARCHAR(30) NOT NULL,             -- 'control_default' | 'objective_default'
    context_id                  INTEGER NOT NULL,                  -- → control_defaults.id 或 objective_defaults.id
    created_at                  TIMESTAMPTZ DEFAULT now() NOT NULL,
    created_user                VARCHAR(50),
    CONSTRAINT uq_mfrdm_doc_context UNIQUE (reference_document_id, context_type, context_id)
);
CREATE INDEX ix_mfrdm_context ON compliance.module_frame_reference_document_mappings (context_type, context_id);
CREATE INDEX ix_mfrdm_doc_id ON compliance.module_frame_reference_document_mappings (reference_document_id);

對齊 SSP 端 oscal.ssp_reference_document_mappings：

• SSP 端 context_type = 'control_implementation' / 'objective'
• 模板端 context_type = 'control_default' / 'objective_default'
• 啟動時對拷做 context_type 翻譯 + context_id re-map

3.2 修改既有 SSP 表（jedi-oscal）

最小改動 — 只加一個欄位：

ALTER TABLE oscal.system_security_plans
    ADD COLUMN template_module_frame_id INTEGER NULL;

用途：紀錄此 SSP 的源頭 module_frame（lineage tracking）。為將來 re-sync feature 預留。

✂️ 明確不加（避免 YAGNI）：

• previous_ssp_id（給未來 SSP-per-round 用，等那個 feature 自己加）
• is_user_modified on control_impl / objectives（給未來 re-sync 用，等那個 feature 自己加）

3.3 SQL Migration 規範

按 CLAUDE.md 規範：

• 檔名：scripts/sql/2026-XX-XX-module-frame-template-defaults.sql
• 檔案開頭：-- Date: 2026-XX-XX
• 每條 ALTER/CREATE 加 (2026-XX-XX) 註解
• 每張新表必須 GRANT SELECT, INSERT, UPDATE, DELETE ... TO cm_app; + sequence 授權

範例（4 張新表 + 1 ALTER）：

-- 1. 4 張新表 CREATE 略（見 §3.1）

-- 2. ALTER SSP table (2026-XX-XX)
ALTER TABLE oscal.system_security_plans
    ADD COLUMN template_module_frame_id INTEGER NULL;

-- 3. CHECK constraint 限制 mappings 的 context_type 合法值 (2026-XX-XX)
ALTER TABLE compliance.module_frame_reference_document_mappings
    ADD CONSTRAINT chk_mfrdm_context_type
    CHECK (context_type IN ('control_default', 'objective_default'));

-- 4. GRANT 權限授予 cm_app (2026-XX-XX)
GRANT SELECT, INSERT, UPDATE, DELETE ON compliance.module_frame_control_defaults TO cm_app;
GRANT USAGE, SELECT ON SEQUENCE compliance.module_frame_control_defaults_id_seq TO cm_app;

GRANT SELECT, INSERT, UPDATE, DELETE ON compliance.module_frame_control_objective_defaults TO cm_app;
GRANT USAGE, SELECT ON SEQUENCE compliance.module_frame_control_objective_defaults_id_seq TO cm_app;

GRANT SELECT, INSERT, UPDATE, DELETE ON compliance.module_frame_reference_documents TO cm_app;
GRANT USAGE, SELECT ON SEQUENCE compliance.module_frame_reference_documents_id_seq TO cm_app;

GRANT SELECT, INSERT, UPDATE, DELETE ON compliance.module_frame_reference_document_mappings TO cm_app;
GRANT USAGE, SELECT ON SEQUENCE compliance.module_frame_reference_document_mappings_id_seq TO cm_app;

3.4 既有 module_frames 不需 backfill

按 §3.1.1 Lazy 預填策略：本次 migration 只建表 + 加欄位，不對既有資料做 backfill。

• 既有 module_frames 行為不變
• defaults 顯示為「未設定」直到使用者編輯
• 既有 SSP template_module_frame_id = NULL（unknown source），不影響任何邏輯

3.5 UID 型別約定

新表的 uid 欄位有兩種型別：

• module_frame_control_defaults.uid / module_frame_control_objective_defaults.uid 用 PostgreSQL UUID
• module_frame_reference_documents.uid 用 VARCHAR(36)（沿用 SSP ssp_reference_documents 既有 convention，避免 jedi-file-upload 整合處要做型別轉換）

JOIN 時注意型別轉換（如 ccai.uid::text = mfod.statement_identifier）。

4.1 既有 Module Frame API — 不動

POST /module-frame、GET /module-frame/{uid}、PUT /module-frame/{uid}、DELETE /module-frame/{uid}、Excel import endpoints 保持不變。

新欄位都不在建立 Dialog 階段填，建立完成後在新詳情頁編輯。

4.2 新增：Module Frame Control Defaults

PUT 驗證流程（重要）：

1. 驗證 module_frame uid 存在且使用者有 manager 權限
2. 驗證 control_identifier 屬於該模板 profile 的 include_controls，否則回 MODULE_FRAME_CONTROL_NOT_IN_PROFILE (MODULE_FRAME_400001)
3. UPSERT row（lazy：不存在則 INSERT，存在則 UPDATE）

Request body 範例 (PUT)：

{
  "implementation_status": "implemented",
  "implementation_description": "本公司透過 ISMS-001 程序書管理...",
  "responsible_role": "資安長",
  "control_origination": "organization",
  "remarks": "..."
}

4.3 新增：Module Frame Objective Defaults（獨立路徑，避免 3 層 nested）

4.4 新增：Module Frame Reference Documents

4.5 新增：Reference Document Mappings（多對多）

4.6 新增：Catalog AO 列舉

→ jedi-oscal 已有 CatalogControlAssessmentRepoImpl，本層只做 API 包裝。回傳：

{ "code": 1, "data": [{ "uid": "...", "name": "Official", "description": "..." }, ...] }

4.7 新增：批次匯入/匯出（mirror SSP Excel import 結構）

→ 完全 mirror SspImportRoute 的 endpoint 結構與 service 邏輯（fork ssp_control_impl_import_service.py）。

4.8 既有 Project Start API 行為調整

POST /oscal/projects/start：

• Request/Response 結構不變
• 內部多一步 _copy_template_to_ssp()，在建立 SSP 與 AP 之後呼叫
• 對 caller 透明

4.9 權限與錯誤處理

按 CLAUDE.md 規範：

• 寫入 API（POST/PUT/DELETE）：須 manager 角色（沿用 module_frame service 既有權限規範）
• 寫入用 @transaction 裝飾器
• 路徑參數 uid → service 層用 module_frame_domain_service.get_one(uid) 驗證 + RLS 自動過濾 tenant
• 新增 ErrorCode 至 common/code/module_frame_error_code.py（新檔）

Error Code 命名（按 CLAUDE.md 規範）：

class ModuleFrameErrorCode(BaseCode):
    MODULE_FRAME_CONTROL_DEFAULT_NOT_FOUND  = ("模板控制項預設值不存在", "MODULE_FRAME_404001")
    MODULE_FRAME_OBJECTIVE_DEFAULT_NOT_FOUND = ("模板 AO 預設值不存在",  "MODULE_FRAME_404002")
    MODULE_FRAME_REFERENCE_DOC_NOT_FOUND     = ("模板程序書不存在",        "MODULE_FRAME_404003")
    MODULE_FRAME_CONTROL_NOT_IN_PROFILE      = ("控制項不屬於此模板的 profile", "MODULE_FRAME_400001")

5.0 重要：與既有 Step 7.5 共存策略 — UPDATE in place

OscalProjectService.start_oscal_project 既有 Step 7.5 (oscal_project_service.py:272-318) 已經為每個 AP control 建立 SSP control_impl 空殼 row + 為每個 AP task (AO) 建立 SSP objective 空殼 row：

• SSP control_impl: implementation_status="unknown", 其餘欄位 NULL
• SSP objective: statement_identifier = task.task_code OR task.title OR str(task.id) (line 307)，其餘欄位 NULL

→ 我們的 _copy_template_to_ssp 在 Step 7.5 之後執行，必須 UPDATE 既有 row 不 INSERT 新 row。

• 否則會產生 duplicate / 撞 uq_ssp_obj_ctrl_impl_stmt unique constraint
• 既有 Step 7.5 邏輯完全不動，保持向後相容

5.1 對拷流程

新增方法 OscalProjectService._copy_template_to_ssp(module_frame_id, ssp_id, ap_id, curr_user)，於 start_oscal_project 的 Step 7.5 之後執行。

-- Step 1: 控制項層 UPDATE in place
-- NULL 語意：模板若未填某欄位，保留 Step 7.5 的 default 值（用 COALESCE 防止 NULL 覆蓋有意義的 default）
UPDATE oscal.system_security_plan_control_implementations ci
SET
  implementation_status = COALESCE(mfcd.implementation_status, ci.implementation_status),
  implementation_description = COALESCE(mfcd.implementation_description, ci.implementation_description),
  responsible_role = COALESCE(mfcd.responsible_role, ci.responsible_role),
  control_origination = COALESCE(mfcd.control_origination, ci.control_origination),
  remarks = COALESCE(mfcd.remarks, ci.remarks),
  updated_user = :curr_user,
  updated_at = now()
FROM compliance.module_frame_control_defaults mfcd
WHERE mfcd.module_frame_id = :module_frame_id
  AND ci.system_security_plan_id = :ssp_id
  AND ci.control_identifier = mfcd.control_identifier;

-- Step 2: AO 層 UPDATE in place（透過 ccai + ap_task 找到對應 ssp objective）
-- 關鍵：obj.statement_identifier 用 Step 7.5 的 convention（COALESCE task_code/title/id），不用 ap_task.uid
-- NULL 語意：同 Step 1，模板若未填則保留 Step 7.5 預設
UPDATE oscal.ssp_control_implementation_objectives obj
SET
  implementation_status = COALESCE(mfod.implementation_status, obj.implementation_status),
  implementation_description = COALESCE(mfod.implementation_description, obj.implementation_description),
  remarks = COALESCE(mfod.remarks, obj.remarks),
  updated_user = :curr_user,
  updated_at = now()
FROM compliance.module_frame_control_objective_defaults mfod
JOIN oscal.catalog_control_assessments ccai
  ON ccai.uid::text = mfod.statement_identifier
JOIN oscal.assessment_plan_tasks ap_task
  ON ap_task.catalog_control_assessment_id = ccai.id
 AND ap_task.assessment_plan_id = :ap_id
WHERE mfod.module_frame_id = :module_frame_id
  AND obj.system_security_plan_id = :ssp_id
  AND obj.control_identifier = mfod.control_identifier
  AND obj.statement_identifier = COALESCE(ap_task.task_code, ap_task.title, ap_task.id::text);

-- Step 3a: 控制項層程序書（→ SSP mappings 表，新增 row）
-- 詳見 §5.4

-- Step 3b: AO 層程序書（→ SSP objective.reference_documents JSONB，UPDATE in place）
-- 詳見 §5.4

-- Step 4: 標記 SSP 來源
UPDATE oscal.system_security_plans
   SET template_module_frame_id = :module_frame_id
 WHERE id = :ssp_id;

→ 整個對拷邏輯不 INSERT 任何 SSP control_impl / objective row，只 UPDATE Step 7.5 已建好的空殼。
→ 沒有 unique constraint 衝突風險。
→ 沒設模板 defaults 的控制項 / AO row 維持 Step 7.5 的空白狀態（行為與既有 100% 一致）。

5.2 實作要求

• 使用 session.bulk_insert_mappings 或 INSERT ... SELECT 形式批次處理（避免 100+ 單行 INSERT）
• 集中在 OscalProjectService._copy_template_to_ssp() method（單一入口）
• 配對 unit test：mock module_frame 含 N 控制項 + M AO + K 程序書，驗證 SSP 端產生對應 row
• 失敗策略：fail loud — 任何一步失敗整個 transaction rollback；不要 try/except 吞掉

5.3 程序書 file_id 共享策略

• 模板的 module_frame_reference_documents.file_id 與 SSP 的 ssp_reference_documents.file_id 指向同一個 file_id
• 啟動專案 = 不複製檔案本體，只複製 metadata + mapping
• 模板若刪除 module_frame_reference_documents row → 只刪 mapping，檔案本體保留；既有專案 SSP 仍可下載

5.4 SSP 端程序書儲存的不對稱性（重要）

實際翻 ssp_control_implementation_service.py 後確認 SSP 端兩層程序書儲存方式不一致：

→ 對拷邏輯需要分兩支處理：

Step 3a: 控制項層程序書（→ SSP mappings 表）
  -- 模板的 module_frame_reference_documents → ssp_reference_documents (context_type='control_implementation')
  -- 模板的 module_frame_reference_document_mappings (context_type='control_default')
  -- → ssp_reference_document_mappings (context_type='control_implementation', context_id=new_ssp_ci.id)

Step 3b: AO 層程序書（→ SSP objective JSONB）
  -- 模板的 module_frame_reference_document_mappings (context_type='objective_default')
  -- → 組成 [{file_id, name, ...}] JSONB array
  -- → UPDATE ssp_control_implementation_objectives SET reference_documents = :jsonb_array

理由： 既有 SSP service 端 add_objective_document 直接操作 JSONB（ssp_control_implementation_service.py:158），改成 mappings 表會破壞既有 API。本 feature 不重構 SSP 端，只在對拷時做格式轉換。

5.5 launch_new_round 補一行 fix（必做，否則破壞既有 AO 程序書資料）

既有 bug： _clone_ssp_objectives (oscal_project_service.py:563-630) 跨 round clone SSP objective 時沒有複製 reference_documents JSONB 欄位（line 616-626 只 copy implementation_status / implementation_description / remarks）。

→ 任何使用者在 round 1 加的 AO 層程序書（包括既有功能填的、不只本 feature 的）都會在 round 2 launch 時消失。

修法： 在 _clone_ssp_objectives line 623（remarks=...）之後、line 624（created_user=...）之前補一行：

reference_documents=getattr(source_obj, "reference_documents", None) or [],

性質： 純 additive bug fix，零向後相容風險。修了之後所有 AO 程序書（不論模板帶來的或使用者自填的）跨 round 都不會掉。

列入本 feature scope — 不修的話本 feature 的「程序書帶入」承諾在 round 2 會破功，等同沒做。

6.1 建立階段（保留現有 2-step Dialog）

ModuleFrame.vue 的「+ 新增」按鈕仍開現有 Dialog：

• Step 1：基本資訊
• Step 2：OSCAL Framework + 控制項 Tree 勾選

按「建立」→ 模板成形（預設值全空）→ Dialog 關閉 → 自動跳轉至新詳情頁。

6.2 新詳情頁：ModuleFrameTemplateEditView.vue

URL： /module-frame/:uid/template-edit

設計策略：高度 reuse ProjectPlanningView.vue 既有結構與元件

6.2.1 Layout（抄 Planning Split Panel）

┌─ Header ───────────────────────────────────────────────────────────┐
│ [← 返回] 模板編輯：ISO27001 v1.0                                  │
│   [stats: 已設定 35/100 控制項 / 12/250 AO]                         │
│   [批次維護 ▾] [程序書池管理]                                       │
└────────────────────────────────────────────────────────────────────┘
┌─ 左 Tree (panel-sidebar) ────┐ ┌─ 右 Content ──────────────────────┐
│ - search                       │ │ - control 編輯區：description /    │
│ - group/control/AO 三層         │ │    status / responsible_role /    │
│ - 狀態 icon (complete/partial/  │ │    control_origination / 備註     │
│   empty)                        │ │ - 程序書區塊（reuse Reference     │
│ - badge: 已設定/總數             │ │   DocumentList）                  │
│                               │ │ - AO 編輯區：相同樣式（Accordion）  │
└───────────────────────────────┘ └────────────────────────────────────┘

6.2.2 直接重用的元件

從 ProjectPlanningView 直接 import：

• SspStatusTag.vue — 狀態 tag
• ReferenceDocumentList.vue — 程序書清單顯示
• DocumentPoolPanel.vue — 程序書池管理 Dialog
• DocumentLinkDialog.vue — 從池選掛
• 整個 Tree（Group → Control → AO 三層 + 狀態 icon + search + expand all）— 抄結構過來
• 整個編輯區塊（textarea + status dropdown + remarks）— 抄結構過來

6.2.3 從 Planning 拿掉的部分

• ❌ Launch 按鈕
• ❌ Task Setup 區塊（<Panel v-for="task in taskMap.get(...)">）
• ❌ Readonly Banner
• ❌ ParticipantsPanel
• ❌ SSP Import / Job Import Dialog（用 module_frame 自己的 batch import）
• ❌ canEditSsp / isPreparing / isApClosed 狀態判斷（模板永遠可編輯）

6.2.4 新增的部分

• control_origination 欄位（Planning 沒這欄位）— dropdown: organization | system-specific | customer-configured | inherited | shared
• stats bar 改成 template 角度：「已設定 X / 總控制項 Y」「已設定 AO X / 總 AO Y」
• 批次維護 menu（含下載 Excel 範本 / 匯出當前 / 上傳 Excel）
• ModuleFrameTemplateImportDialog.vue（fork SspImportDialog.vue）

6.2.5 儲存策略

• 文字欄位（description / responsible_role / remarks）：debounce 800ms 自動 PUT（沿用 audit-scope-merge feature 的「自動儲存 + toast」pattern；參考 docs/changelog/2026-04-25-audit-scope-merge.md）
• 程序書掛載/解除：按按鈕即時 POST/DELETE
• 程序書上傳：選檔後上傳完成顯示 toast

並發/競爭寫入處理： v1 採 last-write-wins，無 etag/version 控制。理由：模板維運通常是少量 manager 序列編輯，並發寫入機率低；YAGNI。後續若實際遇到衝突，可加 If-Match: <updated_at> header 機制。

6.2.6 Lazy 預填的 UI fallback

• Tree 節點 icon：✅（有 default row）/ ⬜（lazy 未建）
• 右側面板：第一次點到未設定的 control 顯示空白欄位 + 灰色 placeholder
• 第一次填字 → debounce 後 PUT → backend 自動建立 row（upsert 模式）

6.3 服務層

新增 src/service/ModuleFrameTemplateService.js，mirror SspService.js 的 API surface 但底層打 module-frame endpoint：

export default {
  listControlDefaults(moduleFrameUid) { ... },
  updateControlDefault(moduleFrameUid, controlIdentifier, payload) { ... },
  listObjectiveDefaults(moduleFrameUid) { ... },
  upsertObjectiveDefault(moduleFrameUid, payload) { ... },

  // 程序書池
  listReferenceDocuments(moduleFrameUid) { ... },
  uploadReferenceDocument(moduleFrameUid, file, meta) { ... },
  deleteReferenceDocument(moduleFrameUid, docUid) { ... },

  // mappings
  attachDocToControl(moduleFrameUid, controlIdentifier, docUid) { ... },
  detachDocFromControl(moduleFrameUid, controlIdentifier, docUid) { ... },
  attachDocToObjective(moduleFrameUid, objectiveDefaultUid, docUid) { ... },
  detachDocFromObjective(moduleFrameUid, objectiveDefaultUid, docUid) { ... },

  // catalog AO 列舉
  listCatalogControlAssessments(controlUid) { ... },

  // 批次
  exportControlDefaults(moduleFrameUid) { ... },
  downloadImportTemplate(moduleFrameUid) { ... },
  importControlDefaults(moduleFrameUid, file) { ... },
}

6.4 i18n 新增 key

src/config/locales/i18n/zh-tw/module-frame.json + en/module-frame.json 新增：

template_edit_title / template_edit_breadcrumb
stat_controls_filled / stat_aos_filled
label_implementation_description / label_implementation_status
label_responsible_role / label_control_origination / label_remarks
placeholder_unfilled / state_filled / state_unfilled
btn_back_to_list / btn_batch_maintain / btn_document_pool
toast_autosaved / toast_document_uploaded / toast_document_attached
confirm_delete_document_with_mappings
... (大量可參考 lang.project_planning.* 並複製改名)

6.5 ProjectCreate / ProjectSettings — 不動

新功能對 ProjectCreate / ProjectSettings 完全透明：

• 啟動專案後 → 使用者進 ProjectPlanning 看到「已預填內容」
• ProjectPlanning UI 完全不需要改

6.6 ModuleFrame 列表頁變更

ModuleFrame.vue 列表每筆模板加「編輯預設值」按鈕，導向 /module-frame/:uid/template-edit。

7.1 現況確認

Project (compliance.projects)
  ↓ 1:1
SSP (oscal.system_security_plans)         ← 系統基線，跨 round 共用、mutable
  ↑ N:1
AP_1 (Round 1) → ssp_id 軟參照同一份 SSP
AP_2 (Round 2) → ssp_id 軟參照同一份 SSP
...

launch_new_round 邏輯：必須舊 AP closed → 新 AP profile_id + ssp_id 沿用舊 AP → AP controls/tasks 重新從 Profile snapshot（每 round 新生 ap_task.uid）。

7.2 statement_identifier 跨 round 對應 — 由既有 _clone_ssp_objectives 處理

重要： SSP objectives 的 statement_identifier 存的是 ap_task.uid，每 round 新生。但 launch_new_round 已經有 _clone_ssp_objectives() 機制處理跨 round mapping（oscal_project_service.py:563）：

1. 抓舊 AP 與新 AP 各自的 tasks
2. 用 task.title 當穩定 key 建立舊→新 ap_task.uid 對照
3. 對每個新 task，從舊 SSP objective（用舊 statement_identifier=舊 ap_task.uid 索引）複製一份新 row（statement_identifier=新 ap_task.uid）

→ Round 2 啟動後，SSP 中會多出新的 objective row 對應新 task uid，舊 round 的 objective row 仍保留（為 future audit history 預留）。

7.3 對本次設計的影響：無（搭配 §5.5 的一行 fix）

Template → SSP 啟動時 UPDATE in place 在 round 1 啟動時執行一次（不是 INSERT）：

• 啟動專案時對 Step 7.5 已建好的 SSP control_impl / objective 空殼 row 做 UPDATE
• statement_identifier 沿用 Step 7.5 的 convention（task.task_code OR task.title OR str(task.id)）
• Round 2/3/N launch 時 → _clone_ssp_objectives 用 task.title 對應，自動把 description / status / remarks / reference_documents (見 §5.5 修補) 複製到新 task uid 上
• 整個 round 演進與 template 無關（snapshot 後完全自治）

→ 本設計在 multi-round 下完全成立，搭配 §5.5 的一行 fix 即可確保程序書跨 round 不消失。

註：_clone_ssp_objectives 用 task.title 當穩定 key 是既有設計選擇。理論上用 catalog_control_assessment_id 作為 stable key 更穩固（title 可能因為翻譯/編輯而變動），但這是既有 launch_new_round 的設計議題，不在本次 scope。

本 feature 的核心承諾：對既有功能、既有資料、既有 API 完全不影響。逐項保證如下：

10A.1 既有 API 行為 — 100% 不變

10A.2 既有資料 — 0 backfill / 0 mutation

• 既有 module_frames 表資料 完全不動
• 既有 SSP / SSP control_impl / SSP objective / SSP reference_documents 資料 完全不動
• 既有 assessment_plans / assessment_plan_tasks 資料 完全不動
• 新欄位 oscal.system_security_plans.template_module_frame_id 為 NULL（對既有 SSP 是 unknown source，不影響任何既有邏輯）
• 新表為空表，等使用者自行編輯後才有 row

10A.3 既有專案啟動行為 — 完全保留

對於沒有設定任何 defaults 的 module_frame（即所有既有模板）：

• _copy_template_to_ssp() 內 UPDATE 的 WHERE clause 對應 0 筆 (因為 module_frame_control_defaults 表為空) → 沒任何 row 被改
• SSP 啟動結果 = 既有行為（Step 7.5 建好的空殼 row 維持不變）
• 使用者進 ProjectPlanning 看到的畫面 100% 與目前一致

→ 既有專案啟動完全不會看到差異，只有「模板已設過 defaults」的新專案才會看到自動帶入內容。

關鍵設計：UPDATE in place 而非 INSERT（見 §5.0） — 因為 Step 7.5 已經建好空殼 row，我們只是把 NULL 欄位填上模板內容，不額外 INSERT 新 row，故沒有 unique constraint 衝突風險。

10A.4 既有 multi-round 行為 — 純加強，不破壞

• launch_new_round 主要邏輯完全不改
• 唯一動作：_clone_ssp_objectives 補一行 copy reference_documents JSONB（見 §5.5）
  • 這是既有 bug fix，純 additive，0 向後相容風險
  • 修了之後所有 AO 程序書（不論模板帶來的或既有功能填的）跨 round 都不會消失
  • 不修反而會破壞既有功能（既有 user 加的 AO 程序書 round 2 也會掉）
• 對拷產生的 SSP description 一旦進 round 1 SSP，就跟一般 SSP 資料一樣由既有 multi-round 機制接手

10A.5 jedi-oscal 套件變更 — 加欄位 only

• 唯一改動：OscalSystemSecurityPlan model 加 template_module_frame_id 欄位（nullable）
• 不改任何既有欄位、不改任何既有 method
• 既有 jedi-oscal 使用者（含本專案其他模組）完全 backward compatible
• 進版號用 minor bump（如 0.0.8 → 0.0.9，schema 變更）

10A.6 整合測試清單（必跑，確保不影響既有功能）

實作完成後必須驗證以下既有行為完全不變：

1. ✅ 沒設 defaults 的模板啟動專案 → SSP 全 NULL（與目前 100% 一致）
2. ✅ 既有 module_frames 列表頁渲染 + Dialog 編輯 → 行為不變
3. ✅ 既有 SSP 編輯（ProjectPlanning）→ 完全不變
4. ✅ 既有 SSP 程序書上傳/掛接（control 層 + AO 層）→ 完全不變
5. ✅ 既有 module_frame Excel import → 完全不變
6. ✅ launch_new_round Round 2 啟動 → SSP objective 跨 round clone 行為不變
7. ✅ jedi-oscal 既有 SSP query / update 流程 → 完全不變
8. ✅ Round 1 user 自填 AO 程序書 → launch_new_round → Round 2 SSP objective 仍保有程序書（驗證 §5.5 fix）
9. ✅ Step 7.5 + _copy_template_to_ssp 共存：模板有 defaults 啟動 → SSP control_impl / objective row 數量 = Step 7.5 該建的數量（無 duplicate row、無 unique constraint 衝突）

10A.7 失敗回滾

• 整個 _copy_template_to_ssp 在 start_oscal_project 的 @transaction scope 內
• 任何一步失敗 → 整個 project start transaction rollback
• 不會留下半完成 SSP 或半 copy defaults 狀態
• 不允許 try/except 吞掉錯誤（fail loud）

11.1 Backend

新增：

• compliance.module_frame_control_defaults (table)
• compliance.module_frame_control_objective_defaults (table)
• compliance.module_frame_reference_documents (table)
• compliance.module_frame_reference_document_mappings (table)
• domain/module_frame/entity/... + infra/module_frame/repository/... + mapper/... 一整套 DDD 層
• app/module_frame/service/module_frame_control_default_service.py
• app/module_frame/service/module_frame_objective_default_service.py
• app/module_frame/service/module_frame_reference_document_service.py
• app/module_frame/service/module_frame_template_import_service.py
• api/module_frame/routes/control_default_route.py
• api/module_frame/routes/objective_default_route.py
• api/module_frame/routes/reference_document_route.py
• api/module_frame/routes/template_import_route.py
• api/oscal/routes/catalog_control_assessment_route.py（如尚未有）
• common/code/module_frame_error_code.py (新檔)
• SQL migration: scripts/sql/2026-XX-XX-module-frame-template-defaults.sql

修改：

• oscal.system_security_plans 加 template_module_frame_id 欄位（jedi-oscal 進版）
• app/project/service/oscal_project_service.py 加 _copy_template_to_ssp() 並在 start_oscal_project 流程中呼叫
• app/oscal/service/... 暴露 catalog_control_assessments 列舉 service（如尚未有）

不動：

• 既有 module_frame 基本 CRUD API
• SSP 端既有 update API
• launch_new_round 流程

11.2 Frontend

新增：

• src/views/module_frame/ModuleFrameTemplateEditView.vue
• src/components/grc/ModuleFrameTemplateImportDialog.vue (fork SspImportDialog)
• src/service/ModuleFrameTemplateService.js
• src/config/router/index.js 加新 route /module-frame/:uid/template-edit
• i18n key（module-frame.json zh-tw + en）

修改：

• src/views/module_frame/ModuleFrame.vue 列表加「編輯預設值」按鈕
• src/config/api/api.js 加新 endpoint 常數

不動：

• ProjectCreateView / ProjectSettingsView / ProjectPlanningView
• 既有 module_frame 建立 Dialog 流程

11.3 jedi-oscal（外部套件）

• 修改：OscalSystemSecurityPlan model 加 template_module_frame_id 欄位
• 進版發佈：依 user 慣例，需明確指示後才執行（CLAUDE.md memory: feedback_jedi_package_publish_flow）

按 CLAUDE.md 規範，本次需產出：

• ✅ docs/features/FR-018-2604-module-frame-template-defaults/design.md（本文件）
• 待產出：docs/features/FR-018-2604-module-frame-template-defaults/implementation-plan.md（writing-plans 階段）
• 待產出：docs/changelog/2026-XX-XX-module-frame-template-defaults.md（實作完成後）

• OSCAL 標準：https://pages.nist.gov/OSCAL/
  • SSP: https://pages.nist.gov/OSCAL/concepts/layer/implementation/ssp/
  • Component Definition: https://pages.nist.gov/OSCAL/concepts/layer/implementation/component-definition/
• 既有設計：
  • SSP 表：scripts/sql/ssp_control_implementation_migration.sql
  • SSP 程序書池：scripts/sql/stage5_migration.sql + scripts/sql/ssp_document_pool_migration.sql
  • 啟動專案：prompt/oscal_project_start_flow.md
  • ProjectPlanning UI：compliance-manager-fe/src/views/project/ProjectPlanningView.vue
• 既有 jedi-oscal model 路徑：~/Projects/Jedicogy/module/jedi-python-package/jedi-oscal/