批次匯入匯出功能設計規格書

提供 Excel 批次匯入匯出機制，讓使用者能高效維護專案內的 SSP 控制項現況說明與 Job 任務設置，取代逐筆 UI 操作。

1.1 功能範圍

1.2 設計原則

• 匯出即範本：匯出的 Excel 帶有現有資料，使用者在此基礎上修改後直接匯入
• 三步驟流程：上傳 → 驗證預覽 → 確認寫入，降低誤操作風險
• 支援重新驗證：前端可在表格中修正錯誤後，送 JSON 重新驗證，不需重新上傳 Excel
• 防禦性寫入：confirm 階段也做基本驗證，防止未經 validate 直接送入錯誤資料

兩個模組共用相同的匯入匯出流程架構：

                    ┌──────────────┐
                    │   匯出 Excel  │
                    │  GET /export  │
                    └──────┬───────┘
                           │
                    瀏覽器下載 .xlsx
                  （灰底=唯讀，黃底=可編輯）
                           │
                    使用者離線編輯 Excel
                           │
                    ┌──────▼───────┐
                    │  上傳 Excel   │
                    │ POST /import  │
                    │(multipart)    │
                    └──────┬───────┘
                           │
                    ┌──────▼───────┐
                    │  驗證結果預覽  │
                    │ valid / error │
                    └──────┬───────┘
                           │
                  ┌────────┼────────┐
                  │有錯誤            │全部有效
                  ▼                  ▼
          前端表格編輯         ┌─────────────┐
                  │           │  確認匯入     │
                  ▼           │POST /confirm │
          ┌─────────────┐    └──────┬──────┘
          │  重新驗證     │           │
          │POST /validate│    批次寫入完成
          │  (JSON)      │    刷新列表
          └──────┬──────┘
                 │
          回到驗證結果預覽
          （可重複多次）

2.1 API 端點模式

每個模組提供 4 支 API：

2.2 Excel 格式規範

2.3 驗證結果格式

{
  "status": true,
  "data": {
    "valid_count": 45,
    "error_count": 3,
    "items": [
      {
        "row": 2,
        "...欄位資料...",
        "errors": []
      },
      {
        "row": 5,
        "...欄位資料...",
        "errors": [
          {"field": "欄位名", "message": "錯誤訊息"}
        ]
      }
    ]
  }
}

• errors 為空陣列 → 該行有效
• errors 有值 → 該行有錯誤，前端標紅顯示

2.4 Confirm 防護機制

即使未經 validate 直接呼叫 confirm，也會：

• 驗證必填欄位（跳過無效行）
• 驗證合法值（如 status、job_type）
• 回傳 skipped_count 告知跳過筆數

3.1 API 端點

3.2 Excel 結構（7 欄）

3.3 實作狀態合法值

implemented, partial, not_applicable, not_implemented, inherited, unknown

3.4 行類型判斷

匯出時：

• 每個控制項先輸出一行（控制項行）
• 接著輸出該控制項下的所有檢查項目（每個一行）

匯入時：

• 有 C 或 D 欄值 → 控制項行
• 有 F 或 G 欄值（且 C/D 無值） → 檢查項目行
• 檢查項目行按控制項下的順序對應 statement_identifier

3.5 資料來源

3.6 驗證結果欄位

3.7 Confirm Response

{
  "updated_controls": 15,
  "updated_objectives": 30,
  "total": 45,
  "skipped_count": 0
}

4.1 API 端點

4.2 Excel 結構（10 欄，A 欄隱藏）

4.3 排序

匯出資料按 控制項群組 → 控制項識別碼 → 檢查項目名稱 升序排列。

4.4 隱藏欄位設計

• A 欄（job_uid）使用 openpyxl column_dimensions["A"].hidden = True
• 使用者在 Excel 中看不到此欄
• openpyxl iter_rows(values_only=True) 仍能讀取隱藏欄的值
• 匯入時用 job_uid 精確匹配，解決同一 AO 下多個同名 Job 的問題

4.5 驗證規則

4.6 部門/設備重名處理

• 驗證階段：檢測到重名部門/設備時報錯，提示使用者改用 UI 設定
• Confirm 階段：重名的 name → uid mapping 已排除，不會指定到錯誤的部門/設備

4.7 指派人員更新機制

• update_job 需要 control_uid 才能更新 assignees（repo 層限制）
• Confirm 時透過 JobImportLookupQuery.get_job_control_uid_map() 批次查詢 job_uid → control_uid 的 mapping
• 查詢路徑：Job → WorkflowExecution → AP Task → TaskControl → Control → uid

4.8 權限控制

• Confirm 端點需要 manager 角色
• 透過 _check_manager_role() 在 service 層驗證
• 非 manager 回傳 403 GRC_403002

4.9 驗證結果欄位

4.10 Confirm Response

{
  "updated_count": 30,
  "skipped_count": 0
}

6.1 DDD 層級分佈

api/                          ← Route 層（HTTP 邊界）
├── oscal/routes/ssp/
│   └── ssp_control_impl_import_route.py    ← SSP 匯入匯出 routes
├── oscal/serializers/ssp/
│   └── ssp_control_impl_import.py          ← SSP Marshmallow schemas
├── grc/routes/
│   └── job_import_route.py                 ← Job 匯入匯出 routes
└── grc/serializers/
    └── job_import.py                       ← Job Marshmallow schemas

app/                          ← App Service 層（業務邏輯編排）
├── oscal/service/
│   └── ssp_control_impl_import_service.py  ← SSP 匯入匯出 service
└── grc/service/
    └── job_import_service.py               ← Job 匯入匯出 service

infra/                        ← 基礎設施層（ORM 查詢）
├── oscal/repository/
│   └── ssp_catalog_title_query.py          ← SSP 控制項/AO 標題查詢
└── grc/repository/
    ├── job_export_query.py                 ← Job 匯出資料查詢
    └── job_import_lookup_query.py          ← Job 匯入驗證/確認 lookup

6.2 DI Container

6.3 依賴關係

SSP Import Service：

SspControlImplImportService
├── SystemSecurityPlanDomainService     (SSP 查詢)
├── ControlImplementationDomainService  (控制項查詢)
├── ControlImplementationObjectiveDomainService (Objective 查詢)
├── SspControlImplementationService     (upsert 複用)
└── SspCatalogTitleQuery                (標題查詢，infra)

Job Import Service：

JobImportService
├── JobService                          (update_job 複用)
├── JobExportQuery                      (匯出資料查詢，infra)
├── JobImportLookupQuery                (驗證/確認 lookup，infra)
├── ProjectDomainService                (權限檢查用)
└── ProjectParticipantDomainService     (權限檢查用)

7.1 新增檔案

7.2 修改檔案