im_server/docs/IM-增强项第一批开发.md

# IM 增强项第一批开发

> 编写日期：2026-08-21
> 来源依据：`docs/IM-未实现后续增强项.md`、`docs/IM-前后端对接文档.md`、当前 `server/main.go` 和 `server/im_http.go` 路由实现。
> 目标：从后续增强项中筛选出当前可以直接开发、且不依赖短信服务商、FCM/APNs、TURN/STUN、SFU、病毒扫描服务等第三方能力的内容，作为第一批排期范围。

## 1. 筛选原则

第一批只纳入满足以下条件的增强项：

1. 只依赖当前 IM 服务、Tinode/IM 租户库、HotGo 控制库或已有 Redis/MySQL 基础设施。
2. 不依赖真实短信供应商、离线推送供应商、音视频媒体服务、病毒扫描引擎等第三方服务。
3. 优先补齐前后端对接文档中已定义，但当前代码未实现或实现不完整的接口。
4. 优先选择能直接提升前端联调完整度、生产可用性和接口一致性的项目。

以下内容不进入第一批：

1. 真实短信发送、短信模板、供应商回执和供应商失败重试。
2. FCM/APNs 离线 Push 投递和供应商错误码处理。
3. TURN/STUN 实际服务接入、SFU、群音视频媒体房间。
4. 第三方病毒扫描或文件内容安全服务。
5. 必须依赖 HotGo 管理后台页面完整改造才能闭环的运营后台功能。

## 2. 第一批开发范围总览

### 2.1 当前开发进度

> 进度更新：2026-08-21

| 开发项 | 状态 | 备注 |
| --- | --- | --- |
| 组织全局成员接口 | 已实现 | 新增 `GET /v1/im/organization/members`，支持部门、关键词、分页和 `has_more`。 |
| 月报 reopen | 已实现 | 新增 `POST /v1/im/reports/monthly/{id}/reopen`，按本人报告和 version 回退草稿。 |
| 实名更正申诉 | 已实现 | 新增 `POST /v1/im/security/realname/appeals` 和 `im_realname_appeals` 表。 |
| 群邀请外部接受 | 已实现 | 新增 `POST /v1/im/group-invitations/{id}/accept`。 |
| 主动创建/获取 P2P 会话 | 已实现 | 新增 `POST /v1/im/conversations/p2p`，复用好友/黑名单策略。 |
| 会话设置 | 已实现 | 新增 `GET/PATCH /v1/im/conversations/{topic}/settings` 和 `im_conversation_settings` 表。 |
| 多端云草稿 | 已实现 | 新增 `GET/PUT /v1/im/topics/{topic}/draft` 和 `im_topic_drafts` 表。 |
| 群文件列表、登记、删除 | 已实现 | 新增 `GET/POST/DELETE /v1/im/groups/{topic}/files`，复用现有群文件表。 |
| 普通消息转发 | 未实现 | 待下一步接入消息快照、目标权限校验和消息落库。 |
| 合并转发 Bundle 详情 | 未实现 | 待下一步新增 bundle 表和详情接口。 |
| 登出与指定会话撤销 | 未实现 | 当前 token 缺少独立 session 标识，需要先统一 session 模型。 |
| 列表 `has_more` 统一 | 部分实现 | 新增/触达接口已补，历史接口需继续横向清理。 |
| 风控 token 单次消费接入业务接口 | 未实现 | 待和具体业务动作一起接入。 |

### 2.2 范围表

| 模块 | 优先级 | 开发项 | 是否依赖第三方 | 当前状态 |
| --- | --- | --- | --- | --- |
| 账号安全 | P0 | 登出与指定会话撤销 | 否 | 文档有接口，代码未见路由 |
| 消息转发 | P0 | 普通消息转发 | 否 | 仅转发目标接口已实现 |
| 消息转发 | P0 | 合并转发 Bundle 详情 | 否 | 文档有接口，代码未见路由 |
| 群聊 | P0 | 群文件列表、登记、删除 | 否 | 路径已不误兜底，但业务未实现 |
| 单聊 | P1 | 主动创建/获取 P2P 会话 | 否 | 文档有接口，代码未见路由 |
| 会话 | P1 | 会话设置 | 否 | 文档有接口，代码未见路由 |
| 会话 | P1 | 多端云草稿 | 否 | 文档有接口，代码未见路由 |
| 群聊 | P1 | 群邀请外部接受 | 否 | 群内邀请已有，外部接受接口未见路由 |
| 安全实名 | P1 | 实名更正申诉 | 否 | 实名提交/查询已有，申诉未见路由 |
| 组织架构 | P1 | 组织全局成员接口 | 否 | 部门成员和组织搜索已有，独立全局成员接口未见路由 |
| 办公协同 | P1 | 月报 reopen | 否 | 月报草稿/提交/详情已有，reopen 未见路由 |
| 协议一致性 | P1 | 列表 `has_more` 统一 | 否 | 部分列表仍只返回 `items,next_cursor` |
| 安全风控 | P1 | 风控 token 单次消费接入业务接口 | 否 | 可签发 `risk_action_token`，业务消费仍需补齐 |

## 3. 详细需求

### 3.1 登出与指定会话撤销

#### 目标

补齐客户端退出登录和安全页踢出指定设备能力，避免只能通过 `auth_version` 做全量失效。

#### 接口

1. `POST /v1/im/auth/logout`
   - 退出当前登录设备。
   - 需要使当前 token 对应 session 失效。
   - 不影响同账号其他设备。

2. `DELETE /v1/im/security/sessions/{id}`
   - 撤销指定 session。
   - 只能撤销本人 session。
   - 撤销后该 session 对应 token 立即不可用。

#### 数据建议

如当前没有独立 session 表，建议新增：

```sql
CREATE TABLE im_user_sessions (
  id BIGINT NOT NULL PRIMARY KEY,
  tenant_id BIGINT NOT NULL,
  user_id BIGINT NOT NULL,
  session_id VARCHAR(64) NOT NULL,
  device_id VARCHAR(128) NOT NULL DEFAULT '',
  platform VARCHAR(32) NOT NULL DEFAULT '',
  token_hash VARCHAR(128) NOT NULL DEFAULT '',
  status VARCHAR(16) NOT NULL DEFAULT 'active',
  last_seen_at DATETIME(3) NULL,
  revoked_at DATETIME(3) NULL,
  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
  UNIQUE KEY uk_im_user_sessions_session (tenant_id, session_id),
  KEY idx_im_user_sessions_user_status (tenant_id, user_id, status)
);
```

主键使用已有雪花 ID 工具生成。

#### 验收点

1. 当前设备登出后，当前 token 访问登录态接口返回未登录或 token 失效。
2. 其他设备 token 不受影响。
3. 删除指定 session 后，被删除设备无法继续访问。
4. 重复登出或重复删除返回幂等成功或稳定错误码。

### 3.2 普通消息转发

#### 目标

补齐普通聊天消息转发能力。现有 `GET /v1/im/forward-targets` 只解决目标选择，不等同于真正转发。

#### 接口

`POST /v1/im/messages/forward`

建议请求字段：

```json
{
  "source_topic": "grp_xxx",
  "message_seqs": [101, 102],
  "target_topics": ["usrA-usrB", "grp_yyy"],
  "mode": "single",
  "client_mid": "uuid"
}
```

`mode` 建议支持：

1. `single`：逐条转发。
2. `bundle`：合并转发，生成转发卡片和 bundle。

#### 关键规则

1. 校验当前用户对源消息有查看权限。
2. 校验当前用户对每个目标会话有发送权限。
3. 不允许转发已被策略禁止转发的消息类型。
4. 文件消息需要重新校验文件访问权限。
5. 使用 HTTP 幂等能力，避免重复转发。

#### 验收点

1. 单条消息可转发到好友、群和文件助手。
2. 多条消息可逐条转发。
3. 无权限源消息、无权限目标会话返回稳定错误。
4. 同一幂等键重试不会重复投递。

### 3.3 合并转发 Bundle

#### 目标

支持合并转发卡片详情查看，使客户端可以打开“聊天记录”样式的转发包。

#### 接口

`GET /v1/im/forward-bundles/{id}`

建议响应结构：

```json
{
  "id": "fb_123",
  "title": "聊天记录",
  "source_summary": {
    "topic": "grp_xxx",
    "message_count": 12
  },
  "items": [],
  "next_cursor": "",
  "has_more": false
}
```

#### 数据建议

建议新增：

```sql
CREATE TABLE im_forward_bundles (
  id BIGINT NOT NULL PRIMARY KEY,
  tenant_id BIGINT NOT NULL,
  bundle_no VARCHAR(64) NOT NULL,
  owner_user_id BIGINT NOT NULL,
  source_topic VARCHAR(128) NOT NULL,
  title VARCHAR(128) NOT NULL DEFAULT '',
  message_count INT NOT NULL DEFAULT 0,
  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
  UNIQUE KEY uk_im_forward_bundles_no (tenant_id, bundle_no),
  KEY idx_im_forward_bundles_owner (tenant_id, owner_user_id, created_at)
);

CREATE TABLE im_forward_bundle_items (
  id BIGINT NOT NULL PRIMARY KEY,
  tenant_id BIGINT NOT NULL,
  bundle_id BIGINT NOT NULL,
  source_topic VARCHAR(128) NOT NULL,
  source_seq INT NOT NULL,
  sender_user_id BIGINT NOT NULL,
  content_json JSON NOT NULL,
  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
  KEY idx_im_forward_bundle_items_bundle (tenant_id, bundle_id, id)
);
```

#### 验收点

1. 合并转发后生成 bundle。
2. 接收方可分页查看 bundle 内容。
3. Bundle 内容使用生成时快照，不因源消息后续不可见而展示异常。
4. 原始会话无权限用户不能直接借 bundle 访问源会话。

### 3.4 群文件

#### 目标

补齐群文件列表、上传登记和删除管理能力。当前 `/groups/{topic}/files` 已不再误返回群详情，但业务仍缺失。

#### 接口

1. `GET /v1/im/groups/{topic}/files`
   - 支持分页、关键词、文件类型筛选。

2. `POST /v1/im/groups/{topic}/files`
   - 将已上传文件登记为群文件。

3. `DELETE /v1/im/groups/{topic}/files/{file_id}`
   - 删除或移除群文件。

#### 数据建议

可复用现有文件上传表，并新增群文件索引表：

```sql
CREATE TABLE im_group_files (
  id BIGINT NOT NULL PRIMARY KEY,
  tenant_id BIGINT NOT NULL,
  topic VARCHAR(128) NOT NULL,
  file_id BIGINT NOT NULL,
  uploader_user_id BIGINT NOT NULL,
  name VARCHAR(255) NOT NULL DEFAULT '',
  mime VARCHAR(128) NOT NULL DEFAULT '',
  size BIGINT NOT NULL DEFAULT 0,
  status VARCHAR(16) NOT NULL DEFAULT 'active',
  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
  deleted_at DATETIME(3) NULL,
  KEY idx_im_group_files_topic (tenant_id, topic, status, created_at),
  UNIQUE KEY uk_im_group_files_file (tenant_id, topic, file_id)
);
```

#### 权限规则

1. 只有群成员可查看群文件。
2. 只有群成员可登记群文件。
3. 删除权限建议第一批按群主、管理员、上传者放行。
4. 退群后不可继续通过群文件入口访问。

#### 验收点

1. 群成员可分页查看群文件。
2. 上传者登记文件后列表可见。
3. 普通成员不能删除其他人的文件，管理员和群主可以删除。
4. 非群成员访问返回无权限。

### 3.5 主动创建/获取 P2P 会话

#### 目标

补齐前端从好友资料页或通讯录进入单聊时的显式会话创建入口。

#### 接口

`POST /v1/im/conversations/p2p`

建议请求：

```json
{
  "peer_user_id": "usr_xxx"
}
```

#### 规则

1. 必须校验双方好友关系。
2. 必须校验黑名单状态。
3. 如果 P2P topic 已存在，直接返回已有 topic。
4. 如果不存在，创建或确保 Tinode P2P 会话关系存在。

#### 验收点

1. 好友之间调用返回稳定 P2P topic。
2. 非好友或黑名单关系返回不可发起会话。
3. 重复调用返回同一个 topic。

### 3.6 会话设置

#### 目标

支持置顶、免打扰、会话备注等跨端同步设置。

#### 接口

1. `GET /v1/im/conversations/{topic}/settings`
2. `PATCH /v1/im/conversations/{topic}/settings`

建议字段：

```json
{
  "pinned": true,
  "muted": false,
  "remark": "",
  "version": 3
}
```

#### 数据建议

```sql
CREATE TABLE im_conversation_settings (
  id BIGINT NOT NULL PRIMARY KEY,
  tenant_id BIGINT NOT NULL,
  user_id BIGINT NOT NULL,
  topic VARCHAR(128) NOT NULL,
  pinned TINYINT(1) NOT NULL DEFAULT 0,
  muted TINYINT(1) NOT NULL DEFAULT 0,
  remark VARCHAR(128) NOT NULL DEFAULT '',
  version BIGINT NOT NULL DEFAULT 1,
  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
  UNIQUE KEY uk_im_conversation_settings_user_topic (tenant_id, user_id, topic)
);
```

#### 验收点

1. 设置后同账号其他端读取一致。
2. 版本冲突返回稳定错误或按后写覆盖策略处理。
3. 非会话参与者不可设置。

### 3.7 多端云草稿

#### 目标

支持同账号多端同步草稿。

#### 接口

`PUT /v1/im/topics/{topic}/draft`

建议请求：

```json
{
  "content": "draft text",
  "entities": [],
  "version": 1
}
```

#### 数据建议

```sql
CREATE TABLE im_topic_drafts (
  id BIGINT NOT NULL PRIMARY KEY,
  tenant_id BIGINT NOT NULL,
  user_id BIGINT NOT NULL,
  topic VARCHAR(128) NOT NULL,
  content TEXT NULL,
  entities_json JSON NULL,
  version BIGINT NOT NULL DEFAULT 1,
  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
  UNIQUE KEY uk_im_topic_drafts_user_topic (tenant_id, user_id, topic)
);
```

#### 验收点

1. 保存草稿后其他端可读取。
2. 清空草稿后其他端同步清空。
3. 非会话参与者不可写入草稿。

### 3.8 群邀请外部接受

#### 目标

支持被邀请人从邀请卡片或外部入口接受群邀请。

#### 接口

`POST /v1/im/group-invitations/{id}/accept`

#### 规则

1. 校验邀请存在、未过期、未失效。
2. 校验当前登录用户是被邀请人。
3. 按群治理策略决定直接入群或进入审批。
4. 重复接受应幂等返回当前状态。

#### 验收点

1. 被邀请人可接受有效邀请。
2. 非被邀请人不可接受。
3. 已过期或已撤销邀请返回稳定错误。
4. 需要审批的群不会绕过审批。

### 3.9 实名更正申诉

#### 目标

实名审核驳回或用户发现实名信息有误时，可提交更正申诉。

#### 接口

`POST /v1/im/security/realname/appeals`

建议请求：

```json
{
  "reason": "证件姓名填写错误",
  "attachments": ["file_1"]
}
```

#### 数据建议

```sql
CREATE TABLE im_realname_appeals (
  id BIGINT NOT NULL PRIMARY KEY,
  tenant_id BIGINT NOT NULL,
  user_id BIGINT NOT NULL,
  reason VARCHAR(500) NOT NULL DEFAULT '',
  attachments_json JSON NULL,
  status VARCHAR(32) NOT NULL DEFAULT 'pending',
  reviewer_id BIGINT NULL,
  review_comment VARCHAR(500) NOT NULL DEFAULT '',
  reviewed_at DATETIME(3) NULL,
  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
  KEY idx_im_realname_appeals_user (tenant_id, user_id, created_at),
  KEY idx_im_realname_appeals_status (tenant_id, status, created_at)
);
```

#### 验收点

1. 用户可提交申诉。
2. 重复待处理申诉按策略限制。
3. 申诉记录可供后续后台审核使用。

### 3.10 组织全局成员接口

#### 目标

补齐前端需要全局组织成员列表时的统一入口，避免只能从部门成员或搜索接口拼装。

#### 接口

`GET /v1/im/organization/members`

建议查询参数：

1. `department_id`
2. `keyword`
3. `cursor`
4. `limit`

#### 规则

1. 复用组织成员表和组织搜索能力。
2. 按租户、部门、成员状态过滤。
3. 字段返回遵循现有隐私策略。

#### 验收点

1. 不传部门时返回全局成员分页。
2. 传部门时返回指定部门成员。
3. keyword 可搜索姓名、账号、手机号等允许搜索字段。
4. 返回 `items,next_cursor,has_more`。

### 3.11 月报 reopen

#### 目标

支持已提交月报按权限退回草稿，便于用户修正后重新提交。

#### 接口

`POST /v1/im/reports/monthly/{id}/reopen`

#### 规则

1. 只能 reopen 本人的月报，或由具备管理权限的用户 reopen。
2. 已归档、已锁定周期不可 reopen。
3. reopen 后状态回到草稿或待修改状态。
4. 保留审计记录。

#### 验收点

1. 已提交月报可按权限 reopen。
2. reopen 后可以继续保存草稿并重新提交。
3. 无权限用户不可 reopen 他人月报。

### 3.12 列表 `has_more` 统一

#### 目标

统一所有 HTTP 列表接口分页协议，减少前端针对每个接口单独判断。

#### 范围

第一批建议优先覆盖新增接口，以及以下已有高频接口：

1. 好友列表、新朋友列表、黑名单列表。
2. 群列表、群成员、群申请、群公告。
3. 会议列表、日报列表、月报列表。
4. 系统通知、举报/反馈相关列表。
5. 搜索类接口。

#### 响应要求

```json
{
  "items": [],
  "next_cursor": "",
  "has_more": false
}
```

#### 验收点

1. 空列表返回 `items: []`、`has_more: false`。
2. 最后一页返回 `has_more: false`。
3. 有下一页时返回非空 `next_cursor` 和 `has_more: true`。

### 3.13 风控 token 单次消费

#### 目标

当前风控确认接口可签发 `risk_action_token`，第一批补齐业务接口消费该 token 的闭环。

#### 范围

优先接入以下业务动作：

1. 打开或发送高风险 URL。
2. 高频添加好友。
3. 高频群邀请或入群申请。
4. 举报提交中的高风险目标。

#### 规则

1. token 必须绑定租户、用户、动作、目标和过期时间。
2. token 只能消费一次。
3. token 只能用于原业务动作，不可跨动作复用。

#### 验收点

1. 未确认风险时业务接口返回 challenge。
2. 确认后携带 token 可继续原动作。
3. token 重复使用返回已消费。
4. token 用于其他动作返回无效。

## 4. 建议开发顺序

### 第一阶段：低风险补齐路由

1. 组织全局成员接口。
2. 月报 reopen。
3. 实名更正申诉。
4. 群邀请外部接受。

这些接口业务边界相对清楚，可以最快完成前端缺口补齐。

### 第二阶段：会话能力

1. 主动创建/获取 P2P 会话。
2. 会话设置。
3. 多端云草稿。
4. 登出与指定会话撤销。

这些能力涉及用户状态和多端一致性，建议一起设计数据表和事件同步。

### 第三阶段：消息与文件增强

1. 普通消息转发。
2. 合并转发 Bundle。
3. 群文件。
4. 收藏分享权限二次校验。
5. 文件下载短时签名 URL。

这些能力涉及消息权限、文件权限和幂等，建议放在同一阶段统一处理。

### 第四阶段：协议一致性与风控闭环

1. 列表 `has_more` 统一。
2. 风控 token 单次消费。
3. 好友申请、入群申请、@ 全体等限频。
4. 二维码吊销与扫码审计。
5. 关系操作审计。

这一阶段适合在主要业务接口补齐后做横向治理。

## 5. 本批次不处理但需保留的增强项

以下增强项仍然重要，但不纳入第一批：

1. 真实短信供应商发送、失败重试和发送审计。
2. FCM/APNs 离线 Push 投递。
3. TURN/STUN 配置实际接入和 SFU 群通话。
4. 病毒扫描和第三方内容安全检测。
5. HotGo 管理后台完整审核流、组织维护界面、信箱后台流转界面。
6. 大规模性能压测和专项压测报告。

这些项目建议作为第二批或外部依赖就绪后的专项处理。

## 6. 文档同步要求

每完成一个开发项，需要同步更新：

1. `docs/IM-前后端对接文档.md`
2. `docs/IM-系统设计文档.md`
3. `docs/IM-未实现后续增强项.md`
4. 必要时补充数据库变更到 `docs/IM-数据库变更汇总.sql`

已经完成的增强项应从 `IM-未实现后续增强项.md` 的待办中移除或标记为已进入基线，避免重复排期。