1463 lines
54 KiB
Markdown
1463 lines
54 KiB
Markdown
# 鸽达达管理后台复刻需求文档
|
||
|
||
调研对象：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` |
|
||
|
||
菜单总览截图：
|
||
|
||
|
||
|
||
## 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`。
|
||
- 页面需支持后续扩展为折线图，但必须保留日期和数量明细。
|
||
|
||
截图：
|
||
|
||
|
||
|
||
### 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`。
|
||
|
||
截图：
|
||
|
||
|
||
|
||
### 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 登录需命中对应白名单；全局黑名单优先级高于白名单。
|
||
|
||
截图：
|
||
|
||
|
||
|
||
### 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` 已解散。
|
||
- 群文件类型：图片、视频、音频、文档、其他。
|
||
|
||
截图：
|
||
|
||
|
||
|
||
### 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`，角色为群主。
|
||
|
||
截图：
|
||
|
||
|
||
|
||
### 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` 否。
|
||
|
||
截图：
|
||
|
||
|
||
|
||
### 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` 发送文本 `哈哈哈哈`。
|
||
|
||
截图：
|
||
|
||
|
||
|
||
### 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` 发送文本 `哈哈哈哈`。
|
||
|
||
截图：
|
||
|
||
|
||
|
||
### 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` 告警。
|
||
- 当前页面查询结果为空，需支持“暂无数据”空态。
|
||
|
||
截图：
|
||
|
||
|
||
|
||
### 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`。
|
||
|
||
截图：
|
||
|
||
|
||
|
||
### 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` 已关闭。
|
||
- 当前页面查询结果为空，需支持“暂无数据”空态。
|
||
|
||
截图：
|
||
|
||
|
||
|
||
### 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`。
|
||
|
||
截图：
|
||
|
||
|
||
|
||
### 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 封禁 |
|
||
|
||
截图：
|
||
|
||
|
||
|
||
### 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` 群解散。
|
||
|
||
截图：
|
||
|
||
|
||
|
||
### 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 |
|
||
|
||
截图：
|
||
|
||
|
||
|
||
### 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` 未知设备。
|
||
- 用户状态同用户管理。
|
||
|
||
截图：
|
||
|
||
|
||
|
||
### 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，平台账号可见。
|
||
- 用户编号、用户名、昵称。
|
||
- 来源：注册、登录，可同时命中。
|
||
- 状态：正常、已封禁。
|
||
- 最近活动。
|
||
|
||
截图：
|
||
|
||
|
||
|
||
### 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` 连续失败次数过多。
|
||
|
||
截图：
|
||
|
||
|
||
|
||
### 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`：关闭手机验证码，仅支持邀请码注册。
|
||
|
||
截图：
|
||
|
||
|
||
|
||
### 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 黑名单优先于用户分组白名单。
|
||
|
||
截图：
|
||
|
||
|
||
|
||
## 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`
|