禮物分帳與結算規格

1名詞與鐵律

四條鐵律（違反即為 bug）

1. 金額與倍率物理隔離：gross 只由 unit_price × qty 產生。DB 的 CHECK 已寫死，程式想乘也乘不進去。
2. 三項加總必須等於流水：platform + tax + host = gross，一分不多一分不少（DB 約束）。
3. 費率下單即鎖定：每張單記 rule_version_id 與當時 platform_pct；日後改費率不回寫歷史。
4. 帳本只增不改：退款靠反向分錄沖銷，永不 UPDATE／DELETE 既有分錄。每筆業務分錄借貸合計 = 0。

2分帳算法

選 floor 而不是四捨五入的原因：① 主播實收永遠是整數且不為負；② 平台不會因為 0.5 鑽而抽走小禮物的全部價值（1 鑽禮物在 50% 費率下平台抽 0）。三項加總天然等於流水，對帳不會出現 1 鑽的鬼差。

費率政策（v1.2 · 與後台「💰 收益與抽佣」一致）

實算對照（單份 · 全局 50%）

最後兩欄就是你要的效果：血條衝得快，但主播後台看到的鑽石完全不變。9,999 鑽的大禮物一樣抽 50%，沒有「大額優惠」。

3資料模型

v1.3 新增 host_commission_rates（主播單獨費率，優先於全局）與 commission_rate_changes（變更紀錄，append-only）；為保持圖面可讀，未在圖中單獨畫出，關係見下表。

完整 DDL（含 trigger、view、種子）：hkplay-schema-gift-settlement.sql · 在瀏覽器開啟　|　第 14 節的 DDL：hkplay-schema-diamond-adjust.sql · 在瀏覽器開啟

每張表在管什麼

4落單與入帳時序

1. 取現行費率版本 + 主播費率：SELECT id, default_pct FROM commission_rule_versions WHERE effective_to IS NULL，再查 host_commission_rates(host_id)。有主播費率就用它，否則用全局 default_pct。整個請求只取一次，避免中途換版。
2. 校驗：禮物上架、庫存 ≥ qty、觀眾鑽石 ≥ 單價 × qty、單筆上限。任一失敗即中止，不產生任何記錄。
3. 同一交易內：扣觀眾鑽石 → 扣禮物庫存 → INSERT gift_orders（只傳單價、數量、版本、倍率分）→ fn_post_gift_order() 寫 4 條分錄。
4. DB trigger 算錢：gross = unit × qty、pct = COALESCE(host_rate, default_pct)、floor 抽佣、host = 餘數、算 available_at。應用層不參與任何金額計算。費率不因金額大小變動。
5. PK 計分：另寫 score_gain = round(gross × 每鑽分數 × 倍率) 與 score_multiplier，同一張單的 pk_match_id 指向場次。
6. 回傳：訂單號、主播實收、剩餘鑽石。App 顯示的「主播實收」直接取資料庫回傳值，不在前端算。
7. 冪等：客戶端帶 Idempotency-Key，落庫時對 (user_id, idem_key) 建唯一索引；重試回傳同一張單，不重複扣鑽、不重複入帳。

5費率版本化與生效

費率有兩層：全局（所有主播的默認）與主播單獨（按合約／等級）。兩者都不是「改舊值」，而是留痕跡：全局關舊開新版本，主播費率變更寫一筆 append-only 紀錄。

-- A. 改全局：關舊開新（此刻之前下的單仍指向舊版）
UPDATE commission_rule_versions SET effective_to = now() WHERE effective_to IS NULL;

INSERT INTO commission_rule_versions (version, default_pct, tax_pct, diamond_to_hkd,
                                      min_payout_diamond, settle_t_days, created_by, note)
VALUES (2, 50, 0, 0.100, 1000, 7, 'admin:1001', '2026-11 政策：統一 50%，大額不讓利');
-- 分層預設只有一個「無上限」層，即所有單價同費率
INSERT INTO commission_tiers (rule_version_id, seq, up_to_diamond, platform_pct)
VALUES (currval('commission_rule_versions_id_seq'), 1, NULL, 50);

-- B. 單獨設定某位主播（優先於全局）
INSERT INTO host_commission_rates (host_id, platform_pct, effective_from, created_by, note)
VALUES ('host_10086', 45, now(), 'admin:1001', '簽約主播合約價')
ON CONFLICT (host_id) DO UPDATE
  SET platform_pct = EXCLUDED.platform_pct,
      effective_from = EXCLUDED.effective_from,
      created_by = EXCLUDED.created_by,
      note = EXCLUDED.note;

-- C. 批量：勾選多個主播套同一費率（一個 batch_id 一次寫入）
SELECT fn_set_host_rates(
  ARRAY['host_10086','host_10087','host_10088'],  -- 主播
  50,                                             -- 平台抽佣 %
  'admin:1001',                                   -- 操作人
  '雙 11 前統一 50%'                               -- 備註
);

• 優先級：host_commission_rates → default_pct。主播有自訂就用自訂，冇就自動跟全局（改全局即時跟隨）。
• 批量與單獨同一條路徑：批量只是同一個交易內多寫幾行，共用 batch_id；失敗整批回滾，不會出現「改了一半」。
• 生效時間：新版本／新主播費率 effective_from = now()，立即對新單生效；已下的單永遠用舊費率（gift_orders.platform_pct 已鎖）。
• 追溯：不允許。要補償請用 adjust 分錄，保留審計軌跡。
• 變更紀錄：commission_rate_changes 只增不改（見第 14 節同款 trigger），批量操作記一條、列出全部主播與新舊值，方便日後對帳。
• 稅費：稅率是版本參數，跟抽佣一起版本化，避免「抽佣改了稅沒改」的半套狀態。
• App 顯示：前端只在「送禮前」讀 /api/rates/current?host_id= 做試算顯示，實際金額以落庫回傳為準。

6凍結期、可提現、提現

匯率是版本參數 diamond_to_hkd，但提現單會再存一份 hkd_rate 快照 —— 日後調匯率不影響已提交的單。

7退款、沖銷與負餘額

1. 退款不改原單金額，只把 status 改 refunded，並寫一組反向分錄（ref_type='refund'）。
2. 若主播已把這筆錢提走，主播帳面會變負 —— 允許負餘額，由下次收益自動抵扣；負餘額期間不可提現。
3. PK 賽果不因退款改寫：score_gain 是已發生的比賽事實，退款只影響錢，不影響輸贏與榜單（除非你有「作弊刷分」判定，那走人工撤榜流程）。
4. 退款窗口建議：T+7 內可退（未過凍結期），逾時只接受爭議單。這條要寫進用戶協議。

8PK 與收益的隔離（架構層保證）

9對帳：四層 + 差異處理

差異處理 SOP

1. 凍結影響面：L2/L3 有差異時，先把涉及的 host_id 標記 payout_hold=true，避免帶錯帳出去。
2. 定位：用 ref_type + ref_id 回查該業務的 4 條分錄；再看是否為重複入帳（UNIQUE 已擋）、漏入帳（交易 rollback？）或人工改數。
3. 修正：只准補 adjust 分錄（正負成對），不准 UPDATE／DELETE 原分錄；原單金額永不改。
4. 結案：recon_diffs.status='resolved' + 備註 + 操作人；同時解除 payout_hold。
5. 月結：本月所有 settlement_batches 必須 reconciled，且 sum(diff_diamond) = 0，財務才可出報表。

每日對帳 SQL（可直接排程）

-- L2：訂單 vs 帳本
INSERT INTO recon_diffs (biz_date, kind, ref, expected, actual)
SELECT current_date, 'order_vs_ledger', order_no::text, host_diamond, ledger_host
  FROM v_recon_order_vs_ledger
 WHERE diff_host <> 0 OR diff_platform <> 0
ON CONFLICT DO NOTHING;

-- L3：餘額 vs 帳本
INSERT INTO recon_diffs (biz_date, kind, ref, expected, actual)
SELECT current_date, 'balance_vs_ledger', host_id::text, ledger_total, book_total
  FROM v_recon_balance
 WHERE diff <> 0
ON CONFLICT DO NOTHING;

-- 日結批次
INSERT INTO settlement_batches (biz_date, orders_count, gross_diamond, platform_diamond, tax_diamond, host_diamond, status)
SELECT created_at::date, count(*), sum(gross_diamond), sum(platform_diamond), sum(tax_diamond), sum(host_diamond), 'closed'
  FROM gift_orders WHERE status = 'settled' AND created_at::date = current_date - 1
 GROUP BY 1
ON CONFLICT (biz_date) DO NOTHING;

10要盯的指標

11驗收用例

12上線順序

1. 建表：執行 hkplay-schema-gift-settlement.sql（純新增，不動現有表）。
2. 雙寫觀察：App 送禮時同時寫 gift_orders，但收益仍用舊邏輯；跑 3 天，確認 L2 差異為 0。
3. 切換真源：主播後台、結算報表改讀 gift_orders / 帳本；舊欄位轉為唯讀。
4. 開提現：先內部帳號小額測試（含駁回、負餘額、凍結退回）。
5. 灰度費率：後台改費率走「開新版本」，觀察 24 小時的實際抽佣率是否等於設定值。
6. 月結演練：完整跑一次 L1–L4 + 月結報表，再對外公佈。

13待你拍板

14會員鑽石派發與審批

第 1–13 節講的是「錢怎麼從觀眾流到主播」。這一節講另一個入口：平台自己發鑽石給會員（測試額度、活動補償、客訴補償、對帳調整）。這條路同樣會產生負債，而且比禮物更容易被內部人濫用，所以它必須是雙人复核的，不能是「後台按一下就直接改餘額」。

14.1 角色與職責

「不可審批自己的」是資料庫層的約束（fn_adj_approve 直接比對 requested_by），不是前端隱藏按鈕。

14.2 資料模型

14.3 狀態機

14.4 分級授權矩陣

14.5 提交與審批時序

1. 填單：選會員（member_id）、方向、數量、原因代碼、備註。前端同時產生一個 Idempotency-Key（UUID），連按兩次不會變成兩筆。
2. 建立 pending：fn_adj_request() 依金額算出 required_approvals 與 need_finance，寫入申請單與第一筆 request 動作。
3. 通知：推播／IM 給有審批權的人；同一張單不可由申請人自己出現在待審清單。
4. 審批：fn_adj_approve() 檢查：不是自己的單、角色足夠、沒重複批同一張。每批一次寫一筆 approve 動作。
5. 達標即入帳：人數夠 → approved → trigger 檢查餘額（扣減不可為負）→ 寫 member_diamond_ledger → 更新餘額 → 標記 applied。
6. 對帳：v_diamond_balance_check 必須 0 行；每日把 Σ adjustment 與錢包端的變動比對。

14.6 六條防線

14.7 對帳與報表

-- 每日對帳：發出去的鑽石 vs 錢包實際增加
SELECT b.member_id,
       b.balance                        AS wallet_balance,
       COALESCE(l.sum_delta, 0)         AS ledger_sum,
       b.balance - COALESCE(l.sum_delta, 0) AS diff
  FROM member_diamond_balances b
  LEFT JOIN (SELECT member_id, sum(delta) sum_delta
               FROM member_diamond_ledger GROUP BY member_id) l USING (member_id)
 WHERE b.balance <> COALESCE(l.sum_delta, 0);     -- 必須 0 行

14.8 與禮物、等級、PK 的邊界

14.9 驗收用例（新增）

14.10 上線順序

1. 建表：執行 hkplay-schema-diamond-adjust.sql（含政策與 4 個示範員工）。
2. 只開「派發」：先讓客服能用小額補償（≤ 1 萬、1 人批），觀察兩週。
3. 開「扣減」：雙簽生效；同時把「直接改餘額」的權限從所有人身上收回。
4. 接錢包：App 錢包改讀 member_diamond_balances；localStorage 只留作離線快取。
5. 月結：把 v_diamond_liability 與 v_diamond_balance_check 納入月結報告，差異必須 0。

15提現與出款（中國銀行批量付款）

第 6 節講的是「主播什麼時候可以提」，這一節講「錢怎麼真的離開公司」。四個角色共用同一條線：主播（鑽石收益）、商戶（貨款）、騎手（配送費）、司機（車費）。全部由平台以中國銀行（香港）公司帳戶統一發放，財務經手、雙人复核。

15.1 狀態機

paid 與 failed 都由「批次」驅動：一個批次 = 一個銀行檔案 = 一次上載。批次內單筆失敗只影響該筆，其餘照常入帳。

15.2 角色矩陣

15.3 金額、費用與凍結

15.4 中銀批量付款檔案（預設欄位）

中銀不同分行、不同網銀版本的範本欄位次序會有差異，所以後台把欄位做成可勾選、可調次序，匯出的 Excel 首行即表頭，直接對應「批量付款上載」。欄位設定存 localStorage，正式版存 bank_file_templates。

15.5 出款時序

1. T0 申請：App 或客服提交 → 檢查最低提現、可提餘額、實名認證 → 建單並凍結金額。
2. T0 審核：主管／財務核准或駁回；駁回即時解凍。
3. T1 建批次：財務勾選已核准的單 → 一個批次 = 一個檔案，總額必須等於該批 Σ hkd_net。
4. T1 匯出：下載 .xlsx（或 CSV）→ 上載中銀企業網銀 → 銀行覆核。
5. T2 回單：銀行成功後回寫流水號，批次標記 paid；退票的單標 failed 並解凍。
6. T3 對帳：銀行月結單 Σ 必須等於 Σ payouts(hkd_net where status='paid')，差額建工單。

15.6 銀行退回與重出

15.7 對帳視圖

-- 批次 vs 明細：總額必須相等，筆數必須相等
SELECT b.batch_no,
       b.total_hkd,
       sum(p.hkd_net)              AS sum_detail,
       count(*)                    AS n_detail,
       b.total_hkd - sum(p.hkd_net) AS diff       -- 必須 0
  FROM payout_batches b
  JOIN payouts p ON p.batch_id = b.id
 GROUP BY b.id, b.batch_no, b.total_hkd;

-- 已出款 vs 銀行回單（回單先入 staging 表）
SELECT p.payout_no, p.hkd_net, s.amount, p.hkd_net - s.amount AS diff
  FROM payouts p
  LEFT JOIN bank_statements s ON s.ref = p.bank_ref
 WHERE p.status = 'paid' AND (s.amount IS NULL OR s.amount <> p.hkd_net);

15.8 驗收用例（新增）

15.9 上線順序

1. 建表：執行 hkplay-schema-gift-settlement.sql 的 8–9 節（payouts / payout_batches / payee_bank_accounts）。
2. 先開放主播：小額（≤ 5,000 鑽）人工審核，財務手動出款，驗證中銀檔案能被網銀接受。
3. 再開商戶／騎手／司機：接上各自的結算週期（商戶 4–8 日、騎手週結、司機日結）。
4. 自動化：銀行回單以 CSV 導入 staging，自動匹配 bank_ref，差額建工單。
5. 權限收口：出款權限只留財務，操作日誌保留 7 年（條款 3.6 帳目可查）。