金流架構重構 — 結帳即記帳 / 關帳只盤點

§1. 為什麼要改

1.1 現狀:雙軌制 + 不一致

1.2 業界怎麼做 — research 結論

Audit Square / Toast / Restaurant365 / Stripe 4 個成熟系統,都用同一套模式:

• Event-sourced ledger:每筆 payment / refund / fee / payout 都是獨立 immutable transaction row。Stripe 的 balance_transactions 就是這樣 — "replay 全部到 T 時刻 = T 時刻的 balance"
• Per-tender mapping:每種付款方式(cash / 信用卡 / LINE Pay / 街口)在系統內 mapping 到一個 asset account。**不**按 processor 分,按 tender 分
• Clearing account 模式:刷卡不直接記「銀行 +1000」,而是記「清算戶 - TapPay +1000」,等 T+2 payout 到帳才轉「銀行 +980 + 手續費 +20 − 清算戶 1000」
• 關帳純盤點:不寫 revenue summary 進 ledger,只記「實點現金 vs 系統算的應有現金 → 差異列 cash short/over」

§2. 新架構設計

2.1 核心原則

1. 每個金流事件都是 asset_transaction(event-sourced) — 結帳 / 退款 / AdHoc / 第三方 payout / 錢箱 reset / 盤點差異,全部一筆一筆寫
2. 關帳完全不寫金流 — 只寫 daily_closes 盤點紀錄。dailyCloseRevenue type 廢除
3. 退款必 link 原 payment — `asset_transactions.refund_of_id` FK 指回原 transaction
4. Clearing account per processor — TapPay / LINE Pay / 街口 / ezPay 各一個清算戶
5. 關帳 = 期末盤點 — 員工點現金 → 比對 ledger 算的「應有現金」 → 差異走 cash_shortage / cash_overage 並填理由

2.2 帳戶結構(餐廳建立時自動 seed)

2.3 完整水流圖

場景 A:客人現金結 $500
  asset_transactions: [
    { type: 'sale_cash', amount: +500, asset: 現金, payment_id: P1, business_date: 2026-05-25 }
  ]
  → 現金 +500

場景 B:客人 TapPay 結 $1000(T+2 入帳)
  Day 0: asset_transactions: [
    { type: 'sale_card', amount: +1000, asset: 清算-TapPay, payment_id: P2, business_date: 2026-05-25 }
  ]
  → 清算-TapPay +1000

  Day +2: 老闆收到 TapPay payout $970(扣 $30 手續費)
  asset_transactions: [
    { type: 'processor_payout',     amount: +970, asset: 銀行,        processor: 'tappay', payout_date: 2026-05-27 },
    { type: 'processor_fee',        amount: -30,  asset: 清算-TapPay, processor: 'tappay', payout_date: 2026-05-27 },
    { type: 'processor_settlement', amount: -1000, asset: 清算-TapPay, processor: 'tappay', payout_date: 2026-05-27 }
  ]
  → 銀行 +970, 清算-TapPay 歸 0(原本 +1000 - 30 - 970 = 0)

場景 C:退款 P1 全額 $500(現金)
  asset_transactions: [
    { type: 'refund_cash', amount: -500, asset: 現金,
      refund_of_id: ,
      payment_id: P1, business_date: 2026-05-25 }
  ]
  → 現金 -500

場景 D:臨時支出 $200 買蔥(從零用金)
  asset_transactions: [
    { type: 'adhoc_expense', amount: -200, asset: 零用金, note: '買蔥',
      created_by: , business_date: 2026-05-25 }
  ]
  → 零用金 -200

場景 E:關帳 — 員工數錢
  ledger 算的「應有現金」 = 期初零用金 +sum(現金 type 的 asset_transactions 當天)
                          = 3000 + 500 - 500 - 200 = 2800
  員工實點 = 2750
  差異 = -50

  daily_closes 寫一筆:
    { close_date: 2026-05-25, close_type: 'final', closed_by: 員工A,
      closed_at: 2026-05-25T22:30:00+08:00,
      expected_cash: 2800, actual_cash: 2750, cash_difference: -50,
      cash_shortage_reason: '找錯 50 給客人 #1234',
      starting_cash_for_next_day: 3000,
      starting_cash_reset_adjustment: +250 (從銀行補 250 進錢箱 → 變回 3000)
    }

  順便寫(if starting_cash 有 reset):
    asset_transactions: [
      { type: 'cash_shortage', amount: -50, asset: 現金, reason: '找錯 50 給客人 #1234' },
      { type: 'cash_drawer_top_up', amount: +250, asset: 現金,
        related_close_id: , note: '從銀行補錢箱回 3000' },
      { type: 'cash_drawer_top_up_offset', amount: -250, asset: 銀行,
        related_close_id:  }
    ]
    → 現金 -50 +250 = 2750 + 250 = 3000 (對標下一個營業日期初)
    → 銀行 -250
  

§3. 老闆已答 6 個議題

§4. DB Schema 變更

4.1 asset_transactions 表擴充

-- 退款 link
ALTER TABLE asset_transactions ADD COLUMN refund_of_id UUID REFERENCES asset_transactions(id);
CREATE INDEX idx_asset_tx_refund_of ON asset_transactions(refund_of_id) WHERE refund_of_id IS NOT NULL;

-- 業務日期(query 不必再 join business hours 算)
ALTER TABLE asset_transactions ADD COLUMN business_date DATE;
CREATE INDEX idx_asset_tx_business_date ON asset_transactions(restaurant_id, business_date);

-- 連回 payment(沒有 FK 因為訂金 / AdHoc 沒對應 payment)
ALTER TABLE asset_transactions ADD COLUMN payment_id UUID;

-- 連回關帳紀錄(對於關帳當下產生的 cash_drawer 操作)
ALTER TABLE asset_transactions ADD COLUMN daily_close_id UUID REFERENCES daily_closes(id);

-- 第三方金流 payout 追蹤
ALTER TABLE asset_transactions ADD COLUMN processor TEXT;
  -- 'tappay' / 'linepay' / 'jkopay' / 'newebpay' / 'ezpay' / NULL(現金 / AdHoc)
ALTER TABLE asset_transactions ADD COLUMN processor_payout_id TEXT;
  -- payout batch id 用來對帳

-- 新 transaction_type values:
--   'sale_cash'       — 現金結帳收入(取代既有 other_income 用於 payment)
--   'sale_card'       — 刷卡 / 行動支付收入(寫到 clearing)
--   'refund_cash'     — 現金退款
--   'refund_card'     — 刷卡退款
--   'adhoc_income'    — 臨時收入(取代既有 other_income for AdHoc)
--   'adhoc_expense'   — 臨時支出(取代既有 other_expense for AdHoc)
--   'cash_shortage'   — 盤點短缺(已存在)
--   'cash_overage'    — 盤點溢餘(新)
--   'cash_drawer_top_up'         — 錢箱補錢(從銀行或其他)
--   'cash_drawer_top_up_offset'  — 對沖,負數,從來源 asset 扣
--   'processor_payout'           — 第三方 payout 進銀行
--   'processor_fee'              — 第三方手續費
--   'processor_settlement'       — clearing 戶歸零

-- 廢除(不再寫,但歷史保留):
--   'daily_close_revenue'
--   'other_income' / 'other_expense'(細分成 sale_* / refund_* / adhoc_*)

4.2 daily_closes 表擴充

-- 是否 reset 零用金(老闆 Q1 已答)
ALTER TABLE daily_closes ADD COLUMN starting_cash_reset_amount NUMERIC;
ALTER TABLE daily_closes ADD COLUMN starting_cash_reset_from_asset_id UUID REFERENCES assets(id);
ALTER TABLE daily_closes ADD COLUMN starting_cash_reset_note TEXT;

-- 老闆編輯紀錄 trail(老闆 Q1:可修改但要 audit)
CREATE TABLE daily_close_edits (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  daily_close_id UUID NOT NULL REFERENCES daily_closes(id) ON DELETE CASCADE,
  edited_by TEXT NOT NULL,
  edited_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  field_name TEXT NOT NULL,
  old_value TEXT,
  new_value TEXT,
  reason TEXT
);

4.3 payment_method → asset mapping 表

CREATE TABLE payment_method_asset_mappings (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  restaurant_id UUID NOT NULL REFERENCES restaurants(id) ON DELETE CASCADE,
  payment_method TEXT NOT NULL,  -- 'cash' / 'credit' / 'apple_pay' / 'linepay' / 'jkopay' / 'newebpay'
  asset_id UUID NOT NULL REFERENCES assets(id),
  is_clearing BOOLEAN NOT NULL DEFAULT FALSE,
  processor TEXT,  -- 'tappay' / 'linepay' / 'jkopay' / 'newebpay'(用於 payout reconciliation)
  UNIQUE (restaurant_id, payment_method)
);
-- 餐廳建立時 seed 預設 mapping

4.4 時區處理

• 所有 timestamptz 存 UTC(Postgres 標準)
• business_date:`DATE` type,用餐廳時區(`restaurants.timezone` 已存在,default Asia/Taipei)算
• 計算公式:business_date = (created_at AT TIME ZONE restaurant.timezone) >= 06:00 ? that_date : that_date - 1
• 提供 SQL function:compute_business_date(ts TIMESTAMPTZ, restaurant_id UUID) RETURNS DATE
• 寫入時由 PaymentService / RefundService / AdHocService 自己算好 business_date(避免 trigger 跑跨表 query 慢)
• 跨年 / 夏令時 邊界 case 處理:餐廳跨年夜跨日營業 → business_date 跟營業日對齊(2026-12-31 凌晨 02:00 的訂單 business_date=2026-12-31 if closing_time_minutes > 1440)

§5. 改動範圍 — Code Audit 結果

§6. Phase Plan

§7. 歷史資料 migration 策略

2 個方案,老闆選一個:

§8. 給老闆的剩餘決策題

§9. 已知風險

• 歷史報表數字飄 — 若選方案 B backfill 失敗,可能影響過去 6 個月的營收報表
• 退款找不到原 asset_transaction — 上線前的 refund 沒對應原 row,refund_of_id=NULL,要在 UI 區別「歷史退款」
• 多裝置時序 — 兩台 POS 同時結 1 桌 → 2 個 asset_transaction,realtime 同步要 idempotent(payment_id UNIQUE 防雙寫)
• 第三方金流 webhook 重試 — TapPay payout webhook 可能重傳,需要 idempotency key(processor_payout_id UNIQUE)
• 跨年 / 夏令時 — Asia/Taipei 沒夏令時,但若未來支援其他時區的餐廳要小心 business_date 算法
• 小數精度 — NUMERIC 不能用 Double 操作,Swift 端要全程 Decimal

§10. 相關文件

• L2 金流總覽:POS_金流系統架構
• L5 臨時支出 FAQ(觸發本 spec 的 root cause):L5_臨時支出_完整操作FAQ
• L5 員工小費系統(同樣是 event-sourced asset 思維):L5_員工小費系統

Spec 建立 2026-05-25 · 等老闆答 6 個 Q 後 Phase 0 開做 · 預估 ~15-17 天