This resume is also available in English.

七、實戰踩坑第 4 / 5 篇 · 全部目錄

專欄 › 七、實戰踩坑 › 第 29 篇

對帳:金流對帳單怎麼對才可靠

Reconciliation: Matching Payment Provider Statements Reliably

兩個系統記同一筆錢,遲早會對不起來。這篇從取得與保存對帳單、解析與日界,到逐筆配對、差異分類與處理、帳本與撥款核對,再到告警與月結,用 Go 寫一個可測試的對帳套件。

  • 支付
  • 對帳
  • Go
  • PostgreSQL
這篇的步驟
  1. 這篇要解決什麼
  2. 第 1 步:對帳是什麼、不是什麼
  3. 第 2 步:可靠地取得對帳單
  4. 第 3 步:逐筆配對
  5. 第 4 步:把差異分類
  6. 第 5 步:處理差異
  7. 第 6 步:和帳本與銀行撥款對起來
  8. 第 7 步:營運
  9. 執行測試
  10. 常見陷阱
  11. 重點整理
  12. 下一篇

上一篇〈支付防重複與事故應變:從按鈕到金流商,出事時怎麼止血〉從按鈕一路擋到金流商,並整理了出事時的止血步驟。但不管防線做得多好,總會有幾筆漏網之魚:回呼全部重送失敗、某個版本的程式寫錯狀態、有人在金流商後台手動退款、手續費和合約不一樣。這些問題都不會讓程式出錯,只會讓帳慢慢對不起來,而唯一能把它們找出來的,是對帳。

〈支付常見問題:重複扣款、回呼與對帳〉的第 8、9 個問題已經簡短介紹過每日對帳與複式記帳。這篇把它展開成完整的做法:對帳單怎麼抓、怎麼保存、怎麼解析才不會被編碼和時區騙;配對的鍵是什麼、一對多怎麼辦;差異分成哪幾類、哪一類要半夜叫人起床;差異怎麼追蹤到結案、為什麼絕對不能直接改金額;最後怎麼讓帳本、對帳單和銀行撥款三方對起來。

這篇要解決什麼

延續整個系列的例子:網路商店 example.com/shop 的 payment 服務把付款與退款存在 PostgreSQL,金額一律是最小貨幣單位的 int64。每次向金流商發起扣款,都用付款嘗試的 ID(例如 pay_1001)當商店訂單編號(各家叫法不同,常見的有 merchant trade no、merchant reference、order id);金流商則回給我們它自己的交易編號。金流商每天提供一份對帳單,並在約定的撥款日把扣掉手續費後的淨額匯進我們的銀行帳戶。

這篇會一步一步做到:

  1. 說清楚對帳要比對哪幾方、多久做一次、誰負責。
  2. 可靠地取得對帳單:排程、重試、原始檔不可改寫、匯入可以重跑。
  3. 解析對帳單:BOM、CSV 引號、編碼、金額轉整數,以及最容易出錯的時區與日界。
  4. 逐筆配對:鍵、一對多、手續費、退款與拒付、狀態對照。
  5. 差異分類:哪一類只是時間差、哪一類代表使用者已經被扣款。
  6. 差異處理:差異表、生命週期、自動結案規則、調整分錄、冪等的修正動作。
  7. 帳本與銀行撥款的核對,以及營運上的告警、重跑、資料保存與月結。

程式碼放在 internal/recon 套件裡,全部可以編譯,並用 go test -race 測過。

提示:各家金流商的對帳單格式差很多,有的是每天一個 CSV 放在 SFTP,有的要呼叫 API 下載,有的是固定寬度的文字檔,欄位名稱與日界的定義也不同。這篇用一個常見的 CSV 格式當例子,實際對接時一定要以你的金流商提供的文件為準。

第 1 步:對帳是什麼、不是什麼

三方對帳

一筆付款的錢,會在三個地方留下紀錄:

  • 我們的紀錄:payment 服務的付款與退款、訂單狀態。
  • 金流商的對帳單:它認為哪些交易成功、金額多少、收了多少手續費、哪天撥款。
  • 銀行的入帳:金流商實際匯進來多少錢。

對帳就是把這三方兩兩比對。我們的紀錄與對帳單逐筆比:每一筆付款都應該在對帳單上找到同一筆,金額、幣別、狀態都相同。對帳單與銀行入帳整批比:某個撥款日的淨額(付款總額減退款、拒付與手續費)應該等於那天銀行實際收到的金額。中間還有一個帳本:每一筆成功的付款、手續費、退款與撥款都寫成複式分錄,所以帳本裡「應收金流商」這個帳戶的餘額,必須和「金流商已經確認、但還沒撥給我們的淨額」一致。

我們的付款紀錄 payment 服務・PostgreSQL 金流商對帳單 每日檔案・逐筆明細 帳本(複式記帳) 應收金流商・手續費・營收 銀行撥款 實際入帳的淨額 逐筆:商店訂單編號 金額・幣別・狀態・手續費 成功的交易記分錄 手續費・退款・拒付 批次:撥款淨額 總額 − 退款 − 手續費 入帳後沖銷應收 三方都一致、帳本借貸平衡,這一天才算對完

圖:我們的紀錄和對帳單逐筆比、對帳單和銀行撥款整批比,三者都要和帳本對得起來。

對帳不是什麼

  • 不是監控的替代品。 對帳通常是隔天才做,發現時錢已經扣了一天。回呼失敗、unknown 太多這類問題,要靠即時的指標與告警(〈可觀測性:日誌、指標、追蹤〉)先發現;對帳是最後一道網。
  • 不是修資料的捷徑。 對帳找到差異後,修正一定要走正規的動作:查詢金流商、補記狀態、退款、寫調整分錄,而不是直接 UPDATE payments SET amount = ...。
  • 不是只比總額。 總額相同不代表每筆都對,一筆多收 100 元、另一筆少收 100 元,總額剛好相同。總額只是一個快速的初步檢查。

每天一次,還是即時?

大部分金流商的對帳單是每天產生一份,涵蓋前一天的交易,所以「每日對帳」是最常見的節奏。有些金流商也提供交易查詢 API,可以做到接近即時的比對,例如每小時把最近的付款拿去查一次。兩者不衝突:即時查詢讓問題更早被發現(這其實就是上一篇補查 pending 的做法),每日對帳則以金流商正式產出的對帳單為準,是月結與會計使用的依據。

誰負責

對帳牽涉工程、財務與客服,最常見的失敗不是技術問題,而是沒有人負責:差異表裡躺了三個月的紀錄沒人看。上線前要講清楚:對帳程式失敗時誰收告警(工程),差異的第一線判斷由誰做(通常是財務或營運),需要查程式或補資料時交給誰(工程),需要聯絡使用者時誰處理(客服),以及誰能核准沖銷(主管)。

第 2 步:可靠地取得對帳單

排程抓檔與重試

對帳單通常在固定時間之後才會出現,例如「每天上午幾點後可下載前一天的檔案」,但實際上常常晚到。抓檔程式要:

  • 在預期時間之後開始抓,抓不到就退避重試(〈逾時、重試與熔斷〉),超過一個期限(例如中午)還沒有才告警,而不是第一次失敗就叫人。
  • 每一次嘗試都寫一筆執行紀錄:哪一個對帳日、從哪裡抓、抓到哪個檔案、幾筆、成功或失敗、錯誤訊息。沒有這張表,就無法回答「11 月 14 日那份到底有沒有匯入過」。
  • 抓到的檔案如果有壓縮或加密,解開的步驟也要記錄並可以重跑。

原始檔不可改寫

對帳單是證據。抓下來的檔案要原封不動地存起來,通常放在物件儲存,並記下 SHA-256 雜湊、大小與抓取時間。之後所有的處理都從這份原始檔重新算出來,任何人都不能直接修改它:解析程式有錯,就修程式後重跑;金流商說檔案有錯,就請它重發一份,新舊兩份都留著。物件儲存可以開啟版本控制或「寫入後不可刪除」的保存設定,讓這件事不只是約定。

暫存表:可以重跑的匯入

解析後的每一列先寫進暫存表,再拿去配對。匯入一定要冪等(〈冪等與分散式鎖〉):排程重試、人工重跑、兩個程序同時跑,結果都要和跑一次相同。做法是:

  • 每一列的唯一鍵是「檔案雜湊+行號」,同一份檔案匯入第二次不會多出列。
  • 匯入某個對帳日時,在同一個交易裡先刪掉這一天的暫存列,再寫入這份檔案的列。這樣金流商重發的更正版(雜湊不同)會整天取代舊版,而不是和舊版混在一起。
  • 同一個對帳日的匯入用 advisory lock 串起來,避免兩個交易交錯執行,留下兩個版本混在一起的結果。
CREATE TABLE statement_files (
  sha256        char(64)    PRIMARY KEY,
  provider      text        NOT NULL,
  recon_day     date        NOT NULL,
  name          text        NOT NULL,
  object_key    text        NOT NULL,   -- 物件儲存裡的位置,例如 recon/raw/2026/11/14/<sha256>.csv
  byte_size     bigint      NOT NULL,
  fetched_at    timestamptz NOT NULL DEFAULT now(),
  superseded_by char(64)    REFERENCES statement_files (sha256)  -- 被哪一份更正版取代
);

CREATE TABLE ingestion_runs (
  id          bigint      GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  provider    text        NOT NULL,
  recon_day   date        NOT NULL,
  file_sha256 char(64)    REFERENCES statement_files (sha256),
  status      text        NOT NULL CHECK (status IN ('running', 'staged', 'matched', 'failed')),
  row_count   int,
  error       text,
  started_at  timestamptz NOT NULL DEFAULT now(),
  finished_at timestamptz
);

CREATE TABLE statement_lines (
  file_sha256       char(64)    NOT NULL REFERENCES statement_files (sha256),
  line_no           int         NOT NULL,
  provider          text        NOT NULL,
  recon_day         date        NOT NULL,
  merchant_trade_no text        NOT NULL,
  provider_txn_id   text        NOT NULL,
  kind              text        NOT NULL CHECK (kind IN ('payment', 'refund', 'chargeback')),
  status            text        NOT NULL CHECK (status IN ('succeeded', 'failed')),
  amount            bigint      NOT NULL CHECK (amount > 0),   -- 最小貨幣單位
  fee               bigint      NOT NULL,
  currency          char(3)     NOT NULL,
  transacted_at     timestamptz NOT NULL,
  settlement_date   date        NOT NULL,
  PRIMARY KEY (file_sha256, line_no)
);
CREATE INDEX statement_lines_day ON statement_lines (provider, recon_day);
CREATE INDEX statement_lines_trade_no ON statement_lines (merchant_trade_no);

-- 匯入一個對帳日:$1 provider、$2 recon_day、$3 這份檔案的 sha256
BEGIN;
SELECT pg_advisory_xact_lock(hashtext('recon:' || $1 || ':' || $2::text));
DELETE FROM statement_lines WHERE provider = $1 AND recon_day = $2;
-- 每一列一個 INSERT,或用 COPY 一次寫入;重跑同一份檔案時不會多出列
INSERT INTO statement_lines (file_sha256, line_no, provider, recon_day, merchant_trade_no,
  provider_txn_id, kind, status, amount, fee, currency, transacted_at, settlement_date)
VALUES ($3, $4, $1, $2, $5, $6, $7, $8, $9, $10, $11, $12, $13)
ON CONFLICT (file_sha256, line_no) DO NOTHING;
UPDATE statement_files SET superseded_by = $3
WHERE provider = $1 AND recon_day = $2 AND sha256 <> $3 AND superseded_by IS NULL;
COMMIT;

上面的 SQL 為了說明把所有參數寫在一起;實際程式裡 INSERT 會對每一列執行一次(或改用 COPY),交易與連線的用法見〈database/sql、交易與連線池〉。

排程抓檔 SFTP 或 API 失敗就重試 原始檔 物件儲存 SHA-256・不改寫 解析 編碼・時區 金額換成整數 暫存表 一天整批取代 鍵:雜湊+行號 合計檢查 筆數與金額 依種類與幣別 逐筆配對 依商店訂單編號 分類差異 差異表 狀態・負責人 每次變更有紀錄 告警與處理 依年齡與金額 自動或人工 每一次執行都寫進 ingestion_runs:哪一天、哪個檔、幾筆、成功或失敗、錯誤訊息

圖:抓檔、保存原始檔、解析、寫入暫存表之後,才做合計檢查、逐筆配對、寫入差異表與告警;每一次執行都留下紀錄。

解析的陷阱:BOM、引號與編碼

CSV 看起來很簡單,實際上幾乎每一個坑都會遇到:

  • BOM。 用試算表軟體另存的 UTF-8 檔案,開頭常常有三個位元組的 BOM(EF BB BF)。不處理的話,第一個欄位名稱會變成 merchant_trade_no,用名稱找欄位就找不到。
  • 引號。 欄位裡有逗號或換行時會用雙引號包起來,例如 "1,000"。千萬不要用 strings.Split(line, ",") 自己切,要用 encoding/csv;它也會正確處理引號裡的換行,這時「第幾行」和「第幾列」就不一樣了。
  • 編碼。 有些系統輸出的不是 UTF-8,而是 Big5 或其他編碼。先檢查 utf8.Valid,不是 UTF-8 就整個檔案拒絕,交給轉碼步驟(例如 golang.org/x/text/encoding)處理,而不是讓亂碼的商店訂單編號流進配對,變成一堆「對方有、我方無」。
  • 欄位順序。 用標題列的名稱找欄位,不要寫死第幾欄;金流商哪天加一個欄位,程式也不會讀錯。必要欄位缺少時,整個檔案拒絕。
  • 金額。 對帳單上的金額通常是十進位字串,例如 12.50 或 1,000。直接轉成最小貨幣單位的整數,全程不經過 float64;小數位數超過幣別允許的範圍就報錯,不要偷偷捨入。新台幣在 ISO 4217 的小數位數是 2,但很多金流商以整數元表示,1,000 要換成 100000(以分計);這種換算放在解析這一層做,下一篇會完整說明。
  • 符號。 有些對帳單把退款寫成負數,有些寫正數再用類型欄位區分。解析時統一成「金額永遠為正、方向看種類」。
  • 狀態。 金流商的狀態字串(SUCCESS、PAID、FAILED……)在解析時就對照成我們的詞彙;遇到不認得的值,整個檔案停下來,而不是猜。

最後一條原則:有一列解析失敗,整個檔案都不匯入。跳過壞掉的列看起來比較「有彈性」,實際上是讓那一筆從對帳裡消失,之後再也沒有人會發現。

時區與日界

這是對帳最常見、也最難察覺的問題。我們的商店在台北,習慣把「11 月 14 日」定義成台北時間 00:00 到 24:00;金流商的對帳單卻可能用 UTC 切日,或用它自己所在地的時區。台北時間的午夜是 UTC 的 16:00,所以一筆在台北時間 11 月 15 日 00:00:30 付款的交易,會出現在金流商 11 月 14 日(UTC)的檔案裡。

台北 00:00 = UTC 16:00 UTC 00:00 = 台北 08:00 台北 UTC 11/14 11/15 11/14 11/15 A 23:59:59 15:59:59 B 00:00:30 16:00:30 A:兩邊都算 11/14。B:台北算 11/15,UTC 的檔案卻算 11/14。 選定一種日界寫進文件;比對時把前後一天的資料也拿進來。

圖:付款 A 在兩邊都屬於 11/14;付款 B 在台北是 11/15,但在 UTC 的檔案裡是 11/14。

要做的事有三件:

  1. 選定一種對帳日的定義,寫進文件。 例如「對帳日 = 交易時間換成 Asia/Taipei 之後的日曆日」。所有報表、差異、月結都用同一個定義。
  2. 解析時把時間帶上正確的時區。 對帳單的時間欄位如果沒有時區資訊,就用金流商文件寫的時區(time.ParseInLocation),再換到約定的時區取日期。
  3. 比對時把前後一天也拿進來。 即使日界定義一致,我們記錄的時間(建立付款的時間)和金流商的交易時間仍然可能差幾秒,剛好跨過午夜。所以前一天沒配對到、但仍在等待的紀錄,要帶到隔天再比一次(第 5 步的自動結案規則)。

台灣沒有日光節約時間,但如果你的業務在有日光節約時間的地區,一天可能是 23 或 25 小時,更不能用「加 24 小時」來算日界,一律用時區資料庫換算。

解析程式

ParseCSV 處理上面所有的陷阱:去掉 BOM、檢查 UTF-8、用欄位名稱找欄位、金額轉成整數、狀態對照、時間帶時區,任何一列有錯就整個檔案拒絕,錯誤訊息帶上行號。

// Package recon 把金流商的對帳單與我們自己的付款紀錄逐筆比對。
package recon

import (
	"bytes"
	"encoding/csv"
	"errors"
	"fmt"
	"io"
	"strconv"
	"strings"
	"time"
	"unicode/utf8"
)

// Kind 是對帳單上一列的交易種類。付款、退款、拒付各自一列,不互相抵銷。
type Kind string

const (
	Payment    Kind = "payment"
	Refund     Kind = "refund"
	Chargeback Kind = "chargeback"
)

// Row 是對帳單的一列;金額一律換成最小貨幣單位的 int64。
type Row struct {
	Line          int    // 這一列在檔案中的起始行號,和檔案雜湊一起當唯一鍵
	TradeNo       string // 我們送出的商店訂單編號(付款嘗試 ID 或退款 ID)
	ProviderTxnID string // 金流商的交易編號
	Kind          Kind
	Status        string    // 已對應到我們的詞彙:succeeded 或 failed
	Amount        int64     // 交易總額(gross),一律為正,方向看 Kind
	Fee           int64     // 這一筆的手續費;退款退回手續費時可能是負數
	Currency      string    // ISO 4217
	At            time.Time // 交易時間,已帶上時區
	SettleDate    string    // 撥款日 YYYY-MM-DD
}

// ErrBadRow 表示對帳單內容不符合預期;整個檔案都不匯入,而不是跳過壞的列。
var ErrBadRow = errors.New("recon: bad statement")

// exponents 是幣別的小數位數(ISO 4217);完整的處理見下一篇。
var exponents = map[string]int{"TWD": 2, "USD": 2, "JPY": 0}

// statusMap 把金流商的狀態字串對到我們的詞彙;不認得的一律報錯,不要猜。
var statusMap = map[string]string{"SUCCESS": "succeeded", "PAID": "succeeded", "FAILED": "failed"}

var columns = []string{"merchant_trade_no", "provider_txn_id", "type", "status",
	"amount", "fee", "currency", "transacted_at", "settlement_date"}

// ParseCSV 解析一份對帳單。providerTZ 是對帳單時間欄位所用的時區(由金流商的文件決定)。
func ParseCSV(data []byte, providerTZ *time.Location) ([]Row, error) {
	data = bytes.TrimPrefix(data, []byte("\xef\xbb\xbf")) // Excel 存的 UTF-8 常帶 BOM
	if !utf8.Valid(data) {
		return nil, fmt.Errorf("%w: not UTF-8, convert the encoding first", ErrBadRow)
	}
	cr := csv.NewReader(bytes.NewReader(data))
	header, err := cr.Read()
	if err != nil {
		return nil, fmt.Errorf("%w: header: %v", ErrBadRow, err)
	}
	idx := make(map[string]int, len(header))
	for i, h := range header {
		idx[strings.ToLower(strings.TrimSpace(h))] = i
	}
	for _, c := range columns {
		if _, ok := idx[c]; !ok {
			return nil, fmt.Errorf("%w: missing column %q", ErrBadRow, c)
		}
	}
	var rows []Row
	for {
		rec, err := cr.Read()
		if err == io.EOF {
			return rows, nil
		}
		if err != nil {
			return nil, fmt.Errorf("%w: %v", ErrBadRow, err)
		}
		line, _ := cr.FieldPos(0) // 引號裡有換行時,這仍是這一列開始的行號
		get := func(c string) string { return strings.TrimSpace(rec[idx[c]]) }
		r, err := parseRow(get, providerTZ)
		if err != nil {
			return nil, fmt.Errorf("%w: line %d: %v", ErrBadRow, line, err)
		}
		r.Line = line
		rows = append(rows, r)
	}
}

func parseRow(get func(string) string, tz *time.Location) (Row, error) {
	r := Row{
		TradeNo:       get("merchant_trade_no"),
		ProviderTxnID: get("provider_txn_id"),
		Kind:          Kind(strings.ToLower(get("type"))),
		Currency:      strings.ToUpper(get("currency")),
		SettleDate:    get("settlement_date"),
	}
	switch r.Kind {
	case Payment, Refund, Chargeback:
	default:
		return Row{}, fmt.Errorf("unknown type %q", r.Kind)
	}
	if r.TradeNo == "" || r.ProviderTxnID == "" {
		return Row{}, errors.New("missing merchant_trade_no or provider_txn_id")
	}
	var ok bool
	if r.Status, ok = statusMap[strings.ToUpper(get("status"))]; !ok {
		return Row{}, fmt.Errorf("unknown status %q", get("status"))
	}
	exp, ok := exponents[r.Currency]
	if !ok {
		return Row{}, fmt.Errorf("unknown currency %q", r.Currency)
	}
	var err error
	if r.Amount, err = parseMinor(get("amount"), exp); err != nil {
		return Row{}, err
	}
	if r.Amount < 0 && r.Kind != Payment {
		r.Amount = -r.Amount // 有些對帳單把退款寫成負數;方向統一由 Kind 表達
	}
	if r.Amount <= 0 {
		return Row{}, fmt.Errorf("amount must be positive, got %q", get("amount"))
	}
	if r.Fee, err = parseMinor(get("fee"), exp); err != nil {
		return Row{}, err
	}
	if r.At, err = time.ParseInLocation(time.DateTime, get("transacted_at"), tz); err != nil {
		return Row{}, fmt.Errorf("transacted_at: %v", err)
	}
	if _, err = time.Parse(time.DateOnly, r.SettleDate); err != nil {
		return Row{}, fmt.Errorf("settlement_date: %v", err)
	}
	return r, nil
}

// parseMinor 把 "1,234.5" 這類十進位字串換成最小單位的整數,全程不經過 float64。
// 小數位數超過幣別允許的就報錯,而不是偷偷捨入。
func parseMinor(s string, exp int) (int64, error) {
	t := strings.ReplaceAll(s, ",", "") // 千分位:欄位有加引號時才可能出現
	neg := strings.HasPrefix(t, "-")
	whole, frac, _ := strings.Cut(strings.TrimPrefix(t, "-"), ".")
	if whole == "" || len(frac) > exp || strings.ContainsAny(whole+frac, "+-") {
		return 0, fmt.Errorf("invalid amount %q", s)
	}
	n, err := strconv.ParseInt(whole+frac+strings.Repeat("0", exp-len(frac)), 10, 64)
	if err != nil {
		return 0, fmt.Errorf("invalid amount %q", s)
	}
	if neg {
		n = -n
	}
	return n, nil
}

// Day 依「對帳日」的定義回傳交易屬於哪一天:先換到約定的時區,再取日曆日。
func Day(t time.Time, loc *time.Location) string {
	return t.In(loc).Format(time.DateOnly)
}

幾個細節:cr.FieldPos(0) 回傳的是這一列在檔案中開始的行號,引號裡有換行時也正確,它和檔案雜湊一起當暫存表的唯一鍵,之後要回頭查原始檔也找得到。parseMinor 先拿掉千分位,再把整數部分與補齊位數的小數部分接起來,用 strconv.ParseInt 一次轉換,溢位時也會回傳錯誤。exponents 只放了範例需要的三個幣別,完整的幣別處理留給下一篇。

測試把 BOM、引號裡的千分位、大寫的類型、負數的退款、日界以及各種壞檔案都涵蓋到:

package recon

import (
	"errors"
	"strings"
	"testing"
	"time"
)

// 台灣沒有日光節約時間,測試用固定時區,不依賴機器上的時區資料庫。
var taipei = time.FixedZone("Asia/Taipei", 8*60*60)

const header = "merchant_trade_no,provider_txn_id,type,status,amount,fee,currency,transacted_at,settlement_date\n"

func TestParseCSVHandlesBOMQuotingAndNegativeRefunds(t *testing.T) {
	data := "\xef\xbb\xbf" + header +
		`pay_1001,T9001,payment,SUCCESS,"1,000",28,TWD,2026-11-14 02:00:00,2026-11-16` + "\n" +
		`"pay_1002","T9002",PAYMENT,success,"12.50",0.36,USD,2026-11-14 03:00:00,2026-11-16` + "\n" +
		`ref_1001,T9003,refund,SUCCESS,-200,0,TWD,2026-11-14 04:00:00,2026-11-16` + "\n"
	rows, err := ParseCSV([]byte(data), time.UTC)
	if err != nil {
		t.Fatal(err)
	}
	want := []struct {
		trade  string
		kind   Kind
		amount int64
		fee    int64
		line   int
	}{
		{"pay_1001", Payment, 100000, 2800, 2}, // TWD 1,000 元 = 100000(以分計)
		{"pay_1002", Payment, 1250, 36, 3},
		{"ref_1001", Refund, 20000, 0, 4}, // 負數的退款轉成正數,方向看 Kind
	}
	if len(rows) != len(want) {
		t.Fatalf("got %d rows, want %d", len(rows), len(want))
	}
	for i, w := range want {
		r := rows[i]
		if r.TradeNo != w.trade || r.Kind != w.kind || r.Amount != w.amount || r.Fee != w.fee || r.Line != w.line {
			t.Errorf("row %d = %+v, want %+v", i, r, w)
		}
	}
}

func TestDayCutOff(t *testing.T) {
	// 對帳單用 UTC;我們的對帳日定義成台北時間的日曆日
	data := header +
		"pay_1,T1,payment,SUCCESS,100,0,TWD,2026-11-14 15:59:59,2026-11-16\n" +
		"pay_2,T2,payment,SUCCESS,100,0,TWD,2026-11-14 16:00:00,2026-11-17\n"
	rows, err := ParseCSV([]byte(data), time.UTC)
	if err != nil {
		t.Fatal(err)
	}
	if got := Day(rows[0].At, taipei); got != "2026-11-14" {
		t.Errorf("23:59:59 Taipei: day %s", got)
	}
	if got := Day(rows[1].At, taipei); got != "2026-11-15" {
		t.Errorf("00:00:00 Taipei: day %s", got)
	}
	if got := Day(rows[1].At, time.UTC); got != "2026-11-14" {
		t.Errorf("same row, provider's UTC day: %s", got)
	}
}

func TestParseCSVRejectsWholeFile(t *testing.T) {
	ok := "pay_1,T1,payment,SUCCESS,100,0,TWD,2026-11-14 01:00:00,2026-11-16\n"
	cases := map[string]struct{ data, msg string }{
		"missing column":  {"merchant_trade_no,amount\npay_1,100\n", `missing column "provider_txn_id"`},
		"unknown status":  {header + ok + "pay_2,T2,payment,PROCESSING,100,0,TWD,2026-11-14 01:00:00,2026-11-16\n", "line 3: unknown status"},
		"too many digits": {header + "pay_2,T2,payment,SUCCESS,10.005,0,USD,2026-11-14 01:00:00,2026-11-16\n", `line 2: invalid amount "10.005"`},
		"negative charge": {header + "pay_2,T2,payment,SUCCESS,-100,0,TWD,2026-11-14 01:00:00,2026-11-16\n", "line 2: amount must be positive"},
		"bad time":        {header + "pay_2,T2,payment,SUCCESS,100,0,TWD,2026/11/14 01:00,2026-11-16\n", "line 2: transacted_at"},
		"not utf-8":       {header + "pay_2,T2,payment,SUCCESS,100,0,TWD,2026-11-14 01:00:00,2026-11-16,\xa4\xa4\n", "not UTF-8"},
		"field count":     {header + ok + "pay_2,T2,payment\n", "wrong number of fields"},
	}
	for name, c := range cases {
		t.Run(name, func(t *testing.T) {
			rows, err := ParseCSV([]byte(c.data), time.UTC)
			if !errors.Is(err, ErrBadRow) || !strings.Contains(err.Error(), c.msg) {
				t.Fatalf("err = %v, want %q", err, c.msg)
			}
			if rows != nil {
				t.Fatalf("got %d rows from a bad file", len(rows))
			}
		})
	}
}

TestDayCutOff 用的是 time.FixedZone,因為台灣沒有日光節約時間,固定時差就足夠,測試也不依賴執行環境裡有沒有時區資料庫。正式程式裡建議用 time.LoadLocation("Asia/Taipei"),並在主程式匯入 time/tzdata,讓容器映像檔裡沒有時區資料時也能運作。

冪等的匯入

Ingest 把「保存原始檔、解析、整天取代暫存資料」串起來。它依賴一個小小的 Store 介面,正式環境的實作是物件儲存加上前面的 SQL,測試用記憶體版本。

package recon

import (
	"context"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"time"
)

// Store 是匯入需要的儲存操作:正式環境是物件儲存加 PostgreSQL,測試用記憶體版。
type Store interface {
	// PutRaw 保存原始檔;同一個雜湊已經存在就什麼都不做,原始檔永遠不改寫。
	PutRaw(ctx context.Context, sum, name string, data []byte) error
	// ReplaceDay 在同一個交易裡刪掉這個對帳日的暫存列,再寫入這個檔案的每一列,
	// 每列以「檔案雜湊+行號」為唯一鍵。
	ReplaceDay(ctx context.Context, day, sum string, rows []Row) error
}

// Ingest 匯入某個對帳日的對帳單,回傳檔案的 SHA-256。
// 同一個檔案重跑幾次結果都一樣;更正版(雜湊不同)會整天取代舊的暫存資料。
func Ingest(ctx context.Context, s Store, day, name string, data []byte, providerTZ *time.Location) (string, error) {
	h := sha256.Sum256(data)
	sum := hex.EncodeToString(h[:])
	// 先存原始檔再解析:解析失敗時,證據也已經留下來了
	if err := s.PutRaw(ctx, sum, name, data); err != nil {
		return "", fmt.Errorf("recon: save raw %s: %w", name, err)
	}
	rows, err := ParseCSV(data, providerTZ)
	if err != nil {
		return sum, fmt.Errorf("recon: parse %s: %w", name, err)
	}
	if err := s.ReplaceDay(ctx, day, sum, rows); err != nil {
		return sum, fmt.Errorf("recon: stage %s: %w", name, err)
	}
	return sum, nil
}

注意順序:先存原始檔再解析。如果反過來,解析失敗的檔案就不會留下來,事後想看「那份壞掉的檔案到底長怎樣」也找不到。

package recon

import (
	"bytes"
	"context"
	"fmt"
	"sync"
	"testing"
	"time"
)

// memStore 是 Store 的記憶體版本,行為和 PostgreSQL 版一致:原始檔只寫一次、每天整批取代。
type memStore struct {
	mu   sync.Mutex
	raw  map[string][]byte
	days map[string]map[string]Row // 對帳日 → "雜湊:行號" → 列
}

func newMemStore() *memStore {
	return &memStore{raw: map[string][]byte{}, days: map[string]map[string]Row{}}
}

func (m *memStore) PutRaw(_ context.Context, sum, _ string, data []byte) error {
	m.mu.Lock()
	defer m.mu.Unlock()
	if _, ok := m.raw[sum]; !ok {
		m.raw[sum] = bytes.Clone(data)
	}
	return nil
}

func (m *memStore) ReplaceDay(_ context.Context, day, sum string, rows []Row) error {
	staged := make(map[string]Row, len(rows))
	for _, r := range rows {
		staged[fmt.Sprintf("%s:%d", sum, r.Line)] = r
	}
	m.mu.Lock()
	defer m.mu.Unlock()
	m.days[day] = staged
	return nil
}

func TestIngestIsIdempotent(t *testing.T) {
	ctx := context.Background()
	s := newMemStore()
	v1 := []byte(header +
		"pay_1,T1,payment,SUCCESS,100,0,TWD,2026-11-14 01:00:00,2026-11-16\n" +
		"pay_2,T2,payment,SUCCESS,250,0,TWD,2026-11-14 02:00:00,2026-11-16\n")

	// 排程重試與人工重跑可能同時發生:同一個檔案匯入八次,結果要和一次相同
	var wg sync.WaitGroup
	for range 8 {
		wg.Go(func() {
			if _, err := Ingest(ctx, s, "2026-11-14", "2026-11-14.csv", v1, time.UTC); err != nil {
				t.Error(err)
			}
		})
	}
	wg.Wait()
	if len(s.raw) != 1 || len(s.days["2026-11-14"]) != 2 {
		t.Fatalf("raw files %d, staged rows %d; want 1 and 2", len(s.raw), len(s.days["2026-11-14"]))
	}

	// 金流商重發更正版:原始檔兩份都留著,暫存資料整天換成新版
	v2 := []byte(header + "pay_1,T1,payment,SUCCESS,100,0,TWD,2026-11-14 01:00:00,2026-11-16\n")
	sum2, err := Ingest(ctx, s, "2026-11-14", "2026-11-14.v2.csv", v2, time.UTC)
	if err != nil {
		t.Fatal(err)
	}
	day := s.days["2026-11-14"]
	if _, ok := day[sum2+":2"]; len(s.raw) != 2 || len(day) != 1 || !ok {
		t.Fatalf("after correction: raw %d, staged %v", len(s.raw), day)
	}
}

func TestIngestKeepsRawEvenWhenParsingFails(t *testing.T) {
	s := newMemStore()
	_, err := Ingest(context.Background(), s, "2026-11-14", "bad.csv", []byte("not,a,statement\n"), time.UTC)
	if err == nil || len(s.raw) != 1 || len(s.days) != 0 {
		t.Fatalf("err %v, raw %d, days %d", err, len(s.raw), len(s.days))
	}
}

第一個測試讓八個 goroutine 同時匯入同一份檔案,配合 -race 檢查 memStore 沒有資料競爭,並確認結果和匯入一次相同;接著匯入更正版,確認原始檔兩份都留著,暫存資料只剩新版。第二個測試確認解析失敗時原始檔仍然留下、暫存資料沒有被動到。

第 3 步:逐筆配對

配對的鍵

配對要用兩邊都有、而且不會變的鍵。最好的選擇是我們自己產生、送給金流商的商店訂單編號:它在送出前就已經存在資料庫裡,即使回呼全部遺失、我們從來沒拿到金流商的交易編號,也還是能配對。金流商的交易編號是第二把鑰匙,用來分辨「同一個商店訂單編號底下的兩筆不同交易」。

這也是為什麼前幾篇一直強調:商店訂單編號要用付款嘗試的 ID,而不是訂單 ID。同一張訂單第一次付款失敗、第二次成功,會有兩個付款嘗試,送出的編號不同,對帳時才分得開。

一對多

不是每一筆都能一對一:

  • 部分退款。 一筆付款可以有多筆退款。每一筆退款要有自己的 ID,並當作退款的商店端編號送出;配對時退款和付款分開配,鍵是「種類+編號」。有些金流商的退款列只帶原始付款的編號加上自己的退款交易編號,這時就以「原始編號+退款交易編號」當鍵,並檢查同一筆付款的退款合計不超過原金額。
  • 分批撥款。 一天的交易可能分好幾批撥款,或是一筆撥款涵蓋好幾天。撥款的比對是以「撥款日」或撥款批號為單位的整批比對(第 6 步),不和逐筆配對混在一起。
  • 拒付(chargeback)。 持卡人向發卡銀行爭議,錢被扣回去。這是金流商那邊發生的事,我們這邊一開始不會有對應的紀錄,所以它一定以「只有對方有」的形式出現,而且通常有回覆期限。

金額、幣別、手續費

  • 金額一律用最小貨幣單位的整數比較,而且幣別也要相同;1000 TWD 和 1000 JPY 不是同一個金額。
  • 對帳單常見兩種寫法:總額(gross)加上手續費欄位,或直接給淨額(net)。逐筆配對要用總額,因為我們記的是使用者付了多少;如果只有淨額,就用「淨額+手續費」還原總額。
  • 手續費可能逐筆收(每筆 2.8%)、整批收(每次撥款收一筆固定費用)或兩者都有。逐筆的手續費在配對時和我們依合約算出的預期值比;整批的費用在撥款核對時比。費率計算一樣有捨入的問題,留給下一篇。

狀態對照

金流商的狀態比我們少,也比我們粗:對帳單上通常只有成功與失敗,有的只列成功的交易。我們這邊則有 pending、unknown 這類「還不知道」的狀態。對照的原則是:

  • 對方說成功、我們也是 succeeded:一致。
  • 對方說成功、我們是 failed、pending 或 unknown:狀態不一致,而且使用者已經被扣款,最危險的一種。
  • 我們是 pending 或 unknown、對方沒有:還在路上,交給上一篇的補查程式,不算對帳差異。
  • 我們是 failed、對方沒有:正常,失敗的交易不一定出現在對帳單上。

Match 把上面所有規則寫成程式。它是純函式,不碰資料庫,所以很容易測;呼叫端負責準備兩邊的資料:

package recon

import (
	"cmp"
	"fmt"
	"slices"
)

// Ours 是我們這邊的一筆紀錄:付款嘗試或退款。
type Ours struct {
	ID          string // 付款嘗試 ID 或退款 ID,送給金流商當商店訂單編號
	Kind        Kind
	Status      string // succeeded / failed / pending / unknown
	Amount      int64  // 最小貨幣單位
	Currency    string
	ExpectedFee int64 // 依合約費率算出的預期手續費
}

// DiffKind 是差異的種類。
type DiffKind string

const (
	MissingAtProvider DiffKind = "missing_at_provider" // 我們成功、對方沒有
	MissingInOurs     DiffKind = "missing_in_ours"     // 對方有、我們完全沒有
	StatusMismatch    DiffKind = "status_mismatch"
	AmountMismatch    DiffKind = "amount_mismatch" // 金額或幣別不同
	FeeMismatch       DiffKind = "fee_mismatch"
	Duplicate         DiffKind = "duplicate" // 對方同一個商店訂單編號出現兩次
)

// Discrepancy 是一筆差異;Urgent 代表使用者可能已被扣款,我們卻沒有記成成功。
type Discrepancy struct {
	Kind   DiffKind
	Key    string
	Ours   *Ours
	Theirs *Row
	Urgent bool
	Note   string
}

// Result 是一次配對的結果。
type Result struct {
	Matched int
	Diffs   []Discrepancy
}

func key(k Kind, tradeNo string) string { return string(k) + "/" + tradeNo }

// Match 逐筆配對。ours 要包含對帳日當天、對帳單上出現的編號與之前未結案的紀錄,
// 跨日的交易才不會被誤判為缺少。
func Match(ours []Ours, theirs []Row) Result {
	mine := make(map[string]*Ours, len(ours))
	for i := range ours {
		mine[key(ours[i].Kind, ours[i].ID)] = &ours[i]
	}
	seen := make(map[string]*Row, len(theirs))
	var res Result
	add := func(d Discrepancy) { res.Diffs = append(res.Diffs, d) }
	for i := range theirs {
		t := &theirs[i]
		k := key(t.Kind, t.TradeNo)
		if first, dup := seen[k]; dup {
			// 交易編號相同 = 同一列被送了兩次,該在匯入時去掉;不同 = 對方真的有兩筆交易
			add(Discrepancy{Kind: Duplicate, Key: k, Theirs: t,
				Urgent: t.ProviderTxnID != first.ProviderTxnID && t.Status == "succeeded",
				Note:   fmt.Sprintf("first %s, again %s", first.ProviderTxnID, t.ProviderTxnID)})
			continue
		}
		seen[k] = t
		o, ok := mine[k]
		switch {
		case !ok:
			add(Discrepancy{Kind: MissingInOurs, Key: k, Theirs: t, Urgent: t.Status == "succeeded"})
		case o.Status != t.Status:
			add(Discrepancy{Kind: StatusMismatch, Key: k, Ours: o, Theirs: t, Urgent: t.Status == "succeeded",
				Note: fmt.Sprintf("ours %s, provider %s", o.Status, t.Status)})
		case o.Amount != t.Amount || o.Currency != t.Currency:
			add(Discrepancy{Kind: AmountMismatch, Key: k, Ours: o, Theirs: t,
				Note: fmt.Sprintf("ours %d %s, provider %d %s", o.Amount, o.Currency, t.Amount, t.Currency)})
		case o.ExpectedFee != t.Fee:
			add(Discrepancy{Kind: FeeMismatch, Key: k, Ours: o, Theirs: t,
				Note: fmt.Sprintf("expected %d, charged %d", o.ExpectedFee, t.Fee)})
		default:
			res.Matched++
		}
	}
	for k, o := range mine {
		// pending、unknown 還在路上,交給補查程式;failed 本來就可能不出現在對帳單上
		if _, ok := seen[k]; !ok && o.Status == "succeeded" {
			add(Discrepancy{Kind: MissingAtProvider, Key: k, Ours: o})
		}
	}
	slices.SortFunc(res.Diffs, func(a, b Discrepancy) int {
		return cmp.Or(cmp.Compare(a.Key, b.Key), cmp.Compare(a.Kind, b.Kind))
	})
	return res
}

ours 要怎麼準備?只拿「對帳日當天」的紀錄是不夠的,因為跨日的交易會被誤判。實務上用三個條件取聯集:對帳日當天建立的紀錄、這份對帳單上出現的所有商店訂單編號(不論哪天建立),以及前幾天還沒結案的「對方沒有」的紀錄:

-- recon_our_records 是把 payments 與 refunds 合在一起的檢視,id 就是送給金流商的商店訂單編號
SELECT id, kind, status, amount, currency, expected_fee
FROM recon_our_records
WHERE (created_at AT TIME ZONE 'Asia/Taipei')::date = $2      -- 對帳日當天
   OR id = ANY ($3::text[])                                    -- 這份對帳單上出現的編號
   OR id IN (SELECT split_part(match_key, '/', 2)              -- 之前還沒結案的「對方沒有」
             FROM recon_discrepancies
             WHERE provider = $1 AND kind = 'missing_at_provider'
               AND state IN ('open', 'investigating'));

第 4 步:把差異分類

Match 產生的差異分成六類,每一類的意義與緊急程度都不一樣:

依(種類, 商店訂單編號)配對 只有我們有 我們是成功 missing_at_provider 多半是時間差,隔天再比 pending/unknown 不算差異 交給補查程式 我們是失敗 正常 失敗的不一定出現 只有對方有 對方是成功 missing_in_ours 使用者已被扣款,緊急 同一編號兩列 duplicate 交易編號不同=重複扣款 拒付列 開爭議案件 回覆有期限 對方是失敗 記錄即可 不影響金額 兩邊都有(依序檢查) 狀態不同 status_mismatch 對方成功=緊急 金額或幣別不同 amount_mismatch 當天查 手續費不同 fee_mismatch 對照合約費率 全部相同 一致 標記已對帳 深色框:使用者可能已被扣款,我們卻沒有記成成功,當天就要處理

圖:先看兩邊是否都有,再依狀態、金額、手續費依序檢查;深色框代表使用者可能已被扣款,當天就要處理。

類型情況常見原因緊急程度
missing_at_provider我們是成功,對帳單上沒有跨日的時間差;我們誤判成功;對方漏列先等一天,隔天仍沒有才查
missing_in_ours對帳單上成功,我們完全沒有回呼全部失敗;在金流商後台手動建立;程式錯誤緊急:使用者已被扣款
status_mismatch兩邊都有,狀態不同逾時後判成失敗,其實成功;回呼處理錯誤對方成功時緊急
amount_mismatch金額或幣別不同部分退款沒同步;幣別換算;資料被改當天調查
fee_mismatch手續費和合約不同費率調整沒通知;捨入方式不同;卡別不同不急,但要和金流商確認
duplicate同一個商店訂單編號在對帳單上出現兩次交易編號相同=檔案重複列;不同=重複扣款交易編號不同且成功時緊急

「只有對方有」和「狀態不同而對方成功」是最危險的兩類:使用者的錢已經被扣了,我們卻沒有出貨,或訂單已經被取消。處理方式和上一篇的補查一樣:先用商店訂單編號向金流商查詢單筆,確認成功後依訂單現況決定補記成功並出貨,或是退款;兩者都要冪等,不能因為對帳重跑就退兩次款。

「只有我們有」大多是時間差,不需要馬上告警,但不能永遠等下去。如果隔天、後天的對帳單上仍然沒有,就要向金流商查詢:也許是我們把逾時誤判成功(那就是嚴重的程式錯誤),也許是對方漏列。

測試把每一種類型都放進同一組資料裡,確認分類、排序與緊急標記:

package recon

import (
	"slices"
	"testing"
)

func TestMatchClassifiesDifferences(t *testing.T) {
	ours := []Ours{
		{ID: "pay_1", Kind: Payment, Status: "succeeded", Amount: 100000, Currency: "TWD", ExpectedFee: 2800},
		{ID: "pay_2", Kind: Payment, Status: "succeeded", Amount: 50000, Currency: "TWD"}, // 對方沒有
		{ID: "pay_3", Kind: Payment, Status: "failed", Amount: 30000, Currency: "TWD"},    // 對方卻扣款成功
		{ID: "pay_4", Kind: Payment, Status: "succeeded", Amount: 20000, Currency: "TWD"},
		{ID: "pay_5", Kind: Payment, Status: "succeeded", Amount: 10000, Currency: "TWD", ExpectedFee: 280},
		{ID: "pay_6", Kind: Payment, Status: "pending", Amount: 10000, Currency: "TWD"}, // 還在路上,不算差異
		{ID: "ref_1", Kind: Refund, Status: "succeeded", Amount: 20000, Currency: "TWD"},
	}
	theirs := []Row{
		{TradeNo: "pay_1", ProviderTxnID: "T1", Kind: Payment, Status: "succeeded", Amount: 100000, Currency: "TWD", Fee: 2800},
		{TradeNo: "pay_3", ProviderTxnID: "T3", Kind: Payment, Status: "succeeded", Amount: 30000, Currency: "TWD"},
		{TradeNo: "pay_4", ProviderTxnID: "T4", Kind: Payment, Status: "succeeded", Amount: 2000, Currency: "TWD"},
		{TradeNo: "pay_5", ProviderTxnID: "T5", Kind: Payment, Status: "succeeded", Amount: 10000, Currency: "TWD", Fee: 300},
		{TradeNo: "pay_7", ProviderTxnID: "T7", Kind: Payment, Status: "succeeded", Amount: 9900, Currency: "TWD"},   // 我們沒有
		{TradeNo: "pay_1", ProviderTxnID: "T8", Kind: Payment, Status: "succeeded", Amount: 100000, Currency: "TWD"}, // 第二筆
		{TradeNo: "ref_1", ProviderTxnID: "R1", Kind: Refund, Status: "succeeded", Amount: 20000, Currency: "TWD"},
	}
	res := Match(ours, theirs)

	type got struct {
		key    string
		kind   DiffKind
		urgent bool
	}
	var diffs []got
	for _, d := range res.Diffs {
		diffs = append(diffs, got{d.Key, d.Kind, d.Urgent})
	}
	want := []got{
		{"payment/pay_1", Duplicate, true},
		{"payment/pay_2", MissingAtProvider, false},
		{"payment/pay_3", StatusMismatch, true},
		{"payment/pay_4", AmountMismatch, false},
		{"payment/pay_5", FeeMismatch, false},
		{"payment/pay_7", MissingInOurs, true},
	}
	if !slices.Equal(diffs, want) {
		t.Fatalf("diffs\n got %v\nwant %v", diffs, want)
	}
	if res.Matched != 2 {
		t.Errorf("matched = %d, want 2", res.Matched)
	}
}

func TestTotalsAndNet(t *testing.T) {
	rows := []Row{
		{Kind: Payment, Status: "succeeded", Amount: 100000, Fee: 2800, Currency: "TWD"},
		{Kind: Payment, Status: "succeeded", Amount: 50000, Fee: 1400, Currency: "TWD"},
		{Kind: Payment, Status: "failed", Amount: 70000, Currency: "TWD"}, // 失敗的不計入
		{Kind: Refund, Status: "succeeded", Amount: 20000, Fee: -560, Currency: "TWD"},
		{Kind: Payment, Status: "succeeded", Amount: 1250, Fee: 36, Currency: "USD"},
	}
	ours := []Ours{
		{Kind: Payment, Status: "succeeded", Amount: 100000, ExpectedFee: 2800, Currency: "TWD"},
		{Kind: Payment, Status: "succeeded", Amount: 50000, ExpectedFee: 1400, Currency: "TWD"},
		{Kind: Refund, Status: "succeeded", Amount: 20000, ExpectedFee: -560, Currency: "TWD"},
	}
	theirs := SumRows(rows)
	diff := CompareTotals(SumOurs(ours), theirs)
	if want := []string{"payment USD: ours 0/0/0, provider 1/1250/36"}; !slices.Equal(diff, want) {
		t.Errorf("CompareTotals = %q, want %q", diff, want)
	}
	// 150000 − 20000 − (2800 + 1400 − 560) = 126360
	if got := Net(theirs, "TWD"); got != 126360 {
		t.Errorf("Net TWD = %d, want 126360", got)
	}
}

pay_6 是 pending、對方沒有,所以不出現在差異裡;pay_1 在對帳單上出現兩次而且交易編號不同,第二次被標成 duplicate。TestTotalsAndNet 用到的合計函式在第 6 步說明。

第 5 步:處理差異

差異表

每一筆差異都寫進一張表,並且有狀態、負責人與完整的歷史。對帳每天重跑時,同一個差異只會有一筆「未結案」的紀錄,靠部分唯一索引保證:

CREATE TABLE recon_discrepancies (
  id            bigint      GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  provider      text        NOT NULL,
  recon_day     date        NOT NULL,          -- 第一次發現的對帳日
  match_key     text        NOT NULL,          -- 例如 payment/pay_1001
  kind          text        NOT NULL,
  urgent        boolean     NOT NULL DEFAULT false,
  our_amount    bigint,
  their_amount  bigint,
  currency      char(3),
  state         text        NOT NULL DEFAULT 'open'
                CHECK (state IN ('open', 'investigating', 'resolved', 'written_off')),
  resolution    text,                          -- matched_later / booked / refunded / adjusted / written_off
  owner         text,
  note          text,
  first_seen_at timestamptz NOT NULL DEFAULT now(),
  last_seen_at  timestamptz NOT NULL DEFAULT now(),
  resolved_at   timestamptz,
  CHECK ((state IN ('resolved', 'written_off')) = (resolved_at IS NOT NULL))
);

-- 同一個差異,未結案的只能有一筆;每天重跑時更新 last_seen_at,而不是新增
CREATE UNIQUE INDEX recon_discrepancies_one_open
  ON recon_discrepancies (provider, match_key, kind)
  WHERE state IN ('open', 'investigating');

-- 每一次變更都寫一筆事件,只新增不修改
CREATE TABLE recon_discrepancy_events (
  id             bigint      GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  discrepancy_id bigint      NOT NULL REFERENCES recon_discrepancies (id),
  actor          text        NOT NULL,         -- 人員帳號,或 system:recon
  action         text        NOT NULL,         -- opened / seen_again / assigned / note / resolved / written_off
  from_state     text,
  to_state       text,
  detail         jsonb       NOT NULL DEFAULT '{}',
  at             timestamptz NOT NULL DEFAULT now()
);

-- 寫入一筆差異:已經有未結案的就更新最後出現時間
INSERT INTO recon_discrepancies
  (provider, recon_day, match_key, kind, urgent, our_amount, their_amount, currency, note)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
ON CONFLICT (provider, match_key, kind) WHERE state IN ('open', 'investigating')
DO UPDATE SET last_seen_at = now(),
              urgent = recon_discrepancies.urgent OR EXCLUDED.urgent
RETURNING id;

生命週期

open 待處理 investigating 調查中 resolved 已解決 written_off 核准沖銷 指派 隔天配對成功,自動結案 補記・退款・調整分錄 主管核准,寫沖銷分錄 每一次轉換都寫一筆事件:誰、什麼時候、為什麼、前後狀態

圖:差異從 open 開始,指派後進入 investigating,修正後 resolved;確定追不回來的經主管核准後 written_off。時間差造成的差異隔天配對成功就自動結案。

  • open:剛被發現,還沒有人處理。
  • investigating:已經指派負責人,正在查。
  • resolved:已經修正,resolution 記錄怎麼修的(補記、退款、寫調整分錄、隔天自動配對成功)。
  • written_off:確定追不回來,或金額小到追的成本高於金額本身,經過核准後沖銷。沖銷也是寫分錄,不是刪紀錄。

每一次狀態變更、指派、補充說明都寫一筆事件。三個月後稽核問「這筆 990 元為什麼沖銷」,要能回答是誰、什麼時候、根據什麼決定的。

自動結案:時間差

跨日造成的 missing_at_provider 是最大宗,也最不值得人看。規則很簡單:這次對帳的開始時間之後,如果某一筆「對方沒有」沒有再被列出來,表示它今天配對成功了,就自動結案並寫事件:

-- $1 provider、$2 這次對帳開始的時間
WITH done AS (
  UPDATE recon_discrepancies
  SET state = 'resolved', resolution = 'matched_later', resolved_at = now()
  WHERE provider = $1 AND kind = 'missing_at_provider'
    AND state = 'open' AND last_seen_at < $2
  RETURNING id
)
INSERT INTO recon_discrepancy_events (discrepancy_id, actor, action, from_state, to_state)
SELECT id, 'system:recon', 'resolved', 'open', 'resolved' FROM done;

這條規則能成立,前提是 ours 一定包含前幾天未結案的紀錄(第 3 步的查詢),而且這次對帳成功跑完;對帳中途失敗時不能執行,否則所有沒被重新列出的差異都會被誤判成已解決。同樣的道理,告警要看年齡:missing_at_provider 第一天不告警,超過兩個對帳日還沒結案才告警。

人工檢查的介面

差異表最後是給人看的。一個好用的檢查畫面至少要有:

  • 依緊急程度、年齡、金額排序,緊急的永遠在最上面。
  • 一筆差異打開後,並排顯示我們的紀錄(付款、訂單、回呼紀錄、狀態變更歷史)與對帳單的原始那一列(可以連到原始檔與行號)。
  • 「向金流商查詢」按鈕,結果寫進事件。
  • 修正動作做成按鈕(補記成功、發起退款、寫調整分錄、申請沖銷),每個動作都要填原因;沖銷需要第二個人核准。
  • 個人資料預設遮蔽(見第 7 步)。

修正的原則:不改金額,寫分錄

對帳發現金額不對時,最直覺的做法是把 payments.amount 改成對帳單上的數字。不要這樣做。 改掉之後,原本的值就消失了,帳本裡已經寫好的分錄也和它對不上,下一次有人查帳時,什麼都說不清楚。

正確的做法是延續〈支付常見問題:重複扣款、回呼與對帳〉第 9 個問題的複式記帳:原本的分錄不動,寫一筆調整分錄把差額補上或沖回,分錄的冪等鍵用差異的 ID,並在差異的事件裡記下分錄編號。例如金流商實際收的手續費比預期多 20 分:

-- 冪等鍵 = 差異 ID,同一筆差異只會調整一次
INSERT INTO journal_entries (idempotency_key, kind)
VALUES ('recon-adjust-' || $1, 'recon_adjustment')
ON CONFLICT (idempotency_key) DO NOTHING
RETURNING id;
-- 有回傳 id 才寫分錄列:借 手續費支出 20、貸 應收金流商 20
-- $1 剛建立的分錄 id、$2 手續費支出帳戶、$3 應收金流商帳戶
INSERT INTO ledger_lines (entry_id, account_id, debit, credit)
VALUES ($1, $2, 20, 0), ($1, $3, 0, 20);

journal_entries 與 ledger_lines 的定義在上面那篇裡;kind 在那裡是自由文字,這裡多了一種 recon_adjustment。

修正動作要冪等

對帳每天重跑,人也可能重複按按鈕。每一個會動到錢的修正動作都要有冪等鍵:

  • 退款:冪等鍵用「差異 ID+動作」,例如 recon-refund-1234,並且同樣送給金流商當退款的商店端編號;重跑時金流商也會擋掉重複。
  • 補記成功並出貨:走正常的狀態機條件式更新(WHERE status IN ('pending', 'unknown', 'failed')),出貨用 Outbox 送事件(〈分散式交易:Saga 與 Outbox〉);條件不成立就表示已經有人處理過。
  • 調整分錄:如上,冪等鍵用差異 ID。

第 6 步:和帳本與銀行撥款對起來

先比合計,再逐筆

逐筆配對之前,先做一次合計檢查:兩邊依「種類+幣別」算筆數、金額與手續費合計。合計對不上,代表一定有差異,逐筆配對會告訴你是哪幾筆;合計對得上,也不代表沒有問題,但如果合計差了一大截(例如對帳單只有平常的一半),通常是檔案不完整或抓錯日期,應該先停下來檢查檔案,而不是產生幾千筆差異。

package recon

import (
	"cmp"
	"fmt"
	"maps"
	"slices"
)

// TotalsKey 把合計依交易種類與幣別分開;不同幣別的金額絕對不能加在一起。
type TotalsKey struct {
	Kind     Kind
	Currency string
}

// Totals 是成功交易的筆數、總額與手續費合計。
type Totals struct {
	Count  int
	Amount int64
	Fee    int64
}

// SumRows 加總對帳單上成功的列。
func SumRows(rows []Row) map[TotalsKey]Totals {
	m := map[TotalsKey]Totals{}
	for _, r := range rows {
		if r.Status != "succeeded" {
			continue
		}
		k := TotalsKey{r.Kind, r.Currency}
		t := m[k]
		t.Count, t.Amount, t.Fee = t.Count+1, t.Amount+r.Amount, t.Fee+r.Fee
		m[k] = t
	}
	return m
}

// SumOurs 加總我們這邊成功的紀錄,手續費用預期值。
func SumOurs(ours []Ours) map[TotalsKey]Totals {
	m := map[TotalsKey]Totals{}
	for _, o := range ours {
		if o.Status != "succeeded" {
			continue
		}
		k := TotalsKey{o.Kind, o.Currency}
		t := m[k]
		t.Count, t.Amount, t.Fee = t.Count+1, t.Amount+o.Amount, t.Fee+o.ExpectedFee
		m[k] = t
	}
	return m
}

// CompareTotals 列出兩邊合計不一致的項目,依固定順序排列。
func CompareTotals(ours, theirs map[TotalsKey]Totals) []string {
	keys := slices.Collect(maps.Keys(ours))
	for k := range theirs {
		if _, ok := ours[k]; !ok {
			keys = append(keys, k)
		}
	}
	slices.SortFunc(keys, func(a, b TotalsKey) int {
		return cmp.Or(cmp.Compare(a.Kind, b.Kind), cmp.Compare(a.Currency, b.Currency))
	})
	var out []string
	for _, k := range keys {
		if a, b := ours[k], theirs[k]; a != b {
			out = append(out, fmt.Sprintf("%s %s: ours %d/%d/%d, provider %d/%d/%d",
				k.Kind, k.Currency, a.Count, a.Amount, a.Fee, b.Count, b.Amount, b.Fee))
		}
	}
	return out
}

// Net 是對方這批應撥給我們的淨額:付款 − 退款 − 拒付 − 全部手續費。
func Net(t map[TotalsKey]Totals, currency string) int64 {
	n := t[TotalsKey{Payment, currency}].Amount -
		t[TotalsKey{Refund, currency}].Amount -
		t[TotalsKey{Chargeback, currency}].Amount
	for k, v := range t {
		if k.Currency == currency {
			n -= v.Fee
		}
	}
	return n
}

Net 算的是這批交易金流商應該撥給我們的淨額:付款總額減掉退款與拒付,再減掉所有手續費。退款退回手續費時,手續費是負數,減掉負數就等於加回來。不同幣別的金額絕對不加在一起,所以合計的鍵一定帶幣別。

測試 TestTotalsAndNet(在上面的 match_test.go 裡)確認失敗的交易不計入、只有一邊有的幣別也會被列出,以及淨額的計算:150000 − 20000 − (2800 + 1400 − 560) = 126360。

帳本裡的四種分錄

要讓帳本和對帳單、銀行對起來,帳本至少要有這幾個帳戶:應收金流商(金流商收了錢、還沒撥給我們)、銀行存款、手續費支出、營收(或給商家的應付款),以及退款相關的帳戶。一筆付款從頭到尾會寫四種分錄:

事件借貸例(分)
付款成功應收金流商營收100000
金流商收手續費手續費支出應收金流商2800
部分退款營收(或銷貨退回)應收金流商20000
撥款進銀行銀行存款應收金流商77200

撥款之後,這一批在「應收金流商」上的借貸剛好抵銷成 0。所以三方對帳可以化成一句話:每個撥款日,應收金流商在帳本上的減少,等於對帳單上這一批的淨額,也等於銀行實際入帳的金額。

對帳單與銀行入帳

銀行端的資料可以來自銀行的對帳單或入帳通知,存在 bank_deposits。以撥款日比較兩邊的淨額:

-- $1 provider;銀行入帳存在 bank_deposits (provider, value_date, amount, currency, reference)
WITH stmt AS (
  SELECT settlement_date, currency,
         sum(CASE kind WHEN 'payment' THEN amount ELSE -amount END) - sum(fee) AS net
  FROM statement_lines
  WHERE provider = $1 AND status = 'succeeded'
  GROUP BY settlement_date, currency
), bank AS (
  SELECT value_date AS settlement_date, currency, sum(amount) AS net
  FROM bank_deposits
  WHERE provider = $1
  GROUP BY value_date, currency
)
SELECT settlement_date, currency, s.net AS statement_net, b.net AS bank_net
FROM stmt s FULL JOIN bank b USING (settlement_date, currency)
WHERE s.net IS DISTINCT FROM b.net
ORDER BY settlement_date, currency;

這個查詢只是起點,實務上有幾個常見的差異來源:撥款遇到假日會延後,銀行的入帳日和對帳單上的撥款日不同(如果金流商提供撥款批號,用批號對比用日期可靠);整批收取的費用、匯費或保留款(reserve)會從撥款中扣掉,要在對帳單或撥款明細裡找到對應的列;拒付可能在之後的撥款裡扣回。每一種都應該有明確的處理規則,而不是每個月由人手算。

帳本與對帳單的每日合計

最後,帳本這邊也做一樣的合計,和對帳單的合計比:

-- 帳本:某個對帳日,「應收金流商」帳戶依分錄種類的筆數與淨變動($1 帳戶、$2 對帳日)
SELECT e.kind, count(*) AS entries, sum(l.debit - l.credit) AS net_change
FROM journal_entries e
JOIN ledger_lines l ON l.entry_id = e.id
WHERE l.account_id = $1
  AND (e.created_at AT TIME ZONE 'Asia/Taipei')::date = $2
GROUP BY e.kind
ORDER BY e.kind;

-- 對帳單:同一個對帳日,依種類的筆數與合計($1 provider、$2 對帳日)
SELECT kind, count(*) AS lines, sum(amount) AS amount, sum(fee) AS fee
FROM statement_lines
WHERE provider = $1 AND recon_day = $2 AND status = 'succeeded'
GROUP BY kind
ORDER BY kind;

帳本的分錄時間是我們記帳的時間(例如收到回呼的時候),不一定和交易時間同一天,這也是一種時間差。比較常見的做法是在分錄上另外存一個「業務日期」欄位,用交易時間換算的對帳日填入,合計時用它,而不是用 created_at。

第 7 步:營運

每日報表

每次對帳跑完,產生一份簡短的報表:對帳日、檔案與雜湊、兩邊的筆數與合計、配對成功筆數、各類差異的筆數與金額、自動結案筆數、未結案差異依年齡的分布。報表本身也存起來,月結時直接引用。

指標與告警

對帳程式也要被監控,和其他服務一樣輸出指標(〈可觀測性:日誌、指標、追蹤〉):

  • 對帳單沒有準時到:超過約定時間仍沒有成功的 ingestion_runs,告警給工程。
  • 對帳失敗:解析錯誤、合計差異過大,告警給工程。
  • 緊急差異 > 0:missing_in_ours、對方成功的 status_mismatch、重複扣款,有一筆就告警,因為每一筆都代表一個被扣了錢卻沒拿到東西的使用者。
  • 未結案差異依年齡:例如 missing_at_provider 超過兩個對帳日、任何差異超過七天,告警給負責人。
  • 未結案差異的金額:依幣別分開算,超過門檻告警。
  • 差異數量的趨勢:平常每天兩三筆,今天突然五十筆,通常代表某個環節壞了(新版程式、金流商改格式),比任何單一差異都值得注意。

指標的標籤只放種類、幣別、年齡區間這類低基數的值,不要放商店訂單編號。

重跑與回補

  • 重跑某一天:因為原始檔不改寫、匯入與差異寫入都冪等,重跑就是「用同一份原始檔再跑一次」,結果應該相同。這也是修好解析程式後回補的方式。
  • 回補一段期間:例如新接一家金流商,或發現某個月的檔案漏抓。依日期順序逐日跑,每一天都寫執行紀錄;不要一次載入整個月再配對,否則跨日的時間差規則不會正確運作。
  • 重跑不能產生副作用:配對與分類是純計算;會動到錢的修正動作都有冪等鍵,重跑不會再退一次款。

資料保存、權限與個人資料

對帳單裡通常有個人資料:持卡人姓名、部分遮蔽的卡號、Email、電話、IP。處理原則:

  • 原始檔放在權限受控的物件儲存,只有對帳程式與少數人能讀;存取要留紀錄。
  • 暫存表只放對帳需要的欄位,個人資料不進暫存表,需要時從原始檔查。
  • 檢查畫面預設遮蔽,需要看完整內容時要有理由並留紀錄。
  • 日誌只記商店訂單編號、金額、差異種類,不記整列內容。
  • 保存期限依會計與法規要求決定,到期後依政策刪除或封存;完整卡號與安全碼本來就不應該出現在對帳單裡,出現了要通報金流商。

月結

月底時,對帳的工作是讓財務能關帳:

  1. 確認這個月每一天都有成功的對帳執行,沒有缺漏的日期。
  2. 所有緊急差異都已結案;其他未結案的差異列成清單,附上原因與預計處理時間,金額小的依政策沖銷。
  3. 這個月的撥款全部和銀行入帳對上;跨月的撥款(月底的交易下個月才撥款)列為應收餘額,並和帳本上應收金流商的餘額一致。
  4. 關帳後,這個月的資料不再改動;之後發現的問題,以下個月的調整分錄處理,並在差異的事件裡註明。

執行測試

$ go vet ./...
$ go test -race ./...
ok  	example.com/shop/internal/recon	1.084s

常見陷阱

  • 用 strings.Split 切 CSV。 遇到引號裡的逗號就錯位。用 encoding/csv,並用欄位名稱找欄位。
  • 用 float64 解析金額。 strconv.ParseFloat("0.29", 64) * 100 轉回整數可能變成 28。直接解析成整數。
  • 跳過壞掉的列。 那一筆從此消失。有錯就整個檔案拒絕。
  • 兩邊用不同的日界。 每天都有一小撮「對方沒有」,而且永遠消不掉。先定義對帳日,再加上跨日帶到隔天的規則。
  • 第一天就對「對方沒有」告警。 告警疲乏後,真正緊急的那一筆也沒人看。依類型與年齡分級。
  • 直接改金額或刪差異。 帳本與事件紀錄是唯一能解釋過去的東西。寫調整分錄、狀態改成結案。
  • 修正動作不冪等。 對帳重跑一次,就多退一次款。
  • 只比總額。 一多一少剛好抵銷。合計只是初步檢查。
  • 對帳失敗時仍執行自動結案。 沒被列出不代表已解決,可能只是沒跑到。

重點整理

  • 對帳是三方的:我們的紀錄和對帳單逐筆比、對帳單和銀行撥款整批比,三者都要和帳本對得起來。
  • 對帳單是證據:原始檔原封不動地保存並記錄雜湊,所有結果都能從原始檔重新算出來。
  • 匯入要冪等:暫存表以「檔案雜湊+行號」為鍵,一個對帳日在同一個交易裡整批取代,更正版直接取代舊版。
  • 解析要嚴格:處理 BOM、引號與編碼,金額直接轉成最小單位的整數,狀態對照不認得就停,有一列錯就整個檔案拒絕。
  • 先定義對帳日,再處理時區:時間帶上正確時區、換到約定時區取日期,跨日的紀錄帶到隔天再比。
  • 用自己產生的商店訂單編號當配對鍵,付款、退款、拒付分開配;先比合計,再逐筆配對。
  • 差異要分類分級:「對方成功、我們沒有成功」是使用者已被扣款,當天處理;時間差隔天自動結案。
  • 差異要有狀態、負責人與事件紀錄;修正寫調整分錄,不改金額;會動到錢的修正都要冪等。

上線前可以逐項確認:

  • 文件寫清楚對帳日的定義(時區與日界)、每一方的資料來源,以及各角色的負責人。
  • 抓檔有排程、退避重試與「逾時未到」告警,每次執行都寫進 ingestion_runs。
  • 原始檔存在物件儲存,記錄 SHA-256,不可改寫;更正版另存一份並標記取代關係。
  • 解析用 encoding/csv、處理 BOM、檢查 UTF-8、用欄位名稱找欄位,金額不經過 float64,錯一列就整檔拒絕,並有對應的測試。
  • 暫存表以「檔案雜湊+行號」為鍵,一個對帳日在同一個交易裡整批取代,同一天的匯入有鎖。
  • 配對鍵是商店訂單編號(付款嘗試 ID、退款 ID),並涵蓋前後一天與未結案的紀錄。
  • 合計檢查(筆數、金額、手續費,依種類與幣別)在逐筆配對之前執行,差距過大就停下來。
  • 差異表有狀態、負責人、事件紀錄與部分唯一索引;時間差有自動結案規則,對帳失敗時不執行。
  • 緊急差異有一筆就告警;其他差異依年齡與金額告警。
  • 修正一律寫調整分錄;退款、補記、沖銷都有冪等鍵;沖銷需要第二個人核准。
  • 撥款以撥款日或批號和銀行入帳比對,應收金流商的餘額和帳本一致。
  • 原始檔與檢查畫面的個人資料有權限控管、預設遮蔽與存取紀錄,並有保存期限。
  • 月結前確認每天都有成功的對帳、緊急差異全部結案、跨月撥款列為應收。

下一篇

對帳時最難纏的差異,往往不是整筆不見,而是差了一兩分錢:手續費依費率乘出來有零頭,我們四捨五入、金流商無條件捨去;一筆折扣分攤到三個商品,退其中一件時退多少;新台幣在對帳單上是整數元,我們內部卻以分計。這些都是「怎麼處理金額」的問題。下一篇〈Go 處理金額:整數分、decimal、幣別、四捨五入與分攤〉從 float64 為什麼不行講起,建立帶幣別的金額型別,並把捨入與分攤做到一分錢都不差。