# B 階段啟動交接 Prompt
> 日期：2026-05-21
> 接手時點：Track A（Excel 匯入）全部 shipped ✅ + jedi-oscal 0.0.17 已發版；準備進入 Track B（SSP 匯出）

---

## 給下一個 session 的人：貼這段進去接手

```
你正在接手 SSP 匯入匯出 Phase 2 — Track B（SSP 匯出）的開發。

## 當前狀態

**Track A（Excel 匯入）全部完成。**

- A0 ~ A5 全 shipped，bugfix 三輪全修完
- jedi-oscal 套件已 bump 0.0.16 → 0.0.17，推 Nexus，主專案 pin 已更新
- feature branch：compliance-manager-be + fe + jedi-oscal 三 repo 都在 `feature/ssp-import-export-phase2`
- 最新 BE commit：6fc39cf（對話紀錄）；FE 最新：bd92e2e（overwrite dialog）
- 主要文件：docs/features/FR-011.2-2605-ssp-import-export-phase2/README.md（進度 tracker）

**Track B（SSP 匯出）全部 pending，你是第一個接手的人。**

---

## Track B 概覽

| Phase | 主題 | 級別 | 說明 |
|-------|------|------|------|
| B1 | Docx 樣板 + generator 骨架 | 中 | 決定 Docx 排版設計 + 建 generator 主架構 |
| B2 | 內容組裝（兩來源共用 data model） | 中 | SSP 資料聚合層（MF + 專案 SSP 兩種來源） |
| B3 | Docx Export API | 輕 | endpoint + streaming response |
| B4 | PDF + ODT 補上 | 輕 | 轉換工具鏈 |
| B5 | OSCAL JSON / XML / YAML 匯出 | 重 | 現有 ssp_yaml_mapper 改造 + 新 JSON / XML |
| B6 | 前端 UI + 格式選擇 | 輕 | 匯出按鈕 + 格式 dropdown |

依賴關係：
- B1 → B2 → B3 → B4 → B6
- B2 → B5 → B6（B5 可在 B2 完成後平行展開）

---

## 兩種匯出來源

| 來源 | API 路徑 | 說明 |
|------|----------|------|
| 合規資源庫（module_frame）| `POST /module-frame/<uid>/export?format=docx\|pdf\|odt\|json\|xml\|yaml` | 從 MF 資料直出 |
| 專案 SSP 版本 | `POST /projects/<project_uid>/ssp/<version_id>/export?format=...` | 從特定版本 SSP 直出 |

B2 的核心工作是讓同一個 content assembler 能接受這兩種來源，輸出相同的 intermediate data model，讓 B3/B5 的 serializer 不用知道來源差異。

---

## 現有可複用基礎設施

### BE（compliance-manager-be）
- `app/oscal/service/ssp_docx_import_app_service.py` — docx import 流程參考（import ↔ export 鏡像）
- `domain/oscal/strategy/module_frame_write_strategy.py` — 讀 MF 資料的各 service 入口
- `app/module_frame/service/` — `module_frame_party_service` / `module_frame_ssp_resources_service` 等讀取層

### jedi-oscal（套件）
- `infra/mapper/ssp/ssp_yaml_mapper.py` — 現有 OSCAL YAML 序列化 mapper（B5 的主要改造對象）
  - 已支援：system-characteristics / metadata / system-implementation（devices/components/leveraged）
  - **未完整支援**：control-implementation（AO objectives） → B5 需補
- `infra/mapper/ssp/` 目錄 — 已有 SSP mapper 架構

### 重要 Schema 參考
- `docs/claude/database-schema.md` — 所有 table 結構
- `docs/features/FR-011.2-2605-ssp-import-export-phase2/design-A4.md` — 控制項 / AO 鉤稽設計（B5 序列化依賴這些資料）

---

## 開工前必讀

1. **`docs/features/FR-011.2-2605-ssp-import-export-phase2/README.md`** — phase tracker（每個 session 開工前先讀）
2. **`docs/features/FR-011.2-2605-ssp-import-export-phase2/requirement-understanding.md`** — B 階段需求說明在 §3（匯出）和 §6（phase 切分）
3. **`docs/features/FR-011.2-2605-ssp-import-export-phase2/design-A4.md`** — 控制項 / AO write pipeline 設計，B5 OSCAL 序列化需要了解這些資料結構
4. **`CLAUDE.md`** — 開發規範，特別注意 DDD 層級規範 + jedi-* 套件修改流程

---

## B5 特別注意：重型 phase，需要 brainstorm

B5（OSCAL JSON / XML / YAML 匯出）被評為「重型」— 開工前必須先做 brainstorm：

**待釐清問題（brainstorm 議題）**：
1. 現有 `ssp_yaml_mapper` 是從 SSP 資料出發的，但 control-implementation 部分（AO objectives / statement）的序列化邏輯尚未完整 — 需要補哪些 mapper 方法？
2. MF 來源 vs SSP 版本來源的 control-implementation 資料路徑不同 — 如何統一？
3. JSON / XML 是否直接從 YAML 轉（pyyaml → json / xmltodict），或另建 serializer？
4. OSCAL 標準的 system-security-plan 根節點結構 — 要完整符合 OSCAL 1.1.x spec，還是只輸出主要欄位？

---

## Track A 已知 follow-up（不阻 B，但要知道）

| 項目 | 說明 |
|------|------|
| cucumber E2E | A1/A2/A4 各有 pending E2E 測試，測試環境配好後補跑 |
| 10 筆 hardware device_id NULL | A0.1 backfill 無法匹配的 10 筆，業務判斷後處理 |
| jedi-oscal feature branch 未 merge main | 14 個 A 階段 feature commits 仍在 feature branch，B 完成後統一 merge |

---

## 推薦開工方式

```
幫我開始 SSP 匯出 Track B，從 B1 開始。
先做一個 brainstorm / 設計收斂，決定：
1. Docx 樣板的排版架構（封面 / TOC / 各章節對應哪個資料領域）
2. Content assembler 的 intermediate data model 設計（B2 的核心）
3. B1 ~ B4 的實作計畫
B5（OSCAL 格式）另開一次重型 brainstorm session。
```
```

---

## 目前 branch 狀態摘要

```
compliance-manager-be:
  branch: feature/ssp-import-export-phase2
  latest commit: 6fc39cf (conversation history)
  working tree: clean（只剩 pyproject.toml path dep 已 comment，正常）
  jedi-oscal pin: 0.0.17

compliance-manager-fe:
  branch: feature/ssp-import-export-phase2
  latest commit: bd92e2e (fix overwrite dialog)
  working tree: clean

jedi-oscal:
  branch: feature/ssp-import-export-phase2
  latest commit: 15ecc66 (bump 0.0.17)
  published: Nexus 0.0.17 ✅
```