im_server/docs/IM-现有实现与新需求差异对照总结.md

# IM 现有实现与新需求差异对照总结

> 对照日期：2026-08-10  
> 新需求来源：[IM 产品原型需求文档](./IM-产品原型需求文档.md)  
> 详细改造分析：[IM 产品需求服务端改造分析报告](./IM-产品需求服务端改造分析报告.md)  
> 对照对象：`chat-0.25.3` 当前服务端源码

## 1. 文档目的

本文从“现有服务端已经实现了什么”出发，对照新产品需求逐项给出处理结论：

- **保留**：现有实现已基本满足需求，只补配置或测试；
- **需修改**：现有能力可复用，但协议、数据模型、权限或流程不完整；
- **新增**：现有系统没有对应实现，需要新增模块；
- **客户端为主**：主要是移动端交互，服务端只提供状态、配置或资源；
- **废弃**：现有产品能力或接入方式在新需求中没有对应章节，不再作为新产品能力继续建设。

“新需求无直接章节”的数据库、对象存储、集群、监控等运行基础设施不按产品功能废弃，而标记为“保留基础设施”。真正需要废弃的能力单列在第 5 节。

## 2. 总体结论

当前系统可以继续作为新产品的即时通讯内核，不需要重写。现有 P2P Topic、群 Topic、Subscription ACL、消息序号、消息广播、回执、文件上传、Push 和 WebRTC 信令均可复用。

新需求与现状的主要关系如下：

| 新需求章节 | 功能域 | 当前覆盖程度 | 结论 |
| --- | --- | --- | --- |
| 第 1 章 | 账号、企业码、短信、实名、独立密码 | 部分覆盖 | 认证内核保留，产品流程需修改，企业码/实名需新增 |
| 第 2 章 | 会话首页、网络状态、消息操作、系统消息 | 部分覆盖 | 会话与连接保留，产品状态和系统通知需修改 |
| 第 3 章 | 单聊、好友状态、回执、媒体和名片 | 部分覆盖 | P2P/回执保留，好友约束和结构化消息需修改 |
| 第 4 章 | 输入、@、语音、文件、收藏、转发 | 少量覆盖 | 文件和通用消息可复用，大部分产品语义需新增 |
| 第 5 章 | 通讯录、好友申请、主页、黑名单 | 少量覆盖 | 用户搜索可改造，关系状态机需新增 |
| 第 6 章 | 群创建、审批、公告、管理、禁言、群文件 | 部分覆盖 | 群和 ACL 保留，群治理业务需新增 |
| 第 7 章 | 收藏、下载、聊天记录搜索 | 少量覆盖 | `slf` 和文件可复用，授权和索引必须修改 |
| 第 8 章 | 语音/视频通话 | 部分覆盖 | P2P WebRTC 信令保留，通话业务状态需修改 |
| 第 9 章 | 组织、会议、日报、月报、信箱 | 未覆盖 | 全部新增业务模块 |
| 第 10 章 | 资料、设置、版本、隐私、青少年模式 | 少量覆盖 | 通用资料可改造，其余多数新增或客户端实现 |
| 第 11 章 | 反诈、举报、反馈 | 未形成业务闭环 | 插件机制保留，业务模型和处置流程新增 |

必须优先处理三个基础问题：

1. 消息发布缺少客户端消息 ID 幂等校验，断线重试可能产生重复消息；
2. 文件下载只校验登录，没有校验用户对文件关联 Topic/消息的读取权限；
3. 当前核心表没有 `tenant_id`，共享数据库部署多个企业前必须完成全链路租户隔离。

## 3. 现有核心实现与新需求关系

| 现有实现 | 源码位置 | 对应新需求章节 | 结论 | 修改说明 |
| --- | --- | --- | --- | --- |
| basic 用户名/密码认证 | `server/auth/basic` | 1.2、1.3、1.4、1.6 | 需修改 | 保留认证器，增加协议确认、密码策略、错误次数、锁定、找回密码编排和旧 Token 撤销 |
| HMAC Token 登录 | `server/auth/token` | 1.2、1.6；2.2 | 保留 | 继续作为登录态；补设备会话、单设备撤销和密码重置后的 Token 失效 |
| 电话号码及短信验证器 | `server/validate/tel` | 1.4、1.5、1.6、1.7 | 需修改 | 保留验证码能力，增加用途隔离、发送频控、`retry_after`、一次性验证票据和审计 |
| REST 外部认证器 | `server/auth/rest` | 1.1、1.2 | 需修改 | 可连接企业账号中心；企业码解析仍需新增独立入口，认证后绑定企业上下文 |
| Session/WebSocket 协议分发 | `server/session.go` | 2.2；第 3、4、8 章 | 保留 | 作为 App 的主实时入口；补幂等、产品策略和结构化错误 |
| Topic 消息顺序、保存和广播 | `server/topic.go` | 第 2、3、4、6、7 章 | 需修改 | 保留核心循环；持久化前增加好友、黑名单、禁言、青少年和内容风险校验 |
| P2P Topic | `server/topic.go` | 3.1-3.12；5.2-5.14 | 需修改 | 保留单聊容器；是否允许创建、发送和呼叫改由好友/黑名单/隐私策略控制 |
| Group Topic | `server/topic.go` | 6.1-6.28；4.2-4.4 | 需修改 | 保留群消息和成员基础；增加审批、公告、二维码、禁言和群文件业务层 |
| Subscription ACL | `server/store/types/types.go`、`server/topic.go` | 3.1-3.8；6.4-6.26 | 需修改 | 保留 Join/Read/Write/Admin/Owner；不能用 ACL 代替好友申请、待审批和禁言记录 |
| Presence、输入状态 | `server/topic.go`、`server/datamodel.go` | 2.1；3.1-3.4；4.9 | 需修改 | 在线/输入状态可复用；增加隐私控制、节流和过期清理 |
| `recv`、`read` 回执 | `server/topic.go` | 3.4、3.7 | 保留 | 定义客户端状态映射；群聊是否显示具体已读人由产品规则控制 |
| 通用 JSON `head/content` 与 Drafty | `server/datamodel.go`、`server/drafty` | 3.6、3.10-3.12；4.1-4.20 | 需修改 | 增加消息类型、schema 版本、字段白名单、引用、@、转发和审核状态，不再允许各端自定义语义 |
| 消息删除 | `server/session.go`、`server/topic.go` | 2.4；3.8；4.15 | 需修改 | 明确仅自己删除、全员撤回、撤回期限、管理员权限和审计，不直接复用模糊的硬删除语义 |
| `slf` 自收藏 Topic | `server/store/types/types.go`、`server/topic.go` | 4.16；7.1-7.8 | 需修改 | 继续保存收藏消息，同时增加收藏索引、来源、去重、类型筛选和源消息删除策略 |
| 文件上传与消息附件关联 | `server/hdl_files.go`、`server/store/store.go` | 3.6、3.10-3.12；4.10-4.20；6.27-6.28；7.3、7.7-7.11 | 需修改 | 保留上传；增加附件所有权、病毒扫描、群文件索引、短时下载 URL 和资源级授权 |
| Push Handler | `server/push.go`、`server/push` | 2.1、2.5；4.4；8.1-8.11；9.3-9.4；10.18 | 需修改 | 保留 Push；扩展 @、审批、会议、通话和安全通知，增加锁屏内容隐私设置 |
| P2P WebRTC 信令 | `server/calls.go` | 8.1-8.11 | 需修改 | 保留 Invite/Offer/Answer/ICE/Hang-up；新增 `call_id`、设备抢答、结束原因、详单和 TURN 指标 |
| Plugin Firehose | `server/plugins.go` | 11.1-11.4；2.5 | 需修改 | 用于外部内容审核和反诈；增加超时、熔断、失败策略和审核结果落库 |
| User Public/Trusted/Tags | `server/store/types/types.go` | 5.1、5.5-5.8；10.1-10.6 | 需修改 | 可保存基础展示资料；生日、可见性、实名和组织关系应使用明确字段/业务表 |
| Topic Public/Trusted/Aux/Tags | `server/store/types/types.go` | 6.10-6.16 | 需修改 | 可保存群基础展示资料；公告、审批、二维码和禁言不能只存任意 JSON |
| `fnd` 用户/Topic 查找 | `server/topic.go` | 5.1、5.3-5.5 | 需修改 | 改成租户内精准 ID/受控搜索；执行隐私策略并防止手机号、用户 ID 枚举 |
| `sys` 系统 Topic | `server/store/types/types.go`、`server/topic.go` | 2.5；第 9、11 章通知 | 需修改 | 作为可信系统消息通道；定义消息类型、模板版本、跳转参数和去重键 |
| MySQL 核心表和 Adapter | `server/db/mysql` | 所有服务端需求的存储基础 | 需修改 | schema 118 已建立 `im_tenant`；仍需为核心表增加 tenant_id，并新增产品表、幂等、搜索索引和文件授权查询 |
| 文件系统/S3 媒体后端 | `server/media/fs`、`server/media/s3` | 第 3、4、6、7、11 章附件 | 保留基础设施 | 生产使用 S3/兼容对象存储，本地文件系统仅开发；补扫描和私有签名地址 |

## 4. 按新需求章节逐项对照

### 4.1 第 1 章：账号注册、登录与身份安全

| 新需求章节 | 新功能 | 当前实现 | 是否改 | 如何修改 |
| --- | --- | --- | --- | --- |
| 1.1 | 企业码登录 | 无企业/租户模型 | 新增 | 增加企业码解析 API、企业状态、服务地址和认证策略；共享库模式需先加 `tenant_id` |
| 1.2-1.3 | 账号密码登录及错误提示 | basic + token 已有 | 需修改 | 增加协议确认、统一错误码、失败计数、账号锁定、设备登录记录和安全通知 |
| 1.4-1.5 | 短信注册和倒计时 | 电话验证器已有 | 需修改 | 新增注册流程 API；验证码按用途隔离，返回有效期和重发时间，服务端强制限频 |
| 1.6 | 忘记密码 | 验证器与密码更新能力分散 | 需修改 | 建立“发码 → 临时票据 → 重置”状态机；成功后撤销旧 Token |
| 1.7 | 敏感操作二次验证 | 无统一业务流程 | 新增 | 增加验证挑战、一次性票据、有效期、错误次数和操作绑定 |
| 1.8-1.10 | 实名认证及状态提醒 | 无 | 新增 | 独立实名表、字段加密、审核状态、脱敏查询、审核回调和提醒消息 |
| 1.11 | 四位独立密码 | 无 | 新增 | 保存强哈希、失败锁定和找回流程；禁止写入普通设置 JSON 或明文日志 |

### 4.2 第 2 章：消息首页、全局导航与系统通知

| 新需求章节 | 新功能 | 当前实现 | 是否改 | 如何修改 |
| --- | --- | --- | --- | --- |
| 2.1 | 会话列表、摘要、未读数 | Subscription/Topic 已有基础 | 需修改 | 增加置顶、免打扰、隐藏、草稿和结构化消息摘要；文件助手使用固定系统 Topic |
| 2.2 | 断网、重连、增量同步 | Session 与序号拉取已有 | 需修改 | 明确同步游标、重连退避、重复消息幂等和连接状态指标 |
| 2.3 | 快捷菜单 | 无服务端页面逻辑 | 客户端为主 | 服务端只返回能力/权限开关，菜单和关闭交互由客户端实现 |
| 2.4 | 引用、复制、收藏、编辑、转发、撤回、删除、多选、群回执 | 仅删除、通用消息、回执基础 | 需修改 | 增加引用/编辑/转发协议，撤回规则和批量操作校验；复制/多选 UI 在客户端 |
| 2.5 | 新设备登录等系统消息 | `sys` Topic 可用，无完整事件生产 | 需修改 | 建立可信系统账号、设备/IP 审计事件、模板、跳转参数和防伪造规则 |

### 4.3 第 3 章：单聊会话、会话建立与消息状态

| 新需求章节 | 新功能 | 当前实现 | 是否改 | 如何修改 |
| --- | --- | --- | --- | --- |
| 3.1-3.5 | 好友申请前后单聊状态 | P2P Topic 有，无好友状态机 | 新增/修改 | 新增好友申请和关系表；申请通过后再开放 Topic Write 与媒体能力 |
| 3.4、3.7 | 发送中、送达、已读、失败 | 消息序号和 read/recv 已有 | 需修改 | 增加客户端消息 ID、稳定状态映射和业务失败原因；拉黑消息不得持久化给对方 |
| 3.6 | 图片/语音/视频进度 | 文件上传与消息可用 | 需修改 | 统一 `file_id`、消息类型和上传完成确认；进度主要由客户端维护 |
| 3.7-3.8 | 拉黑、删除好友后的发送限制 | 无关系策略 | 新增 | 在建会话、发布、通话、名片和文件入口统一执行关系策略 |
| 3.9 | 键盘收起布局 | 无服务端职责 | 客户端为主 | 服务端无需修改 |
| 3.10-3.11 | 多类型文件/混合消息 | 通用 JSON + 文件已有 | 需修改 | 定义 text/image/voice/video/file 类型和字段校验，禁止任意 URL |
| 3.12 | 名片消息 | 无标准类型 | 新增 | 增加 `contact_card`，只传用户 ID 与安全快照，打开时重新检查资料权限 |

### 4.4 第 4 章：消息输入、媒体内容与消息操作

| 新需求章节 | 新功能 | 当前实现 | 是否改 | 如何修改 |
| --- | --- | --- | --- | --- |
| 4.1 | 键盘、草稿 | 无专用服务端草稿 | 客户端为主 | 草稿默认本地；如需多端同步，增加每用户每 Topic 的草稿设置 |
| 4.2-4.4 | @成员、@所有人 | 无结构化 @语义 | 新增 | 消息保存稳定用户 ID；校验群成员和 @所有人权限，生成定向未读与 Push |
| 4.5-4.6 | 表情面板和表情消息 | Drafty 可保存文本 | 保留/客户端为主 | Unicode 表情按文本发送；独立表情包需要资源 ID 和版本，不保存本地路径 |
| 4.7-4.12 | 录音、图片/语音/视频上传与展示 | 文件和通用消息基础已有 | 需修改 | 增加媒体类型、时长/尺寸/缩略图、扫描状态；录音交互和播放进度由客户端实现 |
| 4.13-4.14 | 文件上传和文件卡片 | 已有上传与附件关联 | 需修改 | 补格式/大小策略、所有权、病毒扫描、可预览信息和安全下载 |
| 4.15 | 消息多选批量操作 | 无服务端批量语义 | 需修改 | 客户端选择；服务端逐条鉴权，限制批量数量并返回逐项结果 |
| 4.16 | 批量收藏 | `slf` 可承载 | 需修改 | 增加收藏唯一约束、来源索引、类型和批量幂等 |
| 4.17-4.19 | 单选/多目标逐条转发 | 无标准转发模型 | 新增 | 校验每个目标发送权和附件权；限制目标数；每条新消息使用独立幂等 ID |
| 4.20 | 合并转发 | 无 | 新增 | 创建不可变 `merged_forward` 快照，限制子项和总大小，清理会话 ID 与敏感字段 |

### 4.5 第 5 章：通讯录、好友关系与黑名单

| 新需求章节 | 新功能 | 当前实现 | 是否改 | 如何修改 |
| --- | --- | --- | --- | --- |
| 5.1 | 好友通讯录和企业成员 | `fnd`/Tags 仅提供基础查找 | 需修改 | 新增好友关系和组织成员查询；备注优先；支持字母/拼音索引 |
| 5.2 | 新朋友列表与审批 | 无 | 新增 | 新增好友申请状态机、幂等接受/拒绝、过期和系统通知 |
| 5.3-5.5 | ID、扫码添加好友 | 基础查找可部分复用 | 需修改 | 限定租户内精准搜索；二维码使用签名短 Token；执行隐私和反枚举策略 |
| 5.6 | 好友验证留言 | 无明确模型 | 新增 | 好友申请表保存验证信息、来源、过期时间和风控结果 |
| 5.7-5.8 | 好友/非好友个人主页 | Public/Trusted 可显示基础资料 | 需修改 | 根据关系、企业和隐私设置返回不同字段，不让客户端自行裁剪敏感资料 |
| 5.9-5.10 | 拉黑开关 | 无完整黑名单模型 | 新增 | 关系表记录单方 block；立即影响消息、搜索、呼叫和资料访问 |
| 5.11 | 删除好友 | 无好友关系真源 | 新增 | 事务更新双方关系；默认保留历史但禁止继续发送，规则需产品确认 |
| 5.12-5.14 | 黑名单列表及提示 | 无 | 新增 | 提供黑名单查询、解除接口和统一业务错误，不向被拉黑人泄露过多信息 |

### 4.6 第 6 章：群聊创建、资料维护与成员治理

| 新需求章节 | 新功能 | 当前实现 | 是否改 | 如何修改 |
| --- | --- | --- | --- | --- |
| 6.1-6.2 | 群列表和空状态 | Group Topic 已有 | 需修改 | 复用订阅列表；增加群业务状态、群头像摘要和已解散处理 |
| 6.3-6.6 | 加群、邀请与审批 | ACL 可邀请成员，但无申请状态机 | 新增/修改 | 新增入群申请/邀请表；审批通过后才更新 Subscription，写 Outbox 通知 |
| 6.7-6.9 | 群公告和已读 | 无公告模型 | 新增 | 公告主表、版本、发布权限、置顶和成员已读表；变更通过群系统消息通知 |
| 6.10-6.16 | 群设置、资料、头像、昵称、简介、标识、二维码 | Public/Aux/Private 可部分承载 | 需修改 | 定义可索引字段和修改权限；二维码新增签名 Token、有效期、使用次数和撤销 |
| 6.17-6.22 | 管理员、群主转让 | Admin/Owner ACL 已有 | 需修改 | 复用权限位；补管理员上限、二次确认、操作审计和可靠通知 |
| 6.23-6.24 | 成员禁言 | 当前通知静音不等于发言禁用 | 新增 | 新增全员/成员禁言规则，在消息持久化前强制执行，定义管理员豁免 |
| 6.25-6.26 | 选择新群主及确认 | 已有 Owner 转移逻辑 | 需修改 | 增加风险校验、幂等、候选人有效性、二次确认和审计 |
| 6.27-6.28 | 群文件及上传 | 文件消息可用，无群文件目录 | 新增/修改 | 建群文件索引，支持类型/时间/上传者查询和管理员删除，复用安全上传链路 |

### 4.7 第 7 章：文件下载、收藏管理与聊天记录检索

| 新需求章节 | 新功能 | 当前实现 | 是否改 | 如何修改 |
| --- | --- | --- | --- | --- |
| 7.1-7.8 | 收藏分类、查看和分享 | `slf` Topic 只有基础容器 | 需修改 | 增加收藏索引、类型、去重和源消息引用；分享时重新执行附件和目标会话权限 |
| 7.9-7.11 | 文件下载状态 | 已有 HTTP 下载 | 必须修改 | 下载前检查上传者或关联 Topic Read ACL；使用短时签名 URL；进度/完成状态在客户端 |
| 7.12 | 关键词搜索并定位上下文 | 现有查询只按序号范围 | 新增 | 建消息搜索索引，返回 Topic/SeqId 后重新检查 ACL，并支持上下文拉取 |
| 7.13-7.16 | 文件、链接、图片、视频分类检索 | 无类型索引 | 新增 | 建 `message_type`、`mime_group`、file/link 字段和游标分页，支持历史回填 |

### 4.8 第 8 章：实时语音与视频通话

| 新需求章节 | 新功能 | 当前实现 | 是否改 | 如何修改 |
| --- | --- | --- | --- | --- |
| 8.1-8.4 | 邀请、等待、接听、语音通话 | P2P WebRTC 信令已有 | 需修改 | 增加独立 `call_id`、呼叫类型、响铃/接听时间、忙线/拒接/超时原因和通话记录 |
| 8.5-8.6 | 麦克风与扬声器状态 | 信令可传临时事件 | 客户端为主 | 本地媒体控制由客户端负责，仅在对端需要展示时同步状态 |
| 8.7-8.10 | 视频等待、摄像头关闭、视频中 | WebRTC Offer/Answer/ICE 已有 | 需修改 | 增加视频类型和摄像头状态事件；配置 TURN，监控 ICE 成功率 |
| 8.11 | 通话悬浮状态 | 无服务端职责 | 客户端为主 | 服务端保持呼叫会话和重连状态，悬浮窗由客户端实现 |

当前实现仅适合一对一通话。新需求没有群音视频章节，因此首期不新增 SFU 或群会议通话。

### 4.9 第 9 章：企业工作台与办公协同

| 新需求章节 | 新功能 | 当前实现 | 是否改 | 如何修改 |
| --- | --- | --- | --- | --- |
| 9.1 | 工作台入口 | 无业务模块 | 新增 | 新增工作台应用配置和用户可见权限；页面布局由客户端实现 |
| 9.2 | 部门组织架构 | 无 | 新增 | 新建组织单元和成员表，支持树、搜索、主部门、职位、在职状态和数据范围 |
| 9.3-9.4 | 会议通知 | 仅能发送普通消息 | 新增 | 新建会议和参与人模型；创建/变更/取消通过 Outbox 发送系统消息和定时提醒 |
| 9.5-9.8 | 日报及普通/管理员视图 | 无 | 新增 | 建报告表和提交状态机；管理员查询按组织数据权限过滤 |
| 9.9-9.11 | 月报及详情 | 无 | 新增 | 复用报告模型，以类型/周期区分；增加汇总和附件能力 |
| 9.12-9.13 | 总经理信箱 | 无 | 新增 | 建信箱工单、匿名展示、附件、回复和审计；匿名对业务角色隐藏但保留受控追溯 |

工作台 CRUD 建议走 `/v1/im/*` HTTP API，状态提醒走系统 Topic，不把报告和组织树直接塞进聊天消息协议。

### 4.10 第 10 章：个人资料、通用设置、隐私与青少年模式

| 新需求章节 | 新功能 | 当前实现 | 是否改 | 如何修改 |
| --- | --- | --- | --- | --- |
| 10.1-10.5 | 我的、个人信息、昵称、生日、签名 | Public/Trusted 有通用字段 | 需修改 | 定义资料字段、格式、可见性、敏感词、变更版本和审计；实名信息单独存储 |
| 10.6 | 个人二维码 | 无标准 Token | 新增 | 生成短时签名 Token，扫码后仍执行租户、隐私和账号状态校验 |
| 10.7-10.8 | iOS/Android 设置页 | 无服务端页面逻辑 | 客户端为主 | 服务端提供用户设置和能力开关 |
| 10.9 | 清空缓存 | 不属于服务端数据删除 | 客户端为主 | 只清理设备缓存，不删除云端消息；无需服务端接口 |
| 10.10-10.11 | 版本更新 | 无版本配置服务 | 新增 | 提供平台/渠道最低版本、推荐版本、强更开关、下载地址和文案 API |
| 10.12-10.13 | 隐私设置及添加方式 | 无统一隐私模型 | 新增 | 建隐私设置表，并在搜索、加好友、资料和在线状态接口中强制执行 |
| 10.14-10.17 | 青少年模式 | 无 | 新增 | 服务端保存启用状态、PIN 强哈希、失败锁定和策略版本；所有关键入口强制检查 |
| 10.18 | 推送权限 | Push Token 能力已有 | 需修改/客户端为主 | 系统授权由客户端申请；服务端保存 Token、开关、免打扰和预览策略 |
| 10.19-10.21 | 提醒、相机、麦克风说明 | 无服务端职责 | 客户端为主 | 权限说明和系统授权由客户端实现，可由配置服务下发版本化文案 |

### 4.11 第 11 章：反诈安全、举报与意见反馈

| 新需求章节 | 新功能 | 当前实现 | 是否改 | 如何修改 |
| --- | --- | --- | --- | --- |
| 11.1-11.2 | 反诈一次/二次提示 | Plugin 可拦截消息，无产品策略 | 新增/修改 | 建风险事件和策略版本；同步硬规则本地执行，外部审核设置超时/熔断；客户端按等级弹窗 |
| 11.3-11.4 | 举报提交和分类 | 无举报工单 | 新增 | 建举报、证据、处理状态和审计；服务端在有权限时固化消息快照与哈希 |
| 11.5 | 意见反馈 | 无 | 新增 | 建反馈工单、分类、附件、联系方式和处理状态；附件复用私有文件授权 |

## 5. 新需求未覆盖的现有能力：废弃清单

以下能力在新需求文档中没有对应章节。按新产品范围标注为“废弃”，但应采用“停止新接入 → 观察存量 → 迁移 → 删除”的方式处理，不能在未确认线上使用情况时直接删除源码或数据。

| 现有能力 | 源码/配置 | 新需求章节 | 处理结论 | 废弃方式 |
| --- | --- | --- | --- | --- |
| 匿名登录 | `server/auth/anon` | 无 | **废弃** | 新环境不配置、不向客户端公开；确认无匿名会话后移除注册和文档 |
| 邮箱注册/邮箱验证码/邮箱找回 | `server/validate/email` | 无，新需求只定义手机号短信 | **废弃** | 产品 API 不再暴露 email credential；存量账号先绑定手机号再停用 |
| Channel 只读广播 Topic | `TopicCatGrp` 的 channel 模式 | 无 | **废弃** | 禁止新建 Channel；如有存量，迁移为普通群或公告业务后再移除入口 |
| Long Poll 客户端接入 | `/v0/channels/lp` | 无，新移动端按 WebSocket 设计 | **废弃** | 先记录调用量并公告；无流量后关闭路由，WebSocket 保留 |
| 客户端 gRPC 接入 | `grpc_listen`、客户端 gRPC 服务 | 无 | **废弃** | App 不再接入；注意保留插件所需的 gRPC 能力，两者不能一起误删 |
| 示例 Python Chat Bot | `tinode.conf` 中 `python_chat_bot` | 无 | **废弃** | 从生产配置删除；插件框架因第 11 章风控继续保留 |
| 静态网页托管 | `main.go` 静态文件路由/配置 | 无 Web 产品章节 | **废弃** | 新产品服务端不托管 Web UI；确认运维页面用途后关闭 |
| stdout Push Handler | `server/push/stdout` | 无生产需求 | **废弃（生产）** | 仅允许本地测试使用，生产配置删除；FCM/TNPG 等真实 Push 保留 |
| PostgreSQL Adapter | `server/db/postgres` | 无数据库兼容要求 | **废弃（产品版候选）** | 若确认生产统一 MySQL，则停止产品功能适配和验收；删除前核查部署 |
| MongoDB Adapter | `server/db/mongodb` | 无数据库兼容要求 | **废弃（产品版候选）** | 同上，不继续为新增 `im_*` 业务表实现双写逻辑 |
| RethinkDB Adapter | `server/db/rethinkdb` | 无数据库兼容要求 | **废弃（产品版候选）** | 同上；保留上游代码还是物理删除由仓库维护策略决定 |

以下能力虽然没有独立的新需求章节，但属于满足新需求所需的技术底座，不废弃：

| 基础能力 | 保留原因 |
| --- | --- |
| `me` Topic 和设备同步 | 会话列表、未读数、多端状态需要 |
| `fnd` 查找 Topic | 第 5 章精准用户搜索可在其基础上收紧 |
| `sys` Topic | 第 2、9、11 章的可信系统通知需要 |
| `slf` Topic | 第 4、7 章收藏同步可复用 |
| gRPC Plugin/Firehose | 第 11 章内容审核和反诈外部服务需要 |
| FCM/TNPG Push | 第 2、4、8、9、10 章离线提醒需要，生产只选择实际使用的 Handler |
| 文件系统/S3 Media Adapter | 第 3、4、6、7、11 章附件需要，按环境选择 |
| 集群、缓存、监控、TLS | 属于可用性和安全基础，不是产品页面功能 |
| root/后台管理能力 | 实名审核、举报处置、组织管理和审计需要，但必须收紧权限 |

## 6. 需要新增的服务端模块

| 新模块 | 对应新需求章节 | 主要职责 |
| --- | --- | --- |
| `imapi` | 第 1、5、6、7、9、10、11 章 | HTTP API、认证中间件、输入校验、统一错误和游标分页 |
| `impolicy` | 3.7-3.8；5.9-5.14；6.23-6.24；10.12-10.17 | 好友、黑名单、禁言、隐私和青少年同步授权 |
| `immessage` | 2.4；3.6、3.10-3.12；第 4 章 | 消息类型、schema 校验、@、引用、编辑、转发和摘要 |
| `imbiz/relationship` | 第 5 章 | 好友申请、联系人、备注、拉黑和删除状态机 |
| `imbiz/group` | 6.3-6.28 | 群审批、公告、二维码、角色、禁言和群文件 |
| `imbiz/identity` | 1.7-1.10 | 二次验证、实名认证、审核和脱敏 |
| `imbiz/workbench` | 第 9 章 | 组织、会议、日报、月报和信箱 |
| `imbiz/safety` | 第 11 章 | 风险事件、举报证据、处置、反馈和审计 |
| `imsearch` | 7.12-7.16 | 消息索引、历史回填、检索和 ACL 二次过滤 |
| `imnotify` | 2.5；第 5、6、9、11 章 | Outbox 消费、系统消息和 Push 通知 |
| `imjobs` | 1.5；5.2；6.3-6.6；9.3-9.4 | 申请过期、会议提醒、重试、清理和索引回填 |

## 7. 主要数据修改

### 7.1 核心表必须修改

| 对象 | 对应新需求章节 | 修改内容 |
| --- | --- | --- |
| Message | 2.2、2.4；第 3、4、7 章 | 增加或关联客户端幂等 ID、类型、审核状态、搜索索引；重复发送返回同一 SeqId |
| FileDef/File links | 第 3、4、6、7、11 章 | 增加扫描状态、业务用途和访问查询；下载按消息/Topic ACL 授权 |
| User | 1.1-1.10；5.1；9.2；第 10 章 | 共享 SaaS 时加 tenant；基础资料字段规范化，敏感身份数据独立存储 |
| Topic/Subscription | 第 2、3、5、6 章 | 共享 SaaS 时加 tenant；会话个性设置、群策略和关系状态使用独立业务表 |

### 7.2 新增业务表

| 数据域 | 建议表 | 对应新需求章节 |
| --- | --- | --- |
| 好友与会话 | `im_user_relations`、`im_friend_requests`、`im_conversation_settings`、`im_privacy_settings` | 第 2、3、5 章；10.12-10.13 |
| 群治理 | `im_group_settings`、`im_group_join_requests`、`im_group_mutes`、`im_group_announcements`、`im_group_announcement_reads`、`im_group_invite_tokens` | 第 6 章 |
| 消息与收藏 | `im_message_idempotency`、`im_message_index`、`im_favorites` | 2.2、2.4；第 4、7 章 |
| 身份与设置 | `im_identity_verifications`、`im_user_settings`、`im_teen_mode` | 第 1、10 章 |
| 企业办公 | `im_org_units`、`im_org_members`、`im_meetings`、`im_meeting_participants`、`im_work_reports`、`im_mailbox_messages` | 第 9 章 |
| 安全治理 | `im_reports`、`im_report_evidence`、`im_feedback`、`im_risk_events`、`im_audit_logs` | 第 11 章 |
| 可靠事件 | `im_outbox`、`im_idempotency_keys` | 第 5、6、9、11 章的审批和通知 |

共享数据库的多企业模式下，核心表和全部 `im_*` 表都必须包含 `tenant_id`，并把租户放入唯一索引、查询条件、缓存键和文件路径。若采用一企一实例/一企一库，则企业码负责服务发现，物理隔离优先。

## 8. 主要代码修改位置

| 文件/目录 | 对应新需求章节 | 修改内容 |
| --- | --- | --- |
| `server/datamodel.go` | 第 2、3、4、7、8 章 | 定义 `x-im-schema`、消息类型、幂等 ID、引用、转发、搜索和通话扩展 |
| `server/session.go` | 第 2、3、4、5、8、10、11 章 | 消息幂等、策略调用、租户上下文和统一业务错误 |
| `server/topic.go` | 第 2、3、4、6、7 章 | 保存前执行好友/黑名单/禁言/青少年/风险规则，发送结构化系统消息 |
| `server/calls.go` | 第 8 章 | call_id、设备抢答、标准结束原因、通话记录和指标 |
| `server/hdl_files.go` | 第 3、4、6、7、11 章 | 抽取 HTTP 认证、资源 ACL、签名下载 URL 和扫描状态检查 |
| `server/plugins.go` | 第 11 章 | 审核超时、熔断、失败开放/关闭策略和可观测性 |
| `server/push.go` | 2.5；4.4；第 8、9、10、11 章 | 产品消息类型、@、会议、审批、通话和隐私 Push |
| `server/main.go` | 第 1、5、6、7、9、10、11 章 | 注册 `/v1/im/*` API、业务服务和后台任务；逐步下线废弃路由 |
| `server/store` | 所有服务端章节 | 新增核心事务、幂等、文件授权、搜索接口；明确产品版支持的数据库 |
| `server/db/mysql` | 所有服务端章节 | 从当前 schema 118 继续迁移核心 tenant_id、业务表、索引和 MySQL 实现 |
| `server/tinode.conf` | 所有章节 | 企业、产品模块、搜索、审核、TURN、文件扫描、限流和废弃能力开关 |

## 9. 修改优先级

### P0：先保证新系统不会产生安全和数据问题

| 工作 | 对应新需求章节 |
| --- | --- |
| 确定一企一实例或共享 SaaS | 1.1、5.1、9.2 |
| 确定产品版只支持 MySQL 还是继续支持多数据库 | 所有服务端章节的存储基础 |
| 消息客户端 ID 幂等 | 2.2；3.4、3.7；第 4 章 |
| 文件下载资源级授权 | 3.10-3.12；4.13-4.20；6.27-6.28；7.3、7.7-7.11 |
| 消息类型、错误码和兼容协议 | 2.4；第 3、4、7、8 章 |
| 停止新客户端使用匿名、Long Poll、Channel 和客户端 gRPC | 新需求无对应章节，废弃项 |

### P1：完成即时通讯产品主链路

| 工作 | 对应新需求章节 |
| --- | --- |
| 企业码、短信注册/找回、二次验证、实名 | 第 1 章 |
| 好友申请、联系人、隐私、黑名单 | 第 5 章；3.1-3.8 |
| 结构化消息、@、引用、转发、收藏 | 2.4；第 3、4 章 |
| 会话设置和可信系统通知 | 第 2 章 |

### P2：完成群、文件和搜索

| 工作 | 对应新需求章节 |
| --- | --- |
| 群申请、公告、管理员、禁言、二维码、群文件 | 第 6 章 |
| 收藏分类和分享 | 7.1-7.8 |
| 关键词和媒体类型搜索、历史回填 | 7.12-7.16 |

### P3：完成通话、设置和安全

| 工作 | 对应新需求章节 |
| --- | --- |
| 通话 ID、跨设备状态、TURN 和详单 | 第 8 章 |
| 资料、版本、隐私和青少年模式 | 第 10 章 |
| 反诈、举报、证据、反馈和后台处置 | 第 11 章 |

### P4：完成企业办公

| 工作 | 对应新需求章节 |
| --- | --- |
| 组织与部门 | 9.2 |
| 会议通知 | 9.3-9.4 |
| 日报/月报 | 9.5-9.11 |
| 总经理信箱 | 9.12-9.13 |

## 10. 废弃实施规则

废弃项不要直接删除，应按以下顺序执行：

1. 在配置和对接文档中标记 deprecated，禁止新客户端接入；
2. 为废弃入口增加调用指标，至少观察一个完整客户端版本周期；
3. 对匿名账号、邮箱账号、Channel 等有数据的能力先做存量扫描；
4. 给存量用户提供迁移方案，例如邮箱账号绑定手机号、Channel 迁移普通群；
5. 新版本服务端默认关闭，保留临时回退开关；
6. 确认无调用和无未迁移数据后，再删除路由、配置、代码和测试；
7. 数据库删除列或表必须单独发布，保留备份和回滚窗口。

客户端 gRPC 和 Plugin gRPC 必须分开处理：新需求没有客户端 gRPC，因此前者废弃；第 11 章需要外部审核插件，因此 Plugin Firehose 及其 gRPC 通道保留。

## 11. 验收口径

每项改造只有同时满足以下条件才算完成：

1. 文档中的新需求章节有对应 API/协议、数据表和权限规则；
2. 旧客户端兼容行为有明确结论，不依赖未定义 JSON 字段；
3. 重试、并发、断网恢复不会产生重复业务数据；
4. 用户不能通过直接构造协议绕过好友、黑名单、禁言、隐私和青少年策略；
5. 文件、搜索、转发和收藏均重新执行当前用户的资源权限；
6. 共享 SaaS 模式下通过跨租户负向测试；
7. 审批、实名、举报、群管理和匿名信箱敏感操作有审计记录；
8. 废弃入口有调用量证据和存量迁移结果，不能仅凭新原型没有页面就直接删除；
9. MySQL schema、升级脚本、回滚脚本和代码中的建表定义保持一致；
10. 服务端单元测试、MySQL 集成测试、WebSocket/HTTP 端到端测试和真实设备通话测试全部通过。

## 12. 最终处理建议

新系统应保留 Tinode 的实时消息内核，重点修改认证流程、消息协议、权限策略、文件授权和通话状态；好友、群治理、搜索、企业工作台、实名、青少年和举报作为新的产品业务层建设。

新需求未覆盖的匿名登录、邮箱注册验证、Channel、Long Poll、客户端 gRPC、示例聊天机器人和静态网页托管标记为废弃。多数据库 Adapter 是否物理删除取决于产品数据库决策；若产品版确定只支持 MySQL，则 PostgreSQL、MongoDB 和 RethinkDB 不再承担新业务适配与验收。

改造顺序应先处理租户、消息幂等和文件授权，再完成好友与基础消息，随后完成群治理、搜索、通话与安全，最后建设企业工作台。这样可以最大限度复用现有实现，同时避免继续维护新产品不需要的入口和功能。