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

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

对照日期：2026-08-10
新需求来源：IM 产品原型需求文档
详细改造分析：IM 产品需求服务端改造分析报告
对照对象：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 不再承担新业务适配与验收。

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