im_server/docs/IM-Admin内部查询接口缺口清单.md

IM Admin 内部查询接口缺口清单

目标：梳理 HotGo/Admin 迁移到“Admin 只访问 hotgo，IM Server 只访问租户库”后，IM Server 需要补齐的 /internal/admin-query/* 只读接口。
当前日期：2026-08-27
适用项目：im_manager Admin 后台、im_server IM 服务端。

1. 背景

Kafka 写链路已经在 Admin 侧补齐：Admin 写操作落 im_admin_commands、im_admin_outbox，通过 Kafka 发给 IM Server，IM Server 执行业务后回传 im.admin.command.result。

查询链路还没有完全隔离。Admin 当前仍有不少页面通过 imtenant.DB() 或 resolveImTenantDB() 直连租户库。若要严格满足目标架构，Admin 查询租户业务数据时应调用 IM Server 的内部只读接口：

GET /internal/admin-query/tenants/{tenant_code}/...

IM Server 当前已经具备部分内部查询接口，但还不能覆盖 Admin 后台页面。

2. 已有接口

以下接口在 IM Server 当前实现中已经存在，可供 Admin 先迁移：

接口	用途	备注
GET /internal/admin-query/tenants/{tenant_code}/users/{user_id}	用户详情	需要增强字段，见 P0。
GET /internal/admin-query/tenants/{tenant_code}/groups/{topic}	群详情和治理配置	需要增强 topic 基础字段，见 P0。
GET /internal/admin-query/tenants/{tenant_code}/groups/{topic}/members	群成员列表	当前偏 cursor 分页，Admin 表格还需要 total。
GET /internal/admin-query/tenants/{tenant_code}/messages/{topic}/{seq_id}	消息详情	当前 Admin 暂未完整迁移消息页面。
GET /internal/admin-query/tenants/{tenant_code}/files/{file_id}	文件详情	还缺文件列表和引用列表。
GET /internal/admin-query/tenants/{tenant_code}/kafka/dead-letters	Kafka 死信列表	Admin 已接入。
GET /internal/admin-query/tenants/{tenant_code}/kafka/dead-letters/{dead_id}	Kafka 死信详情	Admin 已接入。

3. 统一约定

3.1 鉴权

沿用 IM Server 内部 API HMAC 鉴权：

X-Service-Name
X-Timestamp
X-Nonce
X-Signature

服务端需要校验：

1. service 是否存在。
2. service 是否包含 admin_query capability。
3. timestamp 是否在允许窗口内。
4. nonce 是否防重放。
5. 签名是否匹配。

3.2 分页返回

Admin 的 BasicTable 更适合 page/per_page/total 格式。建议所有列表接口统一返回：

{
  "code": 0,
  "data": {
    "items": [],
    "total": 0,
    "page": 1,
    "per_page": 20
  }
}

如果 IM Server 内部更适合 cursor，也建议同时返回：

{
  "code": 0,
  "data": {
    "items": [],
    "total": 0,
    "page": 1,
    "per_page": 20,
    "next_cursor": "",
    "has_more": false
  }
}

3.3 详情返回

详情接口统一返回：

{
  "code": 0,
  "data": {}
}

3.4 时间与 ID

1. 时间统一返回 RFC3339/RFC3339Nano 字符串。
2. 雪花 ID、Tinode 用户 ID、19 位整数 ID 建议以字符串返回，避免前端丢精度。
3. 入参同时兼容字符串 ID 和纯数字 ID 时，IM Server 内部自行解析。

4. P0：优先补齐

P0 是 Admin 当前核心页面迁移所需接口，补完后可以先迁移用户、群组、文件等高频页面。

4.1 用户列表

GET /internal/admin-query/tenants/{tenant_code}/users

用途：IM 用户管理列表。

建议查询参数：

参数	类型	说明
user_id	string	用户 ID，支持精确查询。
nickname	string	昵称模糊查询。
auth_name	string	登录标识，匹配 username/phone/email/凭证。
state	int	用户状态。
created_at_start	string	创建时间开始。
created_at_end	string	创建时间结束。
last_seen_start	string	最后在线开始。
last_seen_end	string	最后在线结束。
page	int	页码。
per_page	int	每页数量，最大建议 200。

建议返回字段：

字段	说明
user_id	字符串用户 ID。
username	用户名。
phone	手机号。
nickname	昵称。
public_account	公开账号。
state	用户状态。
gender	性别。
region	地区。
auth_names	登录标识摘要。
credentials	凭证摘要。
auth_version	鉴权版本。
password_updated_at	密码更新时间。
last_seen	最后在线时间。
user_agent	最后设备 UA。
created_at	创建时间。
updated_at	更新时间。

当前 Admin 直连涉及表：im_users、im_user_profiles、im_user_security、im_credentials。

4.2 用户详情增强

现有接口：

GET /internal/admin-query/tenants/{tenant_code}/users/{user_id}

建议增强返回字段：

字段	说明
profile	结构化用户资料。
public	Tinode public JSON。
trusted	Tinode trusted JSON。
access	访问权限 JSON。
tags	标签。
security	auth_version/password_updated_at 等安全信息。
credentials	凭证列表，包含 method/value/done。

4.3 用户设备列表

GET /internal/admin-query/tenants/{tenant_code}/users/{user_id}/devices

用途：用户详情中的登录设备列表。

建议查询参数：

参数	类型	说明
device_id	string	设备 ID。
platform	string	平台。
page	int	页码。
per_page	int	每页数量。

建议返回字段：

字段	说明
device_id	设备 ID。
platform	平台。
user_agent	UA。
last_seen	最后在线。
created_at	创建时间。
updated_at	更新时间。

当前 Admin 直连涉及表：im_devices。

4.4 群列表

GET /internal/admin-query/tenants/{tenant_code}/groups

用途：IM 群组管理列表。

建议查询参数：

参数	类型	说明
topic	string	群 Topic。
owner_id	string	群主 ID。
state	int	Tinode topic 状态。
group_status	string	业务群状态。
created_at_start	string	创建时间开始。
created_at_end	string	创建时间结束。
touched_at_start	string	活跃时间开始。
touched_at_end	string	活跃时间结束。
page	int	页码。
per_page	int	每页数量。

建议返回字段：

字段	说明
topic	群 Topic。
state	Tinode 状态。
owner_id	群主 ID。
seq_id	最新消息序号。
del_id	删除序号。
sub_count	Tinode 订阅成员数。
touched_at	活跃时间。
created_at	创建时间。
updated_at	更新时间。
public	Tinode public JSON。
trusted	Tinode trusted JSON。
tags	标签。
aux	辅助 JSON。
group_name	群名称。
avatar_file_id	群头像文件 ID。
description	群简介。
group_status	业务群状态。
join_approval	入群审批开关。
mute_all	全员禁言。
member_upload_files	成员上传文件。
member_private_chat	成员私聊。
member_invite	成员邀请。
max_member_count	最大成员数。
max_admin_count	最大管理员数。
business_member_count	业务成员数。
settings_version	治理配置版本。
settings_updated_at	治理配置更新时间。

当前 Admin 直连涉及表：im_topics、im_group_settings。

4.5 群详情增强

现有接口：

GET /internal/admin-query/tenants/{tenant_code}/groups/{topic}

当前接口主要返回 im_group_settings。建议增强 Tinode topic 基础字段：

字段	说明
state	Topic 状态。
seq_id	最新消息序号。
del_id	删除序号。
sub_count	订阅数量。
public	public JSON。
trusted	trusted JSON。
access	access JSON。
tags	tags JSON。
aux	aux JSON。
touched_at	活跃时间。

4.6 群成员列表增强

现有接口：

GET /internal/admin-query/tenants/{tenant_code}/groups/{topic}/members

建议增强查询参数：

参数	类型	说明
user_id	string	用户 ID 精确过滤。
role	string	owner/admin/member。
member_status	string	成员状态。
q	string	昵称、公开账号等关键词。
eligible_role	string	候选角色筛选。
page	int	页码。
per_page	int	每页数量。
cursor	string	兼容 cursor 分页。
limit	int	兼容 cursor 分页。

建议增强返回：

字段	说明
total	总数，Admin 表格需要。
items[].user_id	用户 ID。
items[].nickname	昵称。
items[].state	用户状态。
items[].mode_want	期望权限。
items[].mode_given	授予权限。
items[].recv_seq_id	接收序号。
items[].read_seq_id	已读序号。
items[].del_id	删除序号。
items[].role	业务角色。
items[].member_status	成员状态。
items[].group_nickname	群昵称。
items[].pinned	置顶。
items[].mute_notifications	免打扰。
items[].join_source	加入来源。
items[].joined_by	邀请或处理人。
items[].joined_at	加入时间。
items[].left_at	离开时间。
items[].removed_by	移除人。
items[].version	版本。

当前 Admin 直连涉及表：im_group_members、im_subscriptions、im_users、im_user_profiles。

4.7 入群申请列表

GET /internal/admin-query/tenants/{tenant_code}/groups/{topic}/join-requests

建议查询参数：status、applicant_user_id、page、per_page。

建议返回字段：request_id、topic、applicant_user_id、inviter_user_id、source、message、status、reject_reason、handled_by、handled_at、expires_at、version、created_at、updated_at。

当前 Admin 直连涉及表：im_group_join_requests。

4.8 群邀请列表

GET /internal/admin-query/tenants/{tenant_code}/groups/{topic}/invitations

建议查询参数：status、target_user_id、inviter_user_id、page、per_page。

建议返回字段：invitation_id、topic、inviter_user_id、target_user_id、message、status、result、join_request_id、expires_at、handled_at、created_at、updated_at。

当前 Admin 直连涉及表：im_group_invitations。

4.9 群公告列表

GET /internal/admin-query/tenants/{tenant_code}/groups/{topic}/announcements

建议查询参数：status、page、per_page。

建议返回字段：announcement_id、topic、author_user_id、content、status、version、published_at、deleted_by、deleted_at、created_at、updated_at。

当前 Admin 直连涉及表：im_group_announcements。

4.10 群禁言列表

GET /internal/admin-query/tenants/{tenant_code}/groups/{topic}/mutes

建议查询参数：status、user_id、page、per_page。

建议返回字段：topic、user_id、muted_by、muted_at、expires_at、reason、status、revoked_by、revoked_at、version、created_at、updated_at。

当前 Admin 直连涉及表：im_group_mutes。

4.11 群管理日志

GET /internal/admin-query/tenants/{tenant_code}/groups/{topic}/admin-logs

建议查询参数：action、operator_id、page、per_page。

建议返回字段：log_id、topic、operator_id、target_user_id、action、object_type、object_id、before_data、after_data、request_id、idempotency_key、created_at。

当前 Admin 直连涉及表：im_group_admin_logs。

4.12 群文件列表

GET /internal/admin-query/tenants/{tenant_code}/groups/{topic}/files

用途：群治理页面中的群文件列表。不要和已有单文件详情接口混淆。

建议查询参数：status、file_type、file_name、uploader_id、page、per_page。

建议返回字段：group_file_id、topic、file_id、source_topic、source_seq、uploader_id、file_name、mime_type、file_type、file_size、status、deleted_by、deleted_at、created_at、updated_at。

当前 Admin 直连涉及表：im_group_files。

4.13 文件列表

GET /internal/admin-query/tenants/{tenant_code}/files

用途：IM 文件管理列表。

建议查询参数：file_id、user_id、status、mime_type、created_at_start、created_at_end、page、per_page。

建议返回字段：id、file_id、user_id、mime_type、file_size、file_name、location、etag、status、quarantine_reason、created_at、updated_at。

当前 Admin 直连涉及表：im_fileuploads。

4.14 文件引用列表

GET /internal/admin-query/tenants/{tenant_code}/files/{file_id}/links

用途：文件详情中展示消息引用。

建议返回字段：topic、seq_id、user_id、created_at。

当前 Admin 直连涉及表：im_filemsglinks。

5. P1：后台审核和运营页面

5.1 审计日志

GET /internal/admin-query/tenants/{tenant_code}/audit-logs
GET /internal/admin-query/tenants/{tenant_code}/audit-logs/{id}

建议查询参数：actor_user_id、action、target_type、target_id、created_at_start、created_at_end、page、per_page。

建议返回字段：id、request_id、actor_user_id、action、target_type、target_id、ip、user_agent、detail、created_at。

当前 Admin 直连涉及表：im_audit_logs。

5.2 实名审核

GET /internal/admin-query/tenants/{tenant_code}/realname-verifications
GET /internal/admin-query/tenants/{tenant_code}/realname-verifications/{id}

建议查询参数：user_id、status、real_name、created_at_start、created_at_end、page、per_page。

建议返回字段：id、user_id、real_name、id_card_no_masked、front_file_id、back_file_id、status、reject_reason、reviewed_by、reviewed_at、created_at、updated_at。

当前 Admin 直连涉及表：im_realname_verifications。

5.3 举报工单

GET /internal/admin-query/tenants/{tenant_code}/abuse-reports
GET /internal/admin-query/tenants/{tenant_code}/abuse-reports/{id}
GET /internal/admin-query/tenants/{tenant_code}/reports/abuse/{report_id}/target

建议查询参数：reporter_user_id、target_type、target_id、status、created_at_start、created_at_end、page、per_page。

建议返回字段：id、report_id、reporter_user_id、target_type、target_id、reason_code、description、evidence_file_ids、status、handler_id、handled_at、handle_result、created_at、updated_at。

当前 Admin 直连涉及表：im_abuse_reports。

5.4 意见反馈

GET /internal/admin-query/tenants/{tenant_code}/feedback-submissions
GET /internal/admin-query/tenants/{tenant_code}/feedback-submissions/{id}

建议查询参数：user_id、category、status、created_at_start、created_at_end、page、per_page。

建议返回字段：id、feedback_id、user_id、category、content、contact、file_ids、status、handler_id、handled_at、reply、created_at、updated_at。

当前 Admin 直连涉及表：im_feedback_submissions。

5.5 业务 Outbox

GET /internal/admin-query/tenants/{tenant_code}/outbox/business-events
GET /internal/admin-query/tenants/{tenant_code}/outbox/group-events
GET /internal/admin-query/tenants/{tenant_code}/outbox/business-events/{id}
GET /internal/admin-query/tenants/{tenant_code}/outbox/group-events/{id}

建议查询参数：event_type、status、target_type、target、created_at_start、created_at_end、page、per_page。

当前 Admin 直连涉及表：im_business_events_outbox、im_group_events_outbox。

6. P2：如果要完全消除租户库直连

这些不是 Kafka 联调第一优先级，但如果最终要求 Admin 完全不碰租户库，也需要 IM Server 提供内部查询或改为 hotgo 摘要表。

6.1 组织架构

GET /internal/admin-query/tenants/{tenant_code}/org/departments
GET /internal/admin-query/tenants/{tenant_code}/org/members

当前 Admin 直连涉及表：im_org_departments、im_org_members、im_users。

6.2 工作台应用

GET /internal/admin-query/tenants/{tenant_code}/workbench/apps

当前 Admin 直连涉及工作台相关租户表。

6.3 租户任务看板摘要

GET /internal/admin-query/tenants/{tenant_code}/dashboard/summary

当前 Admin 会统计多个租户库中的待处理实名、举报、反馈、Outbox 等数量。

6.4 租户配置类查询

如果这些配置仍放在租户库，也需要补接口；如果后续迁到 hotgo 控制库，则不需要通过 IM Server 查询。

GET /internal/admin-query/tenants/{tenant_code}/feedback-config
GET /internal/admin-query/tenants/{tenant_code}/mailbox-config
GET /internal/admin-query/tenants/{tenant_code}/abuse-reasons
GET /internal/admin-query/tenants/{tenant_code}/app-releases

涉及模块：反馈配置、总经理信箱配置、举报原因、App 发布策略。

6.5 IM Server 补齐状态

截至 2026-08-27，IM Server 已补齐本清单中的内部查询入口，统一走 /internal/admin-query/tenants/{tenant_code}/...，并沿用 HMAC 鉴权。

已接入范围：

1. P0：用户列表、用户详情增强、用户设备、群列表、群详情增强、群成员 total、入群申请、群邀请、群公告、群禁言、群管理日志、群文件、文件列表、文件详情、文件引用。
2. P1：审计日志、实名审核、举报工单、举报目标快照、意见反馈、业务 Outbox、群 Outbox。
3. P2：组织部门、组织成员、工作台应用、任务看板摘要、反馈配置、总经理信箱配置、举报原因、App 发布策略。

实现说明：

1. IM Server 内部使用白名单只读查询规格，不提供任意 SQL 入口。
2. 列表接口统一返回 items/total/page/per_page。
3. 详情接口统一返回单对象。
4. 复杂字段先返回租户库原始 JSON 或轻量关联摘要，Admin 联调时如需展示专用字段再做二次增强。
5. 若租户库未创建某些 P1/P2 表，对应接口会返回内部错误；发版前需要确保租户库 schema 已完整迁移。

7. Admin 侧迁移建议

7.1 第一批迁移

在 IM Server 补完 P0 后，Admin 优先迁移：

1. 用户列表、用户详情、用户设备。
2. 群列表、群详情、群成员。
3. 群入群申请、邀请、公告、禁言、管理日志、群文件。
4. 文件列表、文件详情、文件引用。

7.2 第二批迁移

在 IM Server 补完 P1 后，Admin 再迁移：

1. 审计日志。
2. 实名审核。
3. 举报工单。
4. 意见反馈。
5. 业务 Outbox。

7.3 保留 hotgo 查询的范围

以下数据天然属于 hotgo 控制库，Admin 可继续查 hotgo，不需要走 IM Server：

1. 租户表和租户绑定表。
2. Admin 命令表：im_admin_commands。
3. Admin Outbox 表：im_admin_outbox。
4. Admin Kafka 审计事件表：im_audit_events。
5. 菜单、角色、管理员、系统配置、字典等 HotGo 系统表。

8. 验收标准

1. Admin 查询租户业务数据时，不再出现新的 imtenant.DB() 调用。
2. Admin 查询 IM Server 内部接口时，统一使用 HMAC 签名。
3. 列表接口支持 page/per_page/total，兼容后台表格分页。
4. 详情接口返回结构化 JSON，不返回数据库内部敏感字段。
5. 用户 ID、雪花 ID 等大整数以字符串返回。
6. IM Server 为内部查询写审计日志，至少包含 tenant_code、service_name、path、query、trace_id、status、duration_ms。
7. 关闭 IM Server 内部查询能力时，Admin 应得到明确错误，不泄露租户库信息。