fix: invalidate group settings cache on membership changes

docs/test/IM-群聊测试环境验收报告-20260916.md

@@ -0,0 +1,78 @@
+# IM 群聊测试环境验收报告
+
+## 1. 测试信息
+
+- 测试时间：2026-09-16
+- HTTP：`https://api.118im.com`
+- WebSocket：`wss://api.118im.com/v0/channels`
+- 租户：`default`
+- 数据库：测试环境租户库 `tinode`
+- Redis：测试环境 Redis
+- Kafka：测试环境 Kafka
+- API Key、Token、数据库与中间件凭据未写入报告。
+
+## 2. 验收结论
+
+群聊主要链路通过；群主转让测试发现一处群设置缓存版本未失效问题，代码已修复，等待重新发布后复验转让与解散：
+
+- 群业务 HTTP 深度审计：基础及治理、审批项 `41/41` 通过。
+- 群 WebSocket、消息、文件专项：`16/16` 通过。
+- 群实时收发核心路径额外连续执行 3 轮，`24/24` 通过。
+- 群消息 Kafka 消费组 lag 为 `0`。
+- 群主转让：测试环境当前版本失败，返回 `409 VERSION_CONFLICT`；已定位并修复，需发布复验。
+- 群解散：依赖转让成功后的新群主身份，本轮未能完成最终测试环境验收。
+
+## 3. 功能结果
+
+| 范围 | 结果 | 验证内容 |
+| --- | --- | --- |
+| 群基础管理 | 通过 | 创建、列表、详情、资料修改、个人群设置、群昵称、成员列表与成员资料 |
+| 群治理 | 通过 | 治理配置读取与成功更新，普通成员越权返回 403，版本号递增 |
+| 管理员 | 通过 | 管理员数量限制、设置管理员、管理员修改治理配置、取消管理员 |
+| 禁言 | 通过 | 群主禁言、成员查询自身禁言、被禁言 WS 发消息返回 403、解禁后立即恢复发送 |
+| 公告 | 通过 | 发布公告、公告详情、成员已读 |
+| 入群审批 | 通过 | 非成员申请、普通成员不可读审批、群主查询并通过、新成员进群后可访问、主动退群 |
+| 实时消息 | 通过 | 双端订阅、双向广播、历史拉取，连续 3 轮均成功 |
+| 消息幂等 | 通过 | 相同 `x-im-client-mid` 重复发送返回同一 `seq`，数据库仅保留一条消息 |
+| 消息查询 | 通过 | 消息上下文、聊天记录搜索 |
+| 消息撤回 | 通过 | 发送者在时限内撤回，状态变为 `recalled`，版本由 1 递增为 2 |
+| 群文件 | 通过 | 文件上传 OSS、关联群文件、成员检索、群主删除关联 |
+| 权限隔离 | 通过 | 普通成员修改治理、读取管理限制、禁言他人、读取审批列表均被拒绝 |
+| 群主转让 | 待复验 | 二次验证成功，但读取到缓存版本 4，MySQL 实际版本为 6，提交返回版本冲突 |
+| 群解散 | 待复验 | 转让失败后目标用户不是群主，解散按权限规则返回 403 |
+
+## 4. 数据链路核验
+
+最终消息验证群：`grpMQrTw9wvUlA`。
+
+| 检查项 | 结果 |
+| --- | --- |
+| 月表落库 | `im_group_messages_202609` 存在 `seq=1,2,3` 三条消息 |
+| 旧表隔离 | `im_group_messages` 中该群消息数量为 0 |
+| 撤回状态 | `seq=1` 为 `recalled`，`version=2` |
+| 幂等记录 | `dedup-16737970` 对应 `seq=2`，状态 `done`，无重复行 |
+| 月段路由 | `202609`，`min_seq=1`，`max_seq=3`，`message_count=3` |
+| Redis 原子序号 | `last_seq=3` |
+| Redis 热消息索引 | 包含 `seq=1,2,3` |
+| Redis 月段路由 | `202609 -> 1`，元数据为 `1:3:3` |
+| Kafka 异步落库 | `im-server.group_message_persist` 检查时当前 offset 62、末端 offset 62、lag 0 |
+| 禁言业务状态 | 三轮禁言记录均由 `active` 正常流转为 `revoked`，版本为 2 |
+
+## 5. 测试数据
+
+本轮创建了多组 `a*`、`b*`、`c*` 自动化用户和 `grp*` 自动化群，均位于测试租户 `default`。数据用于回归追踪，后续可按账号前缀和测试时间清理。
+
+## 6. 补充说明
+
+综合 WebSocket 审计中观察到一次 P2P `read` 回执等待超时；群聊段已改为独立重连后执行，所有群聊用例稳定通过。该现象不影响本报告的群聊验收结论，但建议后续单独对 P2P 回执跨节点投递做压力与稳定性测试。
+
+## 7. 已定位问题与修复
+
+入群审批成功和成员退群都会在 MySQL 中重算人数并递增 `im_group_settings.version`，但原实现只清理成员分页缓存，没有清理 Redis `group_settings` 对象缓存。群治理接口因此返回旧版本，导致后续群主转让稳定触发版本冲突。
+
+本轮已在成员直接邀请、接受邀请、审批通过、主动退群和群主转让后统一清理群设置缓存，并增加缓存键单元测试。相关定向测试通过：
+
+- `go test ./server/store ./server/db/mysql`
+- `go test ./server -run 'TestServeIMGroup|TestGroup' -count=1`
+
+修复尚未发布到测试环境；发布后应重新执行“读取最新版本 -> 群主转让 -> 新群主解散 -> 旧成员读取返回 410”闭环。