Appearance
12 · 游戏聚合系统
0. 文档说明
| 项 | 内容 |
|---|---|
| 版本 | V1.0 |
流水之源。注单结算事件驱动 06 成长值 / 08 返水 / 10 打码 / 17 报表;资金动作走 02 的
BET_DEBIT / PAYOUT_CREDIT。站内单币种(本位币),场馆向厂商申报币种由场馆链路 route 决定(§三)。
一、定位与职责
- 定义厂商(vendor)适配层:接入、回调归一化、维护位;
- 定义游戏目录(游戏类型/标签/封面/支持币种)与租户级策展(开关/排序/热门);
- 定义钱包对接模式(Seamless 单一钱包优先);
- 定义场馆链路 route(原生 / CNY 映射)——站内本位币与厂商申报币种的标签映射机制(平台超管级场馆申报口径开关,商户不可见不可改,→ §三);
- 定义游戏会话、注单模型与
BetSettled / BetCancelled事件; - 定义大厅(连续滚动/热门二级 tab/收藏/最近/搜索)与全屏游戏的展示契约。
边界:返水/打码/成长值计算归 08/10/06(本系统只供事实,恒本位币口径);余额记账归 02;站内单币种模型归 02。
二、核心概念与数据模型
2.1 厂商 Vendor(平台目录)与游戏 Game
| Vendor 字段 | 说明 |
|---|---|
vendorCode / name / logo | 厂商标识(logo 即大厅品牌墙资源) |
apiLines | 按申报币种的接入线路:{ "CNY": {…}, "USDT": {…} },进场按场馆 route 选线(§三) |
walletMode | seamless(默认)/ transfer(兼容) |
status | 可用 / 维护中(→ 00 §4.10 降级) |
| Game 字段 | 说明 |
|---|---|
gameId / vendorCode / name | 游戏标识(name 入搜索索引) |
gameType | 游戏类型目录:original(BCG 原创链游)/ slots 电子 / card 棋牌 / live 真人视讯 / lottery 彩票(正常游戏品类,与 09 剔除的「直营彩票活动」无关)/ fish 捕鱼 / sport 体育 / esport 电竞;hot 热门为聚合视图,非类型 |
cover / tags | 封面(原型 data-cov)、标签(hot/new) |
supportedCurrencies | 该游戏/厂商线路支持的申报币种(继承厂商线路能力,决定可走哪些 route) |
2.2 场馆接入档案 VenueProfile(站级)
一个「场馆」= 站内对某厂商(或厂商内某品类)的接入实例。场馆维度的常规配置(启用/排序/维护位)属商户可控;route 申报口径由平台超管专属控制(→ §三 权限定性):
| 字段 | 说明 |
|---|---|
venueId / vendorCode | 场馆标识、所属厂商 |
supportedCurrencies[] | 该场馆可向厂商申报的币种集(⊆ 厂商线路能力) |
route | 场馆链路:native(原生)/ cnyMapped(CNY 映射,1:1),见 §3.1;平台超管专属字段,商户不可见不可改 |
status | 可用 / 维护中 |
2.3 钱包对接模式
| 模式 | 机制 | 说明 |
|---|---|---|
| Seamless(首选) | 厂商每笔下注/派彩实时回调平台记账(BET_DEBIT/PAYOUT_CREDIT) | 单一钱包、余额始终在平台(本位币),体验最优 |
| Transfer(兼容) | 进游戏先转入厂商额度、退出转回 | 为转账制厂商保留;配套「额度转换 / 余额找回」能力(§3.7) |
2.4 游戏会话 GameSession
● ─进入游戏(登录校验 + 按场馆 route 选申报线路)─► ACTIVE(会话中)
─退出/超时─► CLOSED / EXPIREDlaunch(gameId) → 校验(游客弹登录,05 门禁)→ 按场馆 route 决定申报币种与符号(原生=本位币原值原符号;CNY 映射=数值 1:1、符号换 ¥)→ 生成会话 token → 厂商 launch URL(全屏)。
2.5 注单 Bet(归一化)与事件
| 字段 | 说明 |
|---|---|
betId(平台归一 ID)/ extBetNo(厂商原始单号)/ sessionId | 唯一注单:betId 为平台侧归一主键,extBetNo 留厂商原始单号,防重放唯一键 = (tenantId,vendorCode,extBetNo)(→ §八) |
gameId / gameType / vendorCode / venueId | 维度 |
currency | 入库币种 = 本位币(厂商回传若标 CNY(映射场馆)由通道适配层 1:1 重标为本位币,§3.3) |
declaredCurrency / declaredAmount | 场馆计价快照:厂商侧申报的币种与数值(审计留痕;原生=本位币;映射=CNY 数值,1:1) |
stake / payout / winLoss | 本金 / 派彩 / 输赢(本位币) |
validTurnover | 有效投注(结算注单本金;取消/无效注单为 0;平局/退款注单按厂商语义置 0) |
status | PLACED → SETTLED / CANCELLED |
事件:BetSettled(00 已登记,幂等键 betId)与 BetCancelled(→ 00 §4.6,幂等键 betId+cancelSeq)——结算后取消时发出,08/10 冲正、17 修正;同一注单可多次部分/全额取消,cancelSeq 逐次递增以保证幂等与冲正不漏记(与 00/08 一致,10 对齐)。事件载荷金额恒本位币;返水/打码/报表零特判(映射场馆已在适配层重标)。
三、场馆链路 route(原生 / CNY 映射)
这是标签映射,不是换算。站内账本始终记本位币真实值;route 只决定「向厂商申报时用什么币种符号计价」。 权限定性:
route是仅平台超管(包网超管)可见并控制的场馆申报口径开关,默认native,可随时关闭;其他任何角色 / 界面 / 报表(含商户控制台、数据看板)都看不到、也不可改。平台侧只保留中性对账机制(适配层 1:1 重标本位币、对账按 route 分档),不做任何商业化引导。用户端行为不变(某场馆被超管设cnyMapped时,场馆内 ¥ 计价 1:1 + 进场提示照旧)。
3.1 两种链路
| route | 申报口径 | 用户唯一感知 | 适用站型 |
|---|---|---|---|
native(原生,默认) | 向厂商申报本位币原值、原符号 | 场馆内即本位币符号 | 全部站型 |
cnyMapped(CNY 映射) | 数值 1:1 不变,仅把申报符号换成 CNY(¥) | 场馆内计价符号是 ¥(= 本位币等值,1:1) | 仅本位币币值 ≥ CNY 的站型(即 USDT 站) |
3.2 CNY 映射的申报口径机理(1:1 无小数、进出等值可逆)
- 机理:CNY 映射把本位币数值当作同数值的 CNY 向厂商申报——申报数值不变(如 100),只换符号为 CNY;这是符号标签的改写,不是币值换算。站内账本全程记本位币真实值,
declared*保留申报口径快照。 - 1:1 恒等、无小数、进出等值可逆:映射不引入任何小数换算,进场额度与出场额度按 CNY 数值 1:1 与本位币等值互换,可逆无损。
- 仅高币值站可用:
cnyMapped只对「本位币币值 ≥ CNY」的站型(USDT 站)开放;低币值站(VND/IDR/PHP 等)不提供该开关(1:1 会放大申报口径基数,无意义)。 - 中性对账机制:平台侧对映射场馆按 route 分档 1:1 直对(→ 13 §2.3);route 仅为平台超管对账口径,中性分档,不产出任何商业测算——该口径开关的定性与可见范围以 §三「权限定性」为准。
3.3 通道适配层重标规则(厂商回传 → 本位币入库)
CNY 映射场馆的厂商回传注单标着 CNY,由通道适配层在归一化时 1:1 重标为本位币入库:
declaredCurrency = CNY、declaredAmount = 厂商数值(快照留痕);currency = 本位币、stake/payout/winLoss/validTurnover = 厂商数值(数值 1:1 不变,币种标签取本位币);- 之后
BET_DEBIT/PAYOUT_CREDIT、返水(08)、打码(10)、报表(17)全部按本位币,零特判; - 原生场馆:
declaredCurrency = 本位币,重标为恒等,无差异。
3.4 进场提示与额度转换标注(必须)
- 进场提示:进入
cnyMapped场馆前弹提示——「本场馆内计价符号为 ¥,= <本位币> 等值,1:1,进出等值可逆」。 - 额度转换页标注(transfer 制映射场馆):额度转换页须标注「¥ 计价 = <本位币>,1:1,进出等值」。
- 用户唯一感知即「该场馆内计价符号是 ¥」;站内其余界面仍恒本位币符号(→ 02 §七展示铁律)。
3.5 口径归属(平台超管专属 + 账本恒真实)
route是平台超管级场馆申报口径开关(默认native),仅平台超管可见可改;与厂商协议约定的币种口径是否采用 CNY 映射,由平台超管在平台控制台按场馆逐一决定并承担,不下放给商户、商户界面 / 报表不可见;- 平台自身账本 / 对账 / 审计全程真实(本位币实录 +
declared*快照),不因映射失真; - 对账仅保留中性的 route 分档核销(→ 13 §2.3;route 口径定性见 §3.2)。
3.6 场馆链路开关(配置项)见 §四;场馆表字段见 §八。
3.7 场馆钱包管理(额度转换 / 余额找回,单币种口径)
- 额度转换(我的 → 额度转换
#sub-transfer):From/To 兑换式(中心钱包 ⇄ 场馆额度,swap 键调向)+ 场馆筛选选择器(搜索 + 分类,全目录)+ 自定义金额/快捷比例 + 校验链(维护场馆拦、单笔最低、超额、按本位币精度);「自动额度转换」开关(开=进场自动携带余额;关=手动转入,资金不整存三方;接 transfer 会话,接入期);注意:平台无法预知场馆「卡分」,不做任何卡分预判标记/预拦截。中心钱包侧恒本位币;映射场馆内标 ¥(1:1,§3.4)。 - 余额找回(一键,无二级界面):扫描全部场馆 → 正常余额即时回收入中心钱包(本位币);直收失败(接口异常)自动转平台代位下分工单(RQ 单号 → 站内信「已受理」→ 回执入账 → 站内信「成功」);工单带
route与场馆计价快照(declared*),映射场馆按 1:1 重标回本位币入账;场馆已知态仅 维护中 / 代位下分中。 - 原创游戏同样走三方方式接入——不存在「原创直连中心钱包/免转」的特例表述。
3.8 通用业务规则
- 回调幂等:厂商回调防重放的唯一约束落在
vendor_callback_log的 UK(tenant_id,vendor_code,ext_ref,action)——同一注单的下注/结算/取消因action维度不撞键;下注回调先校验余额(02 §3.6,不足即拒);映射场馆回传先经适配层 route 重标本位币(§3.3)再记账; - 申报线路选择:进游戏按场馆 route 选申报线路与符号(原生=本位币线;CNY 映射=按 CNY 数值申报,§3.1);站内单账户,无会话内钱包切换概念;
- 取消冲正:
CANCELLED注单反向记账(退还本金/收回派彩,本位币),validTurnover置 0,发BetCancelled; - 维护降级:厂商/场馆维护位只影响该场馆游戏(封面盖「维护中」),不影响平台其他功能;
- 收藏/最近:登录用户服务端存储(跨端);游客本地存储;「最近」窗口 7 天;
- 搜索:按游戏名索引(原型
GNAMES),范围=该租户已上架游戏。
四、★ 租户可配置项(games 命名空间)
jsonc
"games": {
"vendors": [ { "code": "pg", "enabled": true }, { "code": "jili", "enabled": true } /* … */ ],
"categories": [ "original", "slots", "card", "live", "lottery", "fish", "sport", "esport" ], // 顺序即大厅 tab 序;hot 恒为首个聚合 tab
"hotList": { "mode": "manual", "gameIds": [ /* 策展 */ ] }, // manual | auto(按流水)
"recentWindowDays": 7,
"fullscreen": { "floatButtons": ["exit", "wallet", "transfer", "service"] }, // transfer 仅 transfer 模式厂商生效
// ↓ 场馆链路 route(→ §三;默认 native)。**平台超管级配置项:仅平台超管(包网超管)可见可改,
// 商户控制台不可见不可配**;cnyMapped 仅 USDT 站可用。此块随 games 命名空间下发引擎,
// 但对商户侧一切读接口 / 后台视图 / 报表脱敏隐藏(→ §三 权限定性、§六)
"venues": [
{ "venueId": "pg", "vendorCode": "pg", "route": "native", "supportedCurrencies": ["USDT"] },
{ "venueId": "ag", "vendorCode": "ag", "route": "cnyMapped", "supportedCurrencies": ["CNY","USDT"] },
// ↑ USDT 站示例:AG 真人由平台超管设为 CNY 映射(1:1 申报);账本恒记 USDT 真实值
{ "venueId": "jili", "vendorCode": "jili", "route": "native", "supportedCurrencies": ["USDT"] }
]
}Schema 校验:vendors.code ⊆ 平台目录;categories ⊆ 类型目录;hotList.gameIds ⊆ 已启用厂商的游戏;venues[].route ∈ {native, cnyMapped};route=cnyMapped 仅当 wallet.baseCurrency 币值 ≥ CNY(即 USDT 站) 时合法,否则发布拦截(→ 02 站型);venues[].supportedCurrencies ⊆ 厂商线路能力。venues[].route 的读写权限限平台超管:配置合并链对商户侧读接口与后台渲染统一隐藏该字段(值不下发商户视图),商户提交的配置若含 venues[].route 变更一律被发布校验拒绝(越权)。
五、与其他系统的关系 / 接口
| 接口 | 调用方 | 幂等键 | 说明 |
|---|---|---|---|
getLobby(userId?) | 展示层 | — | 分类游戏列表(分页)+ 热门(推荐/收藏/最近)+ 品牌墙 |
launch(userId, gameId) | 展示层 | 会话号 | 门禁 → 按场馆 route 选申报线路 → launch URL |
vendorCallback(vendor, payload, sign) | 厂商 | 厂商单号+动作 | 下注/结算/取消 → 适配层 route 重标本位币 → 记账 + 归一化注单 |
search(keyword) / fav(gameId, on) | 展示层 | — | 搜索、收藏 |
listBets(userId, filter) | 13 | — | 投注记录(本位币) |
产 BetSettled / BetCancelled | → 06/08/10/17 | BetSettled=betId;BetCancelled=betId+cancelSeq | 流水事实(本位币载荷);同注单可多次部分/全额取消,cancelSeq 区分(→ 00/08,10 对齐) |
六、运营后台能力(→ 15)
| 侧 | 能力 |
|---|---|
| 平台控制台 | 厂商接入与线路管理(按申报币种)、游戏目录与封面素材、全局维护位、场馆 route 配置(native/cnyMapped,平台超管专属;仅 USDT 站可选 cnyMapped) |
| 商户控制台 | 本站厂商/游戏开关与排序、热门策展、分类顺序、维护位(本站级)、注单查询(客诉对单,可见本位币入库值;route 与 declared* 申报口径快照对商户隐藏) |
七、展示契约(→ 原型映射)
站内金额恒本位币符号(→ 02 §七);唯一例外是
cnyMapped场馆内部计价符号 ¥(1:1 等值,进场已提示)。
| UI 元素 | 数据 | 原型载体 | 系统契约 |
|---|---|---|---|
| 大厅列表 | 分类分页游戏 | 连续滚动 + 两段上拉分页(tech-decisions) | getLobby 分页;分类序=配置 |
| 热门二级 tab | 推荐/收藏/最近 + 🔍 | .hot-tabs + renderHot();收藏/最近 localStorage(bf_fav/bf_recent,7 天) | 登录态走服务端收藏/最近,游客用本地 |
| 游戏卡 | 封面/⭐收藏 | data-cov + .fav ⭐(游客点⭐弹登录) | 收藏状态来自服务端 |
| 品牌墙/厂商 logo | vendor 目录 | app/assets/img/brand/wd/pXX.webp(08 返水复用同资源) | logo 由平台目录下发 |
| 全屏游戏 | 会话 + 浮层 | #sub-game 无顶栏;右上 #gf-toggle 展开:退出/充值/额度转换/客服 | Seamless 厂商隐藏「额度转换」;充值浮层直达钱包(03) |
| 映射场馆进场提示 | 场馆 route=cnyMapped | — | 进场弹「本场馆 ¥ 计价 = <本位币>,1:1,进出等值」(§3.4) |
| 额度转换/找回 | 中心钱包(本位币)⇄ 场馆额度 | #sub-transfer | 中心侧本位币;映射场馆额度标 ¥(1:1);找回工单带 route + declared* |
| 维护态 | vendor/venue.status | — | 封面遮罩「维护中」,点击提示 |
八、数据库设计(注单表含 tenant_id;厂商/游戏目录为平台级,场馆档案为站级)
| 表 | 关键字段 | 约束/索引 |
|---|---|---|
vendors(平台级) | vendor_code PK, name, logo, api_lines JSON, wallet_mode, status | — |
games(平台级) | game_id PK, vendor_code, name, game_type, cover, tags JSON, supported_currencies JSON, status | IDX(vendor_code);IDX(game_type) |
venue_profiles(站级) | venue_id PK, tenant_id, vendor_code, route(native/cnyMapped), supported_currencies JSON, status | UK(tenant_id,venue_id);IDX(tenant_id,vendor_code) |
game_sessions | session_id PK, tenant_id, user_id, game_id, venue_id, currency(本位币), route, state, started_at, closed_at | IDX(tenant_id,user_id,started_at) |
bets | bet_id PK(平台归一 ID), tenant_id, user_id, session_id, game_id, game_type, vendor_code, venue_id, ext_bet_no(厂商原始单号), currency(本位币), declared_currency, declared_amount, route, stake, payout, win_loss, valid_turnover, status, placed_at, settled_at | UK(tenant_id,vendor_code,ext_bet_no)(同一厂商注单只归一一条);IDX(tenant_id,user_id,settled_at) |
vendor_callback_log | id PK, tenant_id, vendor_code, ext_ref, action, payload JSON, result, created_at | UK(tenant_id,vendor_code,ext_ref,action) |
venue_rescue_tickets | ticket_id PK, tenant_id, user_id, venue_id, route, declared_currency, declared_amount, credited_amount(本位币), state, created_at, done_at | IDX(tenant_id,user_id,state) |
user_game_prefs | tenant_id, user_id, favorites JSON, recents JSON(带时间戳,7 天窗口) | UK(tenant_id,user_id) |
bets.currency恒本位币;declared_currency/declared_amount存场馆计价快照(映射场馆 =CNY+ 数值,原生 = 本位币);declared*与route属平台超管口径快照,商户侧注单查询隐藏该两列(→ §六)。- 两级去重(分工明确):
bets的 UK(tenant_id,vendor_code,ext_bet_no)只防「同一厂商注单被重复归一成多条」(无action维度);同一注单的下注/结算/取消(不同action)的回调重放去重落在vendor_callback_log的 UK(tenant_id,vendor_code,ext_ref,action)——二者职责不同,§3.8① 的回调防重放指vendor_callback_log。 venue_rescue_tickets= 代位下分工单,带route与场馆计价快照,映射场馆按 1:1 重标回本位币入账。bets高流水下的分区与冷热分层归 13 归档策略统一;分区键与幂等唯一键的落地约束见 13 §三。
九、扩展点与开放问题
- 体育赛事:体育注单有「预扣-部分结算-提前结算」等复杂生命周期,V1 按普通注单归一,深度体育版本单独立项;
- 免转与试玩:试玩模式(demo launch,不记账)按厂商能力开放;门禁上游客点游戏弹登录,游客试玩是否放行待产品定;
- 映射链路币种口径:
cnyMapped是否扩展到「本位币 ≥ CNY」之外的其他高币值本位币(如未来 EUR 站映射),需与厂商协议逐一确认口径,由平台超管决策,商户侧不涉及,待立项; - 热门自动策展:
hotList.mode=auto按近 7 日流水生成,依赖 17 聚合; - 注单归档:高流水下
bets分区与冷热分层,归 13 归档策略统一。
十、验收要点
- [ ] 厂商回调重放不重复记账;下注回调余额不足被拒且厂商侧一致;
- [ ] 取消注单:资金冲正、
validTurnover=0、08/10 同步冲正(经BetCancelled); - [ ]
bets.currency恒本位币;映射场馆厂商回传CNY注单被适配层 1:1 重标本位币入库,declared_currency=CNY快照留痕; - [ ]
route=cnyMapped仅 USDT 站发布通过;CNY 站/低币值站配置该值被拦截; - [ ] 映射场馆进场有 ¥=本位币 1:1 提示;额度转换页标注到位;返水/打码/报表对映射场馆零特判、口径本位币;
- [ ] Seamless 厂商全屏浮层无「额度转换」;transfer 厂商有且转入转出对账平(本位币);
- [ ] 余额找回直收失败转代位下分工单,工单带 route + 场馆计价快照,回执按本位币入账;
- [ ] 游客:浏览大厅可、点游戏/⭐/收藏最近 tab 弹登录(05);
- [ ] 收藏/最近登录后跨端一致;最近仅显示 7 天内;
- [ ] 场馆 route 配置仅平台超管(包网超管)可见可改;商户控制台不出现 route 配置项、注单查询隐藏
route/declared*;商户提交含venues[].route变更被发布校验拒绝; - [ ] route 仅承接中性对账(13 route 分档核销),无任何商业测算或引导落到 route。