# Voice Room Mic And Room Management Development Guide

本文档定义语音房“麦位与房间管理”下一阶段开发设计。目标是在现有 `MicUp/MicDown/ChangeMicSeat/MuteUser/KickUser` 基础上补齐权限矩阵、锁麦、聊天开关、管理员管理、解封、时长型管控和 RTC 推流联动。

## Scope

| Capability | Owner | Required Result |
| --- | --- | --- |
| 麦位状态 | `room-service` | Room Cell 串行维护麦位占用、锁定和换位 |
| 房间角色 | `room-service` | owner、host、admin、audience 权限可判定、可恢复 |
| 管理命令入口 | `gateway-service` | HTTP 只做鉴权和协议转换，actor 只能来自 access token |
| IM 发言守卫 | `gateway-service` + `room-service` | 腾讯 IM 发言前回查禁言、封禁、聊天开关和 presence |
| RTC 推流策略 | Client + Tencent RTC | 服务端给出麦位事实，客户端按麦位事实切换 TRTC role 或推流状态 |
| 房间系统事件 | `room-service` + Tencent IM | 管理动作进入 outbox，并同步推送房间系统消息 |

## Non-Goals

| Non-goal | Reason |
| --- | --- |
| 不在 gateway 判断房间权限 | gateway 不持有 Room Cell，不能复制权限逻辑 |
| 不把 RTC 在线态写进 Room Cell | RTC 连接态属于腾讯 RTC，Room Cell 只保存业务麦位事实 |
| 不做客户端 socket 管理 | 长连接和群消息继续由腾讯 IM 承担 |
| 不把全局封禁放进 room-service | 全局用户状态属于 user-service 或后台风控服务 |
| 不在本阶段做复杂主持排班 | 当前只补房间内即时管理能力 |

## Current State

现有能力：

| Feature | Status | Current Behavior |
| --- | --- | --- |
| 上麦 | `DONE` | `MicUp` 校验用户在 presence、目标麦位存在、未锁、未占用 |
| 下麦 | `DONE` | `MicDown` 可把指定 target 从麦位移下 |
| 换麦 | `DONE` | `ChangeMicSeat` 原子清空源麦位并占用目标麦位 |
| 禁言 | `DONE` | `MuteUser` 写 `MuteUsers` 集合，`CheckSpeakPermission` 拒绝发言 |
| 踢人 | `DONE` | `KickUser` 移除 presence、释放麦位、写 `BanUsers` 集合 |
| 麦位锁定字段 | `PARTIAL` | `SeatState.locked` 和 `RoomState.MicSeat.Locked` 已存在，但没有命令 |
| 管理员集合 | `PARTIAL` | `RoomState.AdminUsers` 和 snapshot `admin_user_ids` 已存在，但没有管理命令 |
| 聊天开关字段 | `PARTIAL` | `chat_enabled` 已影响 `CheckSpeakPermission`，但没有命令 |
| RTC 发流确认 | `DONE` | `MicUp` 进入 `pending_publish`，客户端或 RTC webhook 确认后进入 `publishing`，超时自动下麦 |

现有主要缺口：

- 管理命令没有统一权限矩阵。
- 管理员增删、主持转移、owner 转让未实现。
- 锁麦、聊天开关、解封没有命令。
- 禁言/封禁没有过期时间、原因、操作者审计字段。
- RTC token 仍未按麦位事实动态返回 `anchor/audience`；当前由客户端在 `MicUp` 成功后切换角色并确认发流。

## Target State

本阶段完成后，房间管理应该满足：

- 普通用户只能自助上麦、主动下麦、主动离房和送礼。
- owner/host/admin 可以管理麦位、禁言、踢人和聊天开关。
- 只有 owner 可以增删 admin、转 host；转 owner 推迟到后续房间资产和后台审计阶段。
- 锁麦位后任何角色都不能上麦或换入，必须先解锁。
- 被禁言用户不能发公屏，但仍可收消息、上麦规则由权限策略决定。
- 被踢/ban 用户不能 JoinRoom、不能 IM 进群、不能发言、不能拿 RTC token；已在腾讯 IM 群内的用户必须通过 IM bridge 触发踢出群副作用。
- 所有管理动作写 command log、snapshot、outbox，并可恢复。
- 客户端通过房间系统消息和最新 snapshot 修正本地 UI。

## Role Model

### Roles

| Role | Meaning | Source |
| --- | --- | --- |
| `owner` | 房间所有者，最高权限 | `RoomState.OwnerUserID` |
| `host` | 主持人，负责房间现场管理 | `RoomState.HostUserID` |
| `admin` | 房间管理员 | `RoomState.AdminUsers` 中除 owner/host 外的用户 |
| `audience` | 普通观众 | `OnlineUsers[user].Role` 或默认值 |

角色判定不要只信 `RoomUser.role`。权威顺序：

```text
if actor == owner_user_id -> owner
else if actor == host_user_id -> host
else if admin_users[actor] -> admin
else -> audience
```

`JoinRoom.role` 只能作为展示和默认入房角色，不能让客户端自报 `admin` 获得权限。

### Permission Matrix

| Action | Owner | Host | Admin | Audience |
| --- | --- | --- | --- | --- |
| 自己上麦 `MicUp` | allow | allow | allow | allow |
| 自己下麦 `MicDown(self)` | allow | allow | allow | allow |
| 下别人麦 `MicDown(target)` | allow | allow | allow | deny |
| 换别人麦 `ChangeMicSeat(target)` | allow | allow | allow | deny |
| 锁/解锁麦位 | allow | allow | allow | deny |
| 禁言/解禁 | allow | allow | allow | deny |
| 踢人/ban | allow | allow | allow | deny |
| 解封/unban | allow | allow | deny | deny |
| 开关公屏 | allow | allow | allow | deny |
| 增删 admin | allow | deny | deny | deny |
| 转 host | allow | deny | deny | deny |
| 转 owner（后续批次） | allow | deny | deny | deny |
| 关房（后续批次） | allow | deny by default | deny | deny |

补充约束：

- owner 不能被 host/admin 踢、禁言、下麦或移出管理员集合。
- host 不能被普通 admin 踢、禁言或降级。
- actor 对自己执行 `MuteUser` 和 `KickUser` 默认拒绝，避免错误操作造成不可恢复状态。
- 非 presence 用户不能被设为 host/admin，除非后续明确支持预设管理员。
- 锁麦是硬锁，owner/host/admin 也不能直接上锁定麦位；管理员需要先解锁，或先下麦再锁麦。
- 管理命令 actor 必须在当前房间 presence 中；离房后的 host/admin 不能继续远程管理，重新 JoinRoom 后恢复其持久角色。

## Command Design

现有命令保留：

- `MicUp`
- `MicDown`
- `ChangeMicSeat`
- `MuteUser`
- `KickUser`

本阶段新增命令：

| Command | Purpose | Notes |
| --- | --- | --- |
| `SetMicSeatLock` | 锁定或解锁指定麦位 | 首版只允许锁空麦位 |
| `SetChatEnabled` | 开启或关闭公屏 | 影响 `CheckSpeakPermission` |
| `SetRoomAdmin` | 添加或移除管理员 | 只有 owner 可执行 |
| `TransferRoomHost` | 转移主持人 | 只有 owner 可执行 |
| `UnbanUser` | 解除房间 ban | 用户可重新 JoinRoom |

后续批次命令：

| Command | Reason To Defer |
| --- | --- |
| `TransferRoomOwner` | 影响房间资产、收益、后台审计和纠纷处理，本阶段只做现场主持转移 |
| `CloseRoom` | 属于房间生命周期管理，需要和房间列表、搜索、推荐和恢复策略一起设计 |

### `SetMicSeatLock`

语义：

- `locked=true` 锁麦。
- `locked=false` 解锁。
- 首版锁麦只允许目标麦位为空；如果麦位有人，返回 `CONFLICT`。
- 解锁空麦位或已解锁麦位幂等返回当前快照，不重复写事件。

拒绝锁 occupied seat 的原因：

- 避免一个命令同时产生“下麦”和“锁麦”两个 UI 事件。
- 如果管理端要清空并锁定，应先 `MicDown(target)`，再 `SetMicSeatLock(seat_no,true)`。

### `SetChatEnabled`

语义：

- `enabled=false` 后 `CheckSpeakPermission` 返回 `chat_disabled`。
- 关闭公屏对所有用户自发公屏消息生效，包括 owner/host/admin。
- 系统消息和管理消息不受影响，因为它们由 room-service 通过腾讯 IM REST 发布。
- 重复设置相同值幂等，不重复写事件。

### `SetRoomAdmin`

语义：

- `enabled=true` 添加管理员。
- `enabled=false` 移除管理员。
- owner/host 永远属于管理集合，不能通过该命令移除。
- target 必须在当前房间 presence 中，避免后台误把不存在用户加入房间管理。
- admin 离房后保留 admin 身份，重新 JoinRoom 后继续具备 admin 权限。
- admin 被 KickUser/ban 后必须从 `AdminUsers` 删除；Unban 后不自动恢复 admin，必须 owner 重新添加。

### `TransferRoomHost`

语义：

- 新 host 必须在 room presence 中。
- 新 host 自动进入 `AdminUsers`。
- 旧 host 是否仍为 admin：首版保留为 admin，避免主持交接后失去管理权限造成现场中断。
- host 主动离房后 `HostUserID` 不自动变化，但离房期间不能执行管理命令。
- 当前 host 不能被 KickUser 直接踢出；owner 必须先 `TransferRoomHost`，再按普通 admin/audience 规则管理旧 host。

### Deferred `TransferRoomOwner`

语义：

- 本阶段不实现 HTTP/RPC，只保留后续语义边界。
- 新 owner 必须在 room presence 中。
- 新 owner 自动成为 owner、host 和 admin。
- 旧 owner 是否降级：首版降级为 admin，不继续是 host，避免双 owner。
- 转 owner 必须写强审计事件。

### `UnbanUser`

语义：

- 从 `BanUsers` 删除 target。
- 不自动 JoinRoom；用户必须重新调用 `JoinRoom`。
- 重复 unban 已不在 ban 集合的用户幂等返回当前快照。
- 不恢复被 KickUser 时移除的 admin 身份、麦位或 presence。

### `KickUser` / Room Ban Extension

`KickUser` 表达“踢出房间并写入房间 ban 集合”。如果本阶段要支持限时 ban，直接把请求和快照契约调整为：

```proto
message KickUserRequest {
  RequestMeta meta = 1;
  int64 target_user_id = 2;
  int64 duration_ms = 3;
  string reason = 4;
}
```

语义：

- `duration_ms=0` 表示永久 ban，直到 `UnbanUser`。
- `duration_ms>0` 表示 ban 到 `now + duration_ms`；过期后 JoinRoom、IM 进群和 RTC token 可以重新通过。
- KickUser 成功后必须原子移除 target 的 presence、麦位和 admin 身份，并写 `BanUsers[target]`。
- KickUser 成功提交后，outbox/IM bridge 必须触发腾讯 IM 群成员踢出副作用；副作用失败不回滚 Room Cell，但必须重试。
- 在 IM 踢出副作用成功前，`CheckSpeakPermission` 和 `VerifyRoomPresence` 仍必须拒绝 target，避免其继续发言或重新进群。

### `MuteUser` Extension

如果需要限时禁言，`MuteUser` 请求和快照契约直接调整为：

```proto
message MuteUserRequest {
  RequestMeta meta = 1;
  int64 target_user_id = 2;
  bool muted = 3;
  int64 duration_ms = 4;
  string reason = 5;
}
```

语义：

- `muted=true,duration_ms=0` 表示永久禁言，直到手动解除。
- `muted=true,duration_ms>0` 表示禁言到 `now + duration_ms`。
- `muted=false` 表示解除禁言，忽略 `duration_ms`。
- 当前 snapshot 仍保留 `mute_user_ids`，后续可追加 `mute_states` 暴露过期时间。
- MuteUser 只阻断公屏发言，不移除 presence、不影响收消息、不改变 RTC 麦位；如果需要离房必须使用 KickUser。

## Proto Changes

只允许追加字段、消息和 RPC，不能改已有字段含义或编号。

本阶段固定追加：

```proto
message SetMicSeatLockRequest {
  RequestMeta meta = 1;
  int32 seat_no = 2;
  bool locked = 3;
}

message SetMicSeatLockResponse {
  CommandResult result = 1;
  RoomSnapshot room = 2;
}

message SetChatEnabledRequest {
  RequestMeta meta = 1;
  bool enabled = 2;
}

message SetChatEnabledResponse {
  CommandResult result = 1;
  RoomSnapshot room = 2;
}

message SetRoomAdminRequest {
  RequestMeta meta = 1;
  int64 target_user_id = 2;
  bool enabled = 3;
}

message SetRoomAdminResponse {
  CommandResult result = 1;
  RoomSnapshot room = 2;
}

message TransferRoomHostRequest {
  RequestMeta meta = 1;
  int64 target_user_id = 2;
}

message TransferRoomHostResponse {
  CommandResult result = 1;
  RoomSnapshot room = 2;
}

message UnbanUserRequest {
  RequestMeta meta = 1;
  int64 target_user_id = 2;
}

message UnbanUserResponse {
  CommandResult result = 1;
  RoomSnapshot room = 2;
}
```

如果本阶段启用限时 mute/ban，再追加 moderation state 和 `RoomSnapshot` 字段：

```proto
message ModerationState {
  int64 user_id = 1;
  int64 expires_at_ms = 2;
  int64 operator_user_id = 3;
  string reason = 4;
}

message RoomSnapshot {
  ...
  repeated ModerationState mute_states = 16;
  repeated ModerationState ban_states = 17;
}
```

字段规则：

- `mute_user_ids` / `ban_user_ids` 输出当前仍有效的 user_id，供只关心布尔状态的客户端使用。
- `mute_states` / `ban_states` 输出过期时间、原因和操作者，用于完整管理面展示。
- 快照和恢复链路必须使用同一套 state 结构，不能同时维护两套来源。

`RoomCommandService` 追加：

```proto
rpc SetMicSeatLock(SetMicSeatLockRequest) returns (SetMicSeatLockResponse);
rpc SetChatEnabled(SetChatEnabledRequest) returns (SetChatEnabledResponse);
rpc SetRoomAdmin(SetRoomAdminRequest) returns (SetRoomAdminResponse);
rpc TransferRoomHost(TransferRoomHostRequest) returns (TransferRoomHostResponse);
rpc UnbanUser(UnbanUserRequest) returns (UnbanUserResponse);
```

`TransferRoomOwner` 和 `CloseRoom` 可以放到下一批，如果本阶段只做现场管理。

## HTTP API Design

gateway 追加 HTTP 路由：

```text
POST /api/v1/rooms/mic/lock
POST /api/v1/rooms/chat/enabled
POST /api/v1/rooms/admin/set
POST /api/v1/rooms/host/transfer
POST /api/v1/rooms/user/unban
```

所有请求都必须支持 `command_id`：

```json
{
  "room_id": "room_1001",
  "command_id": "cmd_room_1001_lock_seat_1_10001_1"
}
```

### Command Idempotency

`command_id` 是房间命令幂等键，不是链路追踪 ID。

规则：

- 幂等作用域为 `(app_code, room_id, command_id)`。
- room-service 持久化 command log 时必须保存 `command_type` 和 payload hash。
- 重复提交相同 `(app_code, room_id, command_id, command_type, payload_hash)` 返回幂等成功，不重复执行 mutate、不重复写 outbox。
- 重复提交相同 `(app_code, room_id, command_id)` 但 `command_type` 或 payload hash 不一致，返回 `CONFLICT`。
- 幂等返回可以携带当前最新 snapshot，但 `CommandResult.applied=false`，客户端按 snapshot `version` 修正 UI。
- 业务 no-op 也必须写入幂等记录或 command log；例如重复 `SetChatEnabled(false)` 不能因为未递增版本而丢失幂等保护。
- `request_id` 只用于追踪，可以每次重试不同；不能参与幂等判定。

### Lock Mic

```json
{
  "room_id": "room_1001",
  "command_id": "cmd_lock_1",
  "seat_no": 3,
  "locked": true
}
```

### Chat Enabled

```json
{
  "room_id": "room_1001",
  "command_id": "cmd_chat_off_1",
  "enabled": false
}
```

### Set Admin

```json
{
  "room_id": "room_1001",
  "command_id": "cmd_admin_add_10002",
  "target_user_id": 10002,
  "enabled": true
}
```

### Transfer Host

```json
{
  "room_id": "room_1001",
  "command_id": "cmd_host_to_10002",
  "target_user_id": 10002
}
```

### Unban

```json
{
  "room_id": "room_1001",
  "command_id": "cmd_unban_10002",
  "target_user_id": 10002
}
```

## RoomState Changes

短期最小变更：

```go
type RoomState struct {
    ...
    HostUserID int64
    ChatEnabled bool
    AdminUsers map[int64]bool
    BanUsers map[int64]bool
    MuteUsers map[int64]bool
}
```

这些字段已存在。

如果本阶段启用时长型禁言和封禁，内部状态替换为：

```go
type UserModerationState struct {
    UserID int64
    ExpiresAtMS int64
    OperatorUserID int64
    Reason string
}

MuteUsers map[int64]UserModerationState
BanUsers map[int64]UserModerationState
```

开发策略：

- snapshot 输出 `mute_user_ids`、`ban_user_ids`、`mute_states` 和 `ban_states` 时必须来自同一份状态。
- 请求里没有 `duration_ms` 时按永久处理，不能依赖旧命令语义分支。
- `CheckSpeakPermission`、`VerifyRoomPresence`、`JoinRoom` 和 `/api/v1/rtc/token` 都只看未过期的 ban/mute。
- 如果本阶段不做限时 ban/mute，就不要追加 `duration_ms`、`mute_states`、`ban_states`；保留 bool set，避免半套协议。

## Authorization Design

在 room-service 内新增统一权限 helper：

```go
type roomRole string

const (
    roleOwner roomRole = "owner"
    roleHost roomRole = "host"
    roleAdmin roomRole = "admin"
    roleAudience roomRole = "audience"
)

func actorRole(state *RoomState, actorUserID int64) roomRole
func canManageMic(state *RoomState, actorUserID int64, targetUserID int64) bool
func canManageModeration(state *RoomState, actorUserID int64, targetUserID int64) bool
func canManageAdmins(state *RoomState, actorUserID int64) bool
func canTransferHost(state *RoomState, actorUserID int64) bool
```

权限失败统一返回：

```text
PERMISSION_DENIED
```

不要在错误信息里暴露过多角色细节，避免客户端据此枚举房间管理结构。服务端日志可以记录：

```text
request_id, command_id, room_id, actor_user_id, target_user_id, action, actor_role, denied_reason
```

## RTC Push Linkage

服务端不直接控制 TRTC 推流，但必须区分“业务占麦成功”和“RTC 已确认发布音频”：

| Room State | Client RTC Behavior |
| --- | --- |
| 用户不在麦位 | TRTC role `audience`，不能发布音频 |
| `MicUp` 成功且 `SeatState.user_id == self`、`publish_state=pending_publish` | 客户端切 `anchor` 并 `startLocalAudio`，UI 展示为等待发流确认 |
| SDK 本地发流成功后调用 `ConfirmMicPublishing(mic_session_id, room_version, event_time_ms)` | 服务端把当前麦位切到 `publish_state=publishing` |
| `pending_publish` 超过 `publish_deadline_ms` 未确认 | 服务端自动 `MicDown(reason=publish_timeout)`，客户端停止上行并切回 `audience` |
| `MicDown`/`KickUser`/`LeaveRoom` 后麦位释放 | 客户端停止本地音频上行并切回 `audience` |
| `ChangeMicSeat` | 客户端只更新 UI，不需要重进 RTC |
| `SetMicSeatLock` | 客户端更新麦位 UI，不影响当前 RTC 连接 |

后续接 RTC webhook 时，payload 必须带 `mic_session_id`、`room_version`、`event_time_ms`。room-service 只接受当前 session 且事件时间不旧于已接受事件的数据，旧 audience/leave 事件不能清理新的上麦会话。

`/api/v1/rtc/token` 首版仍返回 `audience`。后续如果要服务端返回 `anchor`，必须在签 token 时读取 Room Cell 麦位事实：

```text
if user is on mic -> role=anchor
else -> role=audience
```

但不要把 RTC 在线态写入 Room Cell。

## Event Design

新增或复用 room outbox 事件：

| Event Type | Trigger | IM Event Type |
| --- | --- | --- |
| `RoomMicChanged` | MicUp/MicDown/ChangeMicSeat | `room_mic_up/down/change` |
| `RoomMicSeatLocked` | SetMicSeatLock | `room_mic_seat_locked` |
| `RoomChatEnabledChanged` | SetChatEnabled | `room_chat_enabled_changed` |
| `RoomAdminChanged` | SetRoomAdmin | `room_admin_changed` |
| `RoomHostTransferred` | TransferRoomHost | `room_host_transferred` |
| `RoomUserMuted` | MuteUser | `room_user_muted` |
| `RoomUserKicked` | KickUser | `room_user_kicked` |
| `RoomUserUnbanned` | UnbanUser | `room_user_unbanned` |

### Event Payload Contract

所有 room outbox 事件和腾讯 IM 系统消息必须使用同一套字段语义，避免客户端按不同来源写两套解析。

| Event Type | Required Payload |
| --- | --- |
| `RoomMicChanged` | `event_id`、`room_id`、`room_version`、`actor_user_id`、`target_user_id`、`from_seat`、`to_seat`、`action`、`mic_session_id`、`publish_state`、`reason`、`publish_deadline_ms`、`publish_event_time_ms` |
| `RoomMicSeatLocked` | `event_id`、`room_id`、`room_version`、`actor_user_id`、`seat_no`、`locked` |
| `RoomChatEnabledChanged` | `event_id`、`room_id`、`room_version`、`actor_user_id`、`enabled` |
| `RoomAdminChanged` | `event_id`、`room_id`、`room_version`、`actor_user_id`、`target_user_id`、`enabled` |
| `RoomHostTransferred` | `event_id`、`room_id`、`room_version`、`actor_user_id`、`old_host_user_id`、`new_host_user_id` |
| `RoomUserMuted` | `event_id`、`room_id`、`room_version`、`actor_user_id`、`target_user_id`、`muted`、`expires_at_ms`、`reason` |
| `RoomUserKicked` | `event_id`、`room_id`、`room_version`、`actor_user_id`、`target_user_id`、`expires_at_ms`、`reason` |
| `RoomUserUnbanned` | `event_id`、`room_id`、`room_version`、`actor_user_id`、`target_user_id` |

事件要求：

- `event_id` 由 outbox 生成。
- `room_version` 必须等于命令提交后的版本。
- 同步 IM publish 失败不回滚命令。
- outbox worker 后续补投。
- 客户端按 `event_id` 去重，按 `room_version` 判断是否需要拉最新 snapshot。
- 客户端不能把 `room_mic_up` 当成音频已发布，只能在 `publish_state=publishing` 后展示为真正发流中。
- IM 系统消息只是 UI 通知；KickUser 的群成员踢出是独立 side effect，必须由 outbox/IM bridge 可重试执行。

### IM Side Effects

`KickUser`/ban 成功提交后，需要两个层面的外部效果：

| Side Effect | Required Behavior |
| --- | --- |
| 房间系统消息 | 发布 `room_user_kicked`，让客户端立即关闭麦位、弹出提示、停止 RTC 上行 |
| 腾讯 IM 群成员移除 | 调用腾讯 IM REST 把 target 从房间群移出，避免继续收公屏消息 |
| 腾讯 IM 失败补偿 | 不回滚 Room Cell；outbox 保留待处理记录，worker 重试直到成功或进入人工告警 |
| 失败窗口守卫 | IM 移除成功前，`CheckSpeakPermission` 继续拒绝发言，`VerifyRoomPresence` 继续拒绝进群 |

首版不在 room-service 管理客户端 socket；如果腾讯 IM REST 持续失败，服务端安全边界是“不能发言、不能重新进群、不能拿 RTC token”，但可能短时间继续收到群消息，需要告警和补偿。

## Recovery Replay

每个新增命令都必须加入：

- `command` 模型。
- `command.Serialize/Deserialize`。
- `replay` 分支。
- command log 测试。

恢复语义：

| Command | Replay Behavior |
| --- | --- |
| `SetMicSeatLock` | 设置 `MicSeats[index].Locked` |
| `SetChatEnabled` | 设置 `ChatEnabled` |
| `SetRoomAdmin` | 增删 `AdminUsers[target]`，但 owner/host 保持 admin |
| `TransferRoomHost` | 更新 `HostUserID`，新 host 加入 `AdminUsers` |
| `UnbanUser` | 删除 `BanUsers[target]` |
| `MuteUser` with duration | 如果恢复时已过期，清理；否则保留 |
| `KickUser` with duration | 恢复 presence/mic/admin 移除结果；ban 未过期时保留，已过期时不恢复 ban |

如果支持时长型禁言/封禁，需要有清理 worker 或在 guard 查询时懒清理过期状态。首版建议 guard 查询时懒判断：

```text
if expires_at_ms > 0 && now >= expires_at_ms -> treat as not muted/banned
```

是否立即写回清理结果可以后续由 moderation sweep worker 完成。

恢复时不要重新执行腾讯 IM 踢人副作用；IM side effect 只从 outbox 待投递记录补偿，不从 command replay 直接调用外部服务。

## Validation Rules

| Input | Rule | Error |
| --- | --- | --- |
| `seat_no` | 必须存在于当前房间麦位 | `INVALID_ARGUMENT` |
| `target_user_id` | 必须大于 0 | `INVALID_ARGUMENT` |
| actor | 必须来自 `RequestMeta.actor_user_id` | `UNAUTHENTICATED` or `INVALID_ARGUMENT` |
| room | 必须 active | `FAILED_PRECONDITION` |
| locked occupied seat | 首版拒绝 | `CONFLICT` |
| permission denied | actor 权限不足 | `PERMISSION_DENIED` |
| target is owner | host/admin 不能管理 owner | `PERMISSION_DENIED` |
| self kick/mute | 默认拒绝 | `INVALID_ARGUMENT` or `PERMISSION_DENIED` |
| `command_id` duplicate with different payload | 同房间同 command_id 不能复用不同 payload | `CONFLICT` |
| `duration_ms` | `>=0`，上限按配置限制，首版建议不超过 30 天 | `INVALID_ARGUMENT` |
| `reason` | trim 后最多 128 字符，不写入客户端不可见敏感信息 | `INVALID_ARGUMENT` |
| target is current host | 首版不能直接 KickUser，owner 需先转 host | `PERMISSION_DENIED` |

## Implementation Order

1. 新增 room-service 权限 helper 和单测，先接入现有 `MicDown/ChangeMicSeat/MuteUser/KickUser`。
2. 补齐 command_id payload hash 校验，确保重复 command_id 不会静默吞掉不同请求。
3. 追加 proto：`SetMicSeatLock`、`SetChatEnabled`、`SetRoomAdmin`、`TransferRoomHost`、`UnbanUser`；如果本阶段启用限时管控，再追加 moderation state 和 duration 字段。
4. 运行 `make proto`，提交生成的 `.pb.go` 和 `_grpc.pb.go`。
5. 扩展 gateway room client、HTTP handler 和 OpenAPI。
6. 新增 command 模型和 `Deserialize` 分支。
7. 在 room-service 实现新增命令，全部走 `mutateRoom`。
8. 新增 room events，接入 outbox 和腾讯 IM system event。
9. 为 KickUser 接入腾讯 IM 群成员移除 side effect，失败不回滚命令但必须由 outbox worker 补偿。
10. 扩展 recovery replay，确保 replay 不直接调用外部 IM。
11. 补全单元测试、gateway transport 测试和 outbox/IM bridge 补偿测试。
12. 客户端联调麦位 UI、系统消息和 RTC 推流切换。

## Test Plan

### Permission Tests

| Case | Expected |
| --- | --- |
| audience 下别人麦 | `PERMISSION_DENIED` |
| audience 自己下麦 | success |
| admin 下 audience 麦 | success |
| admin 下 owner 麦 | `PERMISSION_DENIED` |
| host 禁言 audience | success |
| admin 禁言 host | `PERMISSION_DENIED` |
| owner 添加 admin | success |
| host 添加 admin | `PERMISSION_DENIED` |
| admin 解封用户 | `PERMISSION_DENIED` |
| host 解封用户 | success |

### Mic Tests

| Case | Expected |
| --- | --- |
| 锁空麦 | `SeatState.locked=true`，写事件 |
| 重复锁同一空麦 | 幂等返回，不重复事件 |
| 锁 occupied 麦 | `CONFLICT` |
| 解锁已锁麦 | `SeatState.locked=false` |
| locked seat MicUp | `PERMISSION_DENIED` |
| locked seat ChangeMicSeat | `PERMISSION_DENIED` |
| owner 上 locked seat | `PERMISSION_DENIED`，必须先解锁 |

### Chat Tests

| Case | Expected |
| --- | --- |
| SetChatEnabled false | snapshot `chat_enabled=false` |
| chat disabled 后发言守卫 | `allowed=false, reason=chat_disabled` |
| SetChatEnabled true | 发言守卫恢复正常 |

### Admin And Host Tests

| Case | Expected |
| --- | --- |
| owner 添加 admin | `admin_user_ids` 包含 target |
| owner 移除 admin | `admin_user_ids` 不包含 target |
| 移除 owner admin | 拒绝 |
| TransferRoomHost | `host_user_id` 更新，新 host 在 admin 集合 |
| 新 host 管理麦位 | success |
| admin 离房后重进 | admin 权限保留 |
| Kick admin | admin 身份被移除，Unban 后不自动恢复 |
| Kick current host | `PERMISSION_DENIED`，必须先转 host |

### Ban And Unban Tests

| Case | Expected |
| --- | --- |
| KickUser 后 JoinRoom | `PERMISSION_DENIED` |
| KickUser 后 VerifyRoomPresence | `present=false, reason=user_banned` |
| KickUser 后 CheckSpeakPermission | `allowed=false, reason=user_banned` |
| KickUser 后 IM side effect | outbox/IM bridge 触发群成员移除 |
| IM side effect 失败 | Room Cell 不回滚，outbox 保留重试 |
| 限时 KickUser 过期后 JoinRoom | success |
| UnbanUser 后 JoinRoom | success |
| 重复 UnbanUser | 幂等 |

### Idempotency Tests

| Case | Expected |
| --- | --- |
| 相同 command_id 相同 payload 重试 | 不重复 mutate，不重复 outbox，返回幂等结果 |
| 相同 command_id 不同 payload | `CONFLICT` |
| no-op 命令重试 | 不因未递增版本而丢失幂等保护 |

### Event Payload Tests

| Case | Expected |
| --- | --- |
| 每类 room outbox event | 包含文档 payload 矩阵要求字段 |
| IM system event | 与 outbox payload 字段语义一致 |
| 客户端重复收到同一 event_id | 去重后 UI 不重复变更 |

### Recovery Tests

| Case | Expected |
| --- | --- |
| snapshot 后回放 SetMicSeatLock | locked 状态恢复 |
| snapshot 后回放 SetChatEnabled | chat_enabled 恢复 |
| snapshot 后回放 SetRoomAdmin | admin 集合恢复 |
| snapshot 后回放 TransferRoomHost | host 恢复 |
| snapshot 后回放 UnbanUser | ban 集合恢复 |

## Acceptance Criteria

- 权限矩阵覆盖所有麦位和房间管理命令。
- 普通用户不能管理他人麦位、禁言、踢人、锁麦或开关公屏。
- owner 可以添加管理员、转 host、管理所有麦位。
- 锁麦命令可用，locked 麦位对所有角色都不能上麦或换入。
- 关闭公屏后腾讯 IM 发言回调被拒绝，打开后恢复。
- 踢人后用户不能 JoinRoom、不能 IM 进群、不能发言、不能拿 RTC token。
- 踢人后 outbox/IM bridge 会补偿执行腾讯 IM 群成员移除；副作用失败不回滚 Room Cell。
- 解封后用户可以重新 JoinRoom，但不会自动恢复 presence。
- 解封后不会自动恢复 admin、host、麦位或 RTC 推流状态。
- 相同 command_id 不同 payload 会被拒绝，no-op 管理命令也具备幂等保护。
- 新增管理动作全部写 command log、snapshot、outbox，并能恢复。
- 同步 IM 失败不回滚房间状态，outbox worker 后续补投。
- 客户端可通过系统消息和 snapshot 正确更新麦位、禁言、踢人、聊天开关和管理员 UI。

## Remaining Decisions

- 是否本阶段启用限时 mute/ban；如果不开启，就不要追加 `duration_ms` 和 `mute_states/ban_states`。
- 上麦后 RTC role 首版由客户端自行切换；gateway RTC token 返回 `anchor` 需要后续读取 Room Cell 麦位事实后再做。