# AGENTS.md — 开发规范 / Development Guidelines

> 本文件为所有 AI 编码助手（Claude Code、pi、Cursor 等）提供统一的开发指导。
> This file provides unified development guidelines for all AI coding assistants.

**最后更新 / Last Updated**: 2026-06-11

---

## 目录 / Table of Contents

1. [语言 / Language](#1-语言--language)
2. [代码风格 / Code Style](#2-代码风格--code-style)
3. [禁止模式 / Forbidden Patterns](#3-禁止模式--forbidden-patterns)
4. [错误处理 / Error Handling](#4-错误处理--error-handling)
5. [安全规范 / Security](#5-安全规范--security)
6. [数据库规范 / Database](#6-数据库规范--database)
7. [Socket.IO 事件规范 / Socket.IO Event Conventions](#7-socketio-事件规范--socketio-event-conventions)
8. [日志与可观测性 / Logging & Observability](#8-日志与可观测性--logging--observability)
9. [性能规范 / Performance](#9-性能规范--performance)
10. [测试规范 / Testing](#10-测试规范--testing)
11. [Git 规范 / Git Workflow](#11-git-规范--git-workflow)
12. [工作流程 / Workflow](#12-工作流程--workflow)
13. [架构决策记录 / ADR](#13-架构决策记录--adr)
14. [审查清单 / Review Checklist](#14-审查清单--review-checklist)

---

## 1. 语言 / Language

**Always respond in Chinese (中文).** Use the user's language for all conversations and explanations. Code, commands, and technical terms can remain in English.

始终使用中文回复。代码、命令和技术术语可以保留英文。

---

## 2. 代码风格 / Code Style

### 2.1 基本原则 / Basic Principles

| 规则 | 说明 |
|---|---|
| 遵循现有风格 | Follow existing project conventions |
| 有意义命名 | Use meaningful variable names; avoid single-letter names except loop counters |
| 函数长度 | Keep functions under **50 lines**; split complex logic into smaller functions |
| 嵌套深度 | Maximum nesting depth: **3 levels**; use early returns to flatten logic |
| 注释 | Add comments for complex logic only; prefer self-documenting code |
| 文档注释 | Public items must have `///` doc comments; private items only when logic is non-obvious |

### 2.2 Rust 最佳实践 / Rust Best Practices

```rust
// ✅ 正确 / Correct
fn get_message(id: Uuid) -> Result<Message, sqlx::Error> {
    let msg = db.find_message(id).await?;  // 使用 ? 传播错误
    Ok(msg)
}

// ❌ 错误 / Incorrect
fn get_message(id: Uuid) -> Message {
    db.find_message(id).await.unwrap()  // 禁止 unwrap()
}
```

| 规则 | 说明 |
|---|---|
| 错误传播 | Use `?` operator for error propagation; never use `unwrap()` or `expect()` in non-test code |
| `unsafe` | Avoid `unsafe` blocks; if necessary, add a `// SAFETY:` comment explaining why |
| `clone()` | Minimize `clone()` usage; prefer references or `Arc` for shared ownership |
| 魔法数字 | No magic numbers; define named constants with `const` |
| 硬编码字符串 | No hardcoded strings for config/status; use enums or constants |
| 死代码 | Remove dead code; don't leave commented-out code blocks |
| 未完成代码 | Don't commit `unimplemented!()`, `todo!()`, or `FIXME` without a tracking issue |

### 2.3 导入规范 / Import Guidelines

```rust
// 标准库 → 第三方 crate → 本地模块
// stdlib → third-party crates → local modules
use std::sync::Arc;

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use uuid::Uuid;

use crate::models::message::Message;
use crate::socket::packet::Packet;
```

### 2.4 模型设计规范 / Model Design Guidelines

imks 的 models 层采用 **一文件一实体** 的拆分策略：

```
models/
├── mod.rs                   # 模块声明 + 公开 re-export
├── message.rs               # 核心 Message + MessageDetail + AuthorInfo + MessageType
├── message_attachment.rs    # 附件
├── message_bookmark.rs      # 书签/收藏
├── message_draft.rs         # 草稿
├── message_edit.rs          # 编辑历史
├── message_embed.rs         # 富媒体嵌入 + EmbedField
├── message_mention.rs       # @提及
├── message_pin.rs           # 置顶消息
├── message_poll.rs          # 投票 + Option + Vote
├── message_reaction.rs      # 表情反应
├── message_read_state.rs    # 已读状态
└── message_thread.rs        # 消息线程
```

每个模型文件包含：
- Row struct（`sqlx::FromRow`）
- Summary/detail struct（API 响应用，带 `From` 转换）
- 查询 SQL 常量（`$1, $2...` 占位符）
- `CREATE_TABLE_SQL` 迁移 DDL + 索引
- `#[cfg(test)]` 序列化/转换测试

---

## 3. 禁止模式 / Forbidden Patterns

以下代码模式在项目中严格禁止：

| 禁止项                           | 说明                                             |
|-------------------------------|------------------------------------------------|
| `// ── xxxx ──────────`       | 禁止使用此类分隔线注释                                    |
| `unwrap()` / `expect()` (非测试) | 在非测试代码中禁止使用；使用 `?` 或 `unwrap_or` 等安全替代         |
| `panic!()` / `unreachable!()` | 除极少数不可能到达的分支外禁止使用                              |
| 未处理的 `todo!()`                | 不得提交包含 `todo!()` 的代码，除非有对应的 issue 追踪           |
| 注释掉的代码                        | 不得提交被注释的代码块；使用 Git 历史追溯                        |
| 过深嵌套 (≥4层)                    | 使用 early return、`match`、`map`/`and_then` 扁平化逻辑 |
| 过长函数 (>50行)                   | 拆分为更小的、职责单一的函数                                 |
| 魔法数字                          | 使用 `const` 定义命名常量                              |
| 硬编码字符串                        | 使用枚举或常量定义配置值/状态值                               |
| 死代码                           | 删除未使用的代码、导入和变量                                 |
| `Box<dyn Error>` 在公共 API      | 使用具体错误类型替代 trait object                        |

---

## 4. 错误处理 / Error Handling

### 4.1 错误类型体系 / Error Type System

imks 使用统一的 `ImksError` 枚举和 `ImksResult<T>` 类型别名，与 appks 的 `AppError`/`AppResult` 保持一致风格。

```rust
// error.rs — 统一错误类型
use thiserror::Error;

#[derive(Debug, Error)]
pub enum ImksError {
    // Protocol layer (engine)
    #[error("invalid engine packet type: {0}")]
    InvalidEnginePacketType(u8),
    #[error("invalid engine packet type char: {0}")]
    InvalidEnginePacketTypeChar(char),
    #[error("empty engine packet")]
    EmptyEnginePacket,
    #[error("invalid base64: {0}")]
    InvalidBase64(#[from] base64::DecodeError),
    #[error("invalid utf8 in packet: {0}")]
    InvalidPacketUtf8(#[from] FromUtf8Error),
    #[error("engine serialization error: {0}")]
    EngineSerialization(String),

    // Transport upgrade
    #[error("session not found for upgrade")]
    UpgradeSessionNotFound,
    #[error("session already closed, cannot upgrade")]
    UpgradeSessionClosed,
    #[error("invalid session state for upgrade")]
    UpgradeInvalidState,

    // Socket.IO layer
    #[error("invalid socket packet type: {0}")]
    InvalidSocketPacketType(u8),
    #[error("invalid socket packet type char: {0}")]
    InvalidSocketPacketTypeChar(char),
    #[error("empty socket packet")]
    EmptySocketPacket,
    #[error("invalid socket packet format: {0}")]
    InvalidSocketPacketFormat(String),
    #[error("missing namespace in socket packet")]
    MissingNamespace,
    #[error("invalid attachment count in binary event")]
    InvalidAttachmentCount,

    // Socket namespace
    #[error("namespace error: {0}")]
    Namespace(String),
    #[error("socket not found: {0}")]
    SocketNotFound(String),
    #[error("failed to send packet to socket: channel full")]
    SocketSendFull,

    // Adapter layer
    #[error("adapter redis error: {0}")]
    AdapterRedis(String),
    #[error("adapter nats error: {0}")]
    AdapterNats(String),
    #[error("adapter message bus error: {0}")]
    AdapterMessageBus(String),
    #[error("adapter serialization error: {0}")]
    AdapterSerialization(String),
    #[error("adapter room error: {0}")]
    AdapterRoom(String),

    // Database
    #[error("database error: {0}")]
    Database(#[from] sqlx::Error),

    // gRPC
    #[error("gRPC error: {0}")]
    GrpcStatus(#[from] tonic::Status),
    #[error("gRPC transport error: {0}")]
    GrpcTransport(#[from] tonic::transport::Error),

    // Serialization
    #[error("JSON error: {0}")]
    Json(#[from] serde_json::Error),

    // Auth
    #[error("auth error: {0}")]
    Auth(String),
    #[error("token expired")]
    TokenExpired,

    // General
    #[error("not found: {0}")]
    NotFound(String),
    #[error("invalid input: {0}")]
    InvalidInput(String),
    #[error("internal error: {0}")]
    Internal(String),
}

pub type ImksResult<T> = Result<T, ImksError>;
```

### 4.2 错误处理原则 / Error Handling Principles

| 原则        | 说明                                                                |
|-----------|-------------------------------------------------------------------|
| 统一类型      | 所有公共 API 返回 `ImksResult<T>`，不暴露子模块错误                              |
| 显式处理      | Handle all errors explicitly; no silent failures                  |
| `From` 转换 | 外部库错误通过 `#[from]` 自动转换，减少 `map_err` 样板                            |
| 异步传播      | Use `?` operator; don't suppress errors in spawned tasks          |
| 通道满       | Handle `mpsc::TrySendError` gracefully（buffer or log），don't panic |
| gRPC 错误   | Map `tonic::Status` → `ImksError::Grpc`                           |

### 4.3 错误日志格式 / Error Logging Format

```rust
// 记录错误时包含完整上下文
tracing::error!(
    error = %err,
    socket_sid = %sid,
    event = %event_name,
    "Failed to handle socket event"
);
```

### 4.4 现有子模块迁移 / Migration from Submodule Errors

当前部分子模块使用独立的 `thiserror` enum（`PacketError`、`AdapterError`），需要逐步迁移到 `ImksError`：

```rust
// 旧 / Old
pub enum PacketError { ... }
pub fn decode(data: &str) -> Result<Packet, PacketError> { ... }

// 新 / New
pub fn decode(data: &str) -> ImksResult<Packet> {
    // 内部仍可用 thiserror，对外转为 ImksError
    inner_decode(data).map_err(|e| ImksError::Packet(e.to_string()))
}
```

---

## 5. 安全规范 / Security

> 用户认证、授权、密码管理、2FA 等企业级安全由 appks 统一处理。
> imks 作为内部消息服务，仅负责消息层面的安全。

### 5.1 基础安全 / Basic Security

| 规则      | 说明                                                              |
|---------|-----------------------------------------------------------------|
| 密钥管理    | Never hardcode secrets or API keys; use environment variables   |
| 输入验证    | Always validate and sanitize user input（消息体、事件名、namespace path） |
| SQL 注入  | Use parameterized queries（sqlx handles this automatically）      |
| gRPC 安全 | appks ↔ imks 的 gRPC 连接应使用 mTLS，防止密钥在传输中被截获                      |

### 5.2 JWT 验证双模式 / Dual-Mode JWT Verification

imks 支持两种 JWT 验证模式（详见 `rpc.md`）：

| 模式         | 方式                                    | 延迟  | 适用场景       |
|------------|---------------------------------------|-----|------------|
| **RPC 验证** | 调用 appks `TokenService.VerifyToken()` | 实时  | 敏感操作       |
| **本地验证**   | 启动时拉取 `GetSigningKeys()` 缓存到本地        | 零延迟 | 高频操作（消息收发） |

推荐策略：普通操作（发消息、读频道）→ 本地验证，敏感操作 → RPC 验证。

### 5.3 连接安全 / Connection Security

| 要求     | 说明                                             |
|--------|------------------------------------------------|
| 命名空间验证 | 验证 namespace path（`/` 开头，≤256 字符，无控制字符），防止 DoS |
| 消息体大小  | 限制单条消息大小（`EngineConfig.max_payload`）           |
| 速率限制   | 按 socket 限制消息发送频率                              |

---

## 6. 数据库规范 / Database

### 6.1 基础规范 / Basic Rules

| 规则      | 说明                                                               |
|---------|------------------------------------------------------------------|
| 参数化查询   | Always use parameterized queries (sqlx does this by default)     |
| 迁移规范    | All schema changes must go through migration files in `migrate/` |
| UUID v7 | 所有主键使用 UUID v7（时间有序），便于索引和游标分页                                   |
| 软删除     | 使用 `deleted_at` 字段进行软删除，不用硬删除                                    |
| 去规范化    | 对于高频读取的聚合字段（如 `total_votes`、`unread_count`），可在表中冗余存储             |

### 6.2 imks 管理的数据库表 / imks-Managed Tables

imks 仅管理消息相关表，用户/频道/成员/权限等由 appks 核心服务管理。

| 表                     | 对应模型文件                         | 说明                |
|-----------------------|--------------------------------|-------------------|
| `message`             | `models/message.rs`            | 核心消息表（由 appks 创建） |
| `message_attachment`  | `models/message_attachment.rs` | 文件附件              |
| `message_embed`       | `models/message_embed.rs`      | 富媒体嵌入             |
| `message_embed_field` | `models/message_embed.rs`      | 嵌入字段              |
| `message_poll`        | `models/message_poll.rs`       | 投票                |
| `message_poll_option` | `models/message_poll.rs`       | 投票选项              |
| `message_poll_vote`   | `models/message_poll.rs`       | 投票记录              |
| `message_pin`         | `models/message_pin.rs`        | 置顶消息              |
| `message_read_state`  | `models/message_read_state.rs` | 已读状态              |
| `message_draft`       | `models/message_draft.rs`      | 草稿                |
| `message_edit`        | `models/message_edit.rs`       | 编辑历史              |

### 6.3 性能优化 / Performance Optimization

| 规则          | 说明                                                                              |
|-------------|---------------------------------------------------------------------------------|
| N+1 防护      | Use `JOIN` or batch queries instead of N+1 patterns                             |
| 游标分页        | Use UUID v7 cursor-based pagination（`WHERE id < $3 ORDER BY id DESC`），不用 OFFSET |
| 索引规范        | Add indexes for frequently queried columns; document index rationale            |
| ON CONFLICT | Use `INSERT ... ON CONFLICT` for upsert patterns（draft、read_state）              |

---

## 7. Socket.IO 事件规范 / Socket.IO Event Conventions

### 7.1 事件命名 / Event Naming

imks 使用 Socket.IO 协议进行实时通信，事件名遵循以下约定：

```
// 客户端 → 服务端（发送操作）
"message:send"          // 发送消息
"message:edit"          // 编辑消息
"message:delete"        // 删除消息
"typing:start"          // 开始输入
"typing:stop"           // 停止输入
"reaction:add"          // 添加反应
"reaction:remove"       // 移除反应

// 服务端 → 客户端（推送事件）
"message:new"           // 新消息
"message:updated"       // 消息已更新
"message:deleted"       // 消息已删除
"typing"                // 用户输入状态
"reaction:updated"      // 反应已更新
"presence:update"       // 在线状态变更
```

### 7.2 事件数据结构 / Event Data Structure

```json
// 客户端发送消息事件
// Client sends: "message:send"
{
  "channel_id": "01909a...",
  "body": "hello world",
  "thread_id": null,
  "reply_to_message_id": null
}

// 服务端广播新消息
// Server broadcasts: "message:new"
{
  "id": "01909b...",
  "channel_id": "01909a...",
  "author": { "id": "...", "username": "alice" },
  "body": "hello world",
  "created_at": "2026-06-11T10:00:00Z",
  "reactions": {},
  "attachment_count": 0
}
```

### 7.3 房间（Room）机制 / Room Mechanism

```rust
// channel_id 作为房间名，频道内消息只广播给加入该房间的 sockets
// Use channel_id as room name; messages broadcast only to sockets in that room
namespace.emit_to_room(&channel_id, "message:new", message_data).await;
```

### 7.4 适配器（Adapter）模式 / Adapter Pattern

imks 通过 Adapter trait 支持水平扩展，将 Socket.IO 事件广播到多节点：

```
┌─────────┐     ┌─────────┐     ┌─────────┐
│ Node 1  │────→│  NATS / │←────│ Node 2  │
│ (imks)  │     │  Redis  │     │ (imks)  │
└─────────┘     └─────────┘     └─────────┘
```

| Adapter | 适用场景 |
|---|---|
| `LocalAdapter` | 单节点开发/测试 |
| `RedisAdapter` | 生产环境 Redis Pub/Sub |
| `NatsAdapter` | 生产环境 NATS（更低延迟） |

---

## 8. 日志与可观测性 / Logging & Observability

### 8.1 日志规范 / Logging Standards

```rust
// 使用 tracing crate 进行结构化日志
use tracing::{info, warn, error, debug};

info!(
    socket_sid = %socket.sid,
    engine_sid = %socket.engine_sid,
    namespace = %namespace.path,
    "Socket connected"
);

warn!(
    socket_sid = %sid,
    "Adapter register error: {}",
    e
);

error!(
    error = %err,
    engine_sid = %sid,
    "Failed to handle engine message"
);
```

| 级别      | 用途                                  |
|---------|-------------------------------------|
| `error` | 错误需要立即关注（连接失败、数据库错误）                |
| `warn`  | 异常但可恢复的情况（adapter 注册失败、socket 发送失败） |
| `info`  | 关键业务操作记录（连接/断开、命名空间创建）              |
| `debug` | 开发调试信息（数据包收发详情）                     |
| `trace` | 详细执行路径                              |

### 8.2 关键指标 / Key Metrics

| 指标         | 说明                                                  |
|------------|-----------------------------------------------------|
| 活跃连接数      | Active WebSocket + Polling + WebTransport sessions  |
| 消息吞吐量      | Messages sent/received per second                   |
| 广播延迟       | P50/P95/P99 broadcast latency across nodes          |
| 事件处理延迟     | Event handling time (receive → broadcast → deliver) |
| Adapter 延迟 | NATS/Redis broadcast delay between nodes            |
| 连接错误率      | Connection failure rate                             |
| 数据库查询延迟    | Message insert/select latency                       |

### 8.3 健康检查 / Health Check

```json
// GET /health
{
    "status": "healthy",
    "version": "0.1.0",
    "uptime": 3600,
    "checks": {
        "postgres": { "status": "up", "latency_ms": 5 },
        "redis": { "status": "up", "latency_ms": 2 },
        "nats": { "status": "up", "latency_ms": 1 },
        "appks_grpc": { "status": "up", "latency_ms": 3 }
    }
}
```

---

## 9. 性能规范 / Performance

### 9.1 实时消息 SLA / Real-time Messaging SLA

| 指标           | 目标            |
|--------------|---------------|
| 消息端到端延迟（P50） | <50ms         |
| 消息端到端延迟（P95） | <200ms        |
| 消息端到端延迟（P99） | <500ms        |
| 连接建立时间       | <100ms        |
| 消息吞吐量（单节点）   | >10,000 msg/s |
| 错误率          | <0.1%         |

### 9.2 性能原则 / Performance Principles

| 原则   | 说明                                                                  |
|------|---------------------------------------------------------------------|
| 零拷贝  | Minimize data copying; use references where possible                |
| 批量操作 | Batch adapter broadcasts; use pipelining for Redis                  |
| 无锁优先 | Use `DashMap` (lock-free) for hot-path data; `RwLock` for cold-path |
| 背压控制 | Use bounded `mpsc::channel` (256) to prevent memory blowout         |
| 连接复用 | Reuse gRPC channels to appks                                        |

### 9.3 优化策略 / Optimization Strategies

| 场景      | 策略                               |
|---------|----------------------------------|
| 跨节点广播   | NATS（<1ms P50）优于 Redis（~2ms P50） |
| 消息持久化   | 异步写入 + 批量 COMMIT                 |
| 会话查找    | `DashMap` 直接查找，无锁竞争              |
| gRPC 调用 | 连接池 + 本地密钥缓存减少 RPC 往返            |

---

## 10. 测试规范 / Testing

### 10.1 基础要求 / Basic Requirements

| 规则     | 说明                                                          |
|--------|-------------------------------------------------------------|
| 新功能    | All new features must have unit tests                       |
| Bug 修复 | Bug fixes must include regression tests                     |
| 模型测试   | All model files must have serialization/conversion tests    |
| 测试隔离   | Tests must be independent and not depend on execution order |

### 10.2 测试命令 / Test Commands

```bash
cargo test                       # 运行所有测试
cargo test --lib                 # 仅运行 lib 测试
cargo test models::              # 运行 models 模块测试
cargo test socket::parser::      # 运行 socket parser 测试
cargo test -- --nocapture        # 显示输出
```

### 10.3 测试文件组织 / Test File Organization

```
tests/
├── engine_io_tests.rs     # Engine.IO 协议测试
├── socket_io_tests.rs     # Socket.IO 协议测试
├── adapter_tests.rs       # Adapter 测试
└── session_tests.rs       # 会话管理测试

# 单元测试 (inline)
models/message.rs          → #[cfg(test)] mod tests { ... }
models/message_poll.rs     → #[cfg(test)] mod tests { ... }
socket/parser.rs           → #[cfg(test)] mod tests { ... }
engine/codec.rs            → #[cfg(test)] mod tests { ... }
```

---

## 11. Git 规范 / Git Workflow

### 11.1 提交信息格式 / Commit Message Format

使用 Angular 风格，全部英文：

```
<type>(<scope>): <subject>

[optional body]

[optional footer]
```

| Type       | 说明     |
|------------|--------|
| `feat`     | 新功能    |
| `fix`      | Bug 修复 |
| `refactor` | 重构     |
| `docs`     | 文档     |
| `test`     | 测试     |
| `chore`    | 构建/工具  |
| `perf`     | 性能优化   |
| `style`    | 代码格式   |

**示例 / Examples:**
```
feat(models): add MessagePin, MessageReadState, MessageDraft, MessageEdit models
fix(socket): handle namespace validation on connect
refactor(engine): extract session store to dedicated module
docs(readme): add architecture overview
test(parser): add edge cases for binary event decoding
chore(deps): update tonic to 0.14
```

### 11.2 提交原则 / Commit Principles

| 原则     | 说明                                                       |
|--------|----------------------------------------------------------|
| 原子提交   | Each commit should address one concern                   |
| 完整性    | Each commit should leave the codebase in a working state |
| 禁止强制推送 | Never force push to main branch                          |
| 提交前检查  | Run `cargo check` and `cargo test` before committing     |

### 11.3 分支策略 / Branch Strategy

| 分支          | 用途     |
|-------------|--------|
| `main`      | 生产就绪代码 |
| `feat/*`    | 功能开发   |
| `fix/*`     | Bug 修复 |
| `release/*` | 发布准备   |

---

## 12. 工作流程 / Workflow

### 12.1 开发流程 / Development Process

1. **理解先于编写** — Read before write; understand context first
2. **最小变更** — Minimal changes; don't refactor unrelated code
3. **验证变更** — Verify after changes; run tests or check output
4. **文档同步** — Update documentation when changing public APIs

### 12.2 AI 助手工作规范 / AI Assistant Guidelines

| 规则     | 说明                                                  |
|--------|-----------------------------------------------------|
| 先读后写   | Always read existing code before making changes     |
| 最小侵入   | Make minimal changes; don't refactor unrelated code |
| 验证结果   | Run `cargo check` or `cargo test` after changes     |
| 解释变更   | Explain what you changed and why                    |
| 询问不确定  | Ask when unsure about requirements                  |
| 遵守禁止模式 | Never use `// ── xxxx ──────────` style comments    |

### 12.3 常用命令 / Common Commands

```bash
cargo build                      # 构建
cargo check                      # 快速检查（推荐开发时使用）
cargo test                       # 运行测试
cargo test --lib                 # 仅运行 lib 测试
cargo clippy                     # Lint 检查
cargo fmt                        # 格式化
cargo doc --no-deps              # 生成文档
```

---

## 13. 架构决策记录 / ADR

架构决策记录存放在 `docs/adr/` 目录下，使用 Markdown 格式。

### 当前决策 / Current Decisions

| ADR | 标题 | 状态 |
|---|---|---|
| — | Socket.IO 作为实时通信协议 | Accepted |
| — | UUID v7 作为主键实现游标分页 | Accepted |
| — | 双模式 JWT 验证（本地 + RPC） | Accepted |
| — | Adapter 模式支持多节点水平扩展 | Accepted |
| — | 消息表由 appks 管理，imks 仅扩展富内容表 | Accepted |

### ADR 模板 / ADR Template

```markdown
# ADR-NNN: 标题

## 状态
Accepted | Superseded | Deprecated

## 背景
描述问题背景

## 决策
描述做出的决策

## 后果
描述正面和负面影响
```

---

## 14. 审查清单 / Review Checklist

### 代码审查 / Code Review

- [ ] 代码风格符合项目规范（无 `// ──` 分隔线）
- [ ] 没有使用禁止模式（unwrap、panic、todo 等）
- [ ] 错误处理完整（?传播、具体类型）
- [ ] 安全考虑已处理（JWT 验证模式选择正确）
- [ ] 性能影响已评估（无 N+1、无阻塞调用）
- [ ] 测试已添加（model 文件必须有测试）
- [ ] 文档已更新（新 struct 有 doc comment）

### PR 审查 / PR Review

- [ ] 提交信息符合 Angular 风格
- [ ] 每个提交只关注一个问题
- [ ] 变更范围合理
- [ ] 没有遗留的 TODO/FIXME
- [ ] `cargo check` 和 `cargo test` 通过

### 发布前审查 / Pre-release Review

- [ ] 所有测试通过
- [ ] 无 clippy warning
- [ ] 迁移 SQL 已包含在 `migrate/` 中
- [ ] 依赖安全审计通过（`cargo audit`）

---

## 附录 / Appendix

### 项目架构速查 / Quick Architecture Reference

```
imks — IM 实时消息服务 / Real-time Messaging Service

┌──────────────────────────────────────────────┐
│                  imks                         │
│                                               │
│  ┌─────────────┐  ┌─────────────────────────┐ │
│  │   engine/    │  │       socket/           │ │
│  │             │  │                          │ │
│  │ • websocket  │  │  • server (Socket.IO)    │ │
│  │ • webtransport│  │  • namespace (rooms)    │ │
│  │ • polling   │  │  • parser (protocol)     │ │
│  │ • session   │  │  • adapter (scale-out)   │ │
│  │ • packet    │  │    ├─ local              │ │
│  │ • codec     │  │    ├─ redis              │ │
│  │ • heartbeat │  │    └─ nats               │ │
│  │ • server    │  │  • message_bus           │ │
│  └─────────────┘  │  • session_store         │ │
│                    └─────────────────────────┘ │
│  ┌─────────────┐  ┌─────────────────────────┐ │
│  │   models/    │  │       pb/               │ │
│  │             │  │                          │ │
│  │ 12 个消息    │  │  gRPC client stubs      │ │
│  │ 领域模型     │  │  → appks TokenService    │ │
│  │             │  │  → appks ChannelService   │ │
│  │ message     │  │  → appks MemberService    │ │
│  │ attachment  │  │  → appks PermissionService│ │
│  │ embed/poll  │  │                          │ │
│  │ reaction    │  │                          │ │
│  │ thread/pin  │  │                          │ │
│  │ draft/edit  │  │                          │ │
│  │ mention     │  │                          │ │
│  │ bookmark    │  │                          │ │
│  │ read_state  │  │                          │ │
│  └─────────────┘  └─────────────────────────┘ │
│                                               │
│  ┌─────────────┐                              │
│  │  migrate/    │                              │
│  │             │                              │
│  │ SQL 迁移     │                              │
│  └─────────────┘                              │
└─────────────────────┬────────────────────────┘
                      │ gRPC
                      ▼
┌──────────────────────────────────────────────┐
│                  appks (core)                 │
│                                               │
│  TokenService  │ ChannelService │ MemberSvc   │
│  PermissionSvc │ WebhookSvc     │ EmojiSvc    │
│                                               │
│  Postgres (users, channels, members, ...)     │
│  Redis (JWT keys, sessions, rate limiting)    │
└──────────────────────────────────────────────┘
```

### 基础设施速查 / Infrastructure Quick Reference

| 服务 | 用途 | 协议/库 |
|---|---|---|
| Postgres | 消息数据持久化 | sqlx |
| Redis | Adapter 广播 / 会话存储 | fred |
| NATS | Adapter 广播（低延迟替代） | async-nats |
| appks gRPC | JWT 验证 / 频道/成员/权限查询 | tonic |

### 传输层对比 / Transport Comparison

| 传输               | 适用场景              | 特点                 |
|------------------|-------------------|--------------------|
| **Polling**      | 浏览器不支持 WS 时的降级    | 兼容性最好，延迟高          |
| **WebSocket**    | 主流浏览器/移动端         | 全双工，低延迟            |
| **WebTransport** | 现代浏览器（Chrome 97+） | 基于 QUIC，多路复用，不队头阻塞 |

---

*This document is maintained by the development team. For questions or suggestions, please open an issue.*