# 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` 之連動約束（**不得以決策碼篩選**）；已執行與未竟 |