im_manager/docs/admin-adfahi-research/Admin-Server改造文档.md

# Admin Server 改造文档：对齐鸽达达管理后台

本文基于 `docs/admin-adfahi-research/需求文档.md`、当前 `im_manager` 代码、`im_server` 文档与本地 MySQL 数据核对结果编写。目标是在 HotGo Admin Server 中复刻鸽达达后台的 20 个页面，并保持当前系统“Admin 只直连 hotgo 控制库，IM Server 只直连租户业务库”的边界。

> 实施状态（2026-09-07）：Admin 第二批已完成 `imDashboard`、`imPrivateMessage`、`imGroupMessage`、`imUserLoginHistory`、`imLoginFailureLog` 的 API、service、logic、controller、路由、Vue 页面、字典、导出和菜单权限。消息隐藏/删除、失败日志封禁用户使用 Kafka Admin Command；失败 IP 加黑复用安全策略。对应菜单 SQL 为 `server/storage/data/generate/im_adfahi_batch2_menu.sql`，已在本地 `hotgo` 执行。上述查询仍依赖 IM Server 本文约定的 internal-query；本地 `tinode` 尚无 `im_user_login_logs`、`im_login_failure_logs`，需在 IM Server 批次建表并接入日志采集后才会产生真实数据。

## 1. 改造边界

Admin Server 负责后台菜单、权限、页面、查询聚合、运营配置、Kafka 管理命令投递、命令结果展示与后台审计落库。业务 IM 数据不直接跨库读写，用户、群、消息、文件、反馈、登录等租户数据通过 IM Server 内部只读接口 `/internal/admin-query/tenants/{tenant_code}/...` 查询；用户封禁、群治理、消息处置、文件处置等写操作通过 Kafka Admin Command 下发。

当前本地库观察：

| 数据库 | 现状 |
| --- | --- |
| `hotgo` | 当前有 66 张表，已存在 `im_admin_commands`、`im_admin_operation_audit`、`im_admin_outbox`、`im_registration_invite_codes`、`im_external_config`、`im_file_policy`，并已新增策略分组、敏感词、安全策略和宵禁控制表。 |
| `tinode` | 当前有 73 张表，已有 `im_users`、`im_topics`、`im_subscriptions`、`im_messages`、`im_group_messages`、`im_group_settings`、`im_fileuploads`、`im_feedback_submissions` 等 IM 业务表。 |
| 联调状态 | `hotgo.im_tenant` 已补默认租户映射（`id=1`、`code=default`）；`tinode` 尚无用户登录历史和登录失败日志表，对应页面待 IM Server 批次补齐数据源。 |

敏感配置说明：`hg_sys_config` 中已有声网、阿里云、OSS、短信等配置项。文档与页面只能展示脱敏值，后续应补充加密存储、轮换、审计与权限控制。

## 2. 当前 Admin 能力盘点

已有后台 API 模块：

| 模块 | 主要能力 | 复用结论 |
| --- | --- | --- |
| `imUser` | 用户列表、详情、设备、重置密码、状态、封禁/解封、冻结/解冻、踢设备、全端登出、注销、删除 | 可作为“用户管理”的主体，补鸽达达字段、筛选项、批量操作与审计页联动。 |
| `imGroup` | 群列表、详情、成员、群治理、资料更新、解散、禁言、成员禁言/移除、入群申请、邀请、公告、文件、管理日志 | 可覆盖“群组管理”和“群成员管理”主体，需补独立菜单页与鸽达达状态/字段映射。 |
| `imInvite` | 邀请码列表、新增、批量新增、批量查看、撤销、批量撤销、导出 | 可覆盖“邀请码管理”，但邀请码格式与鸽达达需求存在差异。 |
| `imFile` | 文件列表、详情、隔离、删除、清理孤儿文件 | 可覆盖“文件管理”，需补预览/下载链接、审核枚举、内容风险字段。 |
| `imAuditLog` | 操作日志列表、详情、导出 | 可覆盖后台操作日志的一部分，需扩展为用户账号审计、群事件审计等专题页。 |
| `imKafkaCommand`、`imDeadLetter`、`imOutbox`、`imKafkaAudit` | Kafka 命令、死信、出站事件、审计事件 | 保留为运维治理菜单，不直接出现在鸽达达 20 个业务页中。 |
| `imRegistration`、`imExternalConfig`、`imFilePolicy`、`imFeedbackConfig`、`imMailboxConfig`、`imNotification`、`imAppRelease` | 注册、第三方、文件策略、反馈、邮箱、通知、版本配置 | 可组合成“私域设置”和“安全策略”，需要按鸽达达页面重组展示。 |

已有菜单已包含 `IM管理`、`注册邀请码`、`用户列表`、`群组列表`、`文件治理`、`Kafka命令`、`Kafka死信`、`Kafka审计事件`、`租户管理` 等。缺少与鸽达达完全一致的“单聊消息、群聊消息、敏感词库、用户反馈、用户登录、IP账号统计、登录失败日志”等前台页面。

## 3. 页面级改造

### 3.1 数据概览

新增或改造 `imDashboard` 页面。顶部统计按需求文档展示总用户数、活跃用户、总群组数、总会话数、总消息数、今日消息；趋势表展示最近 7 天用户增长、消息增长。现有 IM Server 内部接口已有 `/internal/admin-query/tenants/{tenant}/dashboard/summary`，但仅返回 `dead_kafka`、`pending_business`、`pending_group`、`pending_realname`、`received_abuse`、`received_feedback`、`active_groups`、`suspended_users`，不足以还原鸽达达数据概览。

Admin 改造：

| 项 | 方案 |
| --- | --- |
| API | 新增 `/imDashboard/overview`、`/imDashboard/trends`。 |
| 数据源 | 控制库租户信息来自 `im_tenant`；统计与趋势来自 IM internal query。 |
| 字段 | `totalUsers`、`activeUsers`、`totalGroups`、`totalConversations`、`totalMessages`、`todayMessages`、`date`、`userCount`、`messageCount`。 |
| 按钮 | 页面无写操作；支持租户切换、日期范围查询、刷新。 |
| 缺口 | IM Server 需补 dashboard 聚合项与趋势接口；Admin 需补租户为空时的默认租户兜底提示。 |

### 3.2 用户管理

复用 `imUser`，页面按鸽达达字段重排。列表数据通过 IM internal `users` 查询，详情通过 `/users/{id}`，设备通过 `/users/{id}/devices`。当前 Admin 已有 `/imUser/list`、`/imUser/view`、`/imUser/devices`、`/imUser/ban`、`/imUser/unban`、`/imUser/freeze`、`/imUser/unfreeze`、`/imUser/deviceKick`、`/imUser/logoutAll`、`/imUser/accountCancel`、`/imUser/accountDelete`、`/imUser/resetPassword`。

字段说明：

| 字段 | 来源 | 说明 |
| --- | --- | --- |
| `user_id` | `tinode.im_users.id` 编码后 | 用户唯一 ID，列表、详情、审计联动主键。 |
| `username` | `im_users.username` | 登录账号。 |
| `phone` | `im_users.phone` | 手机号，页面默认脱敏，导出需权限。 |
| `nickname` | `im_user_profiles.nickname` | 昵称，支持模糊查询。 |
| `public_account` | `im_user_profiles.public_account` | 对外账号/靓号。 |
| `state` | `im_users.state` | Tinode 用户状态。建议映射为正常、封禁、冻结、注销、删除。 |
| `last_seen` | `im_users.last_seen` | 最后在线/活跃时间。 |
| `created_at` | `im_users.created_at` | 注册时间。 |
| `credentials` | IM internal 聚合 | 认证方式摘要，不展示密钥。 |

按钮功能：

| 按钮 | 已有接口 | 功能 |
| --- | --- | --- |
| 查询 | `/imUser/list` | 按用户 ID、昵称、账号、手机号、状态、注册时间、最后活跃时间筛选。 |
| 重置 | 前端表单重置 | 清空筛选项并重新查询。 |
| 查看 | `/imUser/view` | 展示基础信息、资料、设备、最近审计事件。 |
| 封禁/解封 | `/imUser/ban`、`/imUser/unban` | Kafka 命令 `user.ban` / `user.unban`，需填写原因和过期时间。 |
| 冻结/解冻 | `/imUser/freeze`、`/imUser/unfreeze` | Kafka 命令 `user.freeze` / `user.unfreeze`。 |
| 踢设备 | `/imUser/deviceKick` | 指定设备下线。 |
| 全端登出 | `/imUser/logoutAll` | 下发 `user.logout_all`。 |
| 注销/删除 | `/imUser/accountCancel`、`/imUser/accountDelete` | 高危操作，二次确认并写审计。 |

枚举说明：`state` 当前来自 Tinode 状态值，Admin 应新增统一字典 `im_user_state`，至少包含正常、封禁、冻结、注销、删除。封禁/冻结原因不应写死在前端，可复用“安全策略”中的处置原因配置。

### 3.3 用户分组

当前缺少等价模块，需要新增 `imUserPolicyGroup`。该页面不是组织部门，而是账号策略分组，用于控制注册、登录、私聊、建群、入群、发文件、发消息、IP 限制等策略。

Admin 改造：

| 项 | 方案 |
| --- | --- |
| 后端模块 | `api/admin/imuserpolicygroup`、`controller/admin/sys/im_user_policy_group.go`、`logic/sys/im_user_policy_group.go`、`model/input/sysin/im_user_policy_group.go`。 |
| 控制表 | 新增 `im_user_policy_groups`、`im_user_policy_group_members`。 |
| API | `/imUserPolicyGroup/list`、`/view`、`/edit`、`/delete`、`/status`、`/memberList`、`/memberAdd`、`/memberRemove`。 |
| 同步 | 策略变更写 `im_admin_outbox`，发布 Kafka config event；IM Server 缓存策略并执行。 |
| 页面按钮 | 查询、新增、编辑、删除、启用/禁用、成员管理、导出。 |

字段说明：

| 字段 | 说明 |
| --- | --- |
| `group_code` | 分组编码，唯一，不可编辑。 |
| `group_name` | 分组名称。 |
| `priority` | 命中多个分组时的优先级，数字越大优先级越高。 |
| `status` | 启用、禁用。 |
| `policy_json` | 策略 JSON，包含消息、好友、群、文件、登录等开关与限额。 |
| `ip_whitelist`、`ip_blacklist` | IP 白名单/黑名单，支持 CIDR。 |
| `remark` | 备注。 |

好友策略必须覆盖移动端所有加好友入口，不能只依赖前端隐藏。分组策略中至少包含 `allow_add_friend`、`direct_add_friend`、`max_friend_count`、`allow_view_profile_when_friend_disabled`、`allow_qrcode_add_friend`、`allow_group_member_profile`。当全局或分组禁止加好友时，从搜索、通讯录推荐、群成员列表、个人名片、二维码解析、邀请注册自动加好友、转发目标联系人等入口都必须由后端返回禁止或脱敏数据。

枚举说明：`status` 使用 `sys_normal_disable`；策略开关使用布尔值；策略动作建议统一枚举 `allow`、`deny`、`challenge`、`audit_only`。好友入口枚举建议 `search`、`profile_card`、`group_member`、`qrcode`、`invite_auto_add`、`recommendation`。

### 3.4 群组管理

复用 `imGroup`。列表通过 IM internal `groups` 查询，详情通过 `/groups/{topic}`，现有 Admin 已有群资料、治理、成员、申请、邀请、公告、文件、日志等接口。

字段说明：

| 字段 | 来源 | 说明 |
| --- | --- | --- |
| `topic` | `im_topics.name` | 群 Topic，等价群号/群唯一标识。 |
| `group_name` | `im_group_settings.group_name` | 群名称。 |
| `owner_id` | `im_topics.owner` | 群主。 |
| `group_status` | `im_group_settings.group_status` | 群业务状态。 |
| `state` | `im_topics.state` | Tinode topic 状态。 |
| `business_member_count` | `im_group_settings.business_member_count` | 成员数。 |
| `join_approval` | `im_group_settings.join_approval` | 入群审批开关。 |
| `mute_all` | `im_group_settings.mute_all` | 全员禁言。 |
| `created_at`、`updated_at` | topic/settings | 创建与更新时间。 |

按钮功能：

| 按钮 | 已有接口 | 功能 |
| --- | --- | --- |
| 查询 | `/imGroup/list` | 按群号、群名、群主、状态、创建时间查询。 |
| 查看 | `/imGroup/view` | 群资料、成员、公告、邀请、文件、治理配置汇总。 |
| 编辑资料 | `/imGroup/profileUpdate` | Kafka `group.profile.update`。 |
| 治理设置 | `/imGroup/governanceUpdate` | Kafka `group.governance.update`，控制入群审批、全员禁言、成员上传文件、成员私聊、成员邀请。 |
| 解散 | `/imGroup/dissolve` | 高危操作，二次确认。 |
| 禁言/解禁言 | `/imGroup/mute`、`/imGroup/unmute` | 群级禁言。 |
| 成员/申请/邀请/公告/文件/日志 | 已有子接口 | 打开子面板或跳转专题页。 |

枚举说明：新增 `im_group_status`，建议值 `active` 正常、`muted` 禁言、`suspended` 封停、`dissolved` 已解散。当前 IM 命令未看到明确 `group.ban`/`group.unban`，如鸽达达要求群封停，需要新增 Kafka 命令或通过治理状态统一处理。

### 3.5 群成员管理

复用 `/imGroup/memberList` 与成员治理命令，新增独立菜单页 `imGroupMember`，默认要求输入群号或从群详情跳转携带 `topic`。

字段说明：

| 字段 | 说明 |
| --- | --- |
| `topic` | 群 Topic。 |
| `user_id` | 成员用户 ID。 |
| `display_name`/`nickname` | 群内展示名或用户昵称。 |
| `role` | 群主、管理员、普通成员。 |
| `status` | 正常、禁言、已移除。 |
| `muted_until` | 禁言截止时间。 |
| `joined_at` | 入群时间。 |

按钮功能：查询、查看用户、设为管理员、取消管理员、转让群主、成员禁言、解除禁言、移除成员。现有接口分别为 `/imGroup/adminSet`、`/adminRemove`、`/ownerTransfer`、`/memberMute`、`/memberUnmute`、`/memberRemove`。

枚举说明：`role` 新增字典 `im_group_member_role`：`owner` 群主、`admin` 管理员、`member` 成员；成员状态新增 `im_group_member_status`。

### 3.6 邀请码管理

复用 `imInvite`。本地 `hotgo.im_registration_invite_codes` 有样例数据，批次表为空。当前需求文档按鸽达达页面描述 6 位数字邀请码；历史 IM 文档曾描述 5 位 ASCII 字母邀请码，二者冲突。若以复刻鸽达达为目标，应统一改为 6 位数字，Admin 生成、IM 注册校验、数据库唯一索引与错误文案同步调整。

字段说明：`code` 邀请码、`batch_id` 批次、`status` 状态、`max_uses` 最大使用次数、`used_count` 已使用次数、`expires_at` 过期时间、`created_by` 创建管理员、`created_at` 创建时间、`revoked_at` 撤销时间。

按钮功能：查询、新增、批量生成、批量查看、撤销、批量撤销、导出。接口已有 `/imInvite/list`、`/create`、`/batchCreate`、`/batchView`、`/revoke`、`/batchRevoke`、`/export`。

枚举说明：新增或确认 `im_invite_status`：`unused` 未使用、`used` 已用完、`expired` 已过期、`revoked` 已撤销。

### 3.7 单聊消息

当前 Admin 缺少独立消息管理模块，需要新增 `imPrivateMessage`。IM Server 已有消息表 `im_messages`，但 internal admin query 目前只支持 `/messages/{topic}/{seq}` 单条查询，缺少按会话分页检索单聊消息的后台列表接口。

Admin 改造：

| 项 | 方案 |
| --- | --- |
| API | `/imPrivateMessage/list`、`/view`、`/hide`、`/delete`、`/export`。 |
| 数据源 | 新增 IM internal query：`/tenants/{tenant}/private-messages` 或 `/messages?kind=p2p`。 |
| 写操作 | 通过 Kafka 命令新增 `message.hide`、`message.delete` 或复用 IM 已有 recall/delete 能力封装为后台命令。 |
| 页面按钮 | 查询、查看上下文、隐藏、删除、导出。 |

字段说明：`topic` 会话 Topic、`seq_id` 消息序号、`from_user_id` 发送者、`to_user_id` 接收者、`content_type` 内容类型、`content` 内容摘要、`status` 状态、`created_at` 发送时间、`updated_at` 更新时间。

枚举说明：`content_type` 建议 `text`、`image`、`file`、`audio`、`video`、`card`、`system`；`status` 建议 `normal`、`recalled`、`hidden`、`deleted`。

### 3.8 群聊消息

新增 `imGroupMessage` 页面。IM Server 本地有 `im_group_messages` 表，需求需要按群号、发送者、时间、内容关键字筛选。

Admin 改造：新增 `/imGroupMessage/list`、`/view`、`/hide`、`/delete`、`/export`。IM Server 补 internal query `group-messages`，支持 `topic`、`sender_user_id`、`content_type`、`status`、`created_at_start/end`、`keyword`。

字段、按钮、枚举与单聊消息一致，额外展示 `group_name`、`member_role`、`at_users`、`reply_to_seq`。

### 3.9 敏感词库

当前 Admin 与 IM Server 未发现完整敏感词库模块，需要新增。Admin 维护词库，IM Server 在消息发送、昵称/群名修改、反馈/举报提交时执行匹配。

Admin 改造：

| 项 | 方案 |
| --- | --- |
| 表 | `im_sensitive_words`、`im_sensitive_word_groups`、`im_sensitive_word_hits` 可按需拆分。 |
| API | `/imSensitiveWord/list`、`/view`、`/edit`、`/delete`、`/status`、`/import`、`/export`。 |
| 同步 | 词库变更发布 config event 或 cache invalidate，IM Server 热加载。 |
| 按钮 | 查询、新增、编辑、删除、启用/禁用、导入、导出。 |

字段说明：`word` 敏感词、`match_type` 匹配类型、`scene` 生效场景、`action` 命中动作、`replacement` 替换文本、`level` 风险等级、`status` 状态。

枚举说明：`match_type` 为 `exact` 精确、`contains` 包含、`regex` 正则；`scene` 为 `message` 消息、`profile` 资料、`group` 群资料、`feedback` 反馈；`action` 为 `block` 拦截、`replace` 替换、`review` 人审、`audit_only` 仅记录。

### 3.10 文件管理

复用 `imFile`，补齐鸽达达文件字段和预览能力。IM internal 已支持 `files`、`files/{id}`、`files/{id}/links`。本地 `tinode.im_fileuploads` 有数据，`im_group_files` 暂无数据。

字段说明：`file_id` 文件 ID、`user_id` 上传者、`topic` 所属会话、`mime_type` MIME、`size` 文件大小、`location` 存储位置、`etag` 校验、`status` 状态、`review_status` 审核状态、`risk_level` 风险等级、`created_at` 上传时间。

按钮功能：查询、查看、预览/下载、隔离、删除、清理孤儿文件。现有接口 `/imFile/quarantine`、`/imFile/delete`、`/imFile/cleanupOrphan` 可复用；预览/下载建议由 Admin 获取短期签名 URL，不直接暴露 OSS 原始地址。

枚举说明：现有字典包括 `im_storage_provider=oss`、`im_file_review_provider`、`im_file_review_status(pending/running/clean/risky/failed)`、`im_file_review_task_type(content/malware)`；还需补 `im_file_status`：`normal` 正常、`quarantined` 已隔离、`deleted` 已删除。

### 3.11 用户反馈

IM Server 已有 `im_feedback_submissions` 和 internal resource `feedback-submissions`，Admin 目前有反馈配置和工单模块，但缺少完全按鸽达达展示的反馈列表页。建议新增 `imFeedback` 或改造 `imWorkOrder` 作为反馈处理页。

字段说明：`feedback_id` 反馈 ID、`user_id` 用户、`category` 分类、`content` 内容、`contact` 联系方式、`file_ids` 附件、`client_context` 客户端环境、`include_diagnostics` 是否含诊断、`status` 状态、`created_at`、`updated_at`。

按钮功能：查询、查看、标记处理中、标记已处理、关闭、导出。写操作建议先落 Admin 工单状态，再通过 Kafka 或 IM internal 写接口回写业务状态。

枚举说明：`status` 建议 `received` 已收到、`processing` 处理中、`resolved` 已解决、`closed` 已关闭；`category` 来自 `im_feedback_config.categories`，禁止前端硬编码。

### 3.12 操作日志

复用 `imAuditLog` 与 `im_admin_operation_audit`。本地该表已有 45 条记录。页面应覆盖后台管理员对 IM 资源的所有操作，包括用户、群、消息、文件、配置、邀请码、敏感词。

字段说明：`id`、`request_id`、`admin_id`、`admin_name`、`action`、`target_type`、`target_id`、`before_data`、`after_data`、`ip`、`user_agent`、`result`、`created_at`。

按钮功能：查询、查看详情、导出。详情页需展示变更前后 JSON，敏感字段脱敏。

枚举说明：`target_type` 建议 `user`、`group`、`message`、`file`、`invite`、`config`、`sensitive_word`；`result` 为 `success`、`failed`、`pending`。

### 3.13 用户账号审计

新增专题页 `imUserAccountAudit`，从 Admin 操作审计、IM `audit-logs`、Kafka 命令结果中聚合用户生命周期事件。

字段说明：`event_id`、`user_id`、`action`、`operator_type`、`operator_id`、`reason`、`ip`、`device_id`、`before_state`、`after_state`、`created_at`。

按钮功能：查询、查看、跳转用户详情、导出。动作枚举建议包含注册、登录、登出、登录失败、改密、重置密码、封禁、解封、冻结、解冻、注销、删除、踢设备。

缺口：IM Server 当前 `im_audit_logs` 本地为空，需要补登录、失败、状态变更等事件写入。

### 3.14 群事件审计

可复用 `imGroup/adminLogList`、`outbox/group-events` 和 Admin audit，新增独立页面 `imGroupEventAudit`。

字段说明：`event_id`、`topic`、`group_name`、`operator_id`、`target_user_id`、`action`、`object_type`、`object_id`、`before_data`、`after_data`、`created_at`。

按钮功能：查询、查看、跳转群详情、导出。动作枚举建议包含建群、解散、修改资料、修改治理设置、入群申请、审批通过、审批拒绝、成员禁言、解除禁言、移除成员、设管理员、取消管理员、转让群主、公告发布/删除、文件删除。

### 3.15 管理员登录历史

复用 HotGo 系统登录日志能力，不需要 IM Server 改造。若现有登录日志字段不足，补 Admin 聚合接口 `/imAdminLoginHistory/list` 或直接配置菜单指向系统日志页面。

字段说明：管理员 ID、账号、昵称、登录 IP、地区、浏览器、系统、登录结果、失败原因、登录时间。

按钮功能：查询、查看、导出。枚举 `result` 为成功、失败。

### 3.16 用户登录历史

当前缺少完整用户登录历史。IM Server 路由中未看到客户端 `/v1/im/auth/logout` 或独立 session 管理路由；本地 `im_devices` 为空，不能满足鸽达达登录历史。

Admin 改造：新增 `imUserLoginHistory` 页面，查询 IM internal `user-login-logs`。字段包括 `user_id`、`phone`、`login_type`、`device_id`、`platform`、`ip`、`region`、`user_agent`、`result`、`login_at`、`logout_at`。

枚举说明：`login_type` 为 `password`、`sms`、`token_refresh`、`third_party`；`platform` 为 `ios`、`android`、`web`、`desktop`；`result` 为 `success`、`failed`。

### 3.17 IP 账号统计

新增 `imIpAccountStats` 页面。数据由 IM Server 基于注册 IP、登录 IP、失败登录 IP 聚合生成，Admin 只查询展示。

字段说明：`ip`、`region`、`user_count`、`register_count`、`login_count`、`failure_count`、`first_seen_at`、`last_seen_at`、`risk_level`。

按钮功能：查询、查看关联账号、导出、加入黑名单。加入黑名单写入“安全策略”或“用户分组”策略并同步 IM Server。

枚举说明：`risk_level` 为 `low`、`medium`、`high`；黑名单动作 `block_login`、`challenge`、`audit_only`。

### 3.18 登录失败日志

新增 `imLoginFailureLog` 页面。IM Server 需要记录认证失败事件，包含错误原因、IP、设备、账号、风控命中信息。

字段说明：`id`、`account`、`user_id`、`failure_type`、`reason`、`ip`、`region`、`device_id`、`platform`、`user_agent`、`attempt_at`。

按钮功能：查询、查看、导出、加入 IP 黑名单、封禁账号。封禁账号复用 `/imUser/ban`。

枚举说明：`failure_type` 为 `password_error`、`code_error`、`account_not_found`、`account_disabled`、`rate_limited`、`risk_blocked`。

### 3.19 私域设置

以现有 `imRegistration`、`imExternalConfig`、`imFeedbackConfig`、`imMailboxConfig`、`imNotification`、`imAppRelease` 为基础，新增汇总页面 `imTenantSettings`，按鸽达达页面展示私域基础配置。

字段说明：租户标识、注册开关、邀请码开关、短信开关、默认策略分组、客服/反馈配置、上传配置、客户端功能开关、版本策略、更新时间。客户端功能开关中新增 `global_friend_enabled` 和 `message_curfew_enabled` 的只读摘要，便于运营在私域设置页看到当前私域是否允许加好友、是否存在宵禁；实际编辑入口放在“安全策略”。

按钮功能：查看、编辑、保存、测试第三方配置、发布配置。保存后写 `hg_sys_config` 或 `im_tenant_config`，并通过 Kafka config event 通知 IM Server 刷新缓存。

枚举说明：开关统一使用布尔；配置发布状态 `draft`、`published`、`failed`。

### 3.20 安全策略

新增或重组 `imSecurityPolicy` 页面，统一管理登录安全、密码策略、IP 风控、敏感词动作、文件审核、用户处置原因、消息处置策略、全局好友功能与消息宵禁。

字段说明：`password_policy`、`login_rate_limit`、`ip_blacklist`、`ip_whitelist`、`sensitive_word_policy`、`file_review_policy`、`realname_policy`、`risk_challenge_policy`、`global_friend_enabled`、`friend_disabled_policy`、`message_curfew_enabled`、`message_curfew_rules`。

全局好友功能说明：

| 字段 | 说明 |
| --- | --- |
| `global_friend_enabled` | 全局是否允许加好友。关闭后所有移动端加好友入口都禁止。 |
| `friend_disabled_policy.hide_profile` | 禁止加好友时，群成员列表、个人名片、二维码解析是否隐藏个人资料。 |
| `friend_disabled_policy.block_qrcode` | 是否禁止通过二维码添加好友。 |
| `friend_disabled_policy.block_group_member_entry` | 是否禁止从群成员入口查看个人信息或发起添加。 |
| `friend_disabled_policy.blocked_entries` | 被禁用的移动端入口数组：`search`、`profile_card`、`group_member`、`qrcode`、`invite_auto_add`、`recommendation`。关闭全局好友功能时默认全部禁用。 |
| `friend_disabled_policy.message` | 移动端提示文案，例如“当前时段暂不允许添加好友”。 |

宵禁功能说明：

| 字段 | 说明 |
| --- | --- |
| `message_curfew_enabled` | 是否启用消息宵禁。 |
| `message_curfew_rules` | 宵禁规则数组，支持每天、工作日、周末、自定义日期。 |
| `start_time`、`end_time` | 宵禁开始和结束时间，支持跨天，例如 `18:00` 到次日 `09:00`。 |
| `scope` | 管控范围，默认至少包含 `private_message`，即单聊/私聊不能发消息；如产品确认，可扩展 `group_message`。 |
| `whitelist_user_ids`、`whitelist_group_ids` | 豁免用户或群，可选。 |
| `message` | 宵禁期间发送失败提示。 |

按钮功能：查询当前策略、编辑、保存、发布、恢复默认、查看发布历史。保存必须写操作审计。

枚举说明：风控动作统一 `allow`、`challenge`、`block`、`audit_only`；文件审核动作 `allow`、`quarantine`、`delete`、`manual_review`；宵禁范围 `private_message` 单聊/私聊、`group_message` 群聊；日期类型 `daily` 每天、`weekday` 工作日、`weekend` 周末、`custom` 自定义。

## 4. 后端实现方案

按 HotGo 规范新增模块时，必须完成 API、controller、service、logic、model/input、router/genrouter、前端 API、views/model、index、edit。接口命名沿用当前项目风格，例如 `/imPrivateMessage/list`，不直接照搬鸽达达 `/admin/private-messages` 路径；如后续需要兼容外部路径，可单独加网关映射。

新增模块建议：

| 优先级 | 模块 | 说明 |
| --- | --- | --- |
| P0 | `imDashboard` | 首页统计与趋势。 |
| P0 | `imPrivateMessage`、`imGroupMessage` | 单聊/群聊消息查询与处置。 |
| P0 | `imSensitiveWord` | 敏感词库与热更新。 |
| P0 | `imUserLoginHistory`、`imLoginFailureLog` | 用户登录与失败日志。 |
| P1 | `imUserPolicyGroup` | 用户策略分组。 |
| P1 | `imFeedback` | 用户反馈处理页。 |
| P1 | `imIpAccountStats` | IP 聚合与风控联动。 |
| P1 | `imUserAccountAudit`、`imGroupEventAudit` | 专题审计页。 |
| P2 | `imTenantSettings`、`imSecurityPolicy` | 运营配置整合页。 |

Admin 查询 IM 数据统一走 `server/internal/library/iminternal` 或现有 `imadmin` 封装，不在 logic 层直接拼接外部 HTTP 细节。写操作统一创建 `im_admin_commands` 与 `im_admin_outbox`，等待 Kafka result 更新状态；页面展示 `pending/success/failed/dead`。

## 5. 数据库与字典

配套建表与兼容迁移脚本见 [`sql/Admin-Server改造.sql`](sql/Admin-Server改造.sql)。脚本面向 `hotgo` 控制库，只保存管理配置和发布版本，不保存租户业务消息。

控制库新增表优先放在 `hotgo`：

| 表 | 用途 |
| --- | --- |
| `im_user_policy_groups` | 用户策略分组主表。 |
| `im_user_policy_group_members` | 用户与策略分组关系。 |
| `im_sensitive_word_groups` | 敏感词分组。 |
| `im_sensitive_words` | 敏感词主表。 |
| `im_security_policy` | 安全策略草稿/发布版本。 |
| `im_admin_query_snapshots` | 可选，用于缓存重型统计查询快照。 |

字典由后端 `internal/consts` 注册，前端通过 `dict.loadOptions()` 加载。禁止在 `model.ts` 中硬编码枚举中文。

必补字典：`im_user_state`、`im_group_status`、`im_group_member_role`、`im_group_member_status`、`im_invite_status`、`im_message_content_type`、`im_message_status`、`im_sensitive_match_type`、`im_sensitive_scene`、`im_sensitive_action`、`im_feedback_status`、`im_login_type`、`im_login_failure_type`、`im_risk_level`、`im_policy_action`、`im_friend_entry`、`im_curfew_scope`、`im_curfew_date_type`。

## 6. 权限与审计

每个按钮权限与后端路由保持一致，例如 `/imPrivateMessage/delete`、`/imSensitiveWord/import`。高危操作包括用户删除、账号注销、群解散、消息删除、文件删除、IP 拉黑、安全策略发布，必须二次确认、记录原因、写 `im_admin_operation_audit`，并展示 Kafka 命令执行结果。

审计脱敏规则：

| 类型 | 展示规则 |
| --- | --- |
| 手机号 | 中间 4 位脱敏。 |
| 身份证/实名 | 默认只展示脱敏字段。 |
| 配置密钥 | 只展示前后 3-4 位或完全隐藏。 |
| 消息内容 | 列表展示摘要，详情按权限展示全文。 |
| 文件地址 | 不展示原始存储地址，使用短期签名 URL。 |

## 7. 联调与验收

验收顺序建议：

1. 补齐 `hotgo.im_tenant` 与 `tinode` 默认租户映射，确保 Admin 能通过 tenant code 查询 IM internal。
2. 完成数据概览、用户、群、邀请码、文件这些已有基础模块的字段对齐。
3. 新增消息、敏感词、反馈、登录日志、IP 统计等缺口模块。
4. 为 Kafka 命令增加幂等键、结果回写、失败重试、死信展示。
5. 使用本地 `hotgo` 与 `tinode` 数据验证每个页面的查询、按钮、详情和导出。

最低验收标准：20 个菜单均可打开；查询按钮能返回真实或空态数据；表格字段与需求文档一致；所有枚举来自字典；高危按钮有二次确认、原因、审计与结果状态；敏感数据脱敏。