# 数据大屏统计口径

本文档描述 `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`。