im_server/docs/IM-第一二章后续增强项.md

IM 第一至六章后续增强项

日期：2026-08-13 范围：第一章登录注册与安全、第二章消息首页/导航/系统通知、第三章单聊关系、第四章群消息与 @、第五章通讯录/好友/黑名单、第六章群聊创建/资料/治理 用途：记录当前已完成基线之外的增强项，后续统一排期处理。

1. 第一章：登录、注册与安全

1.1 当前已完成基线

1. 企业码解析、租户状态校验和公开租户配置返回。
2. 注册、登录前验证码发送与验证。
3. 注册验证码 Token 消费，避免绕过验证码直接注册。
4. 忘记密码挑战验证与重置确认。
5. Token 绑定 auth_version，密码重置后旧 Token 失效。
6. 登录后敏感操作二次验证挑战。
7. 实名认证状态查询与提交，证件信息脱敏/保护存储。
8. 独立密码设置与验证，包含弱密码规则和失败锁定。
9. 登录后 bootstrap 返回实名、安全与菜单基础能力。

1.2 后续增强项

优先级	增强项	说明	建议验收点
P0	HTTP Idempotency-Key 统一存储与请求摘要冲突检测	当前部分接口要求幂等键，但还没有统一的 tenant_id + uid + method + route + key + body_hash 处理层。	相同键相同 body 返回同一结果；相同键不同 body 返回冲突。
P0	验证码真实发送通道	当前验证码生成、校验和限频链路已具备，短信/邮件供应商发送仍需接入真实服务。	验证码可通过供应商下发；供应商失败有可观测错误和重试策略。
P0	验证码限频维度补强	需要按租户、手机号、IP、设备、场景组合限频，并落库或接入 Redis。	高频请求返回 VERIFICATION_RATE_LIMITED，不同场景互不误伤。
P0	安全事件通知联动	密码重置、实名提交/审核、独立密码变更、新设备登录等应写入系统通知。	操作成功后 /v1/im/system-notifications 能看到对应事件。
P1	实名审核工作流	当前支持提交和状态查询，后续需要后台审核、驳回原因、通过后状态变更。	审核通过后 realname.status=verified；驳回可再次提交。
P1	独立密码用途扩展	当前按 purpose 存储，可继续接入青少年模式关闭、敏感设置修改等业务入口。	不同 purpose 相互隔离；错误次数和锁定互不串扰。
P1	设备与会话管理	需要登录设备列表、主动踢出设备、Token 刷新/撤销审计。	修改密码或踢设备后对应 Token 立即不可用。
P1	API Key 轮换策略	当前 API Key 校验兼容现有逻辑，尚未实现最低可接受序号或撤销表。	旧序号 Key 可按配置禁用，新 Key 不影响正常客户端。
P2	风控与反诈策略接入	第一章安全动作后续应接入风险评分、反诈弹窗和二次确认策略。	高风险动作触发二次验证或反诈提示，低风险动作直通。

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

2.1 当前已完成基线

1. GET /v1/im/bootstrap 返回首页菜单、能力开关、权限和 message_policy。
2. GET /v1/im/search/conversations 支持会话搜索和基础分页。
3. WebSocket 发消息支持 Head["x-im-client-mid"] 幂等，重连重发不重复落库/广播。
4. 消息 Header 基础校验：x-im-schema、type、x-im-client-mid。
5. 普通用户禁止发布 sys Topic，且禁止伪造 Head.type=system。
6. GET /v1/im/topics/{topic}/messages/{seq}/receipts 返回群消息送达/已读基础列表。
7. POST /v1/im/topics/{topic}/messages/{seq}/recall 支持版本校验、权限校验和时限内撤回。
8. POST /v1/im/topics/{topic}/messages/{seq}/revisions 支持文本消息编辑、版本递增和修订记录。
9. GET /v1/im/system-notifications 和 POST /v1/im/system-notifications/{id}/read。

2.2 后续增强项

优先级	增强项	说明	建议验收点
P0	编辑/撤回多端实时事件广播	当前 HTTP 更新 DB 并返回成功，后续需要向 Topic 在线成员广播编辑/撤回事件。	A 端撤回/编辑后，B 端无需刷新即可收到事件并更新 UI。
P0	编辑/撤回事件 Outbox	DB 更新和实时广播应通过事务事件或 Outbox 衔接，避免更新成功但事件丢失。	模拟广播失败后，后台任务可补发事件。
P0	消息变更查询占位策略	已撤回消息在普通拉取中应返回撤回占位，而不是仅靠客户端本地事件。	新设备登录拉历史时能看到撤回占位和版本。
P0	Idempotency-Key 接入编辑/撤回	编辑/撤回目前依赖乐观版本控制，后续需要同时支持 HTTP 幂等键。	客户端超时重试同一请求不会重复写 revision。
P1	群回执隐私和角色策略	当前返回基础 read/recv 列表，后续需按租户策略、群规模、角色决定是否展示具体成员。	普通成员/管理员在不同策略下看到不同粒度回执。
P1	群回执 cursor 精确分页	当前 cursor 是基础位置分页，后续可升级为稳定游标，避免成员变动造成跳页。	成员新增/删除时分页不重复、不漏主要数据。
P1	message_policy 租户配置化	当前 recall/edit 窗口和菜单能力是固定值，后续需要来自租户配置。	不同租户可配置不同撤回/编辑时限和菜单能力。
P1	系统通知可信生产通道	当前已提供通知存储和读取接口，后续需要统一服务端生产 API/事件消费者，禁止业务散落直写。	安全、群、组织等模块通过统一通道创建通知。
P1	系统通知 action 白名单	action.type 和参数需要统一注册、校验和版本化。	非白名单 action 写入失败；客户端只收到可识别跳转。
P1	会话搜索排序与类型过滤	当前按现有订阅数据过滤，后续需支持会话类型、置顶、免打扰、最近活跃排序等。	搜索结果与消息首页排序、筛选规则一致。
P2	离线重连恢复编排测试	需要端到端覆盖 hi -> token login -> sub me -> 恢复 Topic -> get data。	断网重连后未丢消息、未重复消息、未错乱回执。
P2	消息 Header schema 版本演进	当前做基础格式/枚举校验，后续需要按 x-im-schema 版本维护兼容矩阵。	老客户端消息可兼容，新客户端非法字段被拒绝。

3. 第三章：单聊关系、权限与会话上下文

3.1 当前已完成基线

1. 单聊会话上下文接口返回双方关系、发送能力、对端公开资料和 P2P Topic。
2. P2P 发送路径接入好友关系校验，非好友、拉黑状态下禁止直接发送。
3. 好友申请、通过、拒绝、删除好友与单聊关系状态联动。
4. 拉黑/解除拉黑后关系上下文即时反映 blocked_by_me、blocked_by_peer 等状态。
5. 会话侧可根据 can_send 锁定输入框，并引导重新添加好友。

3.2 后续增强项

优先级	增强项	说明	建议验收点
P0	P2P 策略统一入口	当前核心路径已校验好友/黑名单，后续需要把发消息、通话、名片、文件、历史查看统一收敛到同一策略服务。	任一 P2P 业务入口对同一关系状态返回一致权限。
P0	关系变更实时同步	好友通过、删除、拉黑、解除拉黑后，应向双方在线端推送关系和会话能力变化。	A 拉黑 B 后，B 端输入框无需刷新自动锁定。
P0	关系事件 Outbox	关系 DB 状态变化与系统通知、会话事件、Push 需要事务级衔接。	模拟推送失败后后台可补发，不产生重复事件。
P1	Pending 会话体验增强	待处理好友申请对应的单聊页应携带申请摘要、来源、过期时间和快速处理入口。	进入 pending 会话可直接通过/拒绝，不需要跳转新朋友页。
P1	黑名单历史消息策略	当前发送/通话阻断已具备，后续需明确拉黑后历史消息、资料、文件和已读回执可见范围。	被拉黑人在不同策略下看到一致的历史与资料裁剪结果。
P1	非好友资料隐私裁剪	单聊上下文中的对端资料需要接入隐私设置、企业可见性和青少年模式。	非好友只能看到允许公开字段；好友看到扩展字段。
P1	好友关系审计	删除、拉黑、解除拉黑、申请处理等敏感关系操作写审计日志。	后台可按租户、操作者、目标用户查询操作流水。
P2	关系状态迁移测试矩阵	需要覆盖 none、pending_inbound、pending_outbound、friend、blocked_by_me、blocked_by_peer 的全迁移。	任意状态迁移后 DB、HTTP 上下文、WS 权限一致。

4. 第四章：群消息、群成员与 @ 能力

4.1 当前已完成基线

1. 群成员列表接口支持基础分页、搜索和 mentionable 过滤。
2. 返回成员角色、公开资料、ACL 和是否可被 @。
3. 群 @ 消息头部字段校验，支持 mentioned_user_ids、mention_all 等基础结构。
4. 群 @ 权限接入成员 ACL，管理员/群主才具备 @ 全体能力。
5. 群消息读取链路保留 @ 元数据，客户端可据此展示提醒。

4.2 后续增强项

优先级	增强项	说明	建议验收点
P0	@ 实时通知与离线 Push	当前消息元数据已落库，后续需要对被 @ 成员生成高优先级提醒和离线 Push。	被 @ 用户在在线、离线、多端场景均收到一次提醒。
P0	@ 全体频控	@ 全体需要按租户、群、角色、时间窗口限频，避免刷屏。	超限返回稳定错误码，管理员可配置限额。
P0	群成员稳定游标分页	当前成员列表以基础 cursor 分页，后续应使用稳定游标避免成员变动跳页。	成员入群/退群时翻页不重复、不漏主要数据。
P1	群成员资料隐私裁剪	群内非好友主页需要按群关系、好友关系、隐私设置裁剪资料字段。	同一成员从群内和好友主页进入时字段符合策略差异。
P1	群昵称/角色变更事件	群昵称、角色、禁言、移除等变化需要实时推送给群成员并刷新成员列表缓存。	群主修改成员角色后在线端成员列表自动更新。
P1	@ 候选排序优化	@ 面板候选应支持拼音首字母、最近互动、角色优先和本地缓存协同。	大群搜索响应稳定，候选排序符合产品规则。
P1	群治理策略配置化	成员私聊、成员邀请、全员禁言、上传权限等应统一由群治理配置控制。	不同群可配置不同治理能力，HTTP 与 WS 权限一致。
P2	大群性能压测	需要覆盖 500、2000、10000 成员下的成员列表、@ 搜索和发送性能。	达到目标延迟和资源占用阈值。

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

5.1 当前已完成基线

1. 好友列表支持查询、首字母、分页，返回备注、头像、显示名来源和会话 Topic。
2. 新朋友列表、好友申请、通过、拒绝链路已具备。
3. 用户搜索支持账号、精准账号和手机号类型，返回公开资料、关系和 action。
4. 添加好友二维码支持短期签名 Token 生成与解析。
5. 好友个人主页返回关系、资料和操作能力。
6. 群内非好友个人主页返回群角色、关系、资料和操作能力。
7. 好友备注更新、删除好友、拉黑/解除拉黑已具备。
8. 黑名单列表和批量移出黑名单已具备。

5.2 后续增强项

优先级	增强项	说明	建议验收点
P0	好友/黑名单操作统一幂等	拉黑、解除、删除、批量移出、好友申请等需要统一接入 Idempotency-Key 存储和请求摘要。	客户端超时重试不会重复创建申请或重复触发事件。
P0	好友关系实时事件	申请、通过、拒绝、删除、备注、拉黑等状态变化需要向相关在线端实时同步。	两端关系页、会话页和通讯录无需刷新自动更新。
P0	用户搜索隐私策略	当前搜索基线可用，后续需要接入 allow_user_search、添加方式、手机号可搜索等租户和个人隐私设置。	禁止手机号添加的用户无法通过手机号被搜索到，且不泄露存在性。
P0	二维码吊销与一次性策略	当前二维码是短期签名 Token，后续如需主动失效、刷新覆盖、扫码审计，需要落库或接入 Redis。	用户刷新二维码后旧码按策略失效；后台可查询扫码记录。
P1	好友资料字段精细裁剪	个人主页需按好友、非好友、群内关系、黑名单、实名/青少年等规则返回不同字段。	不同入口返回字段符合隐私矩阵。
P1	通讯录排序与拼音索引	当前支持基础 initial，后续需维护昵称/备注拼音、特殊字符分组和本地增量同步。	好友列表与客户端通讯录排序一致，中文首字母稳定。
P1	黑名单占位资料	资料删除、离职或不可见时，黑名单列表仍需返回可解除的受控占位用户。	黑名单中失效用户可展示占位并成功移出。
P1	好友申请防骚扰	需要按目标用户、申请人、IP、设备、来源和群来源限频，并支持拒收策略。	高频申请被限制；群来源申请校验双方仍在群内。
P1	关系审计和安全通知	添加、删除、拉黑、解除、二维码解析等应写审计并按策略生成系统通知。	用户可在通知中看到关键关系事件，后台可追溯。
P2	批量接口部分失败语义增强	批量移出黑名单目前返回逐项结果，后续需要统一批量接口错误码、重试建议和幂等结果缓存。	部分失败时客户端能只重试失败项。

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

6.1 当前已完成基线

1. 群列表、创建群、群资料查询与更新、群头像和群简介保存接口已具备。
2. 群设置、个人群设置、退出群、群昵称接口已具备。
3. 群二维码生成与扫码解析支持 join_group 场景。
4. 群邀请、进群申请、申请列表、同意/拒绝、群 summary 申请计数已具备。
5. 群公告最新查询、发布/更新、详情和已读接口已具备。
6. 群治理配置 GET/PATCH /governance 已具备。
7. 管理员候选、管理员上限、批量添加管理员、删除管理员和群主转让接口已具备。
8. 禁言候选、批量禁言、禁言列表和解除禁言接口已具备。
9. 当前实现优先复用 Topic、Subscription 和 Topic Aux，把产品主链路接口跑通。

6.2 后续增强项

优先级	增强项	说明	建议验收点
P0	群业务独立表拆分	当前群公告、进群申请、治理配置、禁言记录先存 Topic Aux，后续需要拆为独立表。	公告、申请、治理、禁言均有 tenant/topic 维度索引，可稳定分页和审计。
P0	群治理强事务状态机	邀请、申请审批、管理员变更、群主转让、禁言需在事务内同步业务表、订阅 ACL、成员数和事件。	并发审批/转让/禁言不会出现 ACL 与业务状态不一致。
P0	第六章幂等键落库	邀请、申请处理、公告发布、治理 PATCH、管理员批量、群主转让、禁言批量都需要统一幂等。	超时重试同一请求返回同一结果，不重复加人、升权或发事件。
P0	系统事件、Push 与 Outbox	第六章所有成员/公告/治理变化需要生成可信群系统事件，并通过 Outbox 保证推送。	在线端实时刷新；模拟推送失败后可补偿且不重复。
P1	群公告已读独立记录	当前公告已读返回基础结果，后续需记录每个成员的公告已读时间。	新公告只提醒未读成员，已读状态跨端同步。
P1	进群申请隐私与限频	申请入口需要按群治理、租户策略、用户状态、来源、IP/设备限频。	高频申请被限制；普通成员不可看到敏感申请人信息。
P1	管理员/群主角色层级策略	管理员互相操作、管理员禁言、群主转让二次认证等需要完整策略矩阵。	群主、管理员、普通成员在每个治理动作上的权限稳定一致。
P1	禁言发送链路强校验	当前禁言接口已具备，后续需要在 WebSocket 发消息路径校验 GROUP_MUTED。	被禁言成员发群消息被服务端拒绝，过期后自动恢复。
P1	群文件索引	6.27-6.28 需要独立群文件表，绑定上传文件、群成员权限、下载状态和删除权限。	群文件列表可搜索/分页，退群后不可下载旧 URL。
P1	群解散与二维码吊销	群解散、二维码撤销、邀请失效需要状态联动和权限回收。	解散后 Topic、二维码、邀请、文件新增权限全部失效。
P2	大群性能与稳定分页	成员、申请、公告、禁言、文件列表都需要稳定游标和大群压测。	大群场景下分页不重复不漏，接口延迟达标。

7. 统一处理建议

1. 先做 P0：统一幂等、实时事件/Outbox、验证码真实发送与限频、P2P/好友/搜索隐私策略、第六章群业务独立表与事务状态机。
2. 再做 P1：租户策略配置、系统通知生产通道、实名审核、设备管理、资料隐私裁剪、关系审计、群禁言发送校验和群文件索引。
3. 最后做 P2：端到端重连测试、schema 版本演进、大群压测、批量接口体验优化。
4. 每个增强项落地前同步更新 IM-系统设计文档.md 和 IM-前后端对接文档.md 中对应章节状态。