244 lines
6.4 KiB
Markdown
244 lines
6.4 KiB
Markdown
# 机器人房间技术架构文档
|
||
|
||
## 目标
|
||
|
||
机器人房间提供后台配置驱动的内部房间编排能力，支持机器人创建房间、进房、虚拟静音上麦、普通礼物展示、幸运礼物展示，并保证与真实钱包、真实幸运礼物、真实奖池、真实榜单和结算隔离。
|
||
|
||
## 模块边界
|
||
|
||
### admin-platform
|
||
|
||
- 提供机器人房间配置页面。
|
||
- 调用 admin-server HTTP 接口。
|
||
- 不直接访问业务服务。
|
||
|
||
### admin-server
|
||
|
||
- 暴露后台 HTTP API。
|
||
- 做权限、审计、参数校验和 DTO 转换。
|
||
- 通过 gRPC client 调用 room-service 和 robot-service。
|
||
- 通过 wallet-service gRPC 获取礼物配置。
|
||
- 只读用户库补齐机器人展示资料。
|
||
|
||
### robot-service
|
||
|
||
- 只拥有机器人账号池事实。
|
||
- 房间机器人池表：`hyapp_robot.robot_room_robots`。
|
||
- 不处理进房、麦位、送礼和 IM。
|
||
|
||
### room-service
|
||
|
||
- 机器人房间配置 owner。
|
||
- 创建真实房间状态。
|
||
- 管理机器人房间配置表：`hyapp_room.room_robot_rooms`。
|
||
- 执行机器人进房、虚拟静音上麦、送礼循环。
|
||
- 强校验机器人送礼仅限同房间机器人。
|
||
- 生成机器人幸运礼物展示事件。
|
||
|
||
### wallet-service
|
||
|
||
- 机器人礼物扣费入口：`DebitRobotGift`。
|
||
- 使用专用资产 `ROBOT_COIN`。
|
||
- 自动补足机器人专用金币后扣减。
|
||
- 不发出真实 `WalletGiftDebited` 事件。
|
||
- 不写主播周期钻石和真实礼物墙。
|
||
|
||
### activity/statistics
|
||
|
||
- 消费房间送礼事件时跳过 `is_robot_gift`。
|
||
- 机器人礼物不进入真实活动、榜单、任务、成长值和统计。
|
||
|
||
## 核心数据表
|
||
|
||
### `hyapp_robot.robot_room_robots`
|
||
|
||
机器人账号池事实表。
|
||
|
||
关键字段：
|
||
|
||
- `app_code`
|
||
- `room_scene`
|
||
- `user_id`
|
||
- `status`
|
||
- `last_used_at_ms`
|
||
- `used_count`
|
||
|
||
### `hyapp_room.room_robot_rooms`
|
||
|
||
机器人房间配置和占用事实表。
|
||
|
||
关键字段：
|
||
|
||
- `room_id`
|
||
- `room_short_id`
|
||
- `status`
|
||
- `owner_robot_user_id`
|
||
- `robot_user_ids_json`
|
||
- `gift_ids_json`
|
||
- `lucky_gift_ids_json`
|
||
- `normal_gift_interval_ms`
|
||
- `lucky_combo_min`
|
||
- `lucky_combo_max`
|
||
- `lucky_pause_min_ms`
|
||
- `lucky_pause_max_ms`
|
||
|
||
## 后台 API
|
||
|
||
后台 HTTP：
|
||
|
||
- `GET /api/v1/admin/rooms/robot-rooms`
|
||
- `GET /api/v1/admin/rooms/robot-rooms/available-robots`
|
||
- `POST /api/v1/admin/rooms/robot-rooms`
|
||
- `POST /api/v1/admin/rooms/robot-rooms/{room_id}/start`
|
||
- `POST /api/v1/admin/rooms/robot-rooms/{room_id}/stop`
|
||
|
||
room-service gRPC：
|
||
|
||
- `AdminListRobotRooms`
|
||
- `AdminFilterAvailableRoomRobots`
|
||
- `AdminCreateRobotRoom`
|
||
- `AdminSetRobotRoomStatus`
|
||
|
||
wallet-service gRPC：
|
||
|
||
- `DebitRobotGift`
|
||
|
||
## 创建流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Admin as admin-platform
|
||
participant AS as admin-server
|
||
participant RS as room-service
|
||
participant RB as robot-service
|
||
participant DB as MySQL
|
||
|
||
Admin->>AS: POST /admin/rooms/robot-rooms
|
||
AS->>RS: AdminCreateRobotRoom
|
||
RS->>DB: 查询 active 机器人房占用
|
||
RS->>RS: 从候选机器人随机抽取人数
|
||
RS->>RS: CreateRoom(robot_room=true)
|
||
RS->>RS: JoinRoom for robots
|
||
RS->>RS: RobotVirtualMicUp for robots
|
||
RS->>DB: 写 room_robot_rooms
|
||
RS->>RS: start runtime loops
|
||
RS-->>AS: AdminRobotRoom
|
||
AS-->>Admin: 机器人房间详情
|
||
```
|
||
|
||
## 运行时循环
|
||
|
||
room-service 启动时会扫描所有 active 机器人房间并恢复运行时循环。
|
||
|
||
每个 active 机器人房间：
|
||
|
||
- 为每个机器人启动普通礼物 loop。
|
||
- 为每个机器人启动幸运礼物 loop。
|
||
- stop 后取消对应房间的 context。
|
||
|
||
普通礼物 loop：
|
||
|
||
1. 等待 `normal_gift_interval_ms`。
|
||
2. 从 `gift_ids_json` 随机选择礼物。
|
||
3. 从同房间其他机器人随机选择 1 个目标。
|
||
4. 调用 `RobotSendGift`。
|
||
|
||
幸运礼物 loop：
|
||
|
||
1. 从 `lucky_gift_ids_json` 随机选择礼物。
|
||
2. 随机生成 `lucky_combo_min-lucky_combo_max` 连击次数。
|
||
3. 当前机器人向同房间其他机器人逐个送礼。
|
||
4. 使用 `synthetic_lucky_gift=true`，跳过真实抽奖。
|
||
5. 等待 `lucky_pause_min_ms-lucky_pause_max_ms` 后继续。
|
||
|
||
## 服务端安全校验
|
||
|
||
room-service 在机器人送礼时强校验：
|
||
|
||
- 当前房间必须是机器人房间。
|
||
- sender 必须在该机器人房间 `robot_user_ids_json` 内。
|
||
- target 必须在同一机器人房间 `robot_user_ids_json` 内。
|
||
- sender 不能给真人送礼。
|
||
- 当前机器人礼物只允许单目标调用。
|
||
|
||
## 钱包隔离
|
||
|
||
机器人礼物使用 `DebitRobotGift`：
|
||
|
||
- 资产类型固定为 `ROBOT_COIN`。
|
||
- 如果机器人 `ROBOT_COIN` 不足，同一事务内自动补足。
|
||
- 立即扣减本次礼物价格。
|
||
- 交易类型为 `robot_gift_debit`。
|
||
- 不写真实 `gift_debit`。
|
||
- 不发 `WalletGiftDebited`。
|
||
- 不写 `user_gift_wall`。
|
||
- 不写 `host_period_diamond_accounts`。
|
||
|
||
## 幸运礼物隔离
|
||
|
||
机器人幸运礼物不会调用真实幸运抽奖链路。
|
||
|
||
room-service 只生成展示事件：
|
||
|
||
- `RoomRobotLuckyGiftDrawn`
|
||
- 对 IM 客户端映射为 `lucky_gift_drawn`
|
||
- 标记 `synthetic=true`
|
||
- 携带机器人房间、送礼人、收礼人、礼物和展示金额字段
|
||
|
||
真实奖池、真实流水、真实返奖、真实统计完全不写入。
|
||
|
||
## 排行榜与统计隔离
|
||
|
||
`RoomGiftSent` 增加：
|
||
|
||
- `is_robot_gift`
|
||
- `synthetic_lucky_gift`
|
||
|
||
下游服务看到 `is_robot_gift=true` 时跳过：
|
||
|
||
- 活动播报统计
|
||
- 周星
|
||
- 房间流水奖励
|
||
- 每日任务
|
||
- 成长值
|
||
- statistics 礼物消费与幸运礼物统计
|
||
|
||
room-service 本地仍允许机器人房内：
|
||
|
||
- 房间热度增长
|
||
- 麦位热度增长
|
||
- 房内展示事件发送
|
||
|
||
## 本地接口测试
|
||
|
||
测试工具：
|
||
|
||
```bash
|
||
go run ./tools/robot-room-api-test
|
||
```
|
||
|
||
默认依赖：
|
||
|
||
- admin-server: `http://127.0.0.1:13100/api/v1`
|
||
- MySQL: `127.0.0.1:23306`
|
||
- 管理员账号: `admin / admin123`
|
||
|
||
工具会：
|
||
|
||
1. 种 12 个房间机器人账号。
|
||
2. 种 2 个礼物配置和价格。
|
||
3. 登录 admin-server。
|
||
4. 调用可用机器人列表接口。
|
||
5. 创建机器人房间。
|
||
6. 查询 active 列表。
|
||
7. 停止、启动、再次停止机器人房间。
|
||
8. 校验数据库中机器人房间配置和真实 `gift_debit` 隔离。
|
||
|
||
## 运维注意事项
|
||
|
||
- 多实例 room-service 下，机器人房间 runtime 是进程内循环；重启会从 MySQL active 配置恢复。
|
||
- 机器人房间配置以 MySQL 为准。
|
||
- 同一机器人账号不能被多个 active 机器人房间占用。
|
||
- 停止机器人房间只停止 runtime，不删除房间。
|
||
- 如果需要彻底释放机器人账号，应增加删除/归档能力后再开放。
|