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

IM 第一、二章后续增强项

日期：2026-08-12 范围：第一章登录注册与安全、第二章消息首页/导航/系统通知 用途：记录当前已完成基线之外的增强项，后续统一排期处理。

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. 统一处理建议

1. 先做 P0：统一幂等、编辑/撤回实时事件、撤回占位、验证码真实发送与限频。
2. 再做 P1：租户策略配置、系统通知生产通道、实名审核、设备管理。
3. 最后做 P2：端到端重连测试、schema 版本演进和体验型优化。
4. 每个增强项落地前同步更新 IM-系统设计文档.md 和 IM-前后端对接文档.md 中对应章节状态。