# 鸽达达管理后台复刻需求文档

调研对象：https://admin.adfahi.cn  
调研时间：2026-09-04  
当前登录账号视角：`heiyue`  
目标：在本项目中复刻一套功能与页面结构一致的 IM 管理后台。

> 说明：本次通过内置浏览器逐项点击左侧菜单，进入页面后对有查询按钮的页面执行了“查询/查 询”，再采集当前可视区域截图、可见字段、表格列、操作按钮，并下载前端 bundle 反查接口路径。浏览器只读执行环境屏蔽了 `fetch/XMLHttpRequest`，因此未能直接读取接口 JSON body；本文档中的返回字段以页面查询后的渲染结果和前端接口定义反推。

## 0. 本次修订说明

根据补充要求，已做以下修订：

- 截图从原先整页长图改为“当前可视区域截图”，减少大面积空白，更接近实际浏览器视图。
- 每个列表页进入后均点击查询按钮；`群成员管理` 因群号必填，使用群组列表中已有群号 `68127154` 查询，已展示成员数据。
- 单聊消息、群聊消息、文件管理、日志审计、用户登录、IP 统计、登录失败日志等页面查询后均展示了数据。
- 邀请码管理已查询到数据；敏感词库、用户反馈当前查询结果为空，需求文档中按“需支持空态”记录。
- 文档已在每个 `3.x` 页面章节内补充接口字段、查询参数、返回字段、按钮功能、表格字段、枚举、业务动作、危险操作确认、导入导出、分页和空态说明。
- 新截图保存在 `docs/admin-adfahi-research/screenshots-queried/`。

## 1. 总体信息架构

左侧菜单分为 5 个一级模块，当前账号可见 20 个页面：

| 一级模块 | 页面 | 前端路由 |
| --- | --- | --- |
| 数据概览 | 数据概览 | `/dashboard` |
| 用户与群组 | 用户管理 | `/users` |
| 用户与群组 | 用户分组 | `/user-policy-groups` |
| 用户与群组 | 群组管理 | `/groups` |
| 用户与群组 | 群成员管理 | `/group-members` |
| 用户与群组 | 邀请码管理 | `/invite-codes` |
| 内容审核 | 单聊消息 | `/private-messages` |
| 内容审核 | 群聊消息 | `/group-messages` |
| 内容审核 | 敏感词库 | `/sensitive-words` |
| 内容审核 | 文件管理 | `/file-records` |
| 内容审核 | 用户反馈 | `/feedbacks` |
| 日志审计 | 操作日志 | `/audit-logs` |
| 日志审计 | 用户账号审计 | `/user-account-audit` |
| 日志审计 | 群事件审计 | `/group-events` |
| 日志审计 | 管理员登录 | `/admin-login-history` |
| 日志审计 | 用户登录 | `/user-login-history` |
| 日志审计 | IP 账号统计 | `/ip-user-stats` |
| 日志审计 | 登录失败日志 | `/login-failure-logs` |
| 系统设置 | 私域设置 | `/tenant-settings` |
| 系统设置 | 安全策略 | `/security-settings` |

菜单总览截图：

![菜单总览](screenshots-queried/00-menu-overview.png)

## 2. 全局布局与交互

后台采用典型管理系统布局：

- 左侧固定菜单，支持一级菜单展开/收起。
- 顶部显示当前账号头像、用户名、账户操作入口。
- 主区域顶部有多标签页导航，打开过的页面会以 tab 形式保留，可关闭。
- 列表页统一具备查询区、操作按钮区、表格、分页。
- 详情、编辑、重置密码、IP 白名单、处理反馈、分组设置等操作预计以弹窗完成。
- 危险操作需要二次确认，包括封禁、强制下线、强制注销、解散群、删除文件、删除敏感词、解锁账号等。

建议在本项目中按 HotGo 规范实现：后端 GoFrame 分层，前端 Vue 3 + Naive UI，枚举/字典由后端统一维护，前端不硬编码字典文本。

## 3. 页面需求

### 3.1 数据概览

路由：`/dashboard`  
接口：`GET /admin/stats`

页面展示统计卡片和趋势表：

- 总用户数：16
- 活跃用户：0
- 总群组数：6
- 总会话数：11
- 总消息数：220
- 今日消息：0
- 用户增长趋势：日期、数量
- 消息增长趋势：日期、数量

字段与数据口径：

| 字段 | 接口字段建议 | 含义 | 展示/统计规则 |
| --- | --- | --- | --- |
| 总用户数 | `total_users` | 当前租户用户总量 | 建议统计未物理删除用户，可包含正常、封禁、注销 |
| 活跃用户 | `active_users` | 近期活跃用户 | 建议按当天或近 7 天登录/发消息口径统计 |
| 总群组数 | `total_groups` | 当前租户群组总量 | 建议包含正常和封禁群，已解散群是否计入需配置 |
| 总会话数 | `total_conversations` | 单聊和群聊会话总数 | 按会话去重统计 |
| 总消息数 | `total_messages` | 历史消息总量 | 包含文本、图片、视频、语音、文件、名片、系统消息 |
| 今日消息 | `today_messages` | 当日新增消息数 | 按服务器时区从 00:00 统计 |
| 用户增长趋势 | `user_growth[]` | 最近 7 天新增用户 | 元素包含 `date`、`count` |
| 消息增长趋势 | `message_growth[]` | 最近 7 天新增消息 | 元素包含 `date`、`count` |

按钮与交互：

- 本页无查询按钮，进入页面自动调用统计接口。
- 统计卡片为空时数字显示 `0`，趋势表仍展示日期行，数量为 `0`。
- 页面需支持后续扩展为折线图，但必须保留日期和数量明细。

截图：

![数据概览](screenshots-queried/01-dashboard.png)

### 3.2 用户管理

路由：`/users`  
核心接口：

- `GET /admin/users`
- `POST /admin/users`
- `GET /admin/users/{id}`
- `PATCH /admin/users/{id}/status`
- `POST /admin/users/{id}/reset_password`
- `POST /admin/users/{id}/ip-whitelist`
- `POST /admin/users/{id}/kick`
- `POST /admin/users/{id}/deactivate`
- `POST /admin/users/batch`
- `POST /admin/users/batch-ban`
- `POST /admin/users/ban-by-ip`
- `POST /admin/users/import-xlsx`

查询条件：

- 用户编号
- 用户分组
- 状态
- 关键词：用户名、昵称、手机号

顶部操作：

- 创建用户
- 批量创建
- 导入 Excel
- 下载模板

表格列：

- 编号
- 头像
- 用户名
- 昵称
- 手机号
- 注册方式
- 状态
- 用户分组
- 最近登录
- 创建时间
- 操作

行操作：

- 详情
- 重置密码
- IP 白名单
- 调整分组
- 封禁
- 强制下线
- 强制注销

按钮功能说明：

| 按钮 | 对应功能 | 接口 | 详细说明 |
| --- | --- | --- | --- |
| 查 询 | 按条件筛选用户 | `GET /admin/users` | 点击后页码回到第 1 页；支持编号、分组、状态、关键词组合查询 |
| 重 置 | 清空筛选条件 | `GET /admin/users` | 清空编号、用户分组、状态、关键词后重新查询 |
| 创建用户 | 后台新增单个用户 | `POST /admin/users` | 弹窗填写昵称、手机号、密码、用户分组；平台账号还需选择租户；密码受安全策略限制 |
| 批量创建 | 批量生成用户 | `POST /admin/users/batch` | 支持批量数量、默认密码、默认分组；完成后展示成功/失败并支持下载结果 |
| 导入Excel | Excel 批量导入用户 | `POST /admin/users/import-xlsx` | 上传 `.xlsx`；模板列为昵称、手机号、密码；返回成功数、失败数、失败原因 |
| 下载模板 | 下载导入模板 | 静态生成或导出接口 | 模板示例字段：昵称、手机号、密码 |
| 详 情 | 查看用户详情 | `GET /admin/users/{id}` | 展示基础资料、状态、分组、最近登录、IP 白名单、安全权限等 |
| 重置密码 | 管理员重置密码 | `POST /admin/users/{id}/reset_password` | 弹窗输入新密码或生成密码；成功后写用户账号审计 |
| IP白名单 | 设置用户登录白名单 | `POST /admin/users/{id}/ip-whitelist` | 多行 IP/CIDR；用户白名单不覆盖全局登录 IP 黑名单 |
| 调整分组 | 修改用户策略组 | 用户分组分配接口 | 立即影响好友、建群、APP/Web 登录等权限 |
| 封 禁 / 解封 | 切换用户状态 | `PATCH /admin/users/{id}/status` | 封禁后撤销在线会话并禁止登录；需二次确认 |
| 强制下线 | 踢出在线终端 | `POST /admin/users/{id}/kick` | 不改变用户状态，仅撤销当前登录态 |
| 强制注销 | 注销用户账号 | `POST /admin/users/{id}/deactivate` | 高危操作，需二次确认；注销后按规则清理用户数据 |

表格字段说明：

| 表格字段 | 接口字段建议 | 含义 | 展示规则 |
| --- | --- | --- | --- |
| 编号 | `user_no` | 对外展示的用户编号 | 数字，支持精确查询 |
| 头像 | `avatar` | 用户头像 URL | 显示缩略图；无头像显示默认头像；支持点击查看 |
| 用户名 | `username` | 用户登录名/IM 账号 | 样例：`hy73074162` |
| 昵称 | `nickname` | 用户显示名 | 允许为空，空值显示 `--` |
| 手机号 | `mobile` / `phone` | 绑定手机号 | 建议脱敏展示 |
| 注册方式 | `register_type` | 用户来源 | 后台创建、手机号注册、邀请码注册 |
| 状态 | `status` | 账号状态 | 正常绿色、封禁红色、注销灰色 |
| 用户分组 | `policy_group_name` | 所属策略组 | 样例：默认用户组 |
| 最近登录 | `last_login_at` | 最近一次登录时间 | 无记录显示 `--` |
| 创建时间 | `created_at` | 用户创建时间 | `YYYY-MM-DD HH:mm:ss` |

枚举说明：

- 用户状态：`active` 正常、`disabled` 已封禁、`deleted` 已注销。
- 注册方式：`admin` 后台创建、`mobile` 手机号注册、`invite_code` 邀请码注册。
- 批量封禁结果：`success` 成功、`failed` 失败，失败项需返回 `username` 和 `reason`。

截图：

![用户管理](screenshots-queried/02-user-management.png)

### 3.3 用户分组

路由：`/user-policy-groups`  
核心接口：

- `GET /admin/user-policy-groups`
- `POST /admin/user-policy-groups`
- `PUT /admin/user-policy-groups/{id}`
- `DELETE /admin/user-policy-groups/{id}`
- `GET /admin/user-policy-groups/{id}/users`
- `GET/POST /admin/user-policy-groups/ip-whitelist`

顶部操作：

- 添加分组
- IP 白名单

表格列：

- 分组名称
- 用户数
- 允许加好友
- 允许建群
- 直接加好友
- 好友上限
- APP 登录
- Web 登录
- IP 白名单
- 状态
- 权重
- 操作

编辑分组字段：

- 分组名称
- 默认用户组
- 启用状态
- 允许加好友
- 允许建群
- 直接添加好友
- 允许 APP 登录
- 允许 Web 登录
- 启用 IP 白名单
- 好友数量上限，0 表示不限
- 排序权重

IP 白名单字段：

- APP 登录白名单，每行一个 IPv4、IPv6 或 CIDR
- Web 登录白名单，每行一个 IPv4、IPv6 或 CIDR

按钮功能说明：

| 按钮 | 对应功能 | 接口 | 详细说明 |
| --- | --- | --- | --- |
| 添加分组 | 新建用户策略组 | `POST /admin/user-policy-groups` | 弹窗填写分组名称、开关权限、好友上限、排序权重 |
| IP 白名单 | 设置租户渠道白名单 | `GET/POST /admin/user-policy-groups/ip-whitelist` | 分 APP 登录白名单和 Web 登录白名单，每行一个 IP/CIDR |
| 编辑 | 修改策略组 | `PUT /admin/user-policy-groups/{id}` | 默认分组部分字段需禁用，避免系统无默认组 |
| 删除 | 删除策略组 | `DELETE /admin/user-policy-groups/{id}` | 默认用户组不可删除；分组下有用户时应阻止或要求迁移 |

表格字段说明：

| 表格字段 | 接口字段建议 | 含义 | 展示规则 |
| --- | --- | --- | --- |
| 分组名称 | `name` | 策略组名称 | 默认组显示“默认”标记 |
| 用户数 | `user_count` | 分组下用户数量 | 可扩展点击查看用户列表 |
| 允许加好友 | `allow_add_friend` | 是否允许主动加好友 | 允许/禁止 |
| 允许建群 | `allow_create_group` | 是否允许创建群 | 允许/禁止 |
| 直接加好友 | `direct_add_friend` | 加好友是否免确认 | 开启显示开启，关闭显示 `--` |
| 好友上限 | `max_friend_count` | 最大好友数量 | `0` 显示不限 |
| APP 登录 | `allow_app_login` | 是否允许 APP 登录 | 允许/禁止 |
| Web 登录 | `allow_web_login` | 是否允许 Web 登录 | 允许/禁止 |
| IP 白名单 | `ip_whitelist_enabled` | 是否启用分组白名单 | 已启用/未启用 |
| 状态 | `enabled` | 分组是否生效 | 启用/停用 |
| 权重 | `sort_order` | 排序或匹配优先级 | 数字 |

枚举说明：

- 布尔权限统一为 `true/false`，前端按字段语义显示为允许/禁止、启用/停用、开启/关闭。
- 好友上限 `0` 代表不限。
- IP 白名单启用后，APP/Web 登录需命中对应白名单；全局黑名单优先级高于白名单。

截图：

![用户分组](screenshots-queried/03-user-groups.png)

### 3.4 群组管理

路由：`/groups`  
核心接口：

- `GET /admin/groups`
- `GET /admin/groups/{id}`
- `POST /admin/groups/{id}/ban`
- `POST /admin/groups/{id}/unban`
- `DELETE /admin/groups/{id}`
- `GET /admin/groups/{id}/members`
- `GET /admin/groups/{id}/files`
- `DELETE /admin/groups/{id}/files/{fileId}`
- `POST /admin/groups/quick-create`

查询条件：

- 群号
- 关键词：群名称
- 状态

表格列：

- 群组编号
- 群号
- 群组名称
- 成员数
- 群主昵称
- 群主用户名
- 状态
- 创建时间
- 操作

行操作：

- 详情
- 群文件
- 封禁
- 解散

按钮功能说明：

| 按钮 | 对应功能 | 接口 | 详细说明 |
| --- | --- | --- | --- |
| 查 询 | 按群号、群名、状态筛选 | `GET /admin/groups` | 点击后页码回到第 1 页 |
| 重 置 | 清空筛选条件 | `GET /admin/groups` | 清空群号、关键词、状态后重新查询 |
| 详 情 | 查看群详情 | `GET /admin/groups/{id}` | 展示群号、群名、群主、成员数、状态、创建时间 |
| 群文件 | 查看群文件 | `GET /admin/groups/{id}/files` | 弹窗列表支持类型筛选、下载、删除 |
| 封 禁 / 解封 | 切换群状态 | `POST /admin/groups/{id}/ban`、`POST /admin/groups/{id}/unban` | 封禁后群内不可发送消息；需记录群事件审计 |
| 解 散 | 解散群聊 | `DELETE /admin/groups/{id}` | 高危操作，需二次确认；清理成员关系，保留历史记录 |

表格字段说明：

| 表格字段 | 接口字段建议 | 含义 | 展示规则 |
| --- | --- | --- | --- |
| 群组编号 | `id` | 群内部编号 | 数字 |
| 群号 | `group_no` / `group_code` | 用户端可搜索群号 | 支持精确查询 |
| 群组名称 | `name` | 群显示名称 | 样例：冯、冯氏家族 |
| 成员数 | `member_count` | 当前成员数量 | 数字 |
| 群主昵称 | `owner_nickname` | 群主昵称 | 空值显示 `--` |
| 群主用户名 | `owner_username` | 群主用户名 | 样例：`hy69089908` |
| 状态 | `status` | 群状态 | 正常/封禁/已解散 |
| 创建时间 | `created_at` | 群创建时间 | `YYYY-MM-DD HH:mm:ss` |

枚举说明：

- 群组状态：`normal` 正常、`banned` 已封禁、`dissolved` 已解散。
- 群文件类型：图片、视频、音频、文档、其他。

截图：

![群组管理](screenshots-queried/04-group-management.png)

### 3.5 群成员管理

路由：`/group-members`  
接口依赖：

- `GET /admin/groups/{id}/members`
- `POST /admin/groups/{id}/members/kick`
- `POST /admin/groups/{id}/members/mute`
- `POST /admin/groups/{id}/members/unmute`

查询条件：

- 群号，必填
- 角色
- 关键词：用户名、昵称

表格列：

- 编号
- 用户名
- 昵称
- 群昵称
- 角色
- 禁言状态
- 加入时间
- 操作

顶部操作：

- 查询
- 重置
- 刷新

按钮功能说明：

| 按钮 | 对应功能 | 接口 | 详细说明 |
| --- | --- | --- | --- |
| 查 询 | 按群号查询成员 | `GET /admin/groups/{id}/members` | 群号必填；需先按群号解析群 ID |
| 重 置 | 清空群号、角色、关键词 | - | 清空后表格回到空态 |
| 刷 新 | 保持当前条件刷新 | `GET /admin/groups/{id}/members` | 不清空已输入群号 |
| 禁 言 / 解除禁言 | 设置成员禁言状态 | `POST /admin/groups/{id}/members/mute`、`POST /admin/groups/{id}/members/unmute` | 需填写禁言时长/原因；写群事件审计 |
| 踢 出 | 将成员移出群 | `POST /admin/groups/{id}/members/kick` | 需二次确认；群主不可直接踢出 |

表格字段说明：

| 表格字段 | 接口字段建议 | 含义 | 展示规则 |
| --- | --- | --- | --- |
| 编号 | `user_no` | 成员用户编号 | 样例：3 |
| 用户名 | `username` | 成员用户名 | 样例：`hy69089908` |
| 昵称 | `nickname` | 成员昵称 | 样例：F |
| 群昵称 | `group_nickname` | 群内昵称 | 空值显示 `--` |
| 角色 | `role` | 群角色 | 群主/管理员/成员 |
| 禁言状态 | `mute_status` | 是否禁言 | 正常/已禁言 |
| 加入时间 | `joined_at` | 入群时间 | `YYYY-MM-DD HH:mm:ss` |

枚举说明：

- 群成员角色：`owner` 群主、`admin` 管理员、`member` 成员。
- 禁言状态：`normal` 正常、`muted` 已禁言。
- 本次查询样例使用群号 `68127154`，查询到成员 `hy69089908 / F`，角色为群主。

截图：

![群成员管理](screenshots-queried/05-group-members.png)

### 3.6 邀请码管理

路由：`/invite-codes`  
核心接口：

- `GET /admin/invite-codes`
- `POST /admin/invite-codes`
- `DELETE /admin/invite-codes/{id}`
- `GET /admin/invite-codes/{id}/usages`

查询条件：

- 状态
- 邀请码，6 位数字

顶部操作：

- 生成邀请码

业务说明：

- 每次生成 1 个邀请码，可多次使用。
- 可指定企业与用户。
- 可勾选不限制时间，永久有效。
- 可开启自动加好友，使用该码注册的用户直接成为指定用户好友。
- 可查看使用该邀请码注册的用户列表。

表格列：

- 邀请码
- 指定用户
- 自动加好友
- 使用人数
- 创建人
- 状态
- 过期时间
- 创建时间
- 操作

按钮功能说明：

| 按钮 | 对应功能 | 接口 | 详细说明 |
| --- | --- | --- | --- |
| 查 询 | 按状态/邀请码筛选 | `GET /admin/invite-codes` | 邀请码为 6 位数字 |
| 重 置 | 清空状态和邀请码 | `GET /admin/invite-codes` | 回到全部列表 |
| 生成邀请码 | 创建邀请码 | `POST /admin/invite-codes` | 可指定用户、有效期、是否自动加好友；生成 6 位数字码 |
| 查 看 | 查看使用记录 | `GET /admin/invite-codes/{id}/usages` | 展示使用该码注册的用户列表 |
| 删 除 | 删除/停用邀请码 | `DELETE /admin/invite-codes/{id}` | 已使用邀请码建议标记停用，不物理删除 |

表格字段说明：

| 表格字段 | 接口字段建议 | 含义 | 展示规则 |
| --- | --- | --- | --- |
| 邀请码 | `code` | 6 位数字邀请码 | 样例：323441 |
| 指定用户 | `target_username` / `target_user_no` | 注册后绑定或自动加好友目标 | 样例：往事随风 (#2271) |
| 自动加好友 | `auto_add_friend` | 是否自动成为指定用户好友 | 是/否 |
| 使用人数 | `used_count` | 已使用注册人数 | 可点击查看详情 |
| 创建人 | `creator_name` / `creator_id` | 创建者 | 当前样例显示编号 16 |
| 状态 | `status` | 邀请码状态 | 启用/停用/过期 |
| 过期时间 | `expired_at` | 有效期截止时间 | 永久显示“不限制”或“永久” |
| 创建时间 | `created_at` | 创建时间 | `YYYY-MM-DD HH:mm:ss` |

枚举说明：

- 邀请码状态：`active` 启用、`disabled` 停用、`expired` 过期。
- 自动加好友：`true` 是、`false` 否。

截图：

![邀请码管理](screenshots-queried/06-invite-codes.png)

### 3.7 单聊消息

路由：`/private-messages`  
核心接口：

- `GET /admin/messages/search`
- `GET /admin/messages/{id}`

查询条件：

- 消息类型：全部、文本、图片、视频、语音、文件、名片、系统
- 发送人用户名
- 接收人用户名
- 关键词
- 开始时间
- 结束时间

表格列：

- 发送人
- 接收人
- 类型
- 内容
- 状态
- 发送时间
- 操作

按钮功能说明：

| 按钮 | 对应功能 | 接口 | 详细说明 |
| --- | --- | --- | --- |
| 查 询 | 按消息条件检索 | `GET /admin/messages/search` | 查询参数含 `conversation_type=private` |
| 重 置 | 清空筛选条件 | `GET /admin/messages/search` | 清空消息类型、发送人、接收人、关键词、时间 |
| 刷 新 | 保持当前条件刷新 | `GET /admin/messages/search` | 不改变页码和筛选条件 |
| 删 除 | 删除或隐藏消息 | 消息删除接口 | 需二次确认；写内容审核/操作日志 |

表格字段说明：

| 表格字段 | 接口字段建议 | 含义 | 展示规则 |
| --- | --- | --- | --- |
| 发送人 | `sender_nickname`、`sender_username` | 发送方用户 | 两行展示昵称和用户名 |
| 接收人 | `receiver_nickname`、`receiver_username` | 接收方用户 | 两行展示昵称和用户名 |
| 类型 | `message_type` | 消息类型 | 文本/图片/视频/语音/文件/名片/系统 |
| 内容 | `content` | 消息摘要 | 文本直接展示，媒体显示预览/下载 |
| 状态 | `status` | 消息状态 | 正常/已删除/已撤回/拦截 |
| 发送时间 | `sent_at` | 消息发送时间 | `YYYY-MM-DD HH:mm:ss` |

枚举说明：

- 消息类型：`text` 文本、`image` 图片、`video` 视频、`voice/audio` 语音、`file` 文件、`card` 名片、`system` 系统。
- 消息状态：`normal` 正常、`deleted` 后台删除、`recalled` 用户撤回、`blocked` 风控拦截。
- 查询后样例：`F / hy69089908` 给 `冯仁飞 / hy91144536` 发送文本 `哈哈哈哈`。

截图：

![单聊消息](screenshots-queried/07-direct-messages.png)

### 3.8 群聊消息

路由：`/group-messages`  
核心接口：

- `GET /admin/messages/search`
- `GET /admin/messages/{id}`

查询条件：

- 消息类型：全部、文本、图片、视频、语音、文件、名片、系统
- 发送人用户名
- 关键词
- 开始时间
- 结束时间

表格列：

- 发送人
- 群名称
- 类型
- 内容
- 状态
- 发送时间
- 操作

按钮功能说明：

| 按钮 | 对应功能 | 接口 | 详细说明 |
| --- | --- | --- | --- |
| 查 询 | 按群聊消息条件检索 | `GET /admin/messages/search` | 查询参数含 `conversation_type=group` |
| 重 置 | 清空筛选条件 | `GET /admin/messages/search` | 清空消息类型、发送人、关键词、时间 |
| 刷 新 | 保持当前条件刷新 | `GET /admin/messages/search` | 不改变页码和筛选条件 |
| 删 除 | 删除或隐藏群消息 | 消息删除接口 | 需二次确认；建议写群事件/内容审核日志 |

表格字段说明：

| 表格字段 | 接口字段建议 | 含义 | 展示规则 |
| --- | --- | --- | --- |
| 发送人 | `sender_nickname`、`sender_username` | 发送方用户 | 两行展示 |
| 群名称 | `group_name`、`group_no` | 消息所属群 | 两行展示群名和群号 |
| 类型 | `message_type` | 消息类型 | 文本/图片/视频/语音/文件/名片/系统 |
| 内容 | `content` | 消息摘要 | 文本展示内容，媒体展示预览/下载 |
| 状态 | `status` | 消息状态 | 正常/已删除/已撤回/拦截 |
| 发送时间 | `sent_at` | 发送时间 | `YYYY-MM-DD HH:mm:ss` |

枚举说明：

- 消息类型和消息状态同单聊消息。
- 查询后样例：`F / hy69089908` 在群 `冯 / 68127154` 发送文本 `哈哈哈哈`。

截图：

![群聊消息](screenshots-queried/08-group-messages.png)

### 3.9 敏感词库

路由：`/sensitive-words`  
核心接口：

- `GET /admin/sensitive-words`
- `POST /admin/sensitive-words`
- `PUT /admin/sensitive-words/{id}`
- `DELETE /admin/sensitive-words/{id}`
- `POST /admin/sensitive-words/import`
- `GET /admin/sensitive-words/export`

查询条件：

- 状态
- 等级
- 关键词：敏感词

顶部操作：

- 新增敏感词
- 批量导入
- 文件导入
- 批量导出

表格列：

- ID
- 敏感词
- 等级
- 替换词
- 状态
- 创建时间
- 操作

按钮功能说明：

| 按钮 | 对应功能 | 接口 | 详细说明 |
| --- | --- | --- | --- |
| 查 询 | 按状态、等级、关键词筛选 | `GET /admin/sensitive-words` | 点击后页码回到第 1 页 |
| 重 置 | 清空筛选条件 | `GET /admin/sensitive-words` | 回到全部词库 |
| 新增敏感词 | 新增单个词条 | `POST /admin/sensitive-words` | 弹窗填写敏感词、等级、替换词、状态 |
| 批量导入 | 粘贴多行导入 | `POST /admin/sensitive-words/import` | 返回成功、重复、失败数量 |
| 文件导入 | 上传文件导入 | `POST /admin/sensitive-words/import` | 支持 `.txt`、`.csv`、`.xlsx` |
| 批量导出 | 导出当前筛选词库 | `GET /admin/sensitive-words/export` | 导出 CSV/XLSX |
| 编辑 | 编辑词条 | `PUT /admin/sensitive-words/{id}` | 修改后刷新敏感词缓存 |
| 删除 | 删除词条 | `DELETE /admin/sensitive-words/{id}` | 需二次确认，建议软删除 |

表格字段说明：

| 表格字段 | 接口字段建议 | 含义 | 展示规则 |
| --- | --- | --- | --- |
| ID | `id` | 敏感词编号 | 数字 |
| 敏感词 | `word` | 待匹配词条 | 必填，建议唯一 |
| 等级 | `level` | 风险等级 | 低/中/高 |
| 替换词 | `replace_word` | 命中替代文本 | 空值显示 `--` |
| 状态 | `status` | 是否生效 | 启用/停用 |
| 创建时间 | `created_at` | 创建时间 | `YYYY-MM-DD HH:mm:ss` |

枚举说明：

- 敏感词等级：`low` 低、`medium` 中、`high` 高。
- 敏感词状态：`active` 启用、`disabled` 停用。
- 处理动作建议扩展：`replace` 替换、`block` 阻断、`alert` 告警。
- 当前页面查询结果为空，需支持“暂无数据”空态。

截图：

![敏感词库](screenshots-queried/09-sensitive-words.png)

### 3.10 文件管理

路由：`/file-records`  
接口：

- 复用 `GET /admin/messages/search`
- 文件删除可复用消息/群文件删除接口

查询条件：

- 文件类型：全部、图片、视频、音频、文档、其他
- 发送人用户名
- 文件名
- 开始时间
- 结束时间

表格列：

- 发送人
- 接收方
- 类型
- 内容
- 文件名
- 文件大小
- URL
- 状态
- 发送时间
- 操作

行操作：

- 预览
- 下载
- 删除

按钮功能说明：

| 按钮 | 对应功能 | 接口 | 详细说明 |
| --- | --- | --- | --- |
| 查 询 | 按文件条件检索 | `GET /admin/messages/search` | 仅筛选包含文件 URL 的消息 |
| 重 置 | 清空筛选条件 | `GET /admin/messages/search` | 清空类型、发送人、文件名、时间 |
| 刷 新 | 保持当前条件刷新 | `GET /admin/messages/search` | 不改变当前页 |
| 预览 | 查看图片/视频/音频 | 文件 URL | 只对可预览类型显示 |
| 下载 | 下载文件 | 文件 URL | URL 需鉴权或短期签名，避免泄露 |
| 删 除 | 删除文件记录/隐藏文件消息 | 消息或群文件删除接口 | 需二次确认；OSS 文件是否物理删除需配置 |

表格字段说明：

| 表格字段 | 接口字段建议 | 含义 | 展示规则 |
| --- | --- | --- | --- |
| 发送人 | `sender_nickname`、`sender_username` | 文件发送方 | 两行展示 |
| 接收方 | `receiver_name` / `group_name` | 单聊接收人或群 | 两行展示名称和编号 |
| 类型 | `file_type` / `message_type` | 文件类型 | 图片/视频/音频/文档/其他 |
| 内容 | `content` | 文件消息摘要 | 显示预览、下载快捷入口 |
| 文件名 | `file_name` | 原始文件名 | 空值显示 `--` |
| 文件大小 | `file_size` | 文件字节数 | 格式化为 B/KB/MB/GB |
| URL | `file_url` | 文件地址 | 表格省略展示，详情里显示完整 URL |
| 状态 | `status` | 文件消息状态 | 正常/已删除 |
| 发送时间 | `sent_at` | 上传或发送时间 | `YYYY-MM-DD HH:mm:ss` |

枚举说明：

- 文件分类：图片、视频、音频、文档、其他。
- 图片扩展名：`jpg`、`jpeg`、`png`、`gif`、`bmp`、`webp`、`svg`。
- 视频扩展名：`mp4`、`avi`、`mov`、`mkv`、`wmv`、`flv`、`webm`。
- 音频扩展名：`mp3`、`wav`、`flac`、`aac`、`ogg`、`wma`。
- 文档扩展名：`doc`、`docx`、`xls`、`xlsx`、`csv`、`ppt`、`pptx`、`pdf`、`txt`、`md`。

截图：

![文件管理](screenshots-queried/10-files.png)

### 3.11 用户反馈

路由：`/feedbacks`  
核心接口：

- `GET /admin/feedbacks`
- `PUT /admin/feedbacks/{id}`
- `POST /admin/feedbacks/{id}/priority`
- `POST /admin/feedbacks/batch-handle`
- `GET /admin/feedbacks/export`

查询条件：

- 用户 ID
- 状态
- 优先级
- 关键词：内容、联系方式

顶部操作：

- 批量处理
- 导出 CSV

表格列：

- 用户
- 优先级
- 内容
- 状态
- 处理人
- 创建时间
- 操作

按钮功能说明：

| 按钮 | 对应功能 | 接口 | 详细说明 |
| --- | --- | --- | --- |
| 查 询 | 按用户、状态、优先级、关键词筛选 | `GET /admin/feedbacks` | 关键词匹配内容或联系方式 |
| 重 置 | 清空筛选条件 | `GET /admin/feedbacks` | 回到全部列表 |
| 批量处理 | 批量更新反馈处理状态 | `POST /admin/feedbacks/batch-handle` | 对选中反馈统一设置状态和处理备注 |
| 导出 CSV | 导出当前筛选结果 | `GET /admin/feedbacks/export` | 包含用户、联系方式、内容、状态、处理信息 |
| 处理 | 单条处理反馈 | `PUT /admin/feedbacks/{id}` | 填写处理状态、处理备注，记录处理人和处理时间 |
| 调整优先级 | 快速修改优先级 | `POST /admin/feedbacks/{id}/priority` | 修改后刷新列表 |

表格字段说明：

| 表格字段 | 接口字段建议 | 含义 | 展示规则 |
| --- | --- | --- | --- |
| 用户 | `user_id`、`username`、`nickname` | 反馈用户 | 支持按用户 ID 筛选 |
| 优先级 | `priority` | 处理优先级 | 低/中/高，颜色区分 |
| 内容 | `content` | 反馈正文 | 长文本省略，详情查看完整 |
| 状态 | `status` | 处理状态 | 待处理/处理中/已处理/已关闭 |
| 处理人 | `handler_name` | 最后处理管理员 | 未处理显示 `--` |
| 创建时间 | `created_at` | 反馈提交时间 | `YYYY-MM-DD HH:mm:ss` |

枚举说明：

- 优先级：`low` 低、`medium` 中、`high` 高。
- 反馈状态：`pending` 待处理、`processing` 处理中、`resolved` 已处理、`closed` 已关闭。
- 当前页面查询结果为空，需支持“暂无数据”空态。

截图：

![用户反馈](screenshots-queried/11-feedback.png)

### 3.12 操作日志

路由：`/audit-logs`  
接口：`GET /admin/audit/logs`

查询条件：

- 动作
- 目标类型
- 目标用户
- 目标群
- 开始时间
- 结束时间

顶部操作：

- 查询
- 重置
- 导出 CSV

表格列：

- 管理员
- 动作
- 目标类型
- 目标
- 查询条件
- IP
- 时间

按钮功能说明：

| 按钮 | 对应功能 | 接口 | 详细说明 |
| --- | --- | --- | --- |
| 查询 | 按动作、目标类型、目标用户、目标群、时间范围筛选 | `GET /admin/audit/logs` | 查询后页码回到第 1 页 |
| 重 置 | 清空筛选条件 | `GET /admin/audit/logs` | 回到全部日志 |
| 导出 CSV | 导出当前筛选日志 | 导出接口 | 用于审计留存 |
| 详情 | 查看操作详情 | `GET /admin/audit/logs` 或详情接口 | 展示请求参数、变更内容、管理员信息 |

表格字段说明：

| 表格字段 | 接口字段建议 | 含义 | 展示规则 |
| --- | --- | --- | --- |
| 管理员 | `admin_username` | 执行动作的后台账号 | 样例：heiyue |
| 动作 | `action` | 操作类型 | 创建用户、重置密码、封禁等 |
| 目标类型 | `target_type` | 操作对象类型 | 用户、群、消息、文件、设置 |
| 目标 | `target_summary` | 目标摘要 | 用户显示昵称和用户名 |
| 查询条件 | `query_condition` | 操作时使用的查询条件 | 无则显示 `--` |
| IP | `ip` | 管理员操作 IP | IPv4/IPv6 |
| 时间 | `created_at` | 操作发生时间 | `YYYY-MM-DD HH:mm:ss` |

枚举说明：

- 动作：创建用户、重置密码、修改用户名、更新状态、调整分组、强制下线、强制注销、批量封禁、按 IP 封禁、封禁群、解封群、解散群、删除消息、删除文件、保存设置等。
- 目标类型：`user` 用户、`group` 群、`message` 消息、`file` 文件、`setting` 设置。
- 查询后样例：`heiyue` 重置用户密码，目标为 `往事随风 / hy17716319`，IP 为 `141.164.107.33`。

截图：

![操作日志](screenshots-queried/12-operation-logs.png)

### 3.13 用户账号审计

路由：`/user-account-audit`  
接口：`GET /admin/audit/user-account-logs`

查询条件：

- 用户编号
- 用户名
- 操作者
- 操作
- IP
- 时间范围

操作类型包括：

- 修改昵称、修改头像、修改性别、修改签名、修改生日、修改密码
- 主动注销
- 管理员修改用户名、管理员更新状态、管理员重置密码、管理员更新安全权限
- 管理员强制下线、管理员强制注销、管理员调整分组、管理员批量封禁、管理员按 IP 封禁

表格列：

- 操作时间
- 目标用户
- 操作者
- 操作类型
- 变更摘要
- IP / 归属地
- 设备/客户端

按钮功能说明：

- 查询：按用户编号、用户名、操作者、操作、IP、时间范围筛选用户账号审计日志。
- 重置：清空全部筛选条件并重新查询。
- 本页不提供写操作，只用于审计追踪。

表格字段说明：

| 表格字段 | 接口字段建议 | 含义 | 展示规则 |
| --- | --- | --- | --- |
| 操作时间 | `created_at` | 账号变更时间 | 倒序排列 |
| 目标用户 | `target_username`、`target_user_no` | 被操作用户 | 两行展示用户名和编号 |
| 操作者 | `actor_type`、`actor_username` | 管理员或用户本人 | 标签区分管理员/用户本人 |
| 操作类型 | `action` | 账号审计动作 | 字典化为中文 |
| 变更摘要 | `details` / `before_data` / `after_data` | 变更内容 | 长内容 tooltip 展示 |
| IP / 归属地 | `ip`、`ip_location` | 操作来源 | IP 和归属地分行展示 |
| 设备/客户端 | `device_id` / `user_agent` | 客户端信息 | 长文本省略，tooltip 查看 |

操作类型枚举：

| 值 | 中文 |
| --- | --- |
| `change_nickname` | 修改昵称 |
| `change_avatar` | 修改头像 |
| `change_gender` | 修改性别 |
| `change_signature` | 修改签名 |
| `change_birthday` | 修改生日 |
| `change_password` | 修改密码 |
| `deactivate_account` | 主动注销 |
| `update_username` | 管理员修改用户名 |
| `update_status` | 管理员更新状态 |
| `reset_password` | 管理员重置密码 |
| `update_security_perm` | 管理员更新安全权限 |
| `kick_user` | 管理员强制下线 |
| `force_deactivate` | 管理员强制注销 |
| `assign_policy_group` | 管理员调整分组 |
| `batch_ban_users` | 管理员批量封禁 |
| `ban_users_by_ip` | 管理员按 IP 封禁 |

截图：

![用户账号审计](screenshots-queried/13-user-account-audit.png)

### 3.14 群事件审计

路由：`/group-events`  
接口：`GET /admin/groups/events`

查询条件：

- 群号
- 操作人
- 目标用户
- 事件类型
- 开始时间
- 结束时间

表格列：

- 群名称
- 事件类型
- 操作人
- 目标用户
- 可见范围
- 旧值
- 新值
- 时间

按钮功能说明：

- 查询：按群号、操作人、目标用户、事件类型、时间范围筛选。
- 重置：清空筛选项重新查询。
- 本页不提供写操作，数据由群创建、成员加入、踢出、禁言、解散等业务自动写入。

表格字段说明：

| 表格字段 | 接口字段建议 | 含义 | 展示规则 |
| --- | --- | --- | --- |
| 群名称 | `group_name`、`group_no` | 事件所属群 | 两行展示群名和群号 |
| 事件类型 | `event_type` | 群事件 | 成员加入、群创建等 |
| 操作人 | `operator_username`、`operator_nickname` | 发起事件用户 | 系统事件显示系统 |
| 目标用户 | `target_username`、`target_nickname` | 被操作用户 | 无目标显示 `--` |
| 可见范围 | `visibility` | 事件对谁可见 | 全员可见、管理员可见、仅自己 |
| 旧值 | `old_value` | 变更前值 | 无则 `--` |
| 新值 | `new_value` | 变更后值 | 无则 `--` |
| 时间 | `created_at` | 事件时间 | `YYYY-MM-DD HH:mm:ss` |

事件类型枚举建议：

- `group_created` 群创建。
- `member_joined` 成员加入。
- `member_left` 成员退出。
- `member_kicked` 成员被踢。
- `member_muted` 成员禁言。
- `member_unmuted` 解除禁言。
- `owner_transferred` 群主转让。
- `admin_added` 设置管理员。
- `admin_removed` 取消管理员。
- `group_name_changed` 修改群名。
- `group_banned` 群封禁。
- `group_unbanned` 群解封。
- `group_dissolved` 群解散。

截图：

![群事件审计](screenshots-queried/14-group-event-audit.png)

### 3.15 管理员登录历史

路由：`/admin-login-history`  
接口：`GET /admin/admin-login-history`

查询条件：

- 开始时间
- 结束时间

表格列：

- 用户名
- 登录时间
- User-Agent
- IP 地址

按钮功能说明：

- 查询：按开始时间、结束时间筛选管理员登录历史。
- 分页：默认 `20 条/页`。
- 本页不提供写操作。

表格字段说明：

| 表格字段 | 接口字段建议 | 含义 | 展示规则 |
| --- | --- | --- | --- |
| 用户名 | `username` | 管理员账号 | 样例：heiyue |
| 登录时间 | `login_at` | 登录成功时间 | 倒序排列 |
| User-Agent | `user_agent` | 浏览器 UA | 长文本横向滚动或 tooltip |
| IP 地址 | `ip` | 登录 IP | IPv4/IPv6 |

截图：

![管理员登录](screenshots-queried/15-admin-login.png)

### 3.16 用户登录历史

路由：`/user-login-history`  
接口：`GET /admin/user-login-history`

查询条件：

- 用户编号
- 用户名
- 开始时间
- 结束时间
- IP

表格列：

- 用户编号
- 用户名
- 当前状态
- 登录时间
- 设备类型
- 设备型号
- 系统版本
- App 版本
- IP 地址
- 归属地
- 操作

行操作：

- 快速封禁

按钮功能说明：

| 按钮 | 对应功能 | 接口 | 详细说明 |
| --- | --- | --- | --- |
| 查询 | 按用户编号、用户名、时间、IP 筛选 | `GET /admin/user-login-history` | 查询后页码回到第 1 页 |
| 重 置 | 清空筛选条件 | `GET /admin/user-login-history` | 回到全部登录历史 |
| 快速封禁 | 从登录记录封禁用户 | `PATCH /admin/users/{id}/status` | 需二次确认；封禁后撤销在线会话 |

表格字段说明：

| 表格字段 | 接口字段建议 | 含义 | 展示规则 |
| --- | --- | --- | --- |
| 用户编号 | `user_no` | 用户对外编号 | 支持筛选 |
| 用户名 | `username` | 用户名 | 支持筛选 |
| 当前状态 | `status` | 用户当前状态 | 正常/已封禁/已注销 |
| 登录时间 | `login_at` | 本次登录时间 | 倒序排列 |
| 设备类型 | `device_type` | 登录终端 | web/android/ios |
| 设备型号 | `device_model` | 设备名称 | 样例：OPPO PCHM10 |
| 系统版本 | `os_version` | 操作系统版本 | 样例：Android 11 |
| App 版本 | `app_version` | 客户端版本 | web 可显示 `-` |
| IP 地址 | `ip` | 登录 IP | 支持筛选 |
| 归属地 | `ip_location` | IP 地理位置 | 无法解析显示未知 |

枚举说明：

- 设备类型：`web` Web 端、`android` Android APP、`ios` iOS APP、`unknown` 未知设备。
- 用户状态同用户管理。

截图：

![用户登录](screenshots-queried/16-user-login.png)

### 3.17 IP 账号统计

路由：`/ip-user-stats`  
核心接口：

- `GET /admin/audit/ip-user-stats`
- `GET /admin/audit/ip-user-stats/users`
- `POST /admin/users/ban-by-ip`

查询条件：

- IP，支持 IPv4 或 IPv6

表格列：

- IP 地址
- 归属地
- 关联用户
- 注册用户
- 登录用户
- 正常
- 已封禁
- 最近活动
- 操作

行操作：

- 用户列表
- 封禁 IP，平台级账号可见

按钮功能说明：

| 按钮 | 对应功能 | 接口 | 详细说明 |
| --- | --- | --- | --- |
| 查询 | 按 IP 筛选统计 | `GET /admin/audit/ip-user-stats` | 支持 IPv4/IPv6 |
| 重 置 | 清空 IP | `GET /admin/audit/ip-user-stats` | 回到全部统计 |
| 用户列表 | 查看该 IP 关联用户 | `GET /admin/audit/ip-user-stats/users` | 弹窗展示注册/登录命中的用户 |
| 封禁 IP | 封禁该 IP 关联用户 | `POST /admin/users/ban-by-ip` | 平台账号可见；返回命中数、成功数、失败数 |

表格字段说明：

| 表格字段 | 接口字段建议 | 含义 | 展示规则 |
| --- | --- | --- | --- |
| IP 地址 | `ip` | 统计 IP | IPv4/IPv6 |
| 归属地 | `ip_location` | IP 地理位置 | 样例：浙江 绍兴 |
| 关联用户 | `user_count` | 注册或登录命中过该 IP 的用户数 | 大于 1 显示“多账号”标签 |
| 注册用户 | `register_user_count` | 使用该 IP 注册的用户数 | 数字 |
| 登录用户 | `login_user_count` | 使用该 IP 登录的用户数 | 数字 |
| 正常 | `active_user_count` | 关联用户中正常数量 | 数字 |
| 已封禁 | `disabled_user_count` | 关联用户中封禁数量 | 数字 |
| 最近活动 | `last_seen_at` | 最近注册或登录时间 | `YYYY-MM-DD HH:mm:ss` |

关联用户弹窗字段：

- 用户 ID，平台账号可见。
- 用户编号、用户名、昵称。
- 来源：注册、登录，可同时命中。
- 状态：正常、已封禁。
- 最近活动。

截图：

![IP 账号统计](screenshots-queried/17-ip-account-stats.png)

### 3.18 登录失败日志

路由：`/login-failure-logs`  
核心接口：

- `GET /admin/login-failure-logs`
- `POST /admin/security/unlock`

查询条件：

- 类型
- 登录账号
- IP
- 开始时间
- 结束时间

表格列：

- 类型
- 登录账号
- 失败原因
- IP 地址
- User-Agent
- 时间
- 操作

行操作：

- 解锁

按钮功能说明：

| 按钮 | 对应功能 | 接口 | 详细说明 |
| --- | --- | --- | --- |
| 查询 | 按类型、账号、IP、时间筛选 | `GET /admin/login-failure-logs` | 查询后页码回到第 1 页 |
| 重 置 | 清空筛选条件 | `GET /admin/login-failure-logs` | 回到全部失败记录 |
| 解锁 | 解除账号或 IP 登录锁定 | `POST /admin/security/unlock` | 需二次确认 |

表格字段说明：

| 表格字段 | 接口字段建议 | 含义 | 展示规则 |
| --- | --- | --- | --- |
| 类型 | `type` | 登录失败账号类型 | 用户/管理员 |
| 登录账号 | `account` | 输入的账号 | 手机号、用户名或管理员账号 |
| 失败原因 | `reason` | 失败说明 | 样例：密码错误 |
| IP 地址 | `ip` | 失败来源 IP | 支持筛选 |
| User-Agent | `user_agent` | 客户端 UA | 长文本省略 |
| 时间 | `created_at` | 失败时间 | 倒序排列 |

枚举说明：

- 类型：`user` 用户、`admin` 管理员。
- 失败原因：`password_error` 密码错误、`account_not_found` 账号不存在、`account_disabled` 账号被封禁、`captcha_error` 验证码错误、`ip_blocked` IP 被拦截、`too_many_attempts` 连续失败次数过多。

截图：

![登录失败日志](screenshots-queried/18-login-failures.png)

### 3.19 私域设置

路由：`/tenant-settings`  
核心接口：

- `GET /admin/tenant-settings`
- `PUT /admin/tenant-settings`

配置项：

- 消息字符上限：范围 1 到 5000，仅允许调低
- 图片大小上限：范围 1 到 1000 MB
- 文件大小上限：范围 1 到 1000 MB，默认 50 MB
- 最大撤回消息时间：范围 1 到 1440 分钟；群主/管理员可撤回自己或他人消息，普通用户撤回自己的消息固定为 2 分钟
- 是否开启手机验证码：关闭后，注册仅支持邀请码，短信登录与忘记密码不可用

操作：

- 保存设置

按钮与字段说明：

| 字段/按钮 | 接口字段建议 | 范围/枚举 | 业务影响 |
| --- | --- | --- | --- |
| 消息字符上限 | `message_char_limit` | 1 到 5000，仅允许调低 | 用户发送文本消息时校验长度 |
| 图片大小上限（MB） | `image_size_limit_mb` | 1 到 1000 | 图片上传前后端双校验 |
| 文件大小上限（MB） | `file_size_limit_mb` | 1 到 1000，默认 50 | 文件上传前后端双校验 |
| 最大撤回消息时间（分钟） | `max_recall_minutes` | 1 到 1440 | 群主/管理员撤回自己或他人消息的最长时限 |
| 是否开启手机验证码 | `sms_code_enabled` | 开启/关闭 | 关闭后注册仅支持邀请码，短信登录与忘记密码不可用 |
| 保存设置 | - | - | 提交当前租户配置，后端校验后清理租户配置缓存 |

枚举说明：

- `sms_code_enabled=true`：开启手机验证码，支持短信登录、忘记密码、手机号验证码注册。
- `sms_code_enabled=false`：关闭手机验证码，仅支持邀请码注册。

截图：

![私域设置](screenshots-queried/19-private-domain-settings.png)

### 3.20 安全策略

路由：`/security-settings`  
核心接口：

- `GET /admin/security-settings`
- `PUT /admin/security-settings`
- `POST /admin/security/unlock`

配置分组与字段：

- 用户安全
  - 验证码触发次数：连续密码错误该次数后要求验证码，范围 1 到 10
  - 密码最小位数：范围 6 到 32
  - 强制包含字母
- 注册登录管控
  - 用户注册功能
  - 修改密码功能
  - 用户登录功能
  - Web 端多端登录
- 聊天消息管控
  - 全局好友功能
  - 全局群消息
  - 全局私聊消息
  - 群聊发言间隔：0 表示不限制；1 到 1000 表示同一群内两次发言的最小间隔
- 群组功能管控
  - 群号搜索功能
  - 群创建功能
  - 群解散功能
  - 群管理员功能
  - 是否显示群人数
- 其他功能开关
  - 允许用户注销账号
- IP 访问控制
  - 注册 IP 黑名单：每行一个 IPv4、IPv6 或 CIDR，命中后无法注册及获取注册短信验证码
  - 登录 IP 黑名单：命中后无法密码登录、短信登录及刷新 Token；黑名单优先级高于用户分组登录白名单
- 高级功能
  - 消息已读状态

操作：

- 保存设置

按钮与字段说明：

| 分组 | 字段 | 接口字段建议 | 范围/枚举 | 业务影响 |
| --- | --- | --- | --- | --- |
| 用户安全 | 验证码触发次数 | `captcha_trigger_count` | 1 到 10 | 连续密码错误达到次数后要求验证码 |
| 用户安全 | 密码最小位数 | `password_min_length` | 6 到 32 | 注册、修改密码、后台重置密码均生效 |
| 用户安全 | 强制包含字母 | `password_require_letter` | 开启/关闭 | 开启后密码必须包含英文字母 |
| 注册登录管控 | 用户注册功能 | `user_register_enabled` | 开启/关闭 | 关闭后用户端隐藏注册入口 |
| 注册登录管控 | 修改密码功能 | `password_change_enabled` | 开启/关闭 | 关闭后用户无法自行修改密码 |
| 注册登录管控 | 用户登录功能 | `user_login_enabled` | 开启/关闭 | 关闭后用户无法登录，不影响已登录用户 |
| 注册登录管控 | Web 端多端登录 | `web_multi_login_enabled` | 开启/关闭 | 开启后同账号可多浏览器同时登录 |
| 聊天消息管控 | 全局好友功能 | `global_friend_enabled` | 开启/关闭 | 关闭后无法搜索和添加好友 |
| 聊天消息管控 | 全局群消息 | `global_group_message_enabled` | 开启/关闭 | 关闭后所有群无法发送消息 |
| 聊天消息管控 | 全局私聊消息 | `global_private_message_enabled` | 开启/关闭 | 关闭后所有私聊无法发送消息 |
| 聊天消息管控 | 群聊发言间隔（秒） | `group_message_interval_seconds` | 0 到 1000 | 0 不限制，其他值限制同群发言间隔 |
| 群组功能管控 | 群号搜索功能 | `group_search_enabled` | 开启/关闭 | 关闭后隐藏群号和群搜索入口 |
| 群组功能管控 | 群创建功能 | `group_create_enabled` | 开启/关闭 | 关闭后所有人无法新建群聊 |
| 群组功能管控 | 群解散功能 | `group_dissolve_enabled` | 开启/关闭 | 关闭后用户端无法解散群，不影响后台 |
| 群组功能管控 | 群管理员功能 | `group_admin_enabled` | 开启/关闭 | 关闭后无法设置群管理员 |
| 群组功能管控 | 是否显示群人数 | `show_group_member_count` | 开启/关闭 | 关闭后用户端群资料不显示总人数 |
| 其他功能开关 | 允许用户注销账号 | `account_deactivate_enabled` | 开启/关闭 | 关闭后隐藏注销账号按钮 |
| IP 访问控制 | 注册 IP 黑名单 | `register_ip_blacklist` | 多行 IP/CIDR | 命中后无法注册和获取注册短信验证码 |
| IP 访问控制 | 登录 IP 黑名单 | `login_ip_blacklist` | 多行 IP/CIDR | 命中后无法密码登录、短信登录和刷新 Token |
| 高级功能 | 消息已读状态 | `message_read_status_enabled` | 开启/关闭 | 开启后显示消息已读/未读标记 |
| 保存设置 | - | - | 保存安全配置，写操作日志，刷新配置缓存 |

枚举说明：

- 所有开关均使用布尔值：`true` 开启，`false` 关闭。
- IP 黑名单每行一个 IPv4、IPv6 或 CIDR，保存时去空行、去重、校验格式。
- 登录 IP 黑名单优先于用户分组白名单。

截图：

![安全策略](screenshots-queried/20-security-policy.png)

## 4. 接口清单

从前端静态资源反查到的接口如下，建议后端按 REST 风格补齐：

| 模块 | 接口 |
| --- | --- |
| 认证 | `/admin/auth/login`, `/admin/auth/profile`, `/admin/auth/password`, `/admin/auth/totp/status`, `/admin/auth/totp/setup`, `/admin/auth/totp/bind`, `/admin/auth/totp/unbind` |
| 统计 | `/admin/stats` |
| 用户 | `/admin/users`, `/admin/users/{id}`, `/admin/users/{id}/status`, `/admin/users/{id}/username`, `/admin/users/{id}/reset_password`, `/admin/users/{id}/ip-whitelist`, `/admin/users/{id}/friend-privilege`, `/admin/users/{id}/security-perm`, `/admin/users/{id}/kick`, `/admin/users/{id}/deactivate`, `/admin/users/batch`, `/admin/users/batch-ban`, `/admin/users/ban-by-ip`, `/admin/users/import-xlsx` |
| 用户分组 | `/admin/user-policy-groups`, `/admin/user-policy-groups/{id}`, `/admin/user-policy-groups/{id}/users`, `/admin/user-policy-groups/ip-whitelist` |
| 群组 | `/admin/groups`, `/admin/groups/{id}`, `/admin/groups/{id}/ban`, `/admin/groups/{id}/unban`, `/admin/groups/{id}/members`, `/admin/groups/{id}/members/kick`, `/admin/groups/{id}/members/mute`, `/admin/groups/{id}/members/unmute`, `/admin/groups/{id}/files`, `/admin/groups/{id}/files/{fileId}`, `/admin/groups/events`, `/admin/groups/quick-create` |
| 消息与文件 | `/admin/messages/search`, `/admin/messages/{id}` |
| 邀请码 | `/admin/invite-codes`, `/admin/invite-codes/{id}`, `/admin/invite-codes/{id}/usages` |
| 敏感词 | `/admin/sensitive-words`, `/admin/sensitive-words/{id}`, `/admin/sensitive-words/import`, `/admin/sensitive-words/export` |
| 反馈 | `/admin/feedbacks`, `/admin/feedbacks/{id}`, `/admin/feedbacks/{id}/priority`, `/admin/feedbacks/batch-handle`, `/admin/feedbacks/export` |
| 审计 | `/admin/audit/logs`, `/admin/audit/user-account-logs`, `/admin/audit/ip-user-stats`, `/admin/audit/ip-user-stats/users`, `/admin/control/audit-logs` |
| 登录日志 | `/admin/admin-login-history`, `/admin/user-login-history`, `/admin/login-failure-logs` |
| 设置 | `/admin/tenant-settings`, `/admin/security-settings`, `/admin/security/unlock` |
| 当前菜单未展示但 bundle 存在 | `/admin/tenants`, `/admin/admins`, `/admin/tenant-admins`, `/admin/roles`, `/admin/nodes`, `/admin/system/nodes-status`, `/admin/avatar-pool`, `/admin/avatar-pool/backfill`, `/admin/system-conversations`, `/admin/system-conversations/send`, `/admin/conversation-notices`, `/admin/reports`, `/admin/login-streak/rank`, `/admin/private-msg/rank`, `/admin/user-password`, `/admin/keyword-alerts`, `/admin/alert-keywords`, `/admin/alert-bot-config`, `/admin/domain/encrypt`, `/admin/domain/decrypt`, `/admin/domain/obfuscate`, `/admin/domain/config`, `/admin/domain/push-update`, `/admin/domain/push-bucket-update` |

通用响应结构建议：

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [],
    "total": 0,
    "page": 1,
    "size": 20
  }
}
```

列表接口统一分页参数：

- `page`
- `page_size`
- 各页面查询条件

## 5. 核心数据模型建议

建议至少设计以下数据表或领域模型：

- 管理员账号：账号、密码、TOTP、角色、权限、登录历史
- 用户：用户编号、用户名、昵称、手机号、头像、状态、注册方式、用户分组、最近登录、创建时间
- 用户分组：权限开关、好友上限、登录白名单、排序权重、默认分组标记
- 群组：群号、名称、群主、成员数、状态、创建时间
- 群成员：用户、群、角色、群昵称、禁言状态、加入时间
- 消息：会话类型、发送人、接收人/群、消息类型、内容、文件信息、状态、发送时间
- 文件记录：发送人、接收方、文件类型、文件名、大小、URL、消息关联、状态
- 邀请码：邀请码、指定用户、自动加好友、使用人数、创建人、状态、有效期
- 敏感词：词条、等级、替换词、状态、创建时间
- 用户反馈：用户、联系方式、内容、优先级、状态、处理人、处理备注
- 操作日志：管理员、动作、目标类型、目标、查询条件、IP、时间
- 用户账号审计：目标用户、操作者、操作类型、变更前后、IP、归属地、设备
- 群事件审计：群、事件类型、操作人、目标用户、可见范围、旧值、新值、时间
- 登录历史：账号类型、账号、登录时间、设备信息、IP、归属地
- 登录失败日志：类型、账号、失败原因、IP、User-Agent、锁定/解锁状态
- 租户设置：消息、文件、验证码、撤回时间等私域配置
- 安全策略：密码、注册登录、聊天、群组、注销、IP 黑名单、已读状态配置

## 6. 权限建议

前端 bundle 中能看到的权限点包括：

- `tenant_manage`
- `user_manage`
- `group_manage`
- `view_private_chat`
- `view_group_chat`
- `view_audit_log`

建议在 HotGo 中拆成更细的菜单/按钮权限：

- 用户管理：查看、创建、批量创建、导入、详情、重置密码、调整分组、封禁、强制下线、注销、IP 白名单
- 群组管理：查看、详情、群文件、封禁、解散、成员踢出、禁言/解除禁言
- 内容审核：消息查看、文件预览下载删除、敏感词增删改导入导出、反馈处理导出
- 日志审计：查看、导出、解锁、IP 关联用户查看、按 IP 封禁
- 系统设置：私域设置保存、安全策略保存

## 7. 实现优先级

第一阶段建议先完成可见菜单：

1. 后台登录、权限、菜单、布局。
2. 数据概览统计。
3. 用户管理、用户分组、群组管理、群成员管理、邀请码管理。
4. 单聊/群聊消息、文件管理、敏感词库、用户反馈。
5. 操作日志、用户账号审计、群事件审计、登录历史、IP 统计、失败日志。
6. 私域设置、安全策略。

第二阶段再补 bundle 中存在但当前菜单未展示的能力：

- 租户、管理员、角色、节点、头像池、系统会话、系统通知、报表、排行榜、关键词告警、域名加密等。

## 8. 采集产物

本次调研文件保存在：

- 截图目录：`docs/admin-adfahi-research/screenshots-queried/`
- 每页结构化采集：`docs/admin-adfahi-research/*.json`
- 前端 bundle：`docs/admin-adfahi-research/index-RosMaKu2.js`
- 接口尝试结果：`docs/admin-adfahi-research/api-samples.json`