hyapp-server/docs/数据大屏统计口径.md

数据大屏统计口径

本文档描述 statistics-service 提供给后台数据大屏的字段口径。查询入口是 server/admin 转发到 statistics-service 的 /internal/v1/statistics/overview，返回字段同时用于 overview、daily_series、country_breakdown 和 daily_country_breakdown。

通用规则

• 时间范围统一是 [start_ms, end_ms)，包含开始毫秒，不包含结束毫秒。
• 默认统计时区是 UTC；传 stat_tz=Asia/Shanghai 时按中国自然日查询统计读模型。
• 国家和区域只使用事件里的国家/区域字段或统计服务保存的用户维度，不用服务器所在地、IP 或本地时区推断。
• 查询只读 statistics-service 聚合表，不回查 wallet、room、game、user owner 明细表。
• coin_total 为兼容前端保留 JSON 字段名，展示名改为“用户金币数”。

字段口径

字段	展示名	口径
app_code	应用编码	当前查询的租户编码。
stat_tz	统计时区	UTC 或 Asia/Shanghai。
start_ms / end_ms	查询时间	本次查询的毫秒时间范围。
country_id / region_id	国家/区域	聚合维度；未筛选国家时返回国家分解。
new_users	新增用户	UserRegistered 注册 cohort 去重用户数。
active_users	活跃用户	RoomUserJoined、GameOrderSettled 和注册当天活跃写入 stat_user_day_activity 后按用户去重。
paid_users	付费用户	WalletRechargeRecorded 写入 stat_recharge_day_payers 后按用户去重。
new_paid_users	新增付费用户	付费用户中注册 cohort 也落在查询周期内的用户数。
recharge_usd_minor	总充值	WalletRechargeRecorded.usd_minor_amount 累加，单位是美元最小单位。
new_user_recharge_usd_minor	新增充值	recharge_sequence=1 的充值金额累加。
coin_seller_recharge_usd_minor	币商充值	币商进货 USDT 和未识别为 Google/MifaPay/USDT-TRC20/币商转账的充值美元最小单位。
coin_seller_stock_coin	币商充值金币	WalletCoinSellerStockPurchased.coin_amount 累加。
mifapay_recharge_usd_minor	三方充值	recharge_type=mifapay/v5pay 的充值美元最小单位。
google_recharge_usd_minor	Google 充值	recharge_type=google/google_play 的充值美元最小单位。
coin_seller_transfer_coin	币商出货金币	币商向用户转入普通 COIN 金币数量。
coin_total	用户金币数	用户普通 COIN 钱包 available+frozen 余额总和；历史日取当天 23:59:59.999 前最后一次余额，今日按 WalletBalanceChanged 增量滚动更新；多日总览只取结束日快照，日序列展示每天快照。
consumed_coin	消耗金币	游戏投入 + 普通礼物投入 + lucky 礼物投入 + 转盘投入 + 发红包。游戏来自 GameOrderSettled debit/bet，房间礼物来自 RoomGiftSent.coin_spent，钱包只补 direct_gift_debit、wheel_draw_debit、red_packet_create。
output_coin	产出金币	游戏产出 + 收礼产出 + lucky 礼物产出 + 转盘奖励金币 + 红包领取和退回。游戏来自 GameOrderSettled credit/payout，收礼来自 WalletGiftIncomeCredited，lucky 来自 WalletLuckyGiftRewardCredited，转盘金币来自 WalletWheelRewardCredited，红包来自 red_packet_claim/refund。
consume_output_ratio	消耗产出比	output_coin / consumed_coin；消耗为 0 时返回 0。
consume_output_delta	消耗产出差额	consumed_coin - output_coin。
platform_grant_coin	平台发放金币	排行榜奖励、活动奖励、签到/任务奖励、火箭奖励中的 COIN 金币发放；包括对应 Wallet*RewardCredited 和 resource_grant COIN 入账，不含人工发放、装扮价值、lucky 返奖、转盘产出。
manual_grant_coin	人工发放金币	WalletBalanceChanged biz_type=manual_credit 的普通 COIN 正向发放。
salary_usd_minor	工资总和	主播和代理工资钱包结算成功金额，单位是 USD minor。
salary_transfer_coin	工资兑换金币	工资转给币商时币商 COIN_SELLER_COIN 入账金币数量，维度按发起转账用户。
mic_online_ms	麦上总时长	user_mic_daily_stats.mic_online_ms 按日、国家、区域聚合。
mic_online_users	麦上用户数	当日 mic_online_ms > 0 的去重用户数。
avg_mic_online_ms	平均麦上时长	mic_online_ms / mic_online_users。
gift_coin_spent	礼物流水	非机器人真实 RoomGiftSent.coin_spent，历史事件无 coin_spent 时回退 gift_value。
real_room_robot_normal_gift_coin	真人房机器人普通礼物	real_room_robot_gift=true 且非 lucky/super lucky 的礼物金币。
real_room_robot_lucky_gift_coin	真人房机器人 lucky 礼物	真人房机器人 lucky 礼物金币。
real_room_robot_super_gift_coin	真人房机器人 super lucky 礼物	真人房机器人 super lucky 礼物金币。
real_room_robot_total_gift_coin	真人房机器人总礼物	上面三类机器人礼物金币合计。
real_room_robot_gift_room_count	真人房机器人投放房间数	有真人房机器人礼物的房间去重数。
real_room_robot_avg_room_gift_coin	真人房机器人房均投放	real_room_robot_total_gift_coin / real_room_robot_gift_room_count。
lucky_gift_turnover	lucky 礼物流水	RoomGiftSent.pool_id 非空的送礼金币。
lucky_gift_payout	lucky 礼物产出	WalletLuckyGiftRewardCredited.amount，UTC 查询会优先用 activity 的 lucky pool 日表覆盖旧统计行。
lucky_gift_payers	lucky 礼物付费用户	发送 lucky 礼物的用户按日去重。
lucky_gift_profit	lucky 礼物利润	lucky_gift_turnover - lucky_gift_payout。
lucky_gift_payout_rate	lucky 礼物返奖率	lucky_gift_payout / lucky_gift_turnover。
lucky_gift_profit_rate	lucky 礼物利润率	lucky_gift_profit / lucky_gift_turnover。
game_turnover	游戏流水	GameOrderSettled op_type=debit/bet 的金币。
game_payout	游戏返奖	GameOrderSettled op_type=credit/payout 的金币。
game_refund	游戏退款	GameOrderSettled op_type=refund/reverse 的金币。
game_players	游戏玩家数	有游戏投入的用户按日、游戏平台、游戏去重后汇总。
game_profit	游戏利润	game_turnover - game_payout - game_refund。
game_profit_rate	游戏利润率	game_profit / game_turnover。
super_lucky_gift_turnover	super lucky 流水	pool_id 包含 super_lucky 的奖池流水。
super_lucky_gift_payout	super lucky 返奖	pool_id 包含 super_lucky 的奖池返奖。
super_lucky_gift_profit	super lucky 利润	super_lucky_gift_turnover - super_lucky_gift_payout。
super_lucky_gift_profit_rate	super lucky 利润率	super_lucky_gift_profit / super_lucky_gift_turnover。
arpu_usd_minor	ARPU	recharge_usd_minor / active_users。
arppu_usd_minor	ARPPU	recharge_usd_minor / paid_users。
up_value_usd_minor	UP 值	当前与 ARPPU 同口径。

对比字段

以下字段是当前周期与上一等长周期的变化率：recharge_delta_rate、new_user_recharge_delta_rate、active_users_delta_rate、paid_users_delta_rate、new_paid_users_delta_rate、arpu_delta_rate、arppu_delta_rate、gift_coin_spent_delta_rate、coin_seller_transfer_coin_delta_rate、lucky_gift_turnover_delta_rate、lucky_gift_payout_delta_rate、lucky_gift_profit_delta_rate、game_turnover_delta_rate、game_profit_delta_rate。

变化率公式是 (当前值 - 上期值) / abs(上期值)；上期为 0 且当前大于 0 时返回 1。

明细对象

字段	口径
retention	registered_users 为注册 cohort；day1/day7/day30_users 为注册后第 1/7/30 天有活跃的用户；rate 为对应用户数除以注册用户数。
daily_series	按日返回本页主要字段；coin_total 是每天的用户金币数快照，其它流水字段按当天累加。
country_breakdown	按国家返回本页主要字段；coin_total 是查询结束日该国家用户金币数快照，其它字段按查询周期累加。
daily_country_breakdown	按日 + 国家返回主要字段，用于国家弹窗明细。
game_ranking	按 platform_code/game_id 聚合游戏流水、返奖、退款、玩家数、利润和利润率。
lucky_gift_pools	按 pool_id 聚合 lucky 礼物流水、返奖、利润、返奖率和利润率。
report_metric_sources	返回字段来源和口径说明，供前端展示或排查。

当前边界

• 转盘礼物/道具的 RTP 价值在 activity wheel 记录里有 rtp_value_coins，但 wallet 资源 outbox 当前不是稳定 MQ 统计输入；统计服务现在只计转盘金币奖励，礼物价值需要资源奖励事件可稳定发布后接入。
• 平台发放的礼物价值同理，需要 ResourceGranted/ResourceGroupGranted 事件携带可统计的资源金币价值和来源；当前只可靠计入 COIN 入账和已存在的 Wallet*RewardCredited 金币奖励。
• 装扮价值不进入 platform_grant_coin 和 output_coin。
• 后台人工发放只进入 manual_grant_coin，不进入 platform_grant_coin。