# CR-051　商店對帳單（RFP FR §4.3）未承作——語意凍結清單與交付邊界

| 項目   | 內容                                                                                          |
| ---- | ------------------------------------------------------------------------------------------- |
| 文件編號 | CR-051                                                                                      |
| 版本   | **1.4**                                                                                     |
| 狀態   | **S-1～S-7 全數凍結並已落地實作**（2026-10-17）；`SCS-014 §7.2`（v1.5，已實作＋真機驗證）、契約重生、`V4` 遷移、DDD 四層與 4 端點皆完成（見 §7） |
| 觸發   | BEAM PMO 2026-10-17 核准：「ACQ-4.3 商店對帳單——開 CR」（`CR-050 §2.1` 裁定之接續）                                 |
| 需求依據 | RFP `FR.md §4.3 商店對帳單`（Level 1 收單平台）／`§4.4 商店報送與報表`（邊界線索）／`BRD-002 v1.1` ACQ-4.3 缺口註記       |
| 影響模組 | **本 CR 不動程式、不補端點**——語意凍結後方由 SCS／SDD／契約（`gen_openapi.py`）承載                                  |
| 關聯   | `CR-050`（對映誠實化）／`GOV-004 §7`（`GAPS` 缺口登錄）                                                   |

---

## 1. 問題陳述

RFP `FR.md §4.3`（**商店對帳單**）為 Level 1「收單平台」之**已列需求**：

> 1. 列印週期：每日、兩日、月結
> 2. 種類：全額發票、全收據(自然人)
> 3. 郵寄方式：1-掛號、2-限時郵件、5-平信
> 4. 補印
> 5. 電子發票

**現況（2026-10-17 實查）**：`merchant-service` 僅有三端點（`POST /merchants`、  
`GET /merchants/{merchantId}`、`POST /merchant-settlements`——後者為 ACQ-4.2「**商店請款**」語意），  
**對帳單五項子需求皆無承作**；契約／`SDD-006 §7` 亦無任何 statements 路徑。  
`CR-050 §2.1` 已裁定：`merchant-settlements`（請款）≠ `merchant-statements`（對帳單），  
**不可混用對映**；追溯對映已誠實化（`GAPS` 登錄，狀態＝真實缺口）。

## 2. 交付邊界之關鍵線索（實查，非臆造）

RFP `§4.4`（ACQ-4.4 商店報送與報表）之**廠商回覆原文**：「報表功能由**衛星系統**提供，  
CAKU 提供**資料**」——即投標立場已把「文件產出類」定位為**衛星系統產出、本平台供料**。  
商店對帳單之「列印／郵寄／電子發票」極可能同屬此邊界，但 **§4.3 之廠商回覆僅記  
「#2 需要客戶化開發」並請銀行提供格式範本**，未明確切割系統邊界。  
**→ 本 CR 第一待裁項即此（S-1）**；在 S-1 凍結前，本平台貿然補端點或建文件管線  
都有「做錯邊、重複投資」之風險。

## 3. 待凍結清單（逐條裁定；凍結前不動程式）

| #   | 待凍結項                                                                        | 依據／現況                                                         | 候選立場（供裁定）                                                                        |
| --- | --------------------------------------------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| S-1 | **系統邊界**：對帳單之「資料彙總」與「文件產出／遞送」各歸誰？                                           | RFP §4.4 廠商回覆「報表由衛星系統提供、CAKU 提供資料」；§4.3 未明確                   | (a) 本平台出**對帳單資料查詢 API**、文件產出與遞送歸衛星系統（與 §4.4 立場一致）；(b) 本平台全責（含 PDF／電子發票產出）；(c) 混合 |
| S-2 | **列印週期**：每日／兩日／月結之資料粒度與切帳時點                                                 | 現 `merchant-settlements` 為逐筆請款記錄（`settlementDate`）；「兩日結」無既有語意 | 待客戶確認週期與切帳規則；月結是否跨自然月                                                            |
| S-3 | **種類**：全額發票 vs 全收據(自然人)之稅籍語意                                                | RFP §4.3 #2（廠商註記「需要客戶化開發」）                                    | 待客戶提供格式／範本（RFP 廠商補充說明已要求）                                                        |
| S-4 | **郵寄方式**（1-掛號／2-限時／5-平信）：欄位歸屬                                               | RFP §4.3 #3                                                   | 若 S-1 採 (a)，遞送屬外部——本平台是否僅需**保留設定欄**？                                             |
| S-5 | **補印**：重新列印之控管                                                              | RFP §4.3 #4                                                   | 次數上限／授權／留痕（稽核）——語意待客戶確認                                                          |
| S-6 | **電子發票**：對接標的與本平台責任                                                         | RFP §4.3 #5                                                   | 財政部電子發票平台／委外加值中心——**外部依賴**，須客戶指明現行做法                                             |
| S-7 | **API 形態**（S-1 定後才議）：查詢（`GET /api/v1/merchant-statements…`）或產出觸發（`POST`）＋批次 | `SDD-006 §7`／`gen_openapi.py`（契約產生器）                          | 依 S-1～S-6 凍結結果，由 SCS→SDD→契約**規格先行**後實作                                           |

## 4. 建議立場（架構裁定；開發團隊 2026-10-17 擬，**待 BEAM PMO 核准**）

> 僅就**架構可判定**之 S-1／S-2／S-7 擬立場；S-3～S-6 屬客戶業務口徑，不在本節範圍（維持待裁定）。  
> 每項皆附**實查證據**，並標示仍待客戶補足之口徑——**不臆造**。

| 項              | 建議立場                                                                                                                                             | 依據（實查／原文／先例）                                                                                                                                                                                                                         | 待補（客戶口徑）                                       |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
| **S-1** 系統邊界   | **(a) 供料為主**：本平台承作「對帳單**資料查詢 API**」；文件產出（列印／PDF／電子發票）與郵寄遞送歸**衛星系統**                                                                              | RFP §4.4 廠商回覆原文「報表功能由**衛星系統**提供，CAKU 提供**資料**」——投標立場已把文件產出類定位為外部產出、本平台供料；可避免重複投資                                                                                                                                                     | 客戶是否接受對帳單循 §4.4 同一邊界（若要求本平台產出文件→改 (b)，**另估工**） |
| **S-2** 列印週期   | **週期由 `settlement_date` 彙總推導，不新增週期欄**；切帳時點以**參數**承載                                                                                              | 實查 `merchant_settlements`（V1 baseline）：具 `settlement_date` DATE NOT NULL、`batch_count`、金額欄；索引 **`idx_ms_merchant (merchant_id, settlement_date DESC)` 已可支援「依特店＋結算日區間」供料查詢**——每日／兩日／月結皆可由日期區間彙總得出。參數化依 `CR-045` 2.4.3（工作日曆／批次／帳單參數）慣例 | 切帳時點（cut-off time）、「兩日結」之起算日                   |
| **S-7** API 形態 | 若 S-1＝(a)：提供**唯讀供料查詢** `GET /api/v1/merchant-statements?merchantId&from&to&cycle`（由 `gen_openapi.py` **規格先行**，本階段**不動程式**）；若 (b)：另含產出／遞送 API（另估） | 契約產生器即單一真實來源（`gen_openapi.py`）；`CR-050 §2.1` 已禁止以 `merchant-settlements` 混充對帳單——新端點須由**新 CR＋生成器規格**建立                                                                                                                                | 依 S-1 結果而定                                     |

**守界**：本節為**建議**，非已定案；核准後方進入 SCS／SDD／契約。核准前**不補端點、不動程式、不建表**。

## 5. BEAM PMO 裁定結果（2026-10-17）— S-1～S-6 凍結

| 項       | 裁定                                                                | 落地影響（待 SCS 承接）                                                              |
| ------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------- |
| **S-1** | **(b) 本平台全責**（含文件產出：列印／PDF／電子發票）                                  | 推翻建議 (a) 供料為主 → 本平台須建**對帳單產出**能力；邊界不再歸衛星系統                                  |
| **S-2** | **月結為「跨自然月」**                                                     | 月結週期**不對齊**自然月邊界（例：每月 21 日～次月 20 日）→ 週期起訖須**可設定**（參數化），不可硬編自然月              |
| **S-3** | **目前無範本，由我方自行設計，屆時替換**                                            | 對帳單格式／範本由我方設計（**暫行版**），客戶提供後替換 → 範本須**可抽換**（外置／參數化），不可寫死於程式                 |
| **S-4** | 雖 S-1=(b)，**郵件遞送由銀行 mail room 部門負責、委外寄送**——**仍須有記錄可追蹤**           | 本平台產出文件後**交付 mail room**；須建立**遞送記錄（追蹤）**：誰、何時、何批、交予誰、狀況——遞送本身外部化但**軌跡在本平台** |
| **S-5** | **補印無次數上限、無需授權**，但**要留痕**                                         | 補印不設限、不需授權流程；**每一次補印皆須留痕**（稽核軌跡）                                            |
| **S-6** | 現行做法兩種：**API（其實是 MQ）**與**傳檔**；**大部分銀行直接用財政部網頁 upload（傳檔）** | 電子發票對接須**以傳檔為主**（產出檔案供 upload），並保留 MQ／API 路徑為次要 → 兩條路徑皆需，優先傳檔               |
| **S-7** | 依 S-1=(b) 推導：**產出／遞送 API**（含供料查詢＋產出＋檔案匯出）；S-6 傳檔需**檔案產出**         | 由 `gen_openapi.py` 規格先行；若此推導與 BEAM PMO 原意不符請更正                                      |

**★ 設計約束（由 S-2／S-3／S-5 歸納，須落 SCS）**：週期起訖、**對帳單範本**、補印次數**皆應參數化**（`CR-045` 三位一體慣例）——  
客戶口徑未定者先給暫行值並可替換，**不可硬編**。

**★ 補充裁定（2026-10-17，補足 RFP §4.3 之 #2／#3；S-3／S-4 至此全數凍結）**：

- **#2 種類**（全額發票／全收據(自然人)）→ 作為**特店屬性參數** `ticket_type`（`INVOICE`／`RECEIPT`），  
  產出時讀取並**留存於對帳單主檔**（留痕）。
- **#3 郵寄方式**（1-掛號／2-限時／5-平信）→ 預設由參數提供，實際值記錄於遞送記錄  
  `mail_type`（`REGISTERED`／`EXPRESS`／`ORDINARY`）。
- **S-7** 確認：API 含**供料查詢＋產出＋檔案匯出＋遞送記錄** 4 支（原「依 S-1=(b) 推導」之待確認項結案）。
- **★ 留痕原則**：參數可調整，但「**當次產出所用之值**」須寫入主檔／遞送記錄——  
  **事後改參數不得改變已產出對帳單之語意**（同 `SCS-002 §7.9.1`「軌跡 vs 現行定義」）。

## 6. 凍結後之交付路徑（鐵律）

```
S-1～S-6 BEAM PMO／客戶逐條凍結 → SCS（承作範圍與權責）→ SDD／契約（gen_openapi.py）
→ 實作（含真 Oracle／真機驗證）→ 追溯（GAPS 除名、BRD-002/GOV-004 重生）→ E2E
```

★ **未凍結前之守界**：不恢復任何 `merchant-statements` 端點宣告（`CR-050 §2.1`）、  
不建「有人發沒人收」之表、不以 mock 充數（客戶硬性要求）。  
★ **若客戶裁定對帳單屬衛星系統**：本 CR 轉為「供料契約」規格（資料 API），  
`GAPS` 依新語意重新表述——**需求不消失，對映如實**。

## 7. 實作執行結果（2026-10-17，`#A-284`）

> 狀態：**S-1～S-7 全數落地並真機驗證**。以下皆為**實測值**，非計畫值。

| 項目 | 結果 | 證據 |
|---|---|---|
| 契約 | ✅ 4 端點＋5 schema 已重生 | `gen_openapi.py` → **110 端點／0 錯誤**；僅 `merchant-service.yaml` 變動（+504 行） |
| 契約↔DTO | ✅ **不符 0／需確認 0** | `verify_contract_dto.py`（18 服務） |
| 契約缺陷修補 | ✅ 補 GET 查詢參數 | ★ 原產生器之 `GET /merchant-statements` **只帶 `TraceIdHeader`**，與 §7.2.4 明列 `?merchantId&from&to&cycle` **不符** → 補**專屬** query 元件（`from`／`to` 為**閉區間**，與請款查詢之半開 `(from,to]` 語意不同，故不重用） |
| Flyway | ✅ `V4__merchant_statements.sql` | `merchant_statements`／`statement_deliveries`＋`merchant_statement_no_seq`；`validate_sql` **違規 0**；真 Oracle `ALL_TABLES`／`ALL_SEQUENCES` 實查存在 |
| 程式 | ✅ DDD 四層＋REST 4 端點 | domain 不變式（期間、淨額、金額非負）／jdbc 真彙總／service（冪等、留痕、檔案）／controller |
| 測試 | ✅ **77 測 0 失敗**（新增 11 例） | 真 Oracle（V1～V4）＋真 **Garage** ＋真服務編排，**零替身** |

**★ 真機 HTTP 端到端（真 Oracle ＋ 真 Garage ＋ Keycloak 認證，port 8095）**

| 步驟 | 結果 |
|---|---|
| `POST /merchant-statements/generate`（MERCH000002，2026-09-01～09-30） | `201`；`statementNo=MST202610000001`、`ticketType=INVOICE`（參數預設並**留痕**）、`status=GENERATED` |
| 彙總正確性 | 主檔 `TXN_COUNT=3／GROSS=1,500,000／FEE=32,500／TAX=1,000／NET=1,466,500` **與來源 `MERCHANT_SETTLEMENTS` 手算逐欄一致** |
| 檔案產出 | 服務日誌「已上傳 bucket=cardcore-artifacts key=statements/<id>.csv **bytes=490**」；`FILE_SIZE_BYTES=490`、`FILE_CHECKSUM` 有值 |
| `GET …/{id}/file` | `200`；回 `contentType=text/csv; charset=UTF-8`、`sizeBytes=490`、checksum（與主檔一致） |
| `POST …/{id}/deliveries`（MAIL_ROOM／handedTo） | `201`；`status=HANDED_OFF`、`handedAt` 有值、`mailType=REGISTERED`（參數） |
| `GET /merchant-statements?merchantId&cycle` | `200`；★ 對帳單狀態已同步為 **`HANDED_OFF`** |
| 期間語意 | 以 `from=09-01&to=09-30` 查 → **1 筆**（完全落在我範圍內） |

**★ 三項誠實揭露（不宣稱超出實作）**

1. **檔案為 CSV 資料檔，非 PDF 版式**——RFP「列印」之版式待 S-3 範本到位後抽換（`templateCode` 已留痕）。
2. **遞送 `FAILED` 不可達**——契約無失敗回報端點，不臆造「推測失敗」；保留給未來外部結果回報。
3. **對帳單不發射領域事件**——`SAD-002 §3.13`／`SDD-006 §4.2` 未定義其 payload → 不臆造（同 `SCS-014 §10 #8` 原則）。

**★ 實作期發現並修正之語意瑕疵**：郵寄方式參數預設原會套用到 `MQ`／`E_INVOICE_UPLOAD` 通道，
使電子發票遞送軌跡出現「掛號」——看似掛號寄出、實為傳檔。已限縮為**僅實體郵寄通道**
（`MAIL_ROOM`／`OUTSOURCE`）套用，電子通道記 `null`（由真機測試揭露）。

---

## 8. 修訂紀錄

| 版本      | 日期         | 內容                                                                                                                                                                                                                                |
| ------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **1.4** | 2026-10-17 | **S-1～S-7 全數落地並真機驗證**（新增 §7）：契約重生（110 端點／0 錯誤、DTO 不符 0）＋**補 GET 查詢參數**（原僅 `TraceIdHeader`，與 §7.2.4 不符）＋`V4` 二表＋DDD 四層＋**真機 E2E**（4 端點、彙總與來源逐欄一致、檔案真上傳 490 bytes、遞送後狀態轉 `HANDED_OFF`）＋**77 測 0 失敗**（新增 11 例真 Oracle＋真 Garage）。★ 三項誠實揭露（CSV 非 PDF／`FAILED` 不可達／不發射事件）與一項實作期語意修正（郵寄參數僅實體通道） |
| **1.3** | 2026-10-17 | **S-1～S-7 全數凍結**：補入 RFP `§4.3 #2` **種類**（`ticket_type` 特店屬性參數、產出留痕）與 `#3` **郵寄方式**（`mail_type` 留存遞送記錄）；**S-7 確認**為 4 支 API；確立**留痕原則**（參數可調但當次產出值須留存，不得因改參數改變歷史對帳單語意）。已落地 `SCS-014 §7.2`（v1.4，已核定）                                 |
| **1.2** | 2026-10-17 | **BEAM PMO 裁定 S-1～S-6 凍結**（§5）：S-1 **(b) 本平台全責**（推翻建議 (a)）、S-2 月結**跨自然月**（週期可設定）、S-3 範本**暫由我方設計、可抽換**、S-4 郵件遞送歸**銀行 mail room／委外**但**須留遞送記錄**、S-5 補印**無上限、免授權、但留痕**、S-6 電子發票**以傳檔為主**＋MQ 為輔。★ 歸納設計約束：週期起訖／範本／補印**皆參數化**。下一步 `SCS-014` 增補 |
| **1.1** | 2026-10-17 | **新增 §4 建議立場**（開發團隊擬，**待 BEAM PMO 核准**）：S-1 供料為主（依 RFP §4.4 衛星系統立場）、S-2 週期由 `settlement_date` 彙總推導不新增欄（索引 `idx_ms_merchant` 已備）、S-7 唯讀供料查詢（規格先行不動程式）。S-3～S-6 仍待客戶口徑                                                                         |
| 1.0     | 2026-10-17 | 開立（BEAM PMO 核准）：承載 `ACQ-4.3` 商店對帳單缺口之語意凍結清單 S-1～S-7；邊界線索（RFP §4.4 衛星系統立場）；凍結前不動程式                                                                                                                                                        |