# 全站机器人产品文档

## 目标

全站机器人用于自研游戏自动补位。后台批量创建机器人资料号后，游戏服务可以在玩家等待超时后从机器人池选择一个可用机器人参与对局。

## 后台入口

- 菜单位置：游戏管理 / 全站机器人
- 菜单编码：`game-robots`
- 页面地址：`/games/robots`
- 权限：查看使用 `game:view`，创建使用 `game:create`，启停使用 `game:update`，删除使用 `game:delete` 或 `game:update`

## 机器人规则

- 机器人以 App 用户资料形式保存，有 `user_id`、短 ID、昵称、头像、国家、语言等基础资料。
- 机器人注册来源固定为 `game_robot`。
- 机器人不是自然新增用户，不进入新增用户统计、注册 cohort、留存统计。
- 机器人不能通过 App 登录接口登录。
- 机器人创建时不生成 access token、refresh token，也不写登录成功审计。
- 机器人不导入腾讯 IM 登录账号；它只用于游戏资料展示和游戏服务补位。
- 删除机器人只会从全站机器人池移除，用户资料和历史对局记录保留。

## 创建流程

1. 运营在后台选择创建数量、国家、性别和语言元数据。
2. admin-server 从 likei 线上 `user_base_info` 随机抽取正常用户的 `user_nickname` 和 `user_avatar`。
3. admin-server 调 user-service 创建 `source=game_robot` 的资料号，昵称和头像直接使用 likei 资料。
4. user-service 写入用户资料、短 ID 和密码身份，但不创建登录 session。
5. admin-server 调 game-service 把这些 user_id 注册到机器人池。
6. game-service 后续只从启用状态的机器人中选择补位。

## 统计口径

- 实时统计：`source=game_robot` 不写 `UserRegistered` outbox。
- 补数统计：统计补数按 `users.created_at_ms` 扫描时排除 `source=game_robot`。
- 后台创建 100 个全站机器人，不会增加“新增用户数”，也不会进入留存 cohort。

## 登录限制

- 密码登录：即使知道短 ID 和密码，也会被 user-service 拦截。
- 三方登录：机器人没有三方身份绑定，不能通过三方接口登录成机器人。
- refresh token：新机器人不会生成 refresh token；历史上如果存在机器人 session，续期时也会被用户登录判断拦截。
- access token 重签：会复用同一登录判断，机器人不能续签。

## 后台接口

### 列表

- 地址：`GET /admin/game/robots`
- 参数：`gameId`、`status`、`pageSize`、`cursor`
- 返回值：机器人列表、下一页游标、服务器时间
- 相关 IM：无

### 批量创建

- 地址：`POST /admin/game/robots/generate`
- 参数：`count`（默认 20，最多 1000）、`nicknameLanguage`（只作为账号语言元数据）、`gender`、`country`
- 返回值：创建数量、机器人列表
- 相关 IM：无；机器人不导入 IM 登录账号

### 启停

- 地址：`PATCH /admin/game/robots/{user_id}/status`
- 参数：`status`，可传 `active` 或 `disabled`；可选 `gameId`
- 返回值：机器人当前状态
- 相关 IM：无

### 删除

- 地址：`DELETE /admin/game/robots/{user_id}`
- 参数：可选 `gameId`
- 返回值：`deleted`
- 相关 IM：无

## 游戏补位规则

- 自研游戏配置里开启机器人补位后，玩家等待超过配置时间，game-service 会从当前 App 下所有启用且未加入本局的机器人里完全随机抽取一个加入对局。
- 机器人被选中后会记录最近使用时间和累计使用次数；这些字段只用于后台观察命中分布，不影响下一次随机抽取。
- 机器人对局资金由游戏奖池结算，不从机器人钱包扣款。
- 机器人禁用后不会再被新对局选中。