hyapp-server/docs/新App上线配置检查清单.md

新 App 上线配置检查清单

本文档定义 HyApp 新 App 从租户注册到正式运营的配置边界、业务 owner、开启条件和验收标准。它不是“把旧 App 数据全量复制一遍”的脚本说明；每项数据必须按 owner service 和业务键管理，不能跨租户复用原始自增 ID。

1. 使用方式

每次新 App 上线前，先建立一份当次上线记录，填写：

字段	说明
app_code	后端租户编码，全链路使用同一个小写值
App 名称	用户可见品牌名
Android package	Android 包名，必须和 Firebase、Google Play 一致
iOS bundle ID	iOS bundle identifier，必须和 Firebase、Apple 后台一致
对照 App	只用于确定初始产品口径，不代表可以直接复制原始 ID
计划开服时间	UTC epoch milliseconds，用于活动、版本和内容生效时间
支持国家/区域	国家、区域、内容和价格配置的权威范围
负责人	后端、客户端、运营、支付、IM/RTC 各自验收人

状态只使用以下四种：

• NOT_STARTED：尚未配置。
• CONFIGURED：已写入，但未经过真实请求验证。
• VERIFIED：已用新 app_code 走通生产链路并保留证据。
• BLOCKED：存在会阻断上线的问题，必须写明 owner 和解决动作。

2. 上线硬性原则

1. 新 App 数据必须使用新 app_code；不能依赖代码中的 lalu 默认值维持运行。
2. 复制配置必须按 resource_code、group_code、region_code、product_code 等业务键重建引用，不能复制旧 App 的自增 ID。
3. 礼物、活动、VIP、游戏等只有主配置表不算完成；所有价格、区域、资源、奖励和 worker 必须一起验证。
4. 敏感值只能写入线上环境变量或已忽略的运行时 env，不能写入可提交 YAML、SQL、文档或代码。
5. 全部时间使用 UTC，范围统一使用 [start_ms, end_ms)。
6. 共享 RocketMQ topic 不代表多 App 已经就绪；必须确认消息 payload、consumer context、幂等表和 outbox claim 都保留 app_code。
7. 只有完成“配置写入 → 服务加载 → 真实 API/IM/RTC/MQ 请求 → 日志与数据回查”才能标记 VERIFIED。

3. App 注册与租户基础

Owner：user-service、gateway-service。

配置项	数据/配置入口	开启条件	验收标准
App 注册	hyapp_user.apps	status=active，app_code 和包名唯一	按 X-App-Code 和 package 都能解析到同一 App
Android/iOS 包信息	apps 及客户端 flavor	与应用商店、Firebase 完全一致	真实安装包登录成功
Firebase 项目	user-service.third_party.firebase.projects.<app_code>	项目 ID、凭据和签名指纹都属于新 App	Google/Firebase token 在新 App 成功，不被其他 App 接受
JWT/请求元数据	gateway → gRPC RequestMeta.app_code	所有需要租户隔离的 RPC 透传	下游日志和数据行均为新 app_code
登录风控	auth_risk_configs、login_risk_country_blocks	明确复制或新建策略	允许国家可登录，拦截国家返回预期错误

4. 国家、区域与数据可见性

Owner：user-service。

配置项	主表	开启条件	验收标准
国家	countries	运营国家 enabled=1	/api/v1/countries 只返回新 App 允许的国家
区域	regions	status=active	后台和 App 能查到预期区域
国家归属	region_countries	每个启用国家有且只有一个有效业务区域	新注册用户的 region_id 正确
存量用户重建	user_region_rebuild_tasks	只在映射变更或补历史数据时执行	task 完成且 UserRegionChanged outbox 已投递

不能根据服务器所在地、IP 或容器时区推断业务国家/区域。

5. 管理后台与 App 内容入口

Owner：server/admin。

配置项	主表	开启条件	验收标准
App 通用配置	admin_app_configs	新 App 必须有自己的 group + key	H5 入口和功能跳转不读取其他 App 值
Banner	admin_app_banners	至少一个符合首页/区域/国家口径的 active 内容	/api/v1/app/banners 在目标国家返回预期内容
弹窗	admin_app_popups	按产品需求设为 active，并配置生效时间	/api/v1/app/popups 可见且跳转正确
开屏	admin_app_splash_screens	按 platform/国家/区域生效	/api/v1/app/splash-screens 返回预期素材
版本控制	admin_app_versions	Android/iOS 当前生产版本均有记录	/api/v1/app/version 返回正确版本、build 和强更策略
Explore Tab	admin_app_explore_tabs	显式启用并配置预期顺序	App 探索入口与后台一致

内容 API 返回 200 但 items=[] 只证明接口可用，不代表运营配置已完成。

6. 腾讯云 IM、RTC 与播报

Owner：gateway-service、activity-service、room-service；客户端长连属于腾讯云 IM。

配置项	配置/链路	开启条件	验收标准
IM UserSig	gateway-service.tencent_im	SDKAppID、secret、admin identifier 与线上 IM 应用一致	新 App 真实用户能登录 IM
IM callback	gateway callback	callback 能从合法 GroupID/请求中确定 app_code	Fami/Lalu 回调不会互相落库
RTC UserSig	gateway-service.tencent_rtc	SDKAppID、secret、room ID 类型与客户端一致	真实设备进房、上麦、发流成功
RTC callback	tencent_rtc.callback_url	不能把 app_code 写死为其他 App	回调日志与房间租户一致
全局/区域播报群	activity-service.broadcast	为新 App 和所有 active region 建立群	群 ID 含新 app_code，客户端能加入
播报 outbox	im_broadcast_outbox	worker 必须按记录 app_code claim、发送和 mark	新 App 消息从 pending 到 delivered，无跨 App 更新

至少实测一条全局播报、一条区域播报和一条房间系统消息。

7. 房间配置

Owner：room-service。Room Cell 仍然是房间核心状态 owner；新 App 上线不得把房间状态复制到其他服务。

配置项	主表	开启条件	验收标准
麦位	room_seat_configs	有新 App 配置，否则明确接受代码默认值	创房后麦位数量与客户端一致
火箭	room_rocket_configs	enabled=1 且奖励、油箱、频控已设定	完成加油、发射、奖励和 MQ 验证
宝箱	room_treasure_configs	产品需要时显式开启	开关与 App 入口一致
人机房	room_human_robot_configs	只有配好机器人账号和策略后才能开启	机器人加入/离开不污染真人 presence
区域置顶	room_region_pins	按新 App 运营需求单独配置	房间变更区域后重新建立置顶

8. 礼物、资源与装扮

Owner：wallet-service。

礼物上线是一组不可拆分的配置：

配置项	主表	开启条件
资源定义	resources	依赖资源必须 status=active，素材 URL 可访问
资源组	resource_groups、resource_group_items	所有活动/VIP/成就引用必须映射到新 App 资源
资源商店	resource_shop_items	价格、有效期和上架状态已审核
礼物类型	gift_type_configs	礼物分类已按产品口径启用
礼物配置	gift_configs	status=active，生效时间正确
礼物价格	wallet_gift_prices	每个 active 礼物都有有效价格
礼物区域	gift_config_regions	地区限制和新 App 的 region 映射一致
钻石分成	gift_diamond_ratio_configs	送礼所在区域有唯一有效分成规则

验收必须使用新 App 真实账号执行：礼物列表 → 余额校验 → 扣款 → Room Cell 表现 → RoomGiftSent outbox → 统计/活动/通知下游。

9. 充值、支付与兑换

Owner：wallet-service。

配置项	主表/运行配置	开启条件	验收标准
充值商品	wallet_recharge_products	新 App 商品 active，币种、金额、金币数正确	App 返回商品和后台一致
商品区域	wallet_recharge_product_regions	用新 App product_id 和 region_id 重建	每个运营区域都有预期商品
Google Play	google_play 及包名/服务账号	新 package 和验单凭据正确	测试购买、验单、发币、consume 均成功
第三方支付	third_party_payment_channels/methods	渠道、国家、币种和回调签名已配置	下单和回调的 app_code 一致
USDT/币安等外部充值	service YAML/env 的 per-App 映射	必须有新 App 账户/地址，不能回落到 Lalu	创单、归集、确认数和入账正确
钻石兑换	wallet_diamond_exchange_rules	active 规则已按运营口径配置	边界值和余额流水一致
红包	red_packet_configs 及档位表	开关、金额、份数、过期 worker 均支持新 App	发、抢、退、播报完整闭环

10. VIP

Owner：wallet-service；行为唯一依据是 vip_program_configs。

配置项	主表	开启条件	验收标准
VIP 方案	vip_program_configs	program_type、等级数、购买/升降级、发放模式明确	API 返回的方案与后台一致
VIP 等级	vip_levels	只有完成价格、时长和资源组配置的等级才能 active	/api/v1/vip/packages 返回预期等级
VIP 权益	vip_level_benefits	每个 active 等级的权益和资源引用有效	购买/发卡后权益生效
日奖励	cron vip_daily_coin_rebate	cron app_codes 含新 App，金额和 UTC 日切口径已确认	当日 run、领取和钱包流水一致
进房/上线播报	activity IM broadcast	用户开关、VIP 级别和广播群完整	真实设备收到新 App 播报

等级处于 disabled 时，套餐接口返回空数组是正确保护行为，但该 App 不能因此被认为“VIP 已上线”。

11. 活动与奖励

Owner：activity-service。

能力	主表/配置	上线必须同时确认
注册奖励	registration_reward_configs	开关、奖励类型、金额/资源组、每日限制
首充奖励	first_recharge_reward_configs/tiers	主开关和至少一个 active 档位
累充奖励	cumulative_recharge_reward_configs/tiers	主开关、周期口径和 active 档位
邀请奖励	invite_activity_reward_configs/tiers	邀请关系、有效邀请和充值事件消费就绪
七日签到	seven_day_checkin_configs/versions/rewards	开关、一个当前版本和 1–7 天完整奖励
每日任务	task_definitions/versions	active 任务、周期、指标和奖励口径一致
成就	achievement_definitions/conditions	active 成就引用的徽章资源属于新 App
成长等级	growth_level_tracks/rules/tiers	财富/魅力/游戏轨道及展示资源完整
CP 周榜	cp_weekly_rank_configs/rewards	开关、排名数、关系类型和奖励齐全
周星	weekly_star_cycles/gifts/rewards	当前 UTC 时间命中 active 周期，礼物和 Top 奖励完整
房间流水奖励	room_turnover_reward_configs/tiers	开关、周期、档位和钱包发放链路完整
转盘	wheel_rule_versions/prize_tiers	当前规则版本 active，奖品和 RTP 口径已审核

主开关、奖励档位和奖励资源缺任何一项，该活动都不得标记上线。

12. 幸运礼物

Owner：lucky-gift-service。activity-service 中的旧副本不能作为正式运行依据。

配置项	主表/链路	验收标准
规则版本	lucky_gift_rule_versions	每个运营奖池有 active 规则
阶段档位	lucky_gift_stage_tiers	规则对应的 stage/tier 完整且 enabled
独立奖池	lucky_pools	按 app_code + pool_id 初始化；只复制规则时不能复制对照 App 的余额、累计入池/出池或用户运行态
礼物映射	礼物配置与 pool 映射	只有新 App active 礼物才能进入抽奖
owner outbox	lucky_gift_outbox	抽奖事实持久化并发布到独立 MQ topic
区域飘屏	activity 独立 consumer group	不得复用其他 consumer group，且保留 app_code

真实验收要覆盖：普通奖、大奖、幂等重试、钱包入账、outbox 投递和区域飘屏。

13. 游戏

Owner：game-service。

配置项	主表	开启条件
游戏平台	game_platforms	平台 active，启动和回调参数完整
游戏目录	game_catalog	新 App 明确选择要开放的游戏，不强制与对照 App 数量相同
展示规则	game_display_rules	每个 active 游戏有可见规则
自研游戏配置	game_self_game_configs、风控/新手策略	游戏开关、RTP、风控参数已审核
机器人	game_self_game_robots	自研对战需要补位时，必须有新 App 真实机器人用户
档位奖池	game_self_game_stake_pools	每个可玩档位有 active 奖池和初始水位
回调归属	gateway JWT → RequestMeta.app_code	厂商回调不能默认记入 Lalu

第三方游戏少于对照 App 不一定是错误；必须由产品/运营给出明确游戏清单。但自研游戏已对用户开放时，机器人和奖池为空属于上线阻断。

14. cron、MQ、outbox 和通知

配置项	Owner	开启条件	验收标准
cron 任务	cron-service	所有应在新 App 运行的 task app_codes 含新 App	cron_task_runs 按 task_name + app_code 生成成功记录
owner outbox publisher	room/wallet/user/game/lucky-gift	只有 owner 服务扫描自己的 outbox	新 App pending 可持续转 delivered，无长时间积压
RocketMQ consumer group	每个下游服务	不得共享 owner 的 outbox 状态或其他业务消费组	group 存在、无异常 lag、重投幂等
统计消费	statistics-service	wallet/room/user/game 事实消费器已启用	新 App 聚合表产生 UTC 日数据
私有通知	notice-service	RocketMQ 消费器为主链路	钱包/CP/房间通知均使用新 App 租户
系统/活动 inbox	activity-service message owner	后台通知通过 owner API/fanout job 创建	不直写 inbox/fanout 表，能从 App 查看并已读

notice-service 的旧轮询 worker 关闭、RocketMQ consumer 开启是正常迁移状态，不能只看一个 enabled=false 就判定新 App 未开通。

15. 统计与数据大屏

Owner：statistics-service；后台查询入口在 server/admin。

1. 确认 WalletRechargeRecorded、GameOrderSettled、RoomGiftSent、RoomUserJoined、UserRegistered 事件都带新 app_code。
2. 确认消费幂等表已记录新 App 事件。
3. 确认充值、游戏、礼物、活跃、注册和留存聚合表在 UTC 边界正确生成。
4. 确认 admin 大屏选择新 App 时只查聚合表，不回查 owner 明细库。
5. 使用可控测试账号产生一组注册、进房、充值、游戏、送礼事实，核对次日聚合。

16. 客户端与发布

项目	必须验证
flavor/品牌	App 名称、图标、包名、bundle ID、深链、主题和隐私页均为新 App
API host	生产包指向生产 API，不得混入测试 host
Firebase	flavor 使用自己的 google-services.json/iOS 配置
IM/RTC	SDKAppID、UserSig 及回调链路完整
支付	package/product ID/签名与商店后台一致
版本 API	首个生产 build 已写入 admin_app_versions
埋点	心跳、页面、社交漏斗和游戏事件使用新 app_code

必须在真实 Android/iOS 设备上执行最终验收，不能只用 curl 代替 IM、RTC、支付和客户端跳转验证。

17. 正式上线验收清单

17.1 配置一致性

• 新 App 在所有 owner 库的 app_code 一致。
• 所有跨表引用已按业务键重建，不存在指向对照 App ID 的记录。
• 全部敏感配置只存在运行时 env/密钥管理系统。
• 两台或多台副本的 YAML、镜像 tag 和配置 hash 一致。

17.2 业务冒烟

• 注册、登录、刷新 token、用户资料、国家/区域归属正常。
• IM 登录、单聊、房间群、全局/区域播报正常。
• RTC 进房、上麦、发流、回调和离开正常。
• 创房、进房、麦位、踢人、锁房、房间恢复正常。
• 礼物列表、送礼扣款、房间表现、收礼统计正常。
• 充值商品、真实测试购买、回调验单、钱包入账正常。
• VIP/活动/签到/任务/成就/周星等已宣布上线的能力全部真实验证。
• 第三方游戏启动、回调归属和余额一致；自研游戏机器人/奖池可用。

17.3 异步与数据

• owner outbox 无新 App 长时间 pending/failed 积压。
• RocketMQ consumer group 存在且无异常 lag。
• cron 所需 task 已产生新 App 成功运行记录。
• 通知、inbox、播报和 push 不串 App。
• 统计聚合表有新 App 真实事实，UTC 边界正确。

17.4 发布结论

只有以下条件全部满足才能标记“可正式运营”：

1. P0 阻断项为 0。
2. 所有宣布上线的功能已完成真实设备和生产链路验证。
3. 运营明确接受未上线的可选功能，且 App 客户端不展示无配置入口。
4. 发布镜像、数据迁移、MQ、YAML/env、客户端版本和回滚方案均有记录。

18. Fami 生产差异快照（2026-07-13）

本节是对生产 YAML、生产 MySQL、线上镜像和公网 API 的只读快照，用于保留 Fami 从试运营转正式运营前的基线。后续修复后应追加新日期的验收结果，不覆盖本快照。

18.1 P0 阻断项

项目	Fami 当前状态	Lalu 对照	必须动作
礼物	gift_configs=0、wallet_gift_prices=0	95 个 active 礼物、103 个 active 价格	按业务键创建 Fami 礼物和价格，验证送礼闭环
资源	535 条全部 deleted，有效资源/资源组/商城均为 0	501 active 资源、56 active 资源组	重建 Fami 资源体系和全部引用
VIP	方案 active，但 VIP1–VIP10 全部 disabled	VIP1–VIP8 active	只启用已完成价格、权益和资源配置的 VIP1–VIP9
RTC callback	两台 gateway 回调 URL 都写死 app_code=lalu	Lalu 符合当前值	调整回调归属，分别验证 Fami/Lalu RTC 事件
IM 播报 worker	线上 activity-service:20260712-main-7d011ce 仍以默认 Lalu context claim/reconcile	Lalu 已投递 71,564 条	发布多 App claim/建群逻辑，实测 Fami 全局和区域播报
幸运礼物 owner	lucky-gift-service 规则版本和档位均为 0	15 个规则版本、255 个档位	在 owner 库配置，不使用 activity 旧副本代替
首充奖励	开关 0，3 个档位全部 disabled	开关 1，3 个 active	确认奖励后启用并走真实充值事实
累充奖励	开关 0，8 个档位全部 disabled	开关 1，8 个 active	确认周期和奖励后启用
七日签到	开关 0，无生效版本，无奖励	开关 1，有生效版本和 7 天奖励	创建 Fami 版本和 7 天奖励后启用
CP 周榜	开关 0，无奖励	开关 1，3 个奖励	确认关系类型和奖励后启用
周星	当前 UTC 时间无 active 周期	Lalu 有 1 个 active 周期	创建 Fami 周期、指定礼物和 Top 奖励
自研游戏运行数据	机器人 0，档位奖池 0	dice 机器人 80，dice/rock 奖池 8	如 Fami 对用户开放自研游戏，先初始化机器人和奖池

18.2 运营内容缺口

项目	Fami 当前状态	Lalu 对照
首页 Banner	公网 API items=0	相同请求返回 10 条
弹窗	公网 API items=0	1 条
开屏	公网 API items=0	1 条
版本控制	version=""、build_number=0	Android 1.0.9/109
H5 入口	只有 1 条 app config，缺 23 个 h5-links	24 条 app config
第三方游戏目录	34 个 active	37 个 active；Fami 少 Rocket、TeenPattiPro、LavaSlot
成长/成就展示资源	6 个头像框、25 个徽章档位和 32 个成就引用资源，但 Fami 无 active 资源	Lalu 有 active 资源

第三方游戏的三个差异需产品确认，不能在没有授权和产品结论时自动复制。

18.3 条件项

• 币安账户映射当前只有 Lalu。
• TRC20 USDT 收款地址当前只有 Lalu。
• Fami 已有 16 个 active 充值商品和对齐的第三方支付方式；上述两项只在产品要求 Fami 开放对应渠道时才是阻断。

18.4 已就绪项

• Fami App 注册状态为 active。
• Firebase 项目已配置。
• 16 个 cron 任务均已启用且 app_codes 包含 lalu/fami/huwaa。
• Fami 和 Lalu 均有 141 个 enabled 国家，启用国家无缺口。
• Firebase、登录风控、CP 关系配置已建立。
• 红包、房间火箭、邀请奖励、注册金币奖励、房间流水奖励已开启。
• 财富/魅力/游戏成长等级的规则数量已与 Lalu 对齐，但展示资源仍受资源体系缺失阻断。
• room、wallet、user、game、statistics 的共享 MQ/outbox 主开关已开启。

18.5 Fami 建议收敛顺序

1. 重建 Fami 礼物、价格、资源、资源组和商城，修复成长/成就展示引用。
2. 修复 RTC callback 的 App 归属，发布 activity 多 App 播报 claim/建群逻辑。
3. 在 lucky-gift-service owner 库配置 Fami 规则和档位，完成独立 MQ consumer 验证。
4. 完成 VIP 价格/权益/资源后启用 VIP1–VIP9。
5. 按产品范围启用首充、累充、七日签到、CP 周榜和周星。
6. 补齐 Banner、弹窗、开屏、版本和 H5 入口。
7. 确认 Fami 游戏清单；如开放自研游戏，初始化机器人和档位奖池。
8. 执行第 17 节的真实设备、业务、MQ、数据与统计验收，确认 P0 为 0 后再标记可正式运营。

18.6 首批修复记录（2026-07-13）

本次只收敛 RTC/IM 业务租户隔离和幸运礼物初始化，不代表第 18.1 节其他 P0 已解除。

项目	修复结果	验证证据	状态
RTC callback	共享腾讯 RTC 应用不再从 URL 固定读取 app_code=lalu；gateway 验签后按 room_id 调 room-service 解析真实房间租户，再提交对应 Room Cell	两台 gateway 的 callback URL 均已改为无查询参数地址；rooms.room_id 无重复并已增加唯一索引；gateway/room 双节点运行镜像 20260713-fami-app-scope-1 且 healthy	CONFIGURED；仍需 Fami/Lalu 各一次真实设备上麦、退流回调后升为 VERIFIED
IM 播报 worker	同一腾讯 IM SDKAppID 下，群 ID、outbox claim、发送、mark 和 reconcile 均按记录 app_code 隔离；broadcast.app_codes 显式配置 lalu/fami/huwaa	腾讯 IM 云端已存在 hy_fami_bc_g_v2 及区域 24–30 的 7 个 hy_fami_bc_r_v2_* 群；activity 双节点运行镜像 20260713-fami-app-scope-1 且无 reconcile 错误	VERIFIED（建群与运行态）；仍需客户端真实收一条区域/全局播报完成产品验收
幸运礼物规则	从 Lalu 复制所有规则版本和阶段档位到 Fami，只变更租户键	Fami lucky 为 6 个规则版本/106 个档位；super_lucky 为 9 个规则版本/149 个档位，enabled 数量与 Lalu 一致	VERIFIED（配置数据）
幸运礼物奖池	未复制 Lalu 奖池状态；Fami 的 lucky、super_lucky 各自独立初始化	两个池均为 balance=100000、reserve_floor=21000、total_in=0、total_out=0；Fami RTP 窗口、用户状态、抽奖记录和 outbox 均为 0	VERIFIED（初始化数据）；仍需真实普通奖/大奖/钱包/outbox 冒烟

发布前已执行 make proto、make test 和 docker compose config；发布后 6 个实例均 healthy、restart count 为 0，相关 CLB 后端权重均恢复为 100。