CR #201 » SCS-014_特約商店收單服務程式設計規格.md
SCS-014 特約商店收單服務（merchant-service）程式設計規格
| 項目 | 內容 |
|---|---|
| 文件編號 | SCS-014 |
| 版本 | 1.5（§7.2 已實作並真機驗證：契約重生／V4 遷移／DDD 四層／11 例真 Oracle＋真 Garage 整合測試；補 §7.2.6 實作狀態與三項誠實揭露） |
| 狀態 | 已核定（規格先行） |
| 對應需求 |
ACQ-4.1（商戶管理）、ACQ-4.2（商店請款）、ACQ-4.3（商店對帳單） |
| 服務埠號 | 待骨架產生時依 CSP-006 §4 分配（自 8081 起編） |
| 套件根 | com.beam.cardcore.mch |
| 權威 schema | CC_MCH |
| 關聯文件 |
SDD-001 §5.9、SDD-002 §3.6、BRD-002、GOV-005
|
1. 對應需求
| FR 編號 | 需求名稱 | 來源 |
|---|---|---|
ACQ-4.1 |
商戶管理（特約商店） | BRD-002 |
ACQ-4.2 |
商店請款 | BRD-002 |
ACQ-4.3 |
商店對帳單 | BRD-002 |
1.1 上層設計依據（本規格不重複這些圖，僅引用）
| 圖種 | 文件 | 數量（實測） | 本服務相關 |
|---|---|---|---|
| ER-Diagram | SDD-001_領域模型與ER-Diagram |
16 個 erDiagram
|
MERCHANTS/MERCHANT_SETTLEMENTS 實體（SDD-001 §5.9） |
| DFD | SDD-002_DFD與流程分解 |
10 個 flowchart | 收單處理流（SDD-002 §3.6） |
| Sequence | SDD-003_Sequence-Diagrams |
15 個 sequenceDiagram
|
商戶請款／對帳時序 |
| 狀態機 | SDD-005_狀態機設計 |
10 個 stateDiagram
|
⚠️ MERCHANTS.status（ACTIVE→SUSPENDED→TERMINATED）以 CHECK 控管，未定義正式狀態機 |
| API Contract |
SDD-006 + contracts/openapi/merchant-service.yaml
|
17 份 | 本服務 7 支端點（特店 2／請款 1／對帳單 4） |
2. 服務職責與邊界
承作：
- 商戶主檔（
MERCHANTS：名稱、類型、MCC、組織、收單行、終端機、風險等級、KMC 類別） - 商戶結算（
MERCHANT_SETTLEMENTS：毛額／費用／稅／淨額） - 商戶請款、對帳單
不做（屬他服務）：
- 清算對帳 →
clearing-service - 交易授權 →
authorization-service
3. 領域模型
- 聚合：
Merchant（商戶）、MerchantContract（契約）、MerchantSettlement（結算，依services.yamlaggregates） - 值物件：
MerchantType、RiskLevel、OrgCode、SettlementStatus、Money、Currency - 狀態：
MERCHANTS.status ∈ {ACTIVE, SUSPENDED, TERMINATED}（CHECK，預設 ACTIVE）；MERCHANT_SETTLEMENTS.status ∈ {PENDING, SETTLED}
4. 程式結構
| 套件／類別 | 職責 | 對應需求 |
|---|---|---|
domain/model/Merchant MerchantContract MerchantSettlement
|
聚合與值物件 |
ACQ-4.1/4.2/4.3
|
domain/port/MerchantRepository |
持久化埠 | — |
application/MerchantService |
商戶管理／請款／對帳 | ACQ-4.1 |
infrastructure/jdbc/MerchantRepositoryImpl |
JDBC 實作 | — |
interfaces/rest/MerchantController |
REST 端點 | ACQ-4.1 |
5. 資料模型（約束為 Oracle 實測值）
| 表 | 關鍵欄位 | 約束（實測） |
|---|---|---|
MERCHANTS |
MERCHANT_ID VARCHAR2(24) UNIQUE；MERCHANT_NAME VARCHAR2(120)；MERCHANT_FORM（商店型態，V2）；MERCHANT_TYPE（業別）；MCC；ORG；ACQUIRER_ID；TERMINAL_IDS JSON DEFAULT '[]'；PARENT_MERCHANT_ID RAW(16)（V2，自參考）；ACCEPTED_CARD_TYPES JSON DEFAULT '[]'（V2）；SETTLEMENT_BANK；SETTLEMENT_ACCOUNT_ENC BLOB（加密）；RISK_LEVEL DEFAULT 'LOW'；KMC_CATEGORY；STATUS DEFAULT 'ACTIVE'；ONBOARDED_AT
|
merchant_form IN ('SINGLE','FRANCHISE','CHAIN','GROUP')；merchant_type IN ('RETAIL','EC','MOTO','RESTAURANT','TRAVEL','SUPERMARKET','OTHER')；risk_level IN ('LOW','MEDIUM','HIGH')；CK_MERCHANTS_STATUS：status IN ('APPLIED','ACTIVE','SUSPENDED','TERMINATED','CLOSED')
|
MERCHANT_SETTLEMENTS |
SETTLEMENT_NO VARCHAR2(32) UNIQUE；MERCHANT_ID（FK→MERCHANTS.ID）；ORG；SETTLEMENT_DATE；BATCH_NO VARCHAR2(32)（V2）；BATCH_COUNT（筆數，非批次號）；GROSS_AMOUNT/FEE_AMOUNT/TAX_AMOUNT/NET_AMOUNT NUMBER(19)；CURRENCY CHAR(3) DEFAULT 'TWD'；STATUS DEFAULT 'PENDING'；EXCEPTION_REASON VARCHAR2(240)（V2） |
CK_MERCHANT_SETTLEMENTS_STATUS：status IN ('SUBMITTED','VERIFIED','EXCEPTION','PAID','PENDING','SETTLED')；FK(MERCHANT_ID) REFERENCES MERCHANTS(ID) |
含
CREATED_AT/UPDATED_ATTIMESTAMP(6) WITH TIME ZONE、VERSION樂觀鎖。SETTLEMENT_ACCOUNT_ENC為 BLOB 加密欄，落實common-security欄位加密（AesGcmFieldEncryptor）。⚠️ 兩軸之區分（
CR-015，BEAM PMO 2026-09-22 裁定採雙欄位）：MERCHANT_FORM為
商店型態（單店／加盟／連鎖／集團），MERCHANT_TYPE為業別（做什麼生意）——
二者正交（一間「超市」可以是「連鎖」），原契約以單一merchantType承載兩者、
與 DDL 業別值域完全無交集。契約之merchantType對映MERCHANT_FORM，
業別則以新增之industryType對映MERCHANT_TYPE。V1 基線已凍結（
SAD-003 §9）；上述 V2 變更見V2__merchant_form_and_status.sql。
6. API 設計（來自 contracts/openapi/merchant-service.yaml）
| 端點 | 方法 | 說明 | 對應 FR |
|---|---|---|---|
/api/v1/merchants |
POST | 商戶建檔 | ACQ-4.1 |
/api/v1/merchants/{merchantId} |
GET | 商戶查詢 | ACQ-4.1 |
/api/v1/merchant-settlements |
POST | 商戶結算（請款／對帳） |
ACQ-4.2/ACQ-4.3
|
錯誤碼：
409商戶重複（MERCHANT_ID）、404找不到、400參數錯誤（如無效MERCHANT_TYPE）。
7. 關鍵邏輯
-
商戶建檔：
TERMINAL_IDS以 JSON 陣列存多終端；SETTLEMENT_ACCOUNT_ENC加密儲存（PII）。 -
結算：彙總請款批次得淨額（
NET_AMOUNT = GROSS - FEE - TAX），觸發clearing-service對帳。 -
風險：
RISK_LEVEL影響交易監控強度（與authorization-service協調）。
CR-015（BEAM PMO 2026-09-22 裁定）後定案之實作要點
-
兩軸獨立：建檔之
merchantType（商店型態）與industryType（業別）分別落
MERCHANT_FORM／MERCHANT_TYPE；值域各依 DDL CHECK 檢核，未知值回CC-PLT-4003。 -
特店代碼：請求未提供 → 服務端以
merchant_id_seq產生（MERCH＋ 6 位連號，可稽核）；
提供且已存在 →CC-MRC-1001（422）。 -
冪等：以冪等鍵派生主鍵（
UUID v3，前綴mch:merchant:／mch:settlement:）——
同鍵重送命中既有列並回傳原結果，不新增、不重抽序號。
⚠️ 契約所述「同鍵異指紋回 409」未實作（無指紋欄位可存，不挪用他欄）。 -
請款金額為 stand-in：由呼叫方帶入
grossAmount／feeAmount／taxAmount
（收單／清算資料源未就緒）；待clearing-service（C-5）落地後改為服務端彙總。 -
異常判定僅「淨額為負」：落地為
EXCEPTION＋EXCEPTION_REASON（不拋錯，
作業面可查、可更正後重送）。不納入商戶狀態檢核（契約未定義；且無狀態轉換端點，
加了將使正常路徑不可達——見 §10）。
7.1 事件輸出（Transactional Outbox；CR-027 批次 A-4）
掛點：MerchantSettlementService.submit 於 settlementRepository.save(settlement)
之後、同一交易內 append。
事件：merchant.settlement.submitted.v1（SAD-002 §3.13、SDD-006 §4.2）
| 項目 | 值 | 依據 |
|---|---|---|
| Kafka 主題 | cc.merchant.settlement.submitted |
OutboxPublisher.topicFor |
| 分區鍵 |
aggregateId ＝ settlementId
|
SAD-004 §5.4（同聚合有序） |
aggregate_type |
merchant |
— |
event_type（outbox 欄） |
settlement.submitted（不含版本） |
SDD-001 §3.15 |
event_version |
1 |
— |
| payload |
settlementId／merchantId／grossAmount／feeAmount／netAmount（恰 5 欄） |
SDD-006 §4.2 |
主題／
event_type之推導：依SAD-004 §5.4既有慣例——事件全名去.vN後，
再移除一層與aggregate_type相同之首段（merchant.settlement.submitted.v1
→settlement.submitted）。
payload 欄位之來源對映（不得自行推導）：
| payload 欄 | 來源 | 說明 |
|---|---|---|
settlementId |
settlement.id() |
請款單主鍵（亦為分區鍵） |
merchantId |
merchant.merchantId() |
⚠️ 業務代碼（如 MERCH000002），非資料庫主鍵 UUID——依 CR-019 §3.5 裁定 (a)：對外 merchantId 一律為業務代碼（與 MerchantView／MerchantSettlementView 一致） |
grossAmount |
settlement.grossAmount() |
請款總額（分） |
feeAmount |
settlement.feeAmount() |
手續費（分） |
netAmount |
settlement.netAmount() |
淨額（分）＝ gross − fee − tax（§7 結算公式，由聚合推導） |
⚠️ 金額一律最小單位（分）（
SDD-006 §2.5）——禁止浮點。
⚠️ payload 不含taxAmount／currency（契約如此）；netAmount已內含稅之影響。
發射條件：submit 成功建立請款單即發射恰一則。
不發射之情形：
| 情形 | 原因 |
|---|---|
| 冪等重播（同鍵派生主鍵命中既有列） | 早退於寫入之前 → 不發射 |
查無特店（CC-PLT-4040，404） |
拋錯於寫入之前 → 不發射 |
淨額為負 → EXCEPTION
|
仍發射——請款單確實已建立（僅狀態為異常），如實反映（§7 要點 5：不拋錯） |
消費者：clearing（SAD-004 §5.2）——⚠️ 尚未實作（批次 C）。
7.2 商店對帳單（ACQ-4.3；CR-051 裁定，2026-10-17）
✅ 本節狀態＝已核定（BEAM PMO 2026-10-17）：含 S-1～S-6 凍結語意、S-3／S-4 補充（種類／郵寄方式）、
S-7 API 形態、資料模型承載方式（SCS＋Flyway）。核定後方進入gen_openapi.py契約與 Flyway 遷移。
需求的由來：RFPFR.md §4.3（列印週期／種類／郵寄方式／補印／電子發票）原無任何承作，
契約與SDD-006 §7亦無 statements 路徑（CR-050 §1）。
7.2.1 凍結語意（摘自 CR-051 §5 BEAM PMO 裁定）
| 裁定 | 本服務落地 |
|---|---|
| S-1 (b) 本平台全責 | 本平台負責對帳單之資料彙總＋文件產出（列印／PDF／電子發票）——不再歸衛星系統 |
| S-2 月結跨自然月 | 週期起訖可設定（例：每月 21 日～次月 20 日），不對齊自然月 |
| S-3 無範本 → 我方設計、可替換 | 範本外置／參數化（template_code），客戶提供後替換，不寫死於程式
|
| S-4 遞送歸銀行 mail room／委外 | 本平台產出後交付 mail room；遞送記錄留在平台（誰／何時／何批／交予誰／狀況） |
S-3 補充：種類（全額發票／全收據(自然人)，RFP §4.3 #2） |
作為特店屬性參數 ticket_type（INVOICE／RECEIPT）；產出時讀取並留存於對帳單主檔（留痕——避免日後改參數使歷史對帳單語意漂移） |
S-4 補充：郵寄方式（1-掛號／2-限時／5-平信，RFP §4.3 #3） |
預設值由參數提供，實際值記錄於遞送記錄 mail_type（REGISTERED／EXPRESS／ORDINARY），供 mail room 委外追蹤 |
| S-5 補印無上限、免授權 | 每次補印皆留痕（稽核軌跡），不設次數上限、不需授權流程 |
| S-6 電子發票 傳檔為主 | 產出檔案供財政部網頁 upload（主路徑）＋MQ 為輔 |
| S-7（依 S-1=(b) 推導） | API 含供料查詢＋產出＋檔案匯出／遞送（待確認） |
7.2.2 參數化要項（CR-045 三位一體）
-
週期起訖（
cycle／period_from／period_to）——由參數或排程設定決定； -
對帳單範本（
template_code）——可抽換； -
發票／收據種類（
ticket_type＝INVOICE／RECEIPT）——特店屬性參數，產出時留存（留痕）； -
郵寄方式（
mail_type＝REGISTERED掛號／EXPRESS限時／ORDINARY平信；對齊 RFP§4.3 #3之 1／2／5）
——預設由參數提供，實際值留存於遞送記錄； - 補印次數上限——目前＝無上限（參數保留，供日後設定）；
-
遞送通道（
MAIL_ROOM／OUTSOURCE／E_INVOICE_UPLOAD／MQ）。
★ 留痕原則：參數可被調整，故「當次產出所用之值」一律寫入對帳單主檔／遞送記錄——
事後改參數不得改變已產出對帳單之語意（與SCS-002 §7.9.1「軌跡 vs 現行定義」同原則）。
→ 參數缺值時一律 fail-closed（不臆造）；merchant_settlements 維持請款語意、不新增週期欄
（CR-050 §2.1：不得以請款混充對帳單）。
7.2.3 資料模型方向（新增表，待 Flyway 遷移）
-
merchant_statements（對帳單主檔）：merchant_id、cycle、period_from、period_to、
ticket_type（留痕）、template_code（留痕）、status、file_ref、version…
——週期由參數／排程給定。 -
statement_deliveries（遞送記錄）：statement_id、channel、mail_type、handed_to、
handed_at、tracking_ref、status——滿足 S-4「遞送外部化但軌跡在平台」。 - ⚠️ 資料模型承載方式（2026-10-17 BEAM PMO 核定）：本項屬新增能力（不與既有語意衝突），
由SCS-014＋ Flyway 新版本直接承載，不另立CR-053式之資料模型 CR。 - 補印軌跡：每次產出／補印於上述二表留痕（S-5）。
-
資料來源：既有
merchant_settlements（settlement_date、batch_count、gross/fee/tax/net_amount）；
索引idx_ms_merchant (merchant_id, settlement_date DESC)已可支援「依特店＋日期區間」彙總——日／兩日／月結皆可由日期區間得出。 - ⚠️ 新表屬結構新增，須以 Flyway 新版本交付（已套用之遷移不得修改，
SAD-003 §9）。
7.2.4 API 形態（草案；由 gen_openapi.py 規格先行）
| 方法 | 路徑（草案） | 用途 |
|---|---|---|
GET |
/api/v1/merchant-statements?merchantId&from&to&cycle |
供料／查詢 |
POST |
/api/v1/merchant-statements/generate |
產出（補印＝同一 API 重產並留痕；ticket_type／template_code 由參數帶入並留存） |
GET |
/api/v1/merchant-statements/{id}/file |
檔案匯出（供財政部網頁 upload） |
POST |
/api/v1/merchant-statements/{id}/deliveries |
遞送記錄登錄（S-4；含 mail_type、channel、handed_to、tracking_ref） |
★ S-7 已確認（BEAM PMO 2026-10-17 核定）：即上列 4 支（供料查詢＋產出＋檔案匯出＋遞送記錄）。
⚠️ 路徑須經 gen_openapi.py 產生後生效；不得以 merchant-settlements 混充（CR-050 §2.1）。
7.2.5 守界
- 核定前不動程式、不改表結構；
-
回溯不得臆造：歷史請款不得反推對帳單（類推
V10「既有佔用無instrument_id、不得回填」之鐵律）； - 產出失敗／遞送失敗皆留痕且可重試（冪等）；遞送之實際投遞為外部（mail room／委外），
本平台僅記錄交付與軌跡，不宣稱投遞成功。
7.2.6 實作狀態（2026-10-17，#A-284）
| 項目 | 狀態 | 證據 |
|---|---|---|
| 契約 4 端點＋5 schema | ✅ 已重生 |
gen_openapi.py → 110 端點／0 錯誤；verify_contract_dto 不符 0
|
查詢參數（merchantId／from／to／cycle） |
✅ 已補 | 原產生器僅帶 TraceIdHeader（§7.2.4 已列參數卻未生成）→ 已補專屬 query 元件 |
V4__merchant_statements.sql |
✅ 已建 |
merchant_statements／statement_deliveries＋merchant_statement_no_seq；validate_sql 違規 0 |
| DDD 四層＋REST | ✅ 已實作 | domain 不變式、jdbc（含真彙總）、service（冪等／留痕／檔案）、controller 4 端點 |
| 真機驗證 | ✅ 11 例 |
MerchantStatementServiceIntegrationTest：真 Oracle（V1～V4）＋真 Garage ＋真服務編排，零替身
|
★ 期間查詢語意（契約已逐字載明，實作須一致）：from／to 為閉區間且
「對帳單期間完全落在查詢範圍內」（PERIOD_FROM >= from 且 PERIOD_TO <= to）——
與請款交易查詢之半開 (from, to] 語意不同。實測：月結單 09-21～10-20
以 09-01～09-30 查詢不命中（正確），放寬至 09-21～10-31 才命中。
★ 檔案產出之現況（如實揭露）：本期產出 CSV 資料檔（UTF-8 含 BOM），內容為
對帳單標頭＋期間內請款明細；物件鍵以對帳單主鍵為準（statements/<id>.csv），
使同冪等鍵重試時覆蓋同一鍵、不產生孤兒物件。
RFP 所述「列印」之 PDF 版式待 S-3 範本到位後抽換（templateCode 已留痕）
——不以 CSV 冒充已具備列印版式。
★ 遞送狀態判定：契約 StatementDeliveryRequest 無 status 欄位 →
由服務端依「是否載明交付對象」判定：handedTo 有值 → HANDED_OFF（handedAt＝當下）；
否則 PENDING。FAILED 現行無觸發來源（契約無失敗回報端點），保留給未來外部結果回報，
不可達。
★ 郵寄方式參數之適用範圍：參數預設（default-mail-type）僅套用於實體郵寄通道
（MAIL_ROOM／OUTSOURCE）。電子發票（E_INVOICE_UPLOAD／MQ）本無「掛號／限時／平信」
語意，若一併套用會使軌跡出現誤導性郵寄方式（看似掛號寄出、實為傳檔）→ 記 null。
（★ 此為實作期發現之語意瑕疵，已於真機測試揭露並修正。）
8. 外部依賴與降級
| 依賴 | 失敗處理（Stand-in） |
|---|---|
clearing-service（對帳）、authorization-service（風險參考） |
結算失敗重試（冪等）；商戶查詢為讀取，無即時強依賴 |
9. 測試案例（對應 TRP-001）
-
UT-ACQ-001：商戶管理（ACQ-4.1）——建檔、查詢、加密欄位 -
UT-ACQ-002：商店請款（ACQ-4.2） -
UT-ACQ-003：商店對帳單（ACQ-4.3）、風險等級邏輯
10. 已知限制（誠實揭露）
-
MERCHANTS.status轉換未建模為SDD-005正式狀態機
——故本服務不提供狀態轉換端點（核准／停用／終止），特店建檔後恆為APPLIED。 -
SETTLEMENT_ACCOUNT_ENC之金鑰管理（KMC）與common-security之整合待基礎設施設計凍結
——本期建檔不接收該欄位（避免半套加密）。 -
merchant-service骨架與埠號尚未產生（規格先行）
CR-015 執行後新增之限制（2026-09-22）
-
請款金額為 stand-in：由呼叫方帶入（
clearing-service／C-5未開發，服務端無處彙總）；
待C-5落地後改為服務端彙總（CR-015 §3.1 J）。 -
「同鍵異指紋回 409」未實作：兩表無指紋欄位可存，且不挪用他欄（避免假綠）。
已實作之冪等為「同鍵同主鍵」（不重複建檔）——涵蓋實際風險（重複建檔）。 -
商戶狀態檢核未納入請款異常判定：契約未定義「異常」清單；且無狀態轉換端點，
若加「非ACTIVE不得請款」將使「建檔 → 請款」之正常路徑永不可達
（與C-19之ALLOCATED同類陷阱）。待狀態機建模時一併裁定。 -
MERCHANT_SETTLEMENTS之PENDING／SETTLED為 DDL 遺留值：已併入同一值域供相容，
惟本服務 API 不產生此二值（契約面為SUBMITTED／VERIFIED／EXCEPTION／PAID）。 - 無請款查詢端點：契約僅 3 端點（建檔／查詢／請款），請款後之查詢須待契約擴充。
-
對帳單（→ 已實作（2026-10-17，ACQ-4.3）之檔案產出未實作#A-284）：
契約 4 端點、V4二表、DDD 四層與真機 11 例整合測試皆完成。惟仍有三項限制（見下）。
CR-027 批次 A-4 執行後新增之限制（2026-10-01）：
-
事件消費者未實作：
SAD-004 §5.2載merchant.settlement.submitted.v1之消費者為
clearing，惟其尚未訂閱 → 現階段「有人發、沒人收」（批次 C）。見 §7.1。 -
merchant.merchant.registered.v1未發射：SAD-002 §3.13列本服務發布該事件，
惟SDD-006 §4.2未定義其 payload（CR-027 §6 批次 A-4表列為「⬜ 缺」）
→ 不臆造 payload；待補契約後再議。 -
sequenceNo為「同 JVM 內遞增之時間戳基底序號」：多實例部署可能重複；
正解為「聚合層級持久化序號」（SAD-004 §5.4），本期未做（與CR-027 §5 #12同型）。
對帳單實作後新增之限制（2026-10-17，#A-284）：
-
檔案格式為 CSV，非 PDF：RFP 所述「列印」之版式檔待 S-3 範本到位後抽換
（templateCode已留痕）。不以 CSV 冒充已具備列印版式（見 §7.2.6）。 -
遞送
FAILED狀態不可達：契約無失敗回報端點，本平台不臆造「推測失敗」規則
——該值保留給未來外部結果回報（見 §7.2.6）。 -
對帳單不發射領域事件：
SAD-002 §3.13／SDD-006 §4.2皆未定義對帳單事件之
payload → 不臆造（同#8之merchant.registered.v1處理原則）。
11. 修訂記錄
| 版本 | 日期 | 修訂者 | 說明 |
|---|---|---|---|
| 1.5 | 2026-10-17 | WorkBuddy AI |
§7.2 已實作並真機驗證（#A-284）——① 契約重生（110 端點／0 錯誤，verify_contract_dto 不符 0）；② 補 GET 查詢參數（merchantId 必填＋from／to／cycle；原產生器只帶 TraceIdHeader，與 §7.2.4 明列參數不符）；③ V4__merchant_statements.sql（二表＋序號產生器，validate_sql 違規 0）；④ DDD 四層＋4 端點實作（冪等／留痕／真彙總／真檔案上傳）；⑤ 新增 §7.2.6（實作狀態表、期間「完全落在」語意、CSV 非 PDF、FAILED 不可達、郵寄參數僅實體通道）；⑥ §10 新增 3 項限制（10～12）。★ 測試：merchant-service 77 測 0 失敗，其中新增 11 例真 Oracle＋真 Garage 整合測試（零替身） |
| 1.4 | 2026-10-17 | WorkBuddy AI |
§7.2 已核定（BEAM PMO 2026-10-17 依建議核准）——① 補入 RFP §4.3 #2 種類（ticket_type＝INVOICE／RECEIPT，特店屬性參數、產出時留痕）與 #3 郵寄方式（mail_type＝REGISTERED／EXPRESS／ORDINARY，對齊 1／2／5，留存於遞送記錄）；② 確立留痕原則（參數可調，但「當次產出所用值」須寫入主檔／遞送記錄，事後改參數不得改變歷史對帳單語意，同 SCS-002 §7.9.1）；③ S-7 API 形態確認（供料查詢／產出／檔案匯出／遞送記錄 4 支）；④ 資料模型承載方式：屬新增能力、不與既有語意衝突，由 SCS-014＋Flyway 新版本承載，不另立資料模型 CR。⚠️ 核定前不動程式／不改表；回溯不得臆造 |
| 1.3 | 2026-10-17 | WorkBuddy AI |
新增 §7.2 商店對帳單（ACQ-4.3）——依 CR-051 BEAM PMO 2026-10-17 裁定之 S-1～S-6 凍結語意：S-1 (b) 本平台全責（含產出／電子發票）、S-2 月結跨自然月（週期可設定）、S-3 範本暫由我方設計、可抽換、S-4 遞送歸銀行 mail room／委外但遞送記錄留平台、S-5 補印無上限／免授權／但留痕、S-6 電子發票傳檔為主＋MQ 為輔。含參數化要項（週期起訖／範本／補印／遞送通道；缺值 fail-closed）、資料模型方向（merchant_statements／statement_deliveries，待 Flyway 新版本）、API 草案（由 gen_openapi.py 產生）與守界（核定前不動程式／回溯不得臆造）。⚠️ 本節狀態＝待核定
|
| 1.0 | — | 開發團隊 | 初版（規格先行） |
| 1.1 | 2026-09-22 | WorkBuddy AI |
CR-015 執行完成（BEAM PMO 裁定：A 雙欄位、B～G 一次核准）——①**§5 資料模型**：補 MERCHANT_FORM／PARENT_MERCHANT_ID／ACCEPTED_CARD_TYPES／BATCH_NO／EXCEPTION_REASON 與兩具名約束，並載明兩軸之區分；②**§7** 新增實作要點（兩軸獨立、代碼產生、冪等派生主鍵、金額 stand-in、異常僅淨額為負）；③**§10** 移除「骨架未產生」、新增 6 項限制（stand-in／異指紋未實作／狀態檢核未納入／遺留值／無查詢端點／對帳單檔案未產出）；④補建本修訂記錄區（原文件欠缺）。單測 27 例 0 失敗；真機 e2e 7 項（含 DB 複核雙軸獨立） |
| 1.2 | 2026-10-01 | WorkBuddy AI |
CR-027 批次 A-4（#A-137）：①**§7.1 新增事件輸出規格**——merchant.settlement.submitted.v1：主題／分區鍵／payload 逐欄來源對映／發射與否（冪等重播與查無特店不發射、淨額為負之 EXCEPTION 仍發射）；②★ 明確 merchantId 為業務代碼（CR-019 §3.5 裁定 (a)），非資料庫主鍵 UUID；③**§10 新增 3 項限制**（消費者未實作、merchant.registered.v1 無 payload 故未發射、sequenceNo 多實例風險） |