# FR-038 API 清單（已上線端點盤點）

> 來源：實際註冊路由表（`api.oscal` / `api.module_frame` / `api.project` / `api.grc` 的 `create_module()`），2026-06-16 BOOT 後 dump。
> 用途：FE 套用規劃 + 交接查閱。**所有路徑前綴 `/api/1.0`**（下表省略）。
> 標記：**[v2]** = FR-038 已接 jedi_oscal_v2；**[並存]** = 與新引擎並行的現行 API（見 §A 警語）。

## ⚠️ A. 最重要：專案/稽核「雙軌並存」

專案與稽核生命週期目前有**兩套 API 並行註冊**：

| 軌 | URL 樣式 | 狀態 | FE |
|----|---------|------|----|
| **新 FR-038 引擎**（engagement / 輪次為核心）| `/oscal-project/start`、`/audit-round/<uid>/*`、`/ap/<uid>/*` | B2~B5 已接 v2 | **FE 尚未套用** |
| **現行 GRC 專案 API** | `/grc/project/<uid>/ap/<uid>/*`、`/grc/jobs/my/*`、`/grc/.../task-setup` | 現行 FE 在用；部分依賴已退役的舊 AP 表（`assessment_plan_controls/tasks`）→ **狀態待驗** | AuditReview / TaskSetup / MyTasks 在用 |

**FE 套用專案這塊 = 從 `/grc/*` 遷移到新 audit-round 引擎**，跟框架/資源庫的「乾淨換 v2」不同，需先決定遷移策略。

---

## 1. 合規框架 Framework [v2]（框架維護 2a/2b，2026-06-16 完成）— 17

| Method | URL | 用途 |
|--------|-----|------|
| POST | `/oscal-frameworks` | 框架分頁列表 |
| GET | `/oscal-frameworks/menu` | 框架選單（含巢狀版本）|
| POST | `/oscal-framework` | 新增框架 |
| GET/PUT/DELETE | `/oscal-framework/<uid>` | 框架詳情 / 編輯 / 刪除 |
| POST | `/oscal/framework-versions/import` | 版本單發匯入（PDF/Excel → catalog）|
| POST | `/oscal-framework-versions` | 版本分頁列表（樹）|
| GET | `/oscal-framework-versions/menu` | 版本選單 |
| POST | `/oscal-framework-version` | 新增版本 |
| GET/PUT/DELETE | `/oscal-framework-version/<uid>` | 版本詳情 / 編輯 / 刪除 |
| GET | `/oscal-framework-version/<uid>/catalog-tree` | catalog 樹（編輯頁）|
| PUT/DELETE | `/oscal-catalog-group/<uid>` | 群組 改 / 刪 |
| PUT/DELETE | `/oscal-catalog-control/<uid>` | 控制項 改 / 刪 |
| PUT/DELETE | `/oscal-catalog-control-assessment/<uid>` | AO 改 / 刪 |
| GET | `/oscal-framework-parse-jobs` | 兩階段匯入：草稿列表 |
| POST | `/oscal-framework-parse-jobs/parse` | 兩階段匯入：上傳解析 |
| GET/DELETE | `/oscal-framework-parse-jobs/<uid>` | 預覽 / 丟棄 |
| POST | `/oscal-framework-parse-jobs/<uid>/confirm` | 確認匯入 |

## 2. 合規資源庫 Resource Library [v2]（B1，新命名空間）— 4

| Method | URL | 用途 |
|--------|-----|------|
| POST | `/oscal/resource-libraries/list` | 分頁列表 |
| POST | `/oscal/resource-libraries` | 建立（選版本 → clone 三件組）|
| GET | `/oscal/resource-library/<uid>` | 三件組詳情 |
| POST | `/oscal/resource-library/<uid>/publish` | 發布 |

## 3. 專案成立 + 稽核引擎 [v2]（B2~B5 新引擎）— 27

### 3.1 專案成立（B2）
| Method | URL | 用途 |
|--------|-----|------|
| POST | `/oscal-project/start` | 成立專案（clone 資源庫三件組脫鉤）|
| POST | `/oscal-projects` | 專案列表 |
| GET/PUT/DELETE | `/oscal-project[/<uid>]` | 專案詳情 / 編輯 / 刪除 |

### 3.2 稽核輪次（B3a）
| Method | URL | 用途 |
|--------|-----|------|
| POST | `/projects/<uid>/audit-rounds` | 建輪次（initial/surveillance）|
| POST | `/projects/<uid>/audit-rounds/list` | 輪次列表 |
| GET | `/audit-round/<uid>` | 輪次詳情 |
| POST | `/audit-round/<uid>/launch-audit` | 啟動稽核（snapshot SSP + 建 AP/AR）|
| POST | `/audit-round/<uid>/launch-reverify` | 發起覆核（開 close-out round）|
| POST | `/audit-round/<uid>/start-auditing` | 開始填判定 |
| POST | `/audit-round/<uid>/close-round` | 結案 / 覆核連動 |

### 3.3 稽核計畫 AP（B4）
| Method | URL | 用途 |
|--------|-----|------|
| GET | `/audit-round/<uid>/ap` | 取 AP（草稿/詳情）|
| POST | `/audit-round/<uid>/ap/generate-draft` | 從 SSP 快照重生草稿 |
| PUT | `/ap/<uid>/reviewed-controls` | 設定查核控制項 |
| PUT | `/ap/<uid>/assessment-subjects` | 設定抽查名單 |
| PUT | `/ap/<uid>/tasks` | 設定行程 + 方法 |

### 3.4 稽核結果 AR（B5）
| Method | URL | 用途 |
|--------|-----|------|
| GET | `/audit-round/<uid>/ar/findings` | AO 全量判定矩陣 |
| PUT | `/ar/finding/<uid>` | 單 AO 判定 |
| POST | `/audit-round/<uid>/ar/observations` | 建 observation |
| GET/POST | `/audit-round/<uid>/ar/risks` | 系統風險列表 / 建立 |
| PUT | `/ar/risk/<uid>/findings` | 組風險（關聯 finding，多對多）|
| POST | `/audit-round/<uid>/ar/finalize` | AR 定版（→ 結案 / remediation + 生 POA&M）|

### 3.5 POA&M / 結案（B5）
| Method | URL | 用途 |
|--------|-----|------|
| GET | `/audit-round/<uid>/poam-items` | POA&M item 列表 |
| GET | `/poam-item/<uid>` | POA&M item 詳情 |
| POST | `/ar/risk/<uid>/remediations` | 建整改計畫 |
| POST | `/remediation/<uid>/milestones` | 加里程碑 |
| PUT | `/poam-milestone/<uid>` | 改里程碑 |

## 4. SSP 維護 [v2]（B3，ssp-scoped）— 約 31

| 群組 | 端點 |
|------|------|
| 系統特性 | `GET/PUT /ssp/<uid>/system-characteristic` |
| 元件 | `GET/POST /ssp/<uid>/components`、`PUT/DELETE /ssp/<uid>/components/<item_uid>` |
| 資產清冊 | `GET/POST /ssp/<uid>/inventory-items`、`PUT/DELETE .../<item_uid>` |
| 外部服務 | `GET/POST /ssp/<uid>/leveraged`、`PUT/DELETE .../<item_uid>` |
| 人員 | `GET/POST /ssp/<uid>/parties`、`PUT/DELETE .../<party_uid>` |
| 受評標的 | `GET /ssp/<uid>/ssp-resources`、`POST .../items`、`PUT/DELETE .../items/<item_uid>` |
| 控制實作 SoA | `GET /ssp/<uid>/control-implementations`、`GET/POST/PUT /ssp/<uid>/control-implementation/<cid>`、`POST/PUT .../objective/<sid>` |
| 控制/AO 程序書 | `POST/DELETE .../reference-documents[/<doc_uid>]`、`GET/POST/DELETE .../document-mappings[/<doc_uid>]`（控制與 objective 各一組）|
| 程序書池 | `GET/POST /ssp/<uid>/document-pool`、`DELETE .../<doc_uid>` |
| SoA Excel 匯入匯出 | `GET .../control-implementations/export`、`POST .../import`、`.../import/validate`、`.../import/confirm` |
| SSP 匯出 | `GET /ssp/<uid>/export`（docx/pdf/odt/json/yaml/xml）|

## 5. SSP 檔案匯入 [v2]（import-ssp P2/P3）— 約 13

| 群組 | 端點 |
|------|------|
| 資源庫範本 Excel | `POST /ssp-excel-imports/parse`、`GET/DELETE /ssp-excel-import/<uid>`、`POST .../<uid>/confirm` |
| 資源庫範本 Docx | `POST /ssp-docx-imports/parse`、`GET/DELETE /ssp-docx-import/<uid>`、`POST .../<uid>/confirm` |
| 範本下載 | `GET /ssp-import-template` |
| 專案 SSP scoped | `POST /ssp/<uid>/excel-import/upload`、`GET/DELETE /ssp/<uid>/excel-import/<uid>`、`POST .../confirm`（docx 同組）|

## 6. 資源庫範本 Module Frame（B3 接 v2 + 既有）— 約 40

| 群組 | 端點 |
|------|------|
| 範本 CRUD | `POST /module-frames`、`GET /module-frames/menu`、`/module-frame[/<uid>]`、`/module-frame/clone`、`/module-frame/start` |
| SSP 子表 [v2] | `/module-frame/<uid>/{system-characteristic,components,inventory,leveraged,parties,ssp-resources}`（各含子項 CRUD）|
| 範本預設值 | `/module-frame/<uid>/control-defaults[/<ci>]`、`/objective-defaults[/<uid>]`、`/reference-documents[/<uid>]` + 控制/AO 附掛文件 |
| 範本匯入匯出 | `control-defaults/{export,import,import/template,import/verify,import/validate,template/download}`、`ssp-export`、`ssp-import-template`、`/module-frame/{download,import}/*` |
| item（XML）| `/module-frame/item[/<uid>]`、`/module-frame/item/xml/<uid>` |

> 註：`control-defaults` / `objective-defaults` 子系統在新模型下定位待議（資源庫範本內容改走「編範本 SSP」的 SSP維護介面）。

## 7. OSCAL 匯出 [v2]（B5）— 1
| GET | `/oscal/export/<doc_type>/<uid>` | catalog/ssp/assessment-results/poam，裸 OSCAL JSON |

## 8. My Jobs / 任務執行（My Jobs view 接 v2 資料）— 4
| Method | URL |
|--------|-----|
| POST | `/grc/jobs/my/list` |
| GET | `/grc/jobs/my/projects/menu` |
| GET/POST | `/grc/job-executions/<uid>/comments` |
| PUT/DELETE | `/grc/job/comment/<uid>` |

---

## 9. [並存] 現行 GRC 專案 API（FR-038 引擎將取代；部分依賴退役舊表，狀態待驗）— 約 35

> 這些是 FR-038 重設計**前**的專案/稽核 API，現行 FE（AuditReview / TaskSetup / 專案總覽）仍呼叫。
> 其中 AR / task-setup 一支依賴已退役的 `assessment_plan_controls` / `assessment_plan_tasks` 表（B3 收尾確認 MISSING）→ **可能已不正常，需逐一驗證**。

| 群組 | 端點（節錄）|
|------|------|
| 專案 | `POST /grc/projects/list`、`GET /grc/projects/menu`、`GET/PUT/DELETE /grc/project/<uid>`、`GET /grc/project/<uid>/current-ssp-uid`、`POST /grc/project/<uid>/launch-new-round` |
| AP | `GET/PUT/DELETE /grc/project/<uid>/ap/<uid>`、`/activate`、`/launch-audit`、`/confirm-audit`、`/close-round`、`/dashboard`、`/assessment-plans/menu` |
| AR | `/ap/<uid>/ar/controls/list`、`/ar/control/<uid>`、`/ar/control/<uid>/verdict`、`/ar/control/<uid>/findings`、`/ar/finding/<uid>`、`/ar/rounds` |
| 控制/任務 | `/ap/<uid>/control-groups/list`、`/control-group/<uid>[/control/<uid>]`、`/controls/list`、`/control/<uid>/detail`、`/assessment-objects/list`、`/assessment-object/<uid>/jobs/list`、`/task-setup/tree` |
| 內審 review | `/ap/<uid>/control/<uid>/review`、`/control/<uid>/ao/<uid>/review` |
| POA&M（舊）| `/ap/<uid>/poams/list`、`/ap/<uid>/poam/<uid>` |
| Jobs | `/grc/project/<uid>/job/<uid>`、`/jobs/batch-complete`、`/assessment-object/<uid>/jobs`、`/ap/<uid>/jobs/{export,import,import/confirm,import/validate}` |
| 其他 | `POST /grc/audits/my/list`、`GET /grc/dashboard/summary`、`/project-system-info[/<uid>]`、`/project/job-execution-device*` |

---

## 總計

| 區塊 | 數量 |
|------|------|
| 框架 [v2] | 17 |
| 資源庫 [v2] | 4 |
| 專案+稽核引擎 [v2 新] | 27 |
| SSP 維護 [v2] | ~31 |
| SSP 檔案匯入 [v2] | ~13 |
| Module Frame | ~40 |
| OSCAL 匯出 [v2] | 1 |
| My Jobs | 4 |
| **小計（FR-038 v2）** | **~137** |
| [並存] 舊 GRC 專案 API | ~35 |

> 數字以路徑計（單一路徑多 method 算一條的話更少；method 展開更多）。詳細 method 見各節。