13 · 记录与账变系统

0. 文档说明

项	内容
版本	V1.0

账本底座。资金事实的唯一来源是 02 的 wallet_ledger(操作枚举 → 02 §2.4);本系统负责组织、查询、对账、归档,自身不产生资金写操作。本站账本恒记本位币(单币种站,→ 02);展示铁律:四类记录逐笔带「出生币种」,不重标、不换算(边界充提为通道币种入账前的原值+锁价快照,入库后为本位币)。

---

一、定位与职责

• 面向用户的四类记录:交易记录(充值/提现)、游戏报表(注单)、领取记录(类型含 优惠/任务/VIP俸禄/实时返水/推广佣金)、账变明细;
• 面向运营的:流水查询/导出(权限控)、日切对账(账实相符)、差异工单;
• 数据生命周期:热/冷分层与归档。

边界:各单据(充值单/提现单/注单/领取)归属各源系统;本系统建只读组织层(物化 + 视图 + 索引),不改写源数据。

---

二、核心概念与数据模型

2.1 四类用户记录(数据源映射)

记录	数据源	说明
交易记录	03 deposit_orders + 04 withdraw_orders	合并时间线,状态文案取各自状态机;每单带通道币种原值 + 锁价快照 + 本位币入账值(→ 03/04),不重标
投注记录	12 bets	按游戏/厂商/时间/输赢筛选;金额为本位币(CNY 映射场馆厂商回传标「CNY」的注单,已由通道适配层 1:1 重标为本位币入库,→ 12)
领取记录	claim_records(本系统物化)	订阅 RewardClaimed 落地,见 §2.2;金额为本位币
账变明细	02 wallet_ledger 直读	每笔带三桶余额快照(本位币),按操作码分类展示

逐笔带币种(展示铁律):四类记录的每一行都带「出生币种」——站内自产的动作(投注/领取/账变/俸禄…)出生即本位币;边界充提逐单额外保留「通道币种原值 + 锁价 lockedRate」用于溯源。任何一行都不做「数字不变只换符号」的二次渲染。

2.2 领取记录 ClaimRecord(物化)

订阅 RewardClaimed 写入(消费幂等键=claimId):

字段	说明
claimId / tenantId / userId	唯一领取
source	PROMO(优惠)/ TASK(任务)/ VIP_SALARY(VIP俸禄)/ RAKEBACK(实时返水)/ AFFILIATE(佣金)
currency / amount / rewardTarget	币种、金额、入账目标(可用/彩金)
refName	展示名(活动名/任务名/「V18 日俸禄」…,文案键)
claimedAt	时间

2.3 日切对账 ReconciliationRun

每日(租户时区)按 tenant(单币种站,币种恒 = 本位币;平台跨站层面仍按币种分列,→ 17):

① 账实核对:Σ(wallet_ledger 当日净变动) ≟ Σ(账户余额日终 − 日初)          [本位币]
② 单据核对:DEPOSIT_CREDIT ↔ deposit_orders(SUCCESS);WITHDRAW_* ↔ withdraw_orders;BET/PAYOUT ↔ bets
③ 外部核对(按路由 route 分档,→ 12):
     · 充/提通道:通道对账单为**通道币种**口径 ↔ 订单(比对通道币种原值,再验锁价折算后的本位币入账值)
     · 厂商注单:厂商账单为**申报币种**口径 ↔ 平台本位币账,按 route 对账 —
         - route=原生:厂商账单为本位币原值原符号,直对本位币账;
         - route=CNY 映射:厂商账单标「CNY」= 本位币数值 **1:1**,直对(无小数、无换算,进出等值可逆);差异即缺账
差异 → 对账差异工单(15),人工处置(补单/冲正均走既有幂等通道)

路由维度:CNY 映射场馆下,厂商侧以「CNY」计价申报(数值 = 本位币值,1:1),平台账本始终记本位币真实值。对账 ③ 对这类场馆按 1:1 直对,返水/打码/报表零特判(通道适配层已在入库时重标)。原生场馆按本位币原值直对。对账粒度记录 route,仅用于中性分档核销与审计溯源,不产出任何商业测算;route 属平台超管口径(→ 12 §三),对账明细中的 route/declared* 不下发商户报表。

---

三、业务规则

1. 只读:本系统任何接口不产生资金变化;修复动作回源系统走幂等通道;
2. 一致性:claim_records 与 wallet_ledger 中 REWARD_CREDIT/BONUS_GRANT 一一对应(对账 ② 覆盖);
3. 单币种记账:本站账本恒为本位币;充提逐单保留通道币种原值 + 锁价,注单入库前若为「CNY 映射」申报口径由通道适配层 1:1 重标本位币(→ 12),本系统不做任何二次换算,只组织与核对;
4. 路由分档对账:③ 外部核对按 route(原生 / CNY 映射)分档,CNY 映射 1:1 直对(→ §2.3);对账粒度记 route,仅供中性分档核销与审计溯源(route 属平台超管口径,商户报表不下发);
5. 用户可见窗口:用户端默认可查近 N 天(配置),更早数据提示联系客服(后台可查全量);
6. 导出合规:明细导出仅后台、按角色(15),用户侧不提供批量导出;
7. 归档:热数据(90 天)在线表;冷数据归档存储,查询透明路由(后台全量、用户窗口内不受影响)。

---

四、★ 租户可配置项(records 命名空间)

"records": {
  "visibleTabs": ["transaction", "bet", "claim", "ledger"],   // 用户侧开放哪几类
  "userWindowDays": 90,
  "claimFilters": {
    "types": ["ALL", "PROMO", "TASK", "VIP_SALARY", "RAKEBACK", "AFFILIATE"],   // 五源全含(与 §十「五源各一笔逐一命中」验收自洽);AFFILIATE 领取入口在赚钱板块,记录统一进领取记录页
    "times": ["TODAY", "YESTERDAY", "LAST_7D"]
  },
  "recon": {
    "routeAware": true,          // 日切对账 ③ 按场馆链路 route 分档(原生/CNY 映射);CNY 映射 1:1 直对(→ §2.3)
    "channelCurrencyCheck": true // 充提外部核对比对通道币种原值,再验锁价折算后的本位币入账值
  },
  "export": false
}

金额一律本位币单口径(单币种站);对账 route 档位取自 12 场馆配置,本处仅开关是否分档核销。

---

五、与其他系统的关系 / 接口

接口	调用方	说明
listTransactions / listBets / listClaims / listLedger (userId, filter, page)	展示层	四类记录分页查询(筛选见展示契约)
recon(tenant, date)	调度 / 15	日切对账(币种恒 = 本站本位币);按 route 分档外部核对(→ §2.3),产差异工单
queryLedger(admin filter) / export	15 后台	运营查询/导出(权限控)
消费 RewardClaimed	← 07/08/09/10/11	物化 claim_records(幂等)

---

六、运营后台能力(→ 15)

侧	能力
平台控制台	跨租户对账总览、差异工单督办、按 route 分档核销明细(平台超管;含 route/declared* 口径)
商户控制台	四类记录全量查询(用户维度/单号直查)、对账报告(本位币口径,不含 route/declared*)、导出(角色+审计)、客诉对单工作台(输入单号一键串联 订单↔账变↔事件;注单侧仅呈本位币入账值,隐藏 route/declared*)

---

七、展示契约(→ 原型映射)

UI 元素	数据	原型载体	系统契约
领取记录 tab	listClaims	奖励中心「领取记录」:双下拉筛选 类型(全部/优惠/任务/VIP俸禄/实时返水/推广佣金)× 时间(今日/昨日/近7日);无汇总盒	筛选枚举来自 records.claimFilters 配置(五源全含);列表项=refName+金额(本位币符号)+时间;五源(含 AFFILIATE)统一入本页,佣金领取动作虽在赚钱板块触发,记录仍落 claim_records 并在此可筛(→ §十)
交易记录	listTransactions	我的 → 交易记录	状态文案对 03/04 状态机;充值/提现子筛选;每单展示本位币入账值为主,通道币种原值 + 锁价作明细溯源(不重标)
游戏报表(投注记录)	listBets 聚合 + 明细	我的 → 游戏报表 #sub-bets(两页)	单币种口径(本位币):两页全程本位币符号,无币种切换。L1 报表:时间页签(今天默认/昨天/近七天)+ 下注/中奖总额条 + 「厂商×类型」场馆卡(有数据才显示;下单注数/下单金额/中奖金额);L2 我的注单:点卡进入,场馆范围总额条 + 订单卡(下单/中奖金额对、下注时间/内容/状态/单号复制);厂商=纯品牌(PG/AG…),类型独立;中奖金额=派彩口径(赢=本金+净赢/退款=本金/未中=0/待结算不计)。CNY 映射场馆注单入库前已 1:1 重标本位币,报表零特判(→ 12)
账变明细	listLedger	(钱包页流水区)	操作码→中文文案映射表(充值入账/投注/派彩/领取/提现锁定…);金额恒本位币单口径,逐笔带币种、不「换符号重刷」(展示铁律,→ 02)

---

八、数据库设计(全表含 tenant_id;金额 DECIMAL(32,8))

表	关键字段	约束/索引
claim_records	claim_id PK, tenant_id, user_id, source, currency(= 本站本位币), amount, reward_target, ref_name, claimed_at	UK(tenant_id,claim_id);IDX(tenant_id,user_id,source,claimed_at)
reconciliation_runs	id PK, tenant_id, currency(= 本位币,冗余列便于跨站聚合), stat_date, checks JSON(①账实/②单据/③外部,③按 route 分档:原生/CNY 映射), status(BALANCED/DIFF), created_at	UK(tenant_id,stat_date)
recon_diffs	id PK, tenant_id, run_id, kind, route(native/cnyMapped,仅外部厂商核对档填), channel_currency(充提外部核对档填,通道币种原值溯源), ref, expect, actual, ticket_id, state	IDX(run_id);IDX(tenant_id,route)
(归档) *_archive	与源表同构	按月分区(→ 分区/幂等约束见下)

查询加速:wallet_ledger/bets 上的组合索引归源系统建;本系统维护跨表查询视图。

• 对账 route/declared* 属平台超管口径:reconciliation_runs.checks 与 recon_diffs.route 仅供平台侧中性分档核销与审计,不进商户报表(→ 12 §三、§2.3)。

8.1 高频表分区与归档后幂等唯一键(落地约束)

bets(→ 12)、wallet_ledger(→ 02)是高流水表,分区与冷热分层在本系统统一收口;需处理分区键与业务幂等唯一键的正面冲突:

• 冲突点:多数数据库(MySQL/InnoDB)要求「分区键必须包含在每个唯一键内」。若按 created_at(月)分区,而现有幂等唯一键是 bets UK(tenant_id,vendor_code,ext_bet_no)、wallet_ledger UK(tenant_id,op_code,biz_key)——均不含 created_at,直接按时间分区会与这些 UK 冲突,导致 UK 建不出或被迫把 created_at 塞进 UK(破坏业务幂等语义)。
• 落地口径:幂等唯一去重不依赖分表内 UK,由独立幂等表兜底——业务幂等键(biz_key / vendor_code+ext_bet_no)在全局幂等表(不分区、(tenant_id, scope, biz_key) 全局唯一,→ 00 §4.4)登记去重;bets/wallet_ledger 分表内保留 (tenant_id, …) 业务索引供查询,但唯一去重职责上移到幂等表,从而分区键可自由取「tenant_id hash + created_at 月」子分区而不与唯一键打架。
• 归档后跨热/冷去重:热表(90 天)→ *_archive 归档后,同一 biz_key 的迟到回调重放仍查全局幂等表判重(幂等表长期在线、不随业务表归档),保证冷热两侧不重复入账;归档只搬明细行,不搬幂等判重职责。
• 推荐分区维度:bets/wallet_ledger = tenant_id hash 一级 + created_at 月二级;claim_records/reconciliation_runs 数据量小,按 tenant_id+月即可;归档表 *_archive 与热表同构、按月范围分区便于整月搬迁与清退。

---

九、扩展点与开放问题

• 实时对账:日切之外的准实时核对(每小时滚动),在高流水租户开启,基建量力;
• 区块链核对:加密充提与链上事实(txHash)的自动核对纳入对账 ③,依赖节点服务;
• 筛选扩展:领取记录时间档(近30日/自定义区间)按运营诉求加,枚举在配置;
• 审计导出格式:监管报送格式(区域差异)归 compliance。

---

十、验收要点

• [ ] 任何一笔余额变化都能在账变明细查到,且前后快照连续(无跳变);四类记录金额全程本位币单口径、逐笔带币种,页面无「数字不变只换符号」的重刷;
• [ ] 领取记录 = RewardClaimed 全集:五源(优惠/任务/俸禄/返水/佣金)各领取一笔后,筛选组合逐一命中;
• [ ] 双下拉筛选(类型×时间)组合结果正确,枚举随配置变化;无汇总盒;
• [ ] 游戏报表两页全程本位币、无币种切换;CNY 映射场馆注单已 1:1 重标本位币,报表/返水/打码无特判;
• [ ] 日切对账:正常日 BALANCED;人为制造缺账变(测试环境)→ DIFF + 工单;③ 外部核对按 route 分档,CNY 映射场馆按 1:1 直对、原生按本位币原值直对,充提比对通道币种原值 + 锁价折算值;
• [ ] 用户窗口外数据不可见,后台可见全量;导出动作留审计;
• [ ] 归档后单号直查(客诉)仍可命中。