# SCS-019　批次框架與作業（common-batch）程式設計規格（跨域）

| 項目 | 內容 |
|---|---|
| 文件編號 | SCS-019 |
| 版本 | 1.0 |
| 狀態 | **已核定（規格先行·跨域）** |
| 對應需求 | 批次相關 FR（`ISS-2.8` 帳單批次、`ISS-2.13` 清算、`SYS-2.8` 遷移、`ISS-2.7` 分期結清等）＋ `BRD-003` 效能測試／容量規劃 NFR |
| 套件根 | `com.beam.cardcore.batch`（平台函式庫 `common-batch`） |
| 關聯文件 | `CSP-001 §8`、`SDD-001~007`、`BRD-002`、`GOV-005` |

---

## 1. 對應需求

| FR 編號 | 需求名稱 | 批次作業 |
|---|---|---|
| `ISS-2.8` | 信用卡帳單管理 | 帳單週期產生批次 |
| `ISS-2.13` / `ACQ-4.6` / `DEB-3.6` | 清算結算 | 清算檔解析／結算批次 |
| `SYS-2.8` / `SYS-3` | 資料遷移 | 遷移波次批次（W0–W4） |
| `ISS-2.7` | 分期 | 分期到期／提前清償批次 |
| `RWD-5.1` | 點數 | 點數到期批次（`POINTS_EXPIRY_BUCKETS`） |

> 另含：`SETTLEMENT_BATCH_JOB`（結算）、`INTEREST`／`FEE` 計提批次。

---

## 2. 框架職責（引用 `common-batch` 實測類別）

依 `common-batch` 函式庫（已交付，3 測試 0 失敗）：

| 類別 | 職責 |
|---|---|
| `BatchJob` | 批次定義（名稱、參數、排程） |
| `JobStatus` | 狀態（PENDING／RUNNING／COMPLETED／FAILED） |
| `JobExecution` `JobExecutionRepository` `InMemoryJobExecutionRepository` | 執行實例與儲存（可續跑依據） |
| `BatchOrchestrator` | 編排與調度 |
| `ScheduledBatchRunner` | 排程觸發（Spring `@Scheduled` 或 Quartz） |
| `SettlementBatchJob` | 結算範例作業 |

**設計原則**：冪等（同參數重跑安全）、可續跑（檢查點）、容錯（單筆失敗不中斷整批，錯誤隔離）。

---

## 3. 批次作業清單（設計意圖，待各服務 SCS 凍結）

| 作業 | 所屬服務 | 頻率 | 關鍵邏輯 |
|---|---|---|---|
| 帳單週期產生 | `statement-service` | 月 | 取當期交易／餘額產生 `STATEMENTS` |
| 清算檔解析／結算 | `clearing-service` | 日 | 解析 VCF/EMS，對帳後請款 |
| 遷移波次 | `migration-service` | 專案期 | W0–W4，可暫停／回退 |
| 分期到期 | `installment-service` | 日 | 標 OVERDUE、影響 DEFAULTED |
| 點數到期 | `rewards-service` | 日 | `POINTS_EXPIRY_BUCKETS` → EXPIRE |
| 利息／費用計提 | `pricing-service`＋`posting-service` | 日 | ADB 計息、費用入帳 |
| 繳款分配 | `payment-service` | 即時＋批次 | 自扣批次 |

---

## 4. 關鍵邏輯

- **分塊（Chunk）**：大批量分塊處理，降低記憶體與鎖定。
- **續跑**：經 `JobExecution` 檢查點，中斷後從斷點續跑（遷移／清算必須）。
- **補償**：失敗批次經冪等重試；遷移須支援回退（`SCS-015`）。
- **排程**：`ScheduledBatchRunner` 觸發；時區與銀行營業日曆須納入。

---

## 5. 外部依賴與降級

| 依賴 | 失敗處理 |
|---|---|
| 各領域服務（資料來源／入帳目標） | 批次失敗重跑（冪等）；不影響線上即時交易 |

---

## 6. 測試案例（對應 `TRP-001`）

- 批次冪等（重跑無副作用）、可續跑（中斷續跑正確）、錯誤隔離（單筆失敗整批續行）
- 各作業對應 FR 驗收（見 §1）

---

## 7. 已知限制（誠實揭露）

- 各批次作業之**具體參數與排程頻率**待對應領域 SCS（`SCS-011`/`013`/`015` 等）凍結。
- `common-batch` 為函式庫，實際作業類別須由各服務實作並註冊。
- 排程協調器（避免重複觸發、分散式鎖）設計待基礎設施確認。