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 端點本已在契約） |