Track B → A → C — SSP Excel round-trip + MF / SSP 結構對齊 — 交接 prompt

目的：讓專案 SSP 支援 Excel 完整匯出匯入 round-trip + MF template-edit 跟 SSP 結構對齊 接手者：新 session 從這份 handoff 直接開工，毋需重看舊對話 建立日期：2026-05-23（前一 session 收尾時寫） branch：feature/ssp-import-export-phase3（沿用，不要切） 使用者：raymond

接手 docs/features/FR-011.3-2605-ssp-edit-in-project/handoff/2026-05-23-track-bac-excel-roundtrip.md
這份 handoff，照 Track B → A → C 順序開工。Track B 先動。

「從專案那邊做匯出匯入 SSP，讓 user 可以用 Excel 編輯 SSP 的部分」。

實現路徑拆 3 track（B → A → C）：

B1 — Excel sheet 定義擴充

檔案：app/module_frame/excel_template/sheet_definitions.py

• 新 sheet SHEET_SYSTEM_CHARACTERISTIC（sheet_name="01b_受評標的"）
  • 欄位：system_name (required) / security_sensitivity_level (enum: low/moderate/high) / status (enum: under-development/operational/under-major-modification/disposition/other) / target_type / scope_description / authorization_boundary / owner_login_name (lookup_source=USERS — 拿 login_name，BE 端對 matched_user_id)
• SHEET_LEVERAGED 補 column：加 status ColumnDef（enum: operational/under-development/under-major-modification）
• ALL_SHEETS 在 SHEET_METADATA 後插入 SHEET_SYSTEM_CHARACTERISTIC
• 樣板版本 v2.1.0 → v2.2.0（加 sheet 屬 MINOR bump, 對齊 design.md §14 SemVer）

B2 — Parser + dataclass

新 dataclass：domain/oscal/parser/ssp_intermediate.py

@dataclass
class ParsedSystemCharacteristic:
    system_name: str  # required
    security_sensitivity_level: Optional[str] = None  # low/moderate/high
    status: Optional[str] = None
    target_type: Optional[str] = None
    scope_description: Optional[str] = None
    authorization_boundary: Optional[str] = None
    owner_login_name: Optional[str] = None  # parser 拿到的 login_name
    matched_user_id: Optional[int] = None  # reconciler 配對後的 user_id
    match_method: MatchMethod = MatchMethod.UNMATCHED
    match_confidence: float = 0.0

ParsedLeveraged 補欄位：加 category: Optional[str] + status: Optional[str]

新增：ParsedExcelEntityBundle 加 parsed_system_characteristic: Optional[ParsedSystemCharacteristic] = None（per-SSP 只有一筆，不是 list）

Parser sheet handler：app/oscal/service/excel_parser/sheet_handlers.py

• 新 parse_system_characteristic_sheet(ws, errors) -> Optional[dict]（單筆，不是 list）
• 加進 SHEET_NAMES dict

Parser 主幹：app/oscal/service/excel_parser/parser.py:67 區段加

system_characteristic=sh.parse_system_characteristic_sheet(
    sh.get_ws(wb, sh.SHEET_NAMES["system_characteristic"]), validation_errors,
),

ParsedResult (types.py) 加 system_characteristic: Optional[dict] = None

B3 — Reconciler

新檔：domain/oscal/service/reconciliation/system_characteristic_reconciler.py

SystemCharacteristicReconciler — 從 owner_login_name 配對 User.login_name → 填 matched_user_id。

Mirror 既有 leveraged_reconciler.py 結構（最簡 reconciler，只解一條 user lookup）。

B4 — Write strategy

新檔：domain/oscal/service/write_strategy/system_characteristic_write_strategy.py

SystemCharacteristicWriteStrategy — 寫 oscal.system_security_plan_characteristic（per-SSP 單筆 upsert）。

注意：跟其他 write strategy 不同（其他都是 list item 寫到 ssp_system_implementation_items），這個是寫 per-SSP 單一 row 到 SC 表。

實作 pattern：先 get_by_ssp_id(ssp_id)，存在 → update，不存在 → add。entity 用 SspSystemCharacteristicEntity (jedi-oscal)。

LeveragedWriteStrategy 修正：domain/oscal/service/write_strategy/leveraged_write_strategy.py:21

# 修法（B4.2）
def _parsed_to_item_payload(self, parsed: ParsedLeveraged) -> dict:
    return {
        "name": parsed.service_name,
        "provider": parsed.provider,  # ← 改寫到 provider 欄位（之前錯寫到 title）
        "category": parsed.category,  # ← 新增
        "status": parsed.status,      # ← 新增
        "purpose": parsed.purpose,
        "party_uuid": parsed.matched_party_uuid,
        "date_authorized": parsed.date_authorized,
    }

_dict_to_parsed_leveraged：app/oscal/service/ssp_excel_import_app_service.py:1935 接 category + status

B5 — 樣板下載填值

檔案：app/module_frame/service/ssp_import_template_app_service.py

• 新 method _build_system_characteristic(mf) -> Optional[dict]：從 MF 對應 template SSP 拉 oscal.system_security_plan_characteristic 一筆 → 組 dict（含 owner_login_name from User.get_by_id(owner_user_id).login_name）
• 修 _build_leveraged(items)：加 category + status + provider（改從 item.provider 取，不是 party.name — entity 已有獨立 provider 欄位）
• 主 builder 加 bundle.system_characteristic = self._build_system_characteristic(mf)

B6 — Import write 流程整合

檔案：app/oscal/service/ssp_excel_import_app_service.py

• DI 加 system_characteristic_write_strategy
• _dict_to_parsed_system_characteristic(d: dict) -> Optional[ParsedSystemCharacteristic]
• bundle 帶入 parsed_system_characteristic
• reconciler 跑 user lookup
• write strategy 寫
• response 加 system_characteristic_written: bool

B7 — Excel preview / FE 預覽頁

FE 檔案：src/views/module_frame/ImportExcelPreviewPage.vue + 新 src/components/grc/ssp-excel-import/SheetPreviewSystemCharacteristic.vue

• 加 system_characteristic preview tab（單筆顯示，跟其他多筆 sheet preview 不同）
• 加 leveraged 預覽 category/status 欄位顯示

B8 — Test

• tests/test_system_characteristic_write_strategy.py
• tests/test_leveraged_write_strategy_provider_category.py（補 category + status + provider 對 entity 的映射）
• tests/test_ssp_excel_import_system_characteristic_e2e.py（end-to-end with mock）

B9 — Changelog（Track B ship 後）

docs/changelog/YYYY-MM-DD-feat-ssp-excel-system-characteristic-and-leveraged-structured.md

A1 — BE MF system-characteristic 端到端

檔案：

• 新 app/module_frame/service/module_frame_system_characteristic_service.py — mirror module_frame_ssp_resources_service.py pattern（mf_uid → resolve ssp_id → 呼 SspSystemCharacteristicContextService 的方法）
• 新 api/module_frame/routes/module_frame_system_characteristic_route.py — GET / PUT endpoints
• api/module_frame/__init__.py 加 add_resource /module-frame/<uid>/system-characteristic
• di_containers/module_frame/module_frame_container.py 加 provider

注意：SspSystemCharacteristicContextService 可能尚未抽出 (need to check)。若沒有就先抽（mirror SspResourcesContextService 抽法）。

A2 — BE MF leveraged 端到端

檔案：

• 新 app/module_frame/service/module_frame_leveraged_service.py — mirror MF resources pattern
• 新 api/module_frame/routes/module_frame_leveraged_route.py — GET / POST / PUT / DELETE
• api/module_frame/__init__.py 加 /module-frame/<uid>/leveraged
• DI 加 provider
• 走 ensure_sys_impl_main_id（前一輪做的 auto-create, 4595dae）— MF 對應 SSP 不一定有 main row

A3 — FE SspBasicSection generalize

檔案：src/components/grc/ssp/SspBasicSection.vue

加 props（mirror Phase B 4 個 panel）：

apiBase: { type: String, default: 'ssp', validator: v => ['module-frame', 'ssp'].includes(v) }
scopeUid: { type: String, required: true }  // 取代既有 sspUid

apiRoot computed → ${base}/${scopeUid}/system-characteristic

A4 — FE SspLeveragedSection generalize

檔案：src/components/grc/ssp/SspLeveragedSection.vue

同 A3 加 apiBase + scopeUid props，endpoint 走 apiRoot/leveraged/...

A5 — MF template-edit 加 2 個 tab

檔案：src/views/module_frame/ModuleFrameTemplateEditView.vue

加 2 個 TabPanel：

• tab_audit_subject（受評標的）→ mount <SspBasicSection api-base="module-frame" :scope-uid="moduleFrameUid" />
• tab_leveraged（外部利用服務）→ mount <SspLeveragedSection api-base="module-frame" :scope-uid="moduleFrameUid" :on-count="(n) => leveragedCount = n" />

放位置：放在「資訊系統」後、「程序書管理」前（mirror SSP tab 順序）

A6 — i18n

檔案：

• src/config/locales/i18n/zh-tw/module-frame.json + en/
• 加 tab_audit_subject / tab_leveraged (含 count)
• ssp-edit.json 已有的 i18n key 不變（複用）

A7 — 啟動專案 clone system_characteristic

檔案：app/project/service/oscal_project_service.py:533 _setup_ssp_system_implementation

擴充加 system_characteristic clone：

# Step 1.5 — clone system_characteristic from template SSP
template_sc = self._sc_domain_service.get_by_ssp_id(template_ssp.id)
if template_sc:
    new_sc = SspSystemCharacteristicEntity(
        ssp_id=new_ssp_id,
        name=template_sc.name,
        # ... 所有欄位 pass-through
    )
    self._sc_domain_service.add(new_sc)

DI 補注 system_characteristic_domain_service。

A8 — Changelog（Track A ship 後）

docs/changelog/YYYY-MM-DD-feat-mf-template-edit-add-audit-subject-and-leveraged-tabs.md

A9 — Spec sync

• design-C5.md §10 加段落：「對齊 MF template-edit」
• design-C7.md §10 加段落：「MF endpoint + UI tab」
• README.md tracker 加 row：「Track A: MF / SSP 結構對齊」

C1 — 專案 SSP tab 加匯出匯入按鈕

檔案：src/components/grc/ssp/SspTabPanel.vue

在 SSP tab 頂部加兩個按鈕（manager only）：

• 「下載 SSP Excel」→ 呼 GET /ssp/<uid>/excel-template（既有 C2.2 endpoint, 待確認）
• 「匯入 SSP Excel」→ open import dialog → 走既有 SspExcelImportAppService flow

注意：先確認 /ssp/<uid>/excel-template 跟 /ssp/<uid>/excel-import 是否已在 C2.2 ship。沒 ship 要先補 BE endpoint。

C2 — Import dialog 復用

src/views/module_frame/ImportExcelPreviewPage.vue 抽 ImportExcelDialog 元件給 SSP tab 用，或新建一個 SspImportExcelDialog wrap 既有預覽元件。

C3 — Changelog + Spec sync

• changelog: YYYY-MM-DD-feat-project-ssp-excel-roundtrip-entry.md
• design-C5.md §10 加 Track C 段落

既有 commits range（不需動，僅供參考）

已 sync 的 spec / plan

• docs/features/FR-011.3-2605-ssp-edit-in-project/design-C3.md §11 — C3.PR2 已 ship 紀錄
• docs/features/FR-011.3-2605-ssp-edit-in-project/design-C5.md §10 — Phase D Reconciliation 全紀錄
• docs/features/FR-011.3-2605-ssp-edit-in-project/design-C7.md §10 — leveraged 結構化 Phase C Reconciliation
• docs/features/FR-011.3-2605-ssp-edit-in-project/implementation-plan-C3.md T11 — PR2 plan 矯正紀錄
• docs/api/project/api-spec.md §2.2 — project-device endpoint 撤除紀錄

SUMMARY 路徑

docs/features/FR-011.3-2605-ssp-edit-in-project/handoff/2026-05-23-phase-c-d-SUMMARY.md

Tracker

docs/features/FR-011.3-2605-ssp-edit-in-project/README.md — 含 Phase C 全 8 子題 + Phase D / B-generalize / Settings / Issue 1 BE / Bug fix / E cleanup / Auto-create / MF picker cache 共 14 row

操作規範

開發規範

環境參考

Track B 開工順序

1. B1 Excel sheet 定義（含 SHEET_SYSTEM_CHARACTERISTIC + SHEET_LEVERAGED status column + ALL_SHEETS 加入 + 樣板 v2.2.0 bump）
2. B2 parser + dataclass（ParsedSystemCharacteristic + ParsedLeveraged.category/status + parser sheet handler）
3. B3 reconciler（user lookup）
4. B4 write strategy（new + 修 leveraged）
5. B5 樣板下載填值（_build_system_characteristic + 修 _build_leveraged）
6. B6 import 流程整合（DI + dict mapper + bundle）
7. B7 FE preview 頁
8. B8 tests
9. B9 ship + changelog

Track A 開工順序

1. A1 BE MF system-characteristic service + route + DI
2. A2 BE MF leveraged service + route + DI
3. A7 _setup_ssp_system_implementation 擴充 clone SC（提前做給後續測試用）
4. A3 + A4 FE generalize（SspBasicSection + SspLeveragedSection apiBase props）
5. A5 MF view 加 2 tab + count emit
6. A6 i18n
7. A8 ship + changelog
8. A9 spec sync

Track C 開工順序

1. C1 + C2 FE 入口按鈕 + dialog
2. C3 changelog + spec sync

1. SspSystemCharacteristicContextService 可能尚未抽出（C2.1 抽 SspResourcesContextService 時順手抽了 leveraged + resources 兩個，SC 沒抽）— Track A1 第一步 grep 確認，沒抽就先抽 mirror SspResourcesContextService 的 pattern
2. _setup_ssp_system_implementation 擴充 SC clone 後，要重跑 dev 既有測試 SSP 啟動流程，確認 main row + items + SC 都 clone 過去（dev DB 連 192.168.50.188:25432 / guidant_ai_dev）
3. Track C 需確認 /ssp/<uid>/excel-template + /ssp/<uid>/excel-import endpoint 是否在 C2.2 已 ship — 如果沒 ship 要先補 BE endpoint
4. leveraged_write_strategy 修 provider 映射時，要同時清掉「title=provider」的舊 hack（既有 SSP UI CRUD SspLeveragedContextService 已用獨立 provider 欄位，但 write strategy 還是舊路徑）— 兩邊要對齊
5. 樣板版本 v2.2.0 bump 後，舊 Excel template (v2.1.0 / v2.0.0) 匯入時 parser 對缺 sheet 要容錯（mirror SHEET_MISSING non-blocking 處理 — 看 parse_leveraged_sheet 範例）

Track B / A / C 各 ship 後：

1. Commit 用對應 type（feat / fix / tweak）依決策樹判斷
2. 等 user 說「收尾」/「summary」才 batch 寫 changelog
3. spec sync（design-C5/C7 加 Reconciliation 段）
4. tracker README.md 加 row
5. 三 track 全 ship 後寫 final SUMMARY 到 docs/features/FR-011.3-2605-ssp-edit-in-project/handoff/YYYY-MM-DD-track-bac-SUMMARY.md

push 永遠等 user 指示，handoff 跑完不自動 push。