关键词速查
本页是高频关键词的一行定义与出处索引；完整解释见 名词解释，一词多义的模块归属见 术语×模块。
五种序列
| 关键词 |
定义 |
关键约束 |
message_id |
全局唯一、时间有序的消息标识，u128 HLC，含 region_id/writer_id |
writer 启动领取持久 60 s 窗口，崩溃/回拨不复用 |
conversation_seq |
单会话严格递增的历史顺序 |
允许空洞；禁用差值判丢消息、禁 latest - read 算未读 |
last_activity_id |
会话列表与跨会话时间轴排序键 |
与 message_id 同源同格式，可比较 |
mailbox_seq |
(shard_epoch:16, log_offset:48) 复合 u64 |
来自 dispatch 分区 offset；跨 epoch 单调；个人队列稀疏 |
room_seq |
聊天室短期顺序 |
只用于环形缓冲回放，不进邮箱 |
游标与水位
| 关键词 |
定义 |
lane_id |
blake3(tenant_id, user_id)[0] & 63，MailboxShard 内的可见性隔离通道，独立于 user_bucket |
materialized_watermark[lane]（W） |
该 lane 已完整物化、可安全暴露的连续水位，不是"见过的最大 offset" |
W_floor |
水位下限证据，接管时 seek 起点 = min(W)+1 |
mailbox_trim_watermark |
已物理删除的最大 mailbox_seq；空洞可跳过的前置条件 |
MailboxCursor |
设备已应用完成的邮箱位置（≠ 网络已发送），device 级 |
sync_to_seq |
AUTH 时刻的 lane 水位快照，把设备事件切成"客户端拉"与"服务端推"两半 |
read_conversation_seq |
用户级已读水位（read:{user}），跨设备共享 |
CURSOR_EXPIRED |
游标早于有效裁剪点，客户端必须 REBUILD |
实体（禁止别名）
| 实体 |
进程 |
职责 |
| ConnectionNode |
qim-gateway |
帧编解码、认证、心跳、PUSH 写出 |
| ConversationWriter |
qim-writer |
准入、幂等、分配序号、提交状态机、Outbox |
| FanoutCoordinator |
qim-fanout |
消费 Outbox、按冻结成员版本生成 dispatch |
| MailboxNode |
qim-mailbox |
消费 dispatch、物化邮箱、推进 W、服务 PULL_MAILBOX |
| SessionProjection |
qim-session |
会话集合投影、会话列表、定义式未读、MARK_READ |
| HistoryArchiver |
qim-archiver |
异步归档 MessageRecord 到 ScyllaDB、发布归档水位 |
| MessageStore |
库（qim-store） |
单份正文、历史分页、ClientDedup；分层：Redis 热层 + Scylla |
| GroupMembership |
库（qim-common） |
成员关系、不可变成员版本、(joined_at, left_at) 区间 |
| ShardRegistry / PresenceDirectory / NotificationService / RoomWriter / MediaService / ModerationService |
— |
目标形态，部分未实现 |
禁止写法：MessageNode、Mailbox Node、Message Store、connection_epoch。
数据模型
| 关键词 |
说明 |
MessageRecord |
canonical 消息记录，正文只存一份 |
CommitIntent |
RESERVED 时持久的完整 canonical 记录，恢复器不依赖客户端重传 |
GroupDispatch |
每目标 MailboxShard 恰好一条；dispatch_id = blake3("qim.group-dispatch.v1\0"‖message_id‖shard)[0..16] |
DispatchProgress（DP） |
邮箱侧 dispatch 物化进度与身份，dispatch_id + payload_digest 去重 |
UserMailboxEntry |
个人邮箱引用；同 (user, mailbox_seq) 事件组 ≤ 8 条 / 8 KiB |
ConversationHead |
每条消息只更新一次的会话公共头（一期从 canonical history 读取） |
UserConversationState |
会话集合持久权威（一期只存集合，ScyllaDB） |
UserSessionProjection |
可重建的会话列表视图（convs:{user} zset，ZADD GT） |
UserBadgeState |
用户级全局未读聚合（目标形态） |
membership_version |
群消息在分配序号后冻结的不可变成员版本 |
提交状态与 ACK
| 关键词 |
说明 |
| RESERVED → RECORDED → OUTBOXED → COMMITTED |
writer 提交状态机；只有 COMMITTED 能生成 SEND_ACK |
client_message_id（cmid） |
客户端幂等键，非零 16 字节；(tenant, sender, cmid) 唯一 |
ClientDedup |
幂等窗口 2 h（client_dedup_ttl_seconds） |
| local_pending |
客户端未确认发送；重连后先邮箱对账、未命中才重发 |
协议帧（常用）
AUTH / AUTH_OK · SEND_MESSAGE / SEND_ACK · PULL_MAILBOX / MAILBOX_BATCH · SYNC_COMPLETE / ONLINE_READY · PUSH_EVENTS · PULL_HISTORY · PULL_SESSION_LIST / SESSION_LIST_BATCH · SESSION_DELTA · MARK_READ · PULL_MEMBERS · CREATE_GROUP · LEAVE_GROUP · KICKED · PING / PONG。完整表见 PLAN 附录 A。
默认参数（节选，权威见 PLAN 附录 B）
| 参数 |
值 |
lane_count |
64（不可变） |
MailboxShard 数（QIM_MAILBOX_SHARD_COUNT） |
默认 64，二次幂 |
离线邮箱保留 MAILBOX_RETENTION_DAYS |
7 天（ADR-0023） |
历史热窗口 history_hot_window |
7 天（ADR-0018） |
| 默认历史保留 |
30 天，可配 1..3650（ADR-0019） |
| 提交辅助状态 |
COMMITTED 后 2 h 绝对过期 |
| 未读精确窗口 |
200，超过返回饱和值 |
| 大群成员事件广播上限 |
500 |
| 一期群上限 |
1000 |
| 帧头 |
固定 20 字节大端 |
| 分片写出块 |
64 KiB |