SSP 控制項現況批次匯入匯出 — 前端整合規格

§1

功能概述

SSP 控制項現況說明（Control Implementation）的批次匯入匯出功能，讓使用者透過 Excel 一次維護所有控制項與檢查項目的實作狀態、現況描述、以及參考程序書關聯。

§2

功能流程

Step 1: （前置）上傳程序書到 SSP 程序書池
  → 如果需要在 Excel 中關聯程序書，必須先到程序書管理頁面上傳

Step 2: 匯出 Excel
  GET /export → 下載 .xlsx（黃底=可編輯，灰底=唯讀，A 欄隱藏）

Step 3: 上傳 Excel
  POST /import (multipart/form-data) → 回傳驗證結果

Step 4: 驗證結果預覽
  → 有效行 ✓ / 錯誤行 ✗（標紅，顯示錯誤訊息）
  → 使用者可在表格中直接編輯修正

Step 5: 重新驗證（可重複多次）
  POST /import/validate (JSON) → 送修正後的 items → 回傳新的驗證結果

Step 6: 確認匯入
  POST /import/confirm (JSON) → 送有效 items → 批次寫入 → 刷新列表

§3

API 規格

1. 匯出 Excel

GET /api/1.0/ssp/<ssp_uid>/control-implementations/export
Authorization: Bearer <token>

Response: 直接下載 .xlsx 檔案

前端處理：

const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } })
const blob = await res.blob()
const a = document.createElement('a')
a.href = URL.createObjectURL(blob)
a.download = `ssp-control-implementations.xlsx`
a.click()

Excel 結構（9 欄，A 欄隱藏）：

欄	標題	底色	可見	說明
A	statement_id	—	隱藏	AP task UUID，程式用
B	控制項識別碼	灰底（唯讀）	可見	如 `AC.L1-3.1.1`
C	控制項名稱	灰底（唯讀）	可見	如 `Authorized Access Control`
D	實作狀態	淡黃底（可編輯）	可見	下拉選單
E	現況描述	淡黃底（可編輯）	可見	自由文字
F	檢查項目名稱	灰底（唯讀）	可見	如 `[a] authorized users are identified`
G	檢查項目實作狀態	淡黃底（可編輯）	可見	下拉選單
H	檢查項目現況描述	淡黃底（可編輯）	可見	自由文字
I	參考程序書	淡黃底（可編輯）	可見	逗號分隔程序書名稱

實作狀態合法值： implemented, partial, not_applicable, not_implemented, inherited, unknown

行結構（黃底=可填，灰底=不可填）：

控制項行：D, E, I 可填，其他灰底
檢查項目行：G, H, I 可填，其他灰底

參考程序書欄位規則：

逗號分隔程序書名稱，如：資訊安全政策v3.0.pdf, 存取控制管理辦法.docx
名稱必須存在於 SSP 程序書池中（透過 GET /ssp/<uid>/document-pool 查看池中文件）
留空 = 不關聯程序書（不會報錯）
匯入確認後會自動建立程序書與控制項/AO 的關聯

2. 匯入 Excel（上傳 + 驗證）

POST /api/1.0/ssp/<ssp_uid>/control-implementations/import
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <Excel 檔案，僅接受 .xlsx，上限 10MB>

Response：

{
  "status": true,
  "data": {
    "valid_count": 36,
    "error_count": 40,
    "items": [
      {
        "row": 2,
        "control_identifier": "AC.L1-3.1.1",
        "control_name": "Authorized Access Control",
        "objective_id": null,
        "objective_name": null,
        "task_uid": null,
        "implementation_status": "implemented",
        "implementation_description": "組織已具備落實唯一身分識別與鑑",
        "reference_documents": "BT-I-B-13-存取控制管理程序書.docx",
        "errors": []
      },
      {
        "row": 3,
        "control_identifier": "AC.L1-3.1.1",
        "control_name": null,
        "objective_id": "e018c763-...",
        "objective_name": "[a] authorized users are identified",
        "task_uid": "e018c763-...",
        "obj_implementation_status": null,
        "obj_implementation_description": null,
        "reference_documents": "BT-I-B-13-存取控制管理程序書.docx, BT-I-B-09-人員安全與訓練管理程序書.docx",
        "errors": [
          {
            "field": "reference_documents",
            "message": "程序書不存在於池中：BT-I-B-13-存取控制管理程序書.docx, BT-I-B-09-人員安全與訓練管理程序書.docx"
          }
        ]
      }
    ]
  }
}

欄位說明：

欄位	說明	前端用途
`row`	Excel 行號	顯示錯誤位置
`control_identifier`	控制項識別碼	表格顯示
`control_name`	控制項名稱	表格顯示（控制項行有值）
`objective_id`	檢查項目 statement_id	不要顯示，confirm/validate 時原封帶回
`objective_name`	檢查項目名稱	表格顯示（檢查項目行有值）
`task_uid`	AP task UUID	不要顯示，confirm/validate 時原封帶回
`implementation_status`	控制項實作狀態	控制項行才有值，可編輯
`implementation_description`	控制項現況描述	控制項行才有值，可編輯
`obj_implementation_status`	檢查項目實作狀態	檢查項目行才有值，可編輯
`obj_implementation_description`	檢查項目現況描述	檢查項目行才有值，可編輯
`reference_documents`	參考程序書	需顯示，逗號分隔名稱，可編輯
`errors`	驗證錯誤清單	空陣列=有效，有值=該行有錯

判斷行類型：

objective_id != null → 檢查項目行，顯示 objective_name
objective_id == null → 控制項行，顯示 control_name

3. 重新驗證（JSON）

POST /api/1.0/ssp/<ssp_uid>/control-implementations/import/validate
Authorization: Bearer <token>
Content-Type: application/json

Request Body： 與 /import/confirm 相同格式，將所有 items 原封送回

{
  "items": [
    {
      "row": 2,
      "control_identifier": "AC.L1-3.1.1",
      "control_name": "Authorized Access Control",
      "objective_id": null,
      "objective_name": null,
      "task_uid": null,
      "implementation_status": "implemented",
      "implementation_description": "已修正的描述...",
      "reference_documents": ""
    },
    {
      "row": 3,
      "control_identifier": "AC.L1-3.1.1",
      "control_name": null,
      "objective_id": "e018c763-...",
      "objective_name": "[a] authorized users are identified",
      "task_uid": "e018c763-...",
      "obj_implementation_status": "implemented",
      "obj_implementation_description": "修正後的描述...",
      "reference_documents": ""
    }
  ]
}

Response： 與 POST /import（上傳 Excel）完全相同格式

4. 確認匯入（批次寫入）

POST /api/1.0/ssp/<ssp_uid>/control-implementations/import/confirm
Authorization: Bearer <token>
Content-Type: application/json

Request Body： 將驗證結果中 errors 為空的項目 原封送回。

Response：

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

§4

前端 UI 建議

按鈕位置

放在 SSP 控制項現況列表頁面的工具列：

「匯出 Excel」→ 點擊直接下載
「匯入 Excel」→ 點擊開啟 Dialog

匯入 Dialog — 驗證結果表格

表格欄位：

行號	類型	名稱	實作狀態	現況描述	參考程序書	狀態
2	控制項	AC.L1-3.1.1 Authorized Access Control	implemented	組織已具備...	資訊安全政策.pdf	✓
3	檢查項目	[a] authorized users are identified			~~BT-I-B-13-...~~	✗ 程序書不存在
4	檢查項目	[b] processes acting on behalf...				✓

可編輯欄位：

行類型	可編輯欄位
控制項行	`implementation_status`（下拉）、`implementation_description`（文字）、`reference_documents`（文字）
檢查項目行	`obj_implementation_status`（下拉）、`obj_implementation_description`（文字）、`reference_documents`（文字）
不可編輯	`control_identifier`、`control_name`、`objective_id`、`objective_name`、`task_uid`

參考程序書欄位處理：

顯示逗號分隔的程序書名稱
錯誤時標紅，hover 顯示「程序書不存在於池中：xxx」
使用者可清空此欄位（不關聯程序書）或修正名稱後重新驗證
提示：「程序書名稱需與程序書池中的檔案名稱或描述完全一致」

錯誤處理

HTTP Status	錯誤碼	情境	前端處理
400	`GRC_400001`	檔案格式無效（非 .xlsx 或 header 不符）	提示「請使用匯出的 Excel 範本」
400	`GRC_400002`	檔案超過 10MB	提示「檔案大小超過限制」
404	`GRC_404012`	SSP 不存在	提示錯誤

§5

API 總覽

Method	URL	說明
GET	`/api/1.0/ssp/<ssp_uid>/control-implementations/export`	匯出 Excel
POST	`/api/1.0/ssp/<ssp_uid>/control-implementations/import`	上傳 Excel + 驗證
POST	`/api/1.0/ssp/<ssp_uid>/control-implementations/import/validate`	JSON 重新驗證
POST	`/api/1.0/ssp/<ssp_uid>/control-implementations/import/confirm`	確認匯入

§6

注意事項

參考程序書的使用前提

匯入 Excel 中填寫參考程序書名稱前，必須先將程序書上傳到 SSP 程序書池：

進入 SSP 程序書管理頁面（GET /ssp/<uid>/document-pool）
上傳程序書（POST /ssp/<uid>/document-pool）
上傳完成後，在 Excel 的 I 欄填入程序書的檔案名稱或描述
匯入時系統會從池中比對名稱，自動建立關聯

如果不需要關聯程序書，I 欄留空即可。