查卡与机台统计公开字段深度参考
本页解释查卡接口和网页统计卡片的字段分组、合并语义、时间窗口和隐私边界。统计是快照/聚合值，不是永久审计数据。
请求字段
token
当前机台账号会话。失效后停止自动刷新，不能用旧 Token继续读取其它目标。
clientId
当前账号授权的目标机台标识。只能使用页面返回或管理员确认的目标，不要从另一台机台复制。
顶层 playerQueueData
| 字段 | 页面对应 |
|---|---|
clientId | 当前目标机台 |
statistics | 总体统计 |
currentOnlinePlayers | 当前在线用户 |
timeRangeStatistics | 时间段统计 |
playerActivityAnalysis | 用户活跃时长 |
recentPlayRecords | 最近游玩摘要 |
peakHoursAnalysis | 小时峰值 |
sessionStatistics | 会话摘要 |
recentSessionRecords | 最近会话 |
playerSessionFrequencyAnalysis | 频率/回访分析 |
sessionHourlyDistribution | 会话小时趋势 |
缺少某个可选分组时，页面应隐藏该图表或显示暂无数据，不应把整份响应判为失败。
statistics
总体统计可能包括当前人数、总会话、总游玩和时间窗口摘要。字段名称以公开字段目录为准，未知字段保留。总数是统计口径内的值，不等于记录页面的总记录数。
当前在线用户
当前在线对象可能包括：
- 用户显示名；
- 登录时间；
- 游玩时长秒数；
- 格式化游玩时长；
- 当前状态。
在线对象是当前快照。用户离开后下一次刷新可能消失；不应拿它当历史记录。
timeRangeStatistics
每项通常包含：
timeRange：时间窗口名称；playerCount：人数/会话数量；- 去重用户数或同类聚合字段。
比较两个窗口时保持目标、时区和统计口径一致。窗口为空时显示空，不要显示为网络失败。
playerActivityAnalysis
活跃时长分析可能以分组形式返回：
| 字段 | 语义 |
|---|---|
groupName | 分组名称 |
minDuration | 下界 |
maxDuration | 上界 |
playerCount | 分组人数 |
percentage | 分组占比 |
百分比可能已由服务计算，前端不要再次乘 100。分组边界以服务返回为准。
peakHoursAnalysis
小时统计通常有：
hourlyStatistics[]；peakHour；peakHourCount；peakTimeRange。
峰值是当前窗口内最高点，不代表系统异常。小时要按页面时区显示，跨午夜时保留日期上下文。
sessionStatistics
会话摘要可能包含：
- 近期会话数量；
- 日均会话；
- 人均会话；
- 平均时长及格式化值；
- 中位时长及格式化值；
- 最长/最短时长。
多机台合并时，页面可能主动隐藏单机台摘要，因为平均值和中位值会改变语义。不要自行计算并伪装成服务结果。
recentSessionRecords
最近会话对象通常含：
userName；sessionId；loginTime；logoutTime；duration；durationFormatted。
缺失登出时间时不要把时长当作 0。用户名称和时间组合属于敏感信息，导出前脱敏。
recentPlayRecords
最近游玩对象是摘要列表，不一定含完整成绩字段。它适合现场快速确认最近是否有活动，完整记录应转到记录页面和分页接口。
频率和回访分析
frequencyGroups 可能包含最小/最大会话次数、人数和占比；topActiveUsers 可能包含显示名、会话数、总时长、平均时长、首次/最后登录时间；回访区可能包含人数和回访率。
这些字段仅在授权场景展示。对外只提供分布和计数，不公开用户名、会话 ID、精确时间组合。
sessionHourlyDistribution
可能包含每小时会话数量、峰值小时、峰值数量和时间范围。会话趋势与用户趋势不是同一个图表，不应混合标题或单位。
多目标合并规则
网页可能对多个目标执行：
- 数量求和；
- 用户去重；
- 小时点合并；
- 最近记录排序；
- 峰值重新计算。
读取失败的目标不能静默当作 0。客户端应返回部分成功并保留目标来源。
自动刷新安全
自动刷新要保存：
- 启动时间；
- 周期；
- 目标列表；
- 最近成功/失败；
- 停止原因。
页面离开、Token 失效或取消选择后停止轮询。不要用短周期刷新对服务施压。
公开显示规则
- 聚合数值可以在授权范围内展示；
- 单用户和会话明细需授权；
- 机台标识使用别名；
- IP、网关和完整编号不进入截图；
- 统计空值和请求失败分开显示。