444 lines
20 KiB
Markdown
444 lines
20 KiB
Markdown
# User Mic Online Time Architecture
|
||
|
||
本文定义“用户麦上在线时长”的统一统计架构。这个指标属于所有用户，不属于主播专属体系。用户无论当时是不是主播，只要在麦上产生了有效在线时长，都应该累计到用户维度；后续用户成为主播、参与任务、参与活动或参与成长体系时，可以直接读取历史累计结果。
|
||
|
||
## Core Decision
|
||
|
||
麦位时间先按用户维度沉淀，再被主播、任务、活动和工资等业务读取。
|
||
|
||
不能把麦位时间只写进 `host_daily_stats`，也不能在统计事件时判断“这个用户当时是不是主播”。主播身份是后置业务条件，不是麦位在线事实本身。
|
||
|
||
示例：
|
||
|
||
- 用户 A 不是主播时累计麦上在线 10 小时。
|
||
- 后来用户 A 申请并成为主播。
|
||
- 如果任务规则是“主播累计麦上在线达到 10 小时”，该任务可以直接使用用户 A 已有的 10 小时完成。
|
||
|
||
## Goals
|
||
|
||
- 所有用户共享同一套麦上在线时长事实。
|
||
- 支持日统计、周期统计、 lifetime 累计和任务进度读取。
|
||
- 支持用户成为主播前的历史时长被后续主播任务使用。
|
||
- 统计来源必须可恢复、可重放、可幂等。
|
||
- Redis 只能做缓存，不能作为时长事实来源。
|
||
- 后续主播工资如需“只算成为主播后的有效工作时长”，必须在派生层另行按政策过滤，不能污染基础用户时长。
|
||
|
||
## Non-Goals
|
||
|
||
- 不在 room-service 命令链路里同步计算任务进度。
|
||
- 不在上麦接口里同步判断主播、Agency、BD 或任务状态。
|
||
- 不把当前麦位状态当成历史统计。
|
||
- 不用客户端上报时长作为权威事实。
|
||
- 不把单个任务进度直接写进麦位会话表。
|
||
|
||
## Terminology
|
||
|
||
| Term | Meaning |
|
||
| --- | --- |
|
||
| 麦位占用时长 | 从 `MicUp(action=up)` 到 `down/leave/kick/close` 的时间，包含 `pending_publish` |
|
||
| 麦上在线时长 | 用户真实完成发流确认后的麦上时间，默认从 `publish_state=publishing` 开始算 |
|
||
| `mic_session_id` | 单次上麦会话 ID，同一用户多次上下麦会产生多条 session |
|
||
| 基础用户时长 | 不区分用户身份、房间、Agency、BD 的用户级时长事实 |
|
||
| 派生业务时长 | 主播工资、活动任务等业务按自己的政策从基础用户时长或 session 明细派生 |
|
||
|
||
## Which Time Counts
|
||
|
||
首版建议同时保存两个值，但默认任务使用 `mic_online_ms`：
|
||
|
||
| Metric | Start | End | Use |
|
||
| --- | --- | --- | --- |
|
||
| `seat_occupied_ms` | `RoomMicChanged.action=up` | `down/leave/kick/close` | 产品想看“占麦多久”时使用 |
|
||
| `mic_online_ms` | `RoomMicChanged.action=publish_confirmed` | `down/leave/kick/close` | 任务、成长、有效麦上在线默认使用 |
|
||
|
||
原因：
|
||
|
||
- `MicUp` 只表示业务占麦成功，用户可能没有切 RTC anchor、没有打开麦克风、网络失败或马上超时。
|
||
- `publish_confirmed` 表示服务端已经接受客户端或 RTC webhook 的发流确认，更接近“用户真的在麦上在线”。
|
||
- 如果后续有运营活动明确要求“只要占麦就算”，可以读 `seat_occupied_ms`，不需要改历史表。
|
||
|
||
## Source Events
|
||
|
||
权威来源是 `room-service` 的 `room_outbox`：
|
||
|
||
| Event | Action | Effect |
|
||
| --- | --- | --- |
|
||
| `RoomMicChanged` | `up` | 创建或开启一条用户麦位 session，记录 `seat_started_at_ms` |
|
||
| `RoomMicChanged` | `publish_confirmed` | 设置 `publishing_started_at_ms`，开始累计 `mic_online_ms` |
|
||
| `RoomMicChanged` | `change` | 不结束 session，只更新当前 seat；时长连续 |
|
||
| `RoomMicChanged` | `down` | 结束 session，结算 `seat_occupied_ms` 和 `mic_online_ms` |
|
||
|
||
`LeaveRoom`、`KickUser`、`CloseRoom`、RTC `audio_stopped/room_exited` 和 `publish_timeout` 都必须在释放麦位时产生 `RoomMicChanged(action=down)`。user-service mic time consumer 只消费这个统一麦位事实，不从 `RoomUserLeft`、`RoomUserKicked` 或 `RoomClosed` 反推关闭。
|
||
|
||
当前释放原因约定：
|
||
|
||
| Release Path | `RoomMicChanged.reason` |
|
||
| --- | --- |
|
||
| 主动离房 | `leave` |
|
||
| presence stale 清理 | 调用方传入的 stale reason，例如 `presence_stale` |
|
||
| 踢人 | `kick` |
|
||
| 关房 | `room_closed` |
|
||
| pending publish 超时 | `publish_timeout` |
|
||
| RTC 停止/退房 | gateway/RTC 事件传入的 reason |
|
||
|
||
当前 `RoomMicChanged` 已经包含 `mic_session_id`、`publish_state`、`reason`、`publish_deadline_ms` 和 `publish_event_time_ms`。用户麦时长消费者必须优先使用这些字段，不能用 `room_id + user_id` 自行拼会话 ID。
|
||
|
||
事件兼容规则：
|
||
|
||
- `mic_session_id` 为空的 `up/publish_confirmed/down` 事件不能进入正常累计；当前实现写入 `user_mic_event_consumption` 并标记 `skipped/incomplete_mic_event`。
|
||
- `publish_confirmed` 必须只推进当前 open session；如果 session 已结束或事件时间早于已接受时间，按幂等或过期事件处理。
|
||
- `change` 事件没有时长增量，只更新 seat 快照和 `last_event_id`。
|
||
- `down` 的结束时间优先取 envelope `occurred_at_ms`；如果后续事件体提供更精确 RTC stop time，再使用事件体时间。
|
||
- 消费者只消费 `room_outbox` 事实，不订阅腾讯 RTC webhook 原始事件，避免绕过 Room Cell 状态机。
|
||
|
||
## Service Boundary
|
||
|
||
```mermaid
|
||
graph LR
|
||
Room["room-service\nRoom Cell"] --> Outbox[("room_outbox")]
|
||
Outbox --> Consumer["user-service\nmic time consumer"]
|
||
Consumer --> UserMicDB[("hyapp_user\nuser_mic_* tables")]
|
||
UserMicDB --> Task["activity/task service"]
|
||
UserMicDB --> Host["host/agency/bd module"]
|
||
UserMicDB --> Admin["admin salary/risk"]
|
||
```
|
||
|
||
首版建议把用户麦上时长放在 `user-service`，原因：
|
||
|
||
- 统计主维度是 `user_id`，不是房间。
|
||
- 任务、主播身份、Agency 和用户资料都需要读取用户侧统计。
|
||
- `room-service` 应继续只拥有房间实时状态、快照、command log 和 outbox，不承载跨天统计。
|
||
|
||
如果后续活动系统独立承接所有任务，也可以由 `activity-service` 消费 room outbox，但基础事实表仍应按用户维度建模，并通过内部 RPC 提供给 host/admin 使用。
|
||
|
||
## Data Model
|
||
|
||
### `user_mic_sessions`
|
||
|
||
保存每一次上麦会话。它是可审计明细，不直接服务首页大查询。
|
||
|
||
```sql
|
||
user_mic_sessions(
|
||
app_code VARCHAR(32) NOT NULL,
|
||
mic_session_id VARCHAR(128) NOT NULL,
|
||
user_id BIGINT NOT NULL,
|
||
room_id VARCHAR(64) NOT NULL,
|
||
first_seat_no INT NOT NULL DEFAULT 0,
|
||
current_seat_no INT NOT NULL DEFAULT 0,
|
||
status VARCHAR(32) NOT NULL,
|
||
seat_started_at_ms BIGINT NOT NULL,
|
||
publishing_started_at_ms BIGINT NULL,
|
||
ended_at_ms BIGINT NULL,
|
||
end_reason VARCHAR(64) NOT NULL DEFAULT '',
|
||
seat_occupied_ms BIGINT NOT NULL DEFAULT 0,
|
||
mic_online_ms BIGINT NOT NULL DEFAULT 0,
|
||
opened_event_id VARCHAR(128) NOT NULL,
|
||
publish_event_id VARCHAR(128) NOT NULL DEFAULT '',
|
||
closed_event_id VARCHAR(128) NOT NULL DEFAULT '',
|
||
last_event_id VARCHAR(128) NOT NULL,
|
||
last_room_version BIGINT NOT NULL DEFAULT 0,
|
||
created_at_ms BIGINT NOT NULL,
|
||
updated_at_ms BIGINT NOT NULL,
|
||
PRIMARY KEY (app_code, mic_session_id),
|
||
KEY idx_user_mic_sessions_user_status (app_code, user_id, status, updated_at_ms),
|
||
KEY idx_user_mic_sessions_room_status (app_code, room_id, status),
|
||
KEY idx_user_mic_sessions_open_timeout (app_code, status, seat_started_at_ms)
|
||
);
|
||
```
|
||
|
||
`status`：
|
||
|
||
| Status | Meaning |
|
||
| --- | --- |
|
||
| `pending_publish` | 已占麦，尚未确认发流 |
|
||
| `publishing` | 已确认发流，正在累计在线时长 |
|
||
| `ended` | 会话已结束 |
|
||
| `abnormal_closed` | 预留给后续补偿任务；当前基础消费者只写 `ended` |
|
||
|
||
### `user_mic_daily_stats`
|
||
|
||
按当前实现的 UTC 日期聚合，服务任务、活动和个人中心二级页。
|
||
|
||
```sql
|
||
user_mic_daily_stats(
|
||
app_code VARCHAR(32) NOT NULL,
|
||
user_id BIGINT NOT NULL,
|
||
stat_date CHAR(10) NOT NULL,
|
||
seat_occupied_ms BIGINT NOT NULL DEFAULT 0,
|
||
mic_online_ms BIGINT NOT NULL DEFAULT 0,
|
||
session_count BIGINT NOT NULL DEFAULT 0,
|
||
room_count BIGINT NOT NULL DEFAULT 0,
|
||
first_mic_at_ms BIGINT NOT NULL DEFAULT 0,
|
||
last_mic_at_ms BIGINT NOT NULL DEFAULT 0,
|
||
updated_at_ms BIGINT NOT NULL,
|
||
PRIMARY KEY (app_code, user_id, stat_date),
|
||
KEY idx_user_mic_daily_date (app_code, stat_date, mic_online_ms)
|
||
);
|
||
```
|
||
|
||
当前实现以 UTC 日期字符串切分 `stat_date`。跨天 session 必须按 UTC 日切分。例如 23:30 到 01:10，要拆成两天分别累计。后续如果产品需要按 App 运营时区切分，需要先新增明确时区配置和重算策略，不能在代码里隐式依赖机器本地时区。
|
||
|
||
### `user_mic_lifetime_stats`
|
||
|
||
保存用户累计值，避免任务系统每次扫 daily 表。
|
||
|
||
```sql
|
||
user_mic_lifetime_stats(
|
||
app_code VARCHAR(32) NOT NULL,
|
||
user_id BIGINT NOT NULL,
|
||
seat_occupied_ms BIGINT NOT NULL DEFAULT 0,
|
||
mic_online_ms BIGINT NOT NULL DEFAULT 0,
|
||
session_count BIGINT NOT NULL DEFAULT 0,
|
||
first_mic_at_ms BIGINT NOT NULL DEFAULT 0,
|
||
last_mic_at_ms BIGINT NOT NULL DEFAULT 0,
|
||
updated_at_ms BIGINT NOT NULL,
|
||
PRIMARY KEY (app_code, user_id)
|
||
);
|
||
```
|
||
|
||
任务判断“累计麦上在线 10 小时”时优先读 `user_mic_lifetime_stats.mic_online_ms`。
|
||
|
||
### `user_mic_event_consumption`
|
||
|
||
消费者幂等和跳过原因表。所有 room mic 事件先写入这张表，再推进 session/aggregate；重复 `event_id` 直接跳过，避免 `down` 重放重复累计。
|
||
|
||
```sql
|
||
user_mic_event_consumption(
|
||
app_code VARCHAR(32) NOT NULL,
|
||
event_id VARCHAR(128) NOT NULL,
|
||
event_type VARCHAR(64) NOT NULL,
|
||
mic_session_id VARCHAR(128) NOT NULL,
|
||
user_id BIGINT NOT NULL,
|
||
action VARCHAR(32) NOT NULL,
|
||
status VARCHAR(32) NOT NULL,
|
||
skip_reason VARCHAR(128) NOT NULL DEFAULT '',
|
||
created_at_ms BIGINT NOT NULL,
|
||
consumed_at_ms BIGINT NULL,
|
||
updated_at_ms BIGINT NOT NULL,
|
||
PRIMARY KEY (app_code, event_id),
|
||
KEY idx_user_mic_event_session (app_code, mic_session_id, created_at_ms),
|
||
KEY idx_user_mic_event_user (app_code, user_id, created_at_ms)
|
||
);
|
||
```
|
||
|
||
## Event Processing Rules
|
||
|
||
### `up`
|
||
|
||
处理 `RoomMicChanged(action=up)`：
|
||
|
||
1. 用 `app_code + event_id` 做幂等。
|
||
2. 用 `app_code + mic_session_id` upsert `user_mic_sessions`。
|
||
3. 设置 `status=pending_publish`。
|
||
4. 设置 `seat_started_at_ms = envelope.occurred_at_ms`。
|
||
5. 不增加 `mic_online_ms`。
|
||
|
||
### `publish_confirmed`
|
||
|
||
处理 `RoomMicChanged(action=publish_confirmed)`：
|
||
|
||
1. 找到 `mic_session_id` 对应 session。
|
||
2. 如果 session 已经是 `publishing/ended`，按幂等处理。
|
||
3. 设置 `publishing_started_at_ms`。
|
||
4. 设置 `status=publishing`。
|
||
5. 不立即增加 daily/lifetime，避免 open session 周期性重复累计。
|
||
|
||
`publishing_started_at_ms` 建议使用事件里的 `publish_event_time_ms`；如果为空，才使用 envelope 的 `occurred_at_ms`。
|
||
|
||
### `change`
|
||
|
||
处理 `RoomMicChanged(action=change)`：
|
||
|
||
- 不结束 session。
|
||
- 更新 `current_seat_no`。
|
||
- 不切断 `mic_online_ms`。
|
||
|
||
换麦是同一次上麦会话里的位置变化，不应把时长拆断。
|
||
|
||
### `down`
|
||
|
||
处理 `RoomMicChanged(action=down)`：
|
||
|
||
1. 找到 `mic_session_id` 对应 session。
|
||
2. 设置 `ended_at_ms` 和 `end_reason`。
|
||
3. 计算 `seat_occupied_ms = ended_at_ms - seat_started_at_ms`。
|
||
4. 如果已 `publishing`，计算 `mic_online_ms = ended_at_ms - publishing_started_at_ms`。
|
||
5. 按天切分写入 `user_mic_daily_stats`。
|
||
6. 增量写入 `user_mic_lifetime_stats`。
|
||
7. 设置 session `status=ended`。
|
||
|
||
如果没有 `publish_confirmed` 就下麦，`mic_online_ms=0`，但 `seat_occupied_ms` 仍可记录。
|
||
|
||
## Open Session Compensation
|
||
|
||
open session compensation 由 `cron-service` 调度，`user-service` 只暴露单批 `CompensateMicOpenSessions` 处理能力，用于兜底关闭 room-service down 事件缺失导致的异常 open session。补偿只修正用户麦时长事实，不反写 Room Cell，也不向客户端发送房间控制消息。
|
||
|
||
| Case | Action |
|
||
| --- | --- |
|
||
| `pending_publish` 超过 `pending_publish_max_age` | 关闭 session，`end_reason=compensated_publish_timeout`，`mic_online_ms=0` |
|
||
| `publishing` 超过 `publishing_session_max_age` | 关闭 session，`end_reason=compensated_publishing_max_window`，按确认发流后到截断点累计 `mic_online_ms` |
|
||
| 消费者停机后恢复 | room outbox worker 继续从位点扫描；cron-service 触发补偿批处理扫描 MySQL open session 兜底 |
|
||
|
||
补偿扫描使用 MySQL `FOR UPDATE SKIP LOCKED` 锁定候选 session。单批 claim、关闭、daily/lifetime 聚合和 outbox 写入在同一个事务内完成，避免关闭成功但派生事件丢失。
|
||
|
||
补偿关闭必须写 `end_reason=compensated_*`，不能伪装成用户主动下麦。补偿必须设置最大可累计窗口，避免房间事件缺失时把异常 open session 算成超长在线。当前默认配置在 cron-service：
|
||
|
||
| Config | Default | Meaning |
|
||
| --- | ---: | --- |
|
||
| `tasks.mic_open_session_compensation.enabled` | `true` | 是否启动异常 session 补偿调度 |
|
||
| `tasks.mic_open_session_compensation.interval` | `60s` | 没有积压时两轮扫描间隔 |
|
||
| `tasks.mic_open_session_compensation.batch_size` | `100` | 单批最多关闭 session 数 |
|
||
| `tasks.mic_open_session_compensation.pending_publish_max_age` | `2m` | pending 未确认发流的最大保留窗口 |
|
||
| `tasks.mic_open_session_compensation.publishing_session_max_age` | `12h` | publishing session 最大可累计窗口 |
|
||
|
||
## Derived Events And Consumers
|
||
|
||
用户麦时长消费者关闭 session 时，在同一个 MySQL 事务内写入 user-service `user_outbox` 派生事件，供 host stats、任务、活动和 BI 消费。派生事件不能替代基础事实表，消费者失败不影响 `user_mic_sessions`、daily 和 lifetime 事实。
|
||
|
||
| Event | Trigger | Consumer |
|
||
| --- | --- | --- |
|
||
| `UserMicSessionClosed` | 一条 session 正常或补偿结束 | host stats、activity task、BI |
|
||
| `UserMicDailyStatsUpdated` | daily stats 有增量 | task progress、growth system |
|
||
| `UserMicLifetimeStatsUpdated` | lifetime stats 有增量 | lifetime task cache |
|
||
|
||
事件幂等键：
|
||
|
||
| Event | `event_id` |
|
||
| --- | --- |
|
||
| `UserMicSessionClosed` | `UserMicSessionClosed:{mic_session_id}` |
|
||
| `UserMicDailyStatsUpdated` | `UserMicDailyStatsUpdated:{mic_session_id}:{stat_date}` |
|
||
| `UserMicLifetimeStatsUpdated` | `UserMicLifetimeStatsUpdated:{mic_session_id}` |
|
||
|
||
`UserMicSessionClosed` payload 至少包含 `app_code`、`user_id`、`room_id`、`mic_session_id`、`seat_occupied_ms`、`mic_online_ms`、`seat_started_at_ms`、`ended_at_ms`、`end_reason`、`closed_event_id`。
|
||
|
||
daily/lifetime update payload 使用 delta 语义，包含 `seat_occupied_delta_ms`、`mic_online_delta_ms`、`session_count_delta` 和 `updated_at_ms`；daily 事件额外包含 `stat_date`、`room_count_delta`。
|
||
|
||
host/Agency/BD 统计应该优先消费 `UserMicSessionClosed` 或读取 user mic facts 派生关系快照，不应该再直接消费 `RoomMicChanged` 重算同一套用户时长。
|
||
|
||
## Task Usage
|
||
|
||
任务系统不要自己消费房间事件来算麦位时间，应该读取用户麦上时长事实。
|
||
|
||
示例任务：
|
||
|
||
```text
|
||
task: become_host_online_10h
|
||
condition:
|
||
user must currently be host
|
||
user_mic_lifetime_stats.mic_online_ms >= 10 * 60 * 60 * 1000
|
||
```
|
||
|
||
注意：任务判断时校验“当前是否主播”，但时长使用用户历史累计，不要求这些时长发生在成为主播之后。
|
||
|
||
如果某个任务明确要求“成为主播之后再累计 10 小时”，应该新增任务条件：
|
||
|
||
```text
|
||
sum user_mic_daily_stats where stat_date/time >= host_profile.first_became_host_at_ms
|
||
```
|
||
|
||
这属于任务政策，不属于基础统计口径。
|
||
|
||
## Relationship To Host Salary
|
||
|
||
用户麦上在线时长是基础事实；主播工资是派生事实。
|
||
|
||
| Use Case | Recommended Source |
|
||
| --- | --- |
|
||
| 用户成长任务 | `user_mic_lifetime_stats` |
|
||
| 主播入门任务 | `user_mic_lifetime_stats` + 当前 host 身份 |
|
||
| 主播周期任务 | `user_mic_daily_stats` 按周期汇总 |
|
||
| 主播工资 | 从 `user_mic_sessions` 或 `user_mic_daily_stats` 派生，并按工资政策决定是否只算 host 生效后的时间 |
|
||
| Agency/BD 归属工资 | 需要额外关系快照，不直接用基础用户累计 |
|
||
|
||
因此后续 `host_daily_stats` 不应该是唯一时长来源。它可以从 `user_mic_sessions` 派生，并附带 Agency/BD 关系快照，用于工资和团队统计。
|
||
|
||
## API Suggestions
|
||
|
||
### Internal Query
|
||
|
||
```protobuf
|
||
message GetUserMicLifetimeStatsRequest {
|
||
RequestMeta meta = 1;
|
||
int64 user_id = 2;
|
||
}
|
||
|
||
message UserMicLifetimeStats {
|
||
int64 user_id = 1;
|
||
int64 seat_occupied_ms = 2;
|
||
int64 mic_online_ms = 3;
|
||
int64 session_count = 4;
|
||
int64 first_mic_at_ms = 5;
|
||
int64 last_mic_at_ms = 6;
|
||
int64 updated_at_ms = 7;
|
||
string app_code = 8;
|
||
}
|
||
|
||
message GetUserMicLifetimeStatsResponse {
|
||
UserMicLifetimeStats stats = 1;
|
||
}
|
||
```
|
||
|
||
当前 proto 已在 `UserService` 暴露 `GetUserMicLifetimeStats(user_id)`。区间查询后续再加，不把未稳定的 range 语义提前暴露给客户端或任务系统。
|
||
|
||
### App Query
|
||
|
||
个人页首屏不要返回麦位明细。二级页可以提供：
|
||
|
||
```http
|
||
GET /api/v1/users/me/mic-stats?range=lifetime
|
||
GET /api/v1/users/me/mic-stats?from_ms=...&to_ms=...
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"seat_occupied_ms": 39600000,
|
||
"mic_online_ms": 36000000,
|
||
"session_count": 18,
|
||
"first_mic_at_ms": 1777000000000,
|
||
"last_mic_at_ms": 1777996800000
|
||
}
|
||
```
|
||
|
||
## Implementation Sequence
|
||
|
||
1. 已增加 `user_mic_sessions`、`user_mic_daily_stats`、`user_mic_lifetime_stats`、`user_mic_event_consumption`。
|
||
2. 已调整 room-service：释放麦位路径统一产出 `RoomMicChanged(action=down)`，包括 leave、kick、close、RTC stopped、publish timeout。
|
||
3. 已增加 user-service mic time consumer，消费 `RoomMicChanged`。
|
||
4. 已实现 session 状态机：`up -> publish_confirmed -> down`，支持 `change` 不切断。
|
||
5. 已实现 daily/lifetime 聚合，跨 UTC 日切分。
|
||
6. 已增加内部查询 RPC `GetUserMicLifetimeStats`，供任务、主播、后台读取 lifetime 聚合。
|
||
7. 已增加 `CompensateMicOpenSessions`，由 cron-service 调度关闭异常 open session。
|
||
8. 已增加 user mic outbox，产出 `UserMicSessionClosed`、`UserMicDailyStatsUpdated`、`UserMicLifetimeStatsUpdated`。
|
||
9. 任务系统接入 `user_mic_lifetime_stats`，不要重复消费 room 事件。
|
||
10. host stats 从 user mic facts 或 user mic outbox 派生，不直接重复处理 Room Cell 麦位事件。
|
||
|
||
## Verification Matrix
|
||
|
||
| Scenario | Expected |
|
||
| --- | --- |
|
||
| 普通用户上麦并确认发流 10 分钟后下麦 | `mic_online_ms` 增加 10 分钟 |
|
||
| 普通用户只占麦但未发流，超时下麦 | `seat_occupied_ms` 有值，`mic_online_ms=0` |
|
||
| 用户换麦位 | session 不结束，时长连续 |
|
||
| 用户离房释放麦位 | session 结束并累计到 daily/lifetime |
|
||
| 用户被踢释放麦位 | session 结束，`end_reason=kick` |
|
||
| 房间关闭 | 所有 open session 结束 |
|
||
| 同一事件重复消费 | 不重复累计 |
|
||
| 用户跨天上麦 | daily stats 拆成两天 |
|
||
| 用户不是主播时累计 10 小时，后续成为主播 | 读取 lifetime 后主播任务可直接完成 |
|
||
| 工资只要求 host 期间时长 | 工资派生层按 host 生效时间过滤，不改基础累计 |
|
||
| `mic_session_id` 为空的麦位事件 | 不累计，进入异常队列或告警 |
|
||
| host stats 消费用户麦时长派生事件 | 不重复累计 room outbox 同一事件 |
|
||
|
||
## Critical Rules
|
||
|
||
- 基础麦位时长按用户累计，不按主播身份累计。
|
||
- 任务判断可以检查当前身份，但不要把历史时长清零。
|
||
- `pending_publish` 默认不算 `mic_online_ms`。
|
||
- `change` 不结束 session。
|
||
- Redis 不能作为时长事实来源。
|
||
- 客户端上报时长不能作为权威，只能作为辅助诊断。
|
||
- 所有统计写入必须带 `app_code`。
|
||
- `mic_session_id` 是会话幂等和新旧事件隔离的核心字段，不能用用户当前是否在麦位替代。
|
||
- host stats、任务和活动读取用户麦时长事实，不应各自重复消费 room 麦位事件。
|