hy/hyapp-server

Fork 0

ZuoZuo d455d24016 机器人房

2026-06-15 23:53:30 +08:00

6.4 KiB

Raw Blame History

机器人房间技术架构文档

目标

机器人房间提供后台配置驱动的内部房间编排能力，支持机器人创建房间、进房、虚拟静音上麦、普通礼物展示、幸运礼物展示，并保证与真实钱包、真实幸运礼物、真实奖池、真实榜单和结算隔离。

模块边界

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

创建流程

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：

等待 normal_gift_interval_ms。
从 gift_ids_json 随机选择礼物。
从同房间其他机器人随机选择 1 个目标。
调用 RobotSendGift。

幸运礼物 loop：

从 lucky_gift_ids_json 随机选择礼物。
随机生成 lucky_combo_min-lucky_combo_max 连击次数。
当前机器人向同房间其他机器人逐个送礼。
使用 synthetic_lucky_gift=true，跳过真实抽奖。
等待 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 本地仍允许机器人房内：

房间热度增长
麦位热度增长
房内展示事件发送

本地接口测试

测试工具：

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

工具会：

种 12 个房间机器人账号。
种 2 个礼物配置和价格。
登录 admin-server。
调用可用机器人列表接口。
创建机器人房间。
查询 active 列表。
停止、启动、再次停止机器人房间。
校验数据库中机器人房间配置和真实 gift_debit 隔离。

运维注意事项

多实例 room-service 下，机器人房间 runtime 是进程内循环；重启会从 MySQL active 配置恢复。
机器人房间配置以 MySQL 为准。
同一机器人账号不能被多个 active 机器人房间占用。
停止机器人房间只停止 runtime，不删除房间。
如果需要彻底释放机器人账号，应增加删除/归档能力后再开放。

6.4 KiB Raw Blame History Unescape Escape