金流總體規劃 — POS + ArenaMate 整合

0給 builder 的三句話

1. 接在既有 infra 上,不要另起爐灶。POS 已有一套「#W13 現金流重構」:藍新 NewebPay 收款 + asset_transactions 複式記帳(清算戶/銀行戶)+ compute-settlement 關帳 + ezPay 發票。Arena 的拆帳/撥款要長在這套之上。
2. 金流核心是後端。拆帳/撥款/退款/發票的決策邏輯寫在 supabase/functions/_shared(TS,單一真相源),POS 與 Arena 都是薄 client 呼叫同一組 API。兩端 client 語言不同(Swift / Dart)本來就無法共用程式碼,共用點在後端。
3. 只有「你抽成的錢」准走平台帳戶。商家自己的營業額(POS 餐廳結帳、場館櫃檯收費)必須進商家自己的金流帳戶,否則會把全部營業額算進平台的「代理收付金額」,秒破 10 億門檻 → 被逼辦電子支付執照。細節見 §2。

1現況盤點:別重造的既有 infra

動工前先讀這些,能重用的重用。金流商後端主線是 藍新 NewebPay + ezPay 發票(不是綠界;綠界只在 Arena 櫃檯個人收款那條出現過,平台拆帳統一走藍新)。

2⚠️ 分流鐵則(最高優先)

三種金流要嚴格分帳,決定你會不會被當成「電子支付機構」:

法規門檻速記

• 年代收代付總額 < 10 億 → ① 商業登記營業項目含第三方支付 + ② 向數位發展部辦「洗錢防制能量登錄」即可,不需電支執照。
• > 10 億,或做「儲值 / 預付錢包」 → 進電子支付機構規範(資本額 1 億 / 5 億)。結論:千萬別做儲值錢包功能,一做就跳門檻。(現有 wallet 是 Apple/Google 會員卡 loyalty,非儲值,OK。)

3統一架構:後端引擎 + 薄 client

        ┌──────────── 藍新 NewebPay 平台商帳號(你公司) ────────────┐
        │                                                            │
   ┌────┴──── supabase/functions/_shared/payout (單一真相源 TS) ─────┴────┐
   │  collectOrchestrator / splitPayoutOrchestrator / refundOrchestrator  │
   │  PayoutGates(computeSplit / canReleasePayout / canRefund)            │
   │  → 寫入 asset_transactions(沿用既有清算戶/銀行戶分錄)               │
   │  → ezpay-invoice 開平台抽成發票                                       │
   └───────▲──────────────────────────────────────▲─────────────────────┘
           │ 薄 client 呼叫                          │ 薄 client 呼叫
   ┌───────┴────────┐                       ┌───────┴─────────────────┐
   │  POS (Swift)   │                       │ ArenaMate (Dart)        │
   │  ①訂閱 ②餐廳直收 │                       │ ①訂閱 ②櫃檯直收 ③報名費/學費拆帳 │
   └────────────────┘                       └─────────────────────────┘

• 拆帳/撥款/退款 Gate 只寫一次(TS,edge function),POS 與 Arena 打同一組 API —— 照既有 thin-client pattern。
• 沿用 asset_transactions 分錄 + newebpay-payout-webhook 撥款回呼;Arena 拆帳只是多幾種 asset 科目(平台抽成戶 / 場館應付戶 / 教練應付戶 / 準備金戶)。
• 一個藍新平台商帳號同時服務兩 App 的 ①訂閱 與 ③拆帳;② 商家直收走商家各自帳號。

4拆帳分潤 Spec(payout 模組)

照 4 層架構(Route/View → Orchestrator → Gate + Primitive + Repository)。Gate 為純函數,一律要單元測試。

4.1 狀態機

collected ──► held(escrow) ──► releasable ──► paid
                  │
                  ├──► refunding ──► refunded   (撥款前可退)
                  └──► reversed                 (爭議/退單反轉拆帳)

• collected:藍新代收成功。held:款在金流商託管,尚不可撥。releasable:Gate 判定可撥。paid:已撥款、平台抽成入帳、發票已開。
• ⭐ 錢永遠在金流商託管,App 只記帳 + 下拆帳指令,絕不自己保管本金。

4.2 Gate(純函數,必測)

// lib/data/payout/payout_gates.dart  ＆  supabase/functions/_shared/payout/gates.ts(鏡像)

class SplitBreakdown {          // 金額一律用整數「元」,避免浮點
  final int gross;              // 消費者付的總額
  final int paymentCost;        // 金流手續費(給金流商)
  final int platformFee;        // 平台抽成(給你)
  final int payeeNet;           // 撥給場館/教練的淨額
  // 恆等式:gross == paymentCost + platformFee + payeeNet
}

enum SplitRuleType { registrationFee, coachTuition }

class SplitPolicy {             // 唯一真相源,別散落 View
  static const registrationPlatformPct = 0.05;   // 報名費平台抽 5%
  static const coachPlatformPct        = 0.20;   // 教練學費平台抽 20%
  static const coachHoldbackPct        = 0.15;   // 學費保留 15% 準備金到課程週期結束
  static const paymentCostPct          = 0.028;  // 信用卡,實際以藍新合約為準
}

SplitBreakdown computeSplit(int gross, SplitRuleType type);   // 冪等;餘數固定歸金流成本

bool canReleasePayout(SettlementEntry e, DateTime now);
//  報名費: 賽事已結束 && now >= eventEndedAt + settleDelay(T+N)
//  學費  : 該堂已「銷課完成」 || (月結日已到 && 已扣準備金)

int reserveHoldback(int payeeNet, double pct) => (payeeNet * pct).floor();

class RefundDecision { final bool allowed; final int refundable; final bool needsReversal; }
RefundDecision canRefund(SettlementEntry e, DateTime now);
//  held → 可全退;paid → 只能反轉平台抽成 or 走人工

4.3 Primitive(單一副作用)

insertSettlementEntry(...)                    // 建一筆代收帳
callGatewayCollect(orderId)                   // 藍新代收 → collected
callGatewaySplitPayout(entryId, breakdown)    // 下拆帳撥款指令
writeAssetTransactions(entryId, breakdown)    // 沿用既有複式分錄(清算戶↔應付戶↔銀行戶)
markPayoutPaid(entryId, txnRef)
issuePlatformFeeInvoice(entryId)              // 平台抽成 → ezpay-invoice
callGatewayRefund(entryId, amount)
recordHoldback(entryId, amount)               // 準備金掛帳

4.4 Orchestrator

// 選手繳報名費 → 代收 → held
collectRegistrationFeeOrchestrator(matchId, playerId, amount)
  = insertSettlementEntry → callGatewayCollect → status=held

// 賽事結束 → 撥款場館 + 平台抽成入帳 + 開發票
releaseVenuePayoutOrchestrator(matchId, now)
  = for each entry: if canReleasePayout(e, now)
      → computeSplit → callGatewaySplitPayout → writeAssetTransactions
      → issuePlatformFeeInvoice → markPayoutPaid
    → Result(paidCount, heldCount)

// 教練學費撥款(月結 / 銷課) → 扣抽成 + 保留準備金
coachPayoutOrchestrator(coachId, period, now)
  = for each tuition entry: if canReleasePayout
      → computeSplit → holdback = reserveHoldback(payeeNet, coachHoldbackPct)
      → callGatewaySplitPayout(payeeNet - holdback) → recordHoldback → invoice → paid

// 取消/退費
refundOrchestrator(entryId, now)
  = d = canRefund(e, now); if !d.allowed → Err
    → callGatewayRefund(d.refundable) → (d.needsReversal ? reverse split) → refunded

5抽成參數 + 教練學費 escrow

抽成比例集中在 SplitPolicy,並做成後台可調(不同賽別/教練可 override 但預設走 policy)。

6場館「報名費管理系統」

撥給場館的 payeeNet 進場館的收支帳本(這層不碰金流 API,純 CRUD + Gate):

VenueLedger(matchId)
  收入: 平台撥入的報名費淨額
  支出分類(場館自己登記,可核銷):
    ├─ 獎金 prize      ├─ 獎品 goods
    ├─ 裁判費 referee  ├─ 工作人員 staff
    └─ 直播 livestream └─ 其他 misc
  結餘 = 撥入 − 支出   (可匯出報表 / 對帳)

Gate: canEditLedger(role, matchStatus)  // 僅場館幹部可改;賽事結算後鎖定

7有限公司開立(背景 / 非工程)

主體選一人有限公司(不是行號):代收代付 + 抽成 + 未來擴張/募資都指向法人;行號無限責任、不能發股份、金流商談不到拆帳方案。

設立步驟(政府「公司一站式線上申請」)

1. 公司名稱預查(1~2 工作天,備 2~3 名)。
2. 開銀行籌備戶 + 存資本額(一人公司無下限,建議 10 萬以上;要貸款/補助抓 50~100 萬)。
3. 會計師資本額查核簽證 —— 不分金額,有限公司一律要(約 NT$3,000~8,000)。
4. 設立登記(同時給統編 + 稅籍)。
5. 刻公司大小章 → 辦發票字軌 / 電子發票 → 開正式帳戶 → 勞健保投保單位 → 申請工商憑證(報稅要用)。
6. 另辦:數位發展部「第三方支付洗錢防制能量登錄」。

營業項目

可同時掛 第三方支付 / 資訊軟體服務 / 運動場館・活動企劃 / 餐館業。餐廳只是掛項目不用額外執照;真的開店才要食品業登記等。公司一律要開發票。

沒營運也跑不掉的月成本(約)

8自己做帳 + 記帳工具

自己做帳法律上可行,務實走「混合制」:記帳 + 每 2 月營業稅 401 自己做,每年 5 月營所稅結算外包記帳士(單次 8k~20k,最難最容易罰的一關買專業背書)。第一年建議記帳士帶一輪把科目表立好。

記帳工具(可做,且與金流引擎同源)

asset_transactions 已是複式分錄帳本 → 只要在其上加「會計視圖」:

金流事件(payout 引擎 / 既有 asset_transactions)
  └─► 依固定規則 mapping 到會計科目
       ├─ 月損益表 / 資產負債表(草稿)
       ├─ 每 2 月「營業稅 401 試算表」(銷項/進項/應納)
       ├─ 代收款 vs 已撥款 vs 準備金 對帳表
       ├─ 平台抽成營收 & 已開發票勾稽
       └─ 一鍵匯出 CSV/Excel 給記帳士 / 貼進財政部系統

9落地順序 + builder checklist

1. P1 共用 payout 引擎:supabase/functions/_shared/payout(Gates + Orchestrators),寫入既有 asset_transactions。新增 asset 科目:平台抽成戶 / 場館應付戶 / 教練應付戶 / 準備金戶。
2. P1 Gate 單元測試:Dart 端 test/payout/ + TS 端鏡像,拆帳恆等式與 escrow 邊界全綠。
3. P2 Arena client 接單:報名費 collectRegistrationFeeOrchestrator / releaseVenuePayoutOrchestrator;教練 coachPayoutOrchestrator(卡銷課)。
4. P2 場館 VenueLedger:CRUD + canEditLedger Gate + 匯出。
5. P3 會計視圖 / 記帳工具:asset_transactions → 損益表 + 401 試算 + 對帳 + 匯出。
6. P3 後台抽成設定:SplitPolicy 可調 + 賽別/教練 override。

10待老闆拍板

• 抽成比例:報名費 5% / 教練學費 20% + 準備金 15% —— 沿用還是調整?
• 撥款週期:報名費賽後 T+7、學費月結 or 銷課後 —— 確認?
• 平台拆帳金流商:統一藍新 NewebPay(現有主線)還是引入綠界平台商方案?(建議統一藍新,減一套對接)
• 公司設立時間點:確定串金流前 1~2 個月;資本額抓多少?
• 記帳:混合制(自記 + 5 月外包)還是全外包第一年?