Q-IM 设计与实现文档¶
Q-IM 是 Rust 实现的即时通讯服务端与多端客户端。本站由仓库 docs/、README.md、CLAUDE.md（项目记忆）自动生成，外加本站专门绘制的业务流程图与数据流图。
契约权威
docs/PLAN.md 的 §5.1 实体命名表、§6 标识序列与游标、§7 核心数据模型、附录 A 协议帧、附录 B 默认参数是契约核心，任何专题文档与本站图示都不得重新定义它们；冲突时以 PLAN 为准。
从哪里读起¶
| 想了解 | 入口 |
|---|---|
| 一张图看懂系统 | 数据流图 · 系统总览 |
| 一条消息怎么走 | 业务流程图 · 消息处理流程 |
| 术语与关键词 | 关键词速查 · 名词解释 · 术语×模块 · 行话 |
| 契约与决策 | PLAN · ADR 索引 |
| 当前状态、实测数据、教训 | 项目记忆 |
一句话架构¶
客户端经 TLS 长连接接入 ConnectionNode（qim-gateway）；ConversationWriter（qim-writer） 在 Redis 原子分配序号并写入提交事实，追加 Redpanda Outbox 后才回 SEND_ACK；FanoutCoordinator（qim-fanout） 按冻结成员版本把 Outbox 展开为每个 MailboxShard 一条 dispatch；MailboxNode（qim-mailbox） 消费 dispatch 日志物化个人邮箱并推进连续水位，再尽力推送；SessionProjection（qim-session） 独立消费 dispatch 维护会话集合并在读路径按定义式算未读；HistoryArchiver（qim-archiver） 异步把历史归档进 ScyllaDB。
当前状态（2026-09-28）¶
- 主链路、完整客户端、Redis/Scylla 双后端已落地；功能 smoke、Scylla RF3 契约、writer SIGKILL 恢复门禁已通过。
- 本开发机 10k msg/s × 180 s 门禁稳定通过；这不是目标硬件容量结论。
- 仍未完成：目标硬件 180 s + T-HEAVY、混沌门禁、租户保留策略、lane 独立推进、PresenceDirectory / NotificationService / WebSocket / E2EE。
ADR 索引¶
| ADR | 主题 |
|---|---|
| 0001 | MailboxStore 选型与三级演进 |
| 0002 | 客户端传输 |
| 0003 | 大群分发策略 |
| 0004 | mailbox_seq 复合编码 |
| 0005 | 小会话正文内联 |
| 0006 | 服务端语言与日志系统 |
| 0007 | 一期部署形态 |
| 0008 | 登录对账与幂等窗口 |
| 0010 | 客户端 SDK 形态与绑定 |
| 0011 | 邮箱热路径表示 |
| 0012 | Fanout 不用 Kafka 事务 |
| 0013 | Redis 水平分片 |
| 0014 | 邮箱 Redis 实例数是容量参数 |
| 0015 | packed watermark v2 |
| 0016 | Outbox 分区与冻结快照缓存 |
| 0017 | dispatch 生产者关闭幂等 |
| 0018 | 历史热窗口与异步归档 |
| 0019 | 一期历史保留期 |
| 0020 | fencing_epoch 推迟到租约模型 |
| 0021 | 群成员可见区间与会话集合 |
| 0022 | Scylla 邮箱前沿水位与时间戳单调写 |
| 0023 | 离线邮箱 7 天与新设备同步 |