# CR-059　Corp 端點納入 OpenAPI（`rebind`／`limit-adjustments`）

| 項目 | 內容 |
|---|---|
| 文件編號 | CR-059 |
| 版本 | **1.0** |
| 狀態 | **已完成**（契約重生 **123 端點／0 錯誤**；`verify_contract_dto` **0 不符／0 需確認**） |
| 觸發 | BEAM PMO 2026-10-18：「Corp 端請幫忙立 CR 納入 OpenAPI」 |
| 需求依據 | `CR-058`（C 改綁／D 企業覆核）、`CR-055` P4-3（既有 corp 端點） |
| 影響模組 | `tools/gen_openapi.py`、`contracts/openapi/limit-service.yaml` |
| 關聯 | `CR-058`／`CR-055`／`#A-301` |

---

## 1. 現況盤點（含一處**更正**）

| # | 事實 | 說明 |
|---|---|---|
| 1 | **既有 5 個 corp 端點早已在契約** | `POST /corp-units`、`GET/PUT /corp-units/{unitId}/limit`、`POST /corp-units/{unitId}/holds`、`POST /corp-units/{unitId}/instruments` 均已存在於 `gen_openapi.py` 與 `limit-service.yaml` |
| 2 | **先前敘述為誤判** | `CR-058 §8.3`／`HANDOVER #A-301` 曾稱「`gen_openapi.py` 無 corp 區塊」——實為以 BSD `grep` 之 `\|` 替代語法查詢失效所致；本 CR 一併更正 |
| 3 | **真正缺的是 #A-301 新增的 2 支** | `POST /corp-units/{unitId}/instruments/{instrumentId}/rebind`、`POST /corp-units/{unitId}/limit-adjustments` |

> ★ 教訓：**查詢工具語法錯誤會製造「幽靈缺口」**。判定「契約有沒有某端點」應以產生器原始碼＋重生結果為準，不可只憑一次 grep。

## 2. 新增內容

### 2.1 端點

| 方法 | 路徑 | 說明 | 回應 schema |
|---|---|---|---|
| `POST` | `/api/v1/corp-units/{unitId}/instruments/{instrumentId}/rebind` | 企業卡改綁（forward-only；既有佔用不搬移） | `RebindView` |
| `POST` | `/api/v1/corp-units/{unitId}/limit-adjustments` | 企業額度申請（走覆核狀態機） | `AdjustmentView` |

### 2.2 Schema

| Schema | 用途 |
|---|---|
| `RebindCorpInstrumentRequest` | `reason`（必填）、`changedBy`（稽核標註）、`currency` |
| `RebindView` | `unitId`／`instrumentId`／`fromUnitId`／`toUnitId`／`openHoldsAtOldUnit`／`changedAt` |
| `CorpLimitAdjustmentRequest` | `targetAmount`（必填）、`reason`（必填）、`applicantId`（必填）、`currency` |
| `AdjustmentView` | `adjustmentId`／`unitId`／`unitNo`／`status`／`beforeAmount`／`afterAmount`／`applicantId`／`approverId`／`createdAt` |

### 2.3 既有 schema 描述更新

`SetCorpUnitLimitRequest`：改為「**風控直接核定**；`CR-058` D 起仍留一筆 `EFFECTIVE` 軌跡；稽核資訊以 header `X-Reason`／`X-Operator` 傳入；客戶申請請用 `POST /corp-units/{unitId}/limit-adjustments`」。

> ★ **為何稽核不放進 DTO**：`changedBy`／`operatorId` 一度加入 `SetCorpUnitLimitRequest`，遭 `verify_contract_dto` 判為「DTO 有、契約無」。改以 **header** 傳遞，不動請求 DTO 契約，並保留審計能力。

## 3. 產生器變更

- 於 `gen_openapi.py` 之 `limit-service` schema 區新增上述 4 個 schema。
- 於端點清單新增上述 2 支（`CorpLimits` tag）。
- 執行 `python3 tools/gen_openapi.py`（**無 CLI 旗標**，一次重生全部 17 份 YAML）。

## 4. 驗證

| 關卡 | 結果 |
|---|---|
| OpenAPI 結構驗證 | **123 端點／0 錯誤** |
| `verify_contract_dto` | **0 不符／0 需確認**（9 則 INFO） |
| 程式 | **未改**——端點已於 `#A-301` 實作；本 CR 只補契約 |

## 5. 明確不做

- **不手改** `contracts/openapi/*.yaml`（一律由 `gen_openapi.py` 重生）。
- **不**把 `changedBy`／`applicantId` 當授權依據（僅稽核標註；端點由服務安全層保護）。

## 6. 修訂紀錄

| 版本 | 日期 | 內容 |
|---|---|---|
| **1.0** | 2026-10-18 | 開立並完成：補入 `rebind`／`limit-adjustments` 兩支端點與 4 個 schema；更新 `SetCorpUnitLimitRequest` 描述；契約重生 **123 端點／0 錯誤**、`verify_contract_dto` **0/0**。★ 併更正「`gen_openapi.py` 無 corp 區塊」之誤判（既有 5 個 corp 端點本已在契約） |