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 的内部只读接口：

```text
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 鉴权：

```text
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 格式。建议所有列表接口统一返回：

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

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

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

### 3.3 详情返回

详情接口统一返回：

```json
{
  "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 用户列表

```text
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 用户详情增强

现有接口：

```text
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 用户设备列表

```text
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 群列表

```text
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 群详情增强

现有接口：

```text
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 群成员列表增强

现有接口：

```text
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 入群申请列表

```text
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 群邀请列表

```text
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 群公告列表

```text
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 群禁言列表

```text
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 群管理日志

```text
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 群文件列表

```text
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 文件列表

```text
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 文件引用列表

```text
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 审计日志

```text
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 实名审核

```text
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 举报工单

```text
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 意见反馈

```text
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

```text
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 组织架构

```text
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 工作台应用

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

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

### 6.3 租户任务看板摘要

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

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

### 6.4 租户配置类查询

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

```text
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 应得到明确错误，不泄露租户库信息。