CR #496 » CR-051_商店對帳單（RFP-FR-4.3）未承作之語意凍結清單與交付邊界.md
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-限時郵件、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/.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 筆（完全落在我範圍內） |
★ 三項誠實揭露（不宣稱超出實作）
-
檔案為 CSV 資料檔，非 PDF 版式——RFP「列印」之版式待 S-3 範本到位後抽換（
templateCode已留痕）。 -
遞送
FAILED不可達——契約無失敗回報端點，不臆造「推測失敗」；保留給未來外部結果回報。 -
對帳單不發射領域事件——
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 衛星系統立場）；凍結前不動程式 |