CR #224 » CR-023_Stand-in後送作業台之清單與批次端點.md
CR-023 Stand-in 後送作業台之清單與批次端點（SCS-001 §7.7 職責補齊）
| 項目 | 內容 |
|---|---|
| 文件編號 | CR-023 |
| 版本 | 1.0 |
| 提出日 | 2026-09-24 |
| 提出者 | WorkBuddy AI（開發團隊） |
| 緣起 | BEAM PMO 指示「開始執行 SDD-007 §5.4.23（/auth/stip 頁），依規格先行」。動工前查證發現：SCS-001 §7.7 定義之三項職責中，「查詢待補送佇列」與「批次手動上送」無端點可達——實作僅有單筆之 POST /authorizations/{authNo}/advices，頁面無法完整實作（僅能做「輸入 authNo → 盲後送」） |
| 影響範圍 |
tools/gen_openapi.py → contracts/openapi/authorization-service.yaml（新增 2 端點＋3 schemas）；SCS-001 §7.7（職責↔端點對應）；SDD-007 §5.4.23（逐鈕定義）；AuthorizationController／AuthorizationRepository／JdbcAuthorizationRepository／StandInUploadService
|
| 狀態 | ✅ 已執行（2026-09-24）——依「規格先行」：先立 SCS-001 §7.7 → 改產生器 → 重生契約（77 端點、驗證 0 錯誤）→ 實作端點 → SDD-007 §5.4.23 逐鈕定義 → 實作頁面 |
1. 缺口之逐項證據
SCS-001 §7.7 原表列三項「職責」而未對應端點，實作現況如下：
| 規格職責 | 規格描述 | 實作現況 | 缺口 |
|---|---|---|---|
| 手動觸發上送 | 「立即執行一次『待補送上送』（等同排程之一次執行），回報本次上送筆數與結果」 | 僅 POST /authorizations/{authNo}/advices（單筆） |
⚠️ 批次語意無端點；單筆之回應為 AuthorizeResponse，不含筆數
|
| 查詢待補送佇列 | 「回報尚未上送之 Stand-in 佔用清單」 | 無 | ⚠️ 完全無端點 |
| 查詢補送結果 | 「回報指定授權之補送狀態（已上送時間／未上送）」 | 僅能由單筆 POST 之回應間接得知 |
⚠️ 無查詢端點 |
佐證：contracts/openapi/authorization-service.yaml 原有 6 端點（authorizations 之 GET/POST、{authNo}、reversals、advices、overrides、check-results），無任何 standin 清單端點；
AuthorizationRepository 亦僅有 findPendingStandIn（供排程用）而無對外查詢埠。
判定：此為規格與實作之落差（規格先寫、實作只做 1/3），非新功能需求。
若不補，§5.4.23頁面將成為半成品（違反客戶硬性要求「不造空殼」）。
2. 變更內容
2.1 新增端點（2 支）
| 方法 | 路徑 | 語意 | 回應 |
|---|---|---|---|
GET |
/api/v1/authorizations/standin?status=&limit= |
查詢 Stand-in 佔用清單（standin_flag = 1） |
200 StandInAdviceViewList
|
POST |
/api/v1/authorizations/standin/advices?batchSize= |
批次後送（手動觸發一次待補送上送） | 201 StandInAdviceResult
|
status 參數：PENDING（預設，standin_upload_at IS NULL）／UPLOADED（已後送）／ALL。
2.2 新增 schema（3 支）
-
StandInAdviceView：authNo／decision／amountMinor／currency／holdId／txTime／standinUploadAt -
StandInAdviceViewList：StandInAdviceView[] -
StandInAdviceResult：uploaded（本次上送筆數）／remaining（仍待上送筆數）
2.3 路徑設計之取捨（不設 /standin/pending）
| 方案 | 評估 |
|---|---|
/standin/pending＋/standin/uploaded 兩端點 |
❌ 兩處來源必漂移；且「補送結果」與「待補送佇列」實為同一資源之不同狀態 |
/standin?status=（採此） |
✅ 單一端點、同一 SQL 加條件；狀態值域由查詢參數表達 |
⚠️ 命名衝突檢查：standin 為字面路徑段，與 /authorizations/{authNo} 之模板段並存時，
Spring 依「literal 優先於 template」匹配；authNo 格式固定為 AUTH + 6 位數字，不衝突。
3. ★ 與 CR-022／§7.7.1 之連動（最關鍵之設計約束）
清單之篩選條件必須為 standin_flag = 1，不得為 decision = 'STANDIN'：
- 依
SCS-001 §7.7.1（#A-98真機實測揭露並修正），standin_flag之語意為
「該筆佔用未經額度服務確認」，依佔用方式（HoldResult.standIn）判定； -
§7.8新增REFERRAL後，轉人工件於本地代佔時standin_flag亦為 1； - 若以決策碼篩選 → 轉人工件被漏 → 與
#A-98修正前之缺陷同型（該筆永不後送）。
已落實於：JdbcAuthorizationRepository.STANDIN_LIST_SQL（WHERE standin_flag = 1）、
SDD-007 §5.4.23 之說明、前端頁面文案。
4. 已執行之驗證
| 項 | 證據 |
|---|---|
| 契約重生 |
tools/gen_openapi.py → 77 端點、驗證 0 錯誤；authorization-service 6 → 8 端點
|
| 單元測試 |
:services:authorization-service:test → BUILD SUCCESSFUL（含新增 adviceAll 之案例） |
| 真機驗證 | 見 HANDOVER §3.A #A-99（清單／批次／前端頁面） |
5. 未竟（誠實揭露）
- ⚠️ 「後送成功」路徑仍無法真機驗證——受
GOV-006 §4 #21（Feign 未帶 M2M outbound token → 401）阻塞，屬CR-010/011範疇；
本 CR 之端點已可正確回報失敗並保留待後送（此為規格要求之行為）。 - ⚠️ 無「取消待後送」端點（刻意）——後送係收斂額度落差之必要動作，取消將使落差永久化；誤送應以沖正處理（
SDD-007 §5.4.23已載明）。
6. 修訂記錄
| 版本 | 日期 | 說明 |
|---|---|---|
| 1.0 | 2026-09-24 | 初版：SCS-001 §7.7 三職責之端點缺口逐項證據；新增 2 端點＋3 schemas；路徑設計取捨（不設 /pending）；★ 與 §7.7.1 之連動約束（不得以決策碼篩選）；已執行與未竟 |