feat(telemetry): integrate OpenTelemetry observability stack with health metrics

- Add OpenTelemetry SDK, OTLP exporter, Prometheus integration
- Implement connection tracking with active/total/disconnection metrics
- Add health endpoint with uptime and connection counts
- Integrate tracing spans for socket events and engine messages
- Add metrics collection for event handling duration
- Update health endpoint to include live runtime state
- Add graceful telemetry shutdown in main function
- Implement engine session active metrics tracking
- Add namespace-specific attributes to connection metrics
- Introduce message edit history retrieval endpoint
- Add scheduled message CRUD operations and dispatcher
- Update Socket.IO event registration with observability
- Refactor component update to remove dead code allowance
- Add comprehensive environment variables documentation
- Implement detailed development guidelines in AGENTS.md

README.md

@@ -0,0 +1,126 @@
+# imks — IM 实时消息服务
+
+基于 **Engine.IO + Socket.IO** 协议的即时通讯（IM）实时消息服务，支持 WebSocket、WebTransport、HTTP Long-Polling 多种传输层，通过 gRPC 与 [appks](https://github.com/your-org/appks) 核心服务集成，提供认证、权限、消息持久化和跨节点广播。
+
+## 架构
+
+```
+Client (Browser/App)
+    │  Socket.IO over WebSocket / WebTransport / Polling
+    ▼
+┌─────────────────────────────────────┐
+│              imks                    │
+│                                     │
+│  engine/     socket/                │
+│  • WS/WT/      • Socket.IO Server   │
+│    Polling     • Namespace/Room     │
+│  • Session     • Adapter (Redis/NATS)│
+│  • Heartbeat   • Message Bus        │
+│                                     │
+│  models/      repo/       svc/      │
+│  • 20+ 消息     • SQL CRUD   • 业务    │
+│    领域模型      • 分页查询    逻辑层   │
+│                                     │
+│  auth/        rpc/                  │
+│  • JWT 双模    • gRPC Stubs         │
+│    验证        • Token/Channel/     │
+│  • 密钥缓存      Member/Permission  │
+└──────────────┬──────────────────────┘
+               │ gRPC (mTLS)
+               ▼
+┌─────────────────────────────────────┐
+│              appks (core)           │
+│  Token  │ Channel │ Member │ ...    │
+│  Postgres • Redis • NATS            │
+└─────────────────────────────────────┘
+```
+
+## 快速开始
+
+### 前置依赖
+
+- **Rust** 1.85+ (edition 2024)
+- **PostgreSQL** 16+ (消息持久化)
+- **appks** gRPC 服务 (认证 & 权限)
+- **Redis** (可选, 多节点广播)
+- **NATS** (可选, 低延迟多节点广播)
+
+### 安装 & 运行
+
+```bash
+# 克隆仓库
+git clone https://github.com/your-org/imks.git
+cd imks
+
+# 配置环境变量
+cp .env.example .env
+# 编辑 .env，至少设置 DATABASE_URL 和 APPKS_GRPC_ADDR
+
+# 数据库迁移（自动执行）
+# 首次启动会自动运行 migrate/ 下的 SQL 迁移
+
+# 编译
+cargo build --release
+
+# 运行
+cargo run --release
+# 默认监听 http://0.0.0.0:3000
+```
+
+### 端点
+
+| 端点 | 说明 |
+|---|---|
+| `GET /engine.io/` | Engine.IO 握手 & WebSocket 升级 |
+| `POST /engine.io/` | Engine.IO HTTP Long-Polling |
+| `GET /health` | 健康检查（含连接数、会话数、依赖检查） |
+| `GET /metrics` | Prometheus 格式指标 |
+
+### 健康检查示例
+
+```json
+{
+  "status": "healthy",
+  "version": "0.1.0",
+  "timestamp": "2026-06-11T10:00:00Z",
+  "uptime_secs": 3600,
+  "connections_active": 42,
+  "sessions_count": 42,
+  "checks": {
+    "postgres": { "status": "up", "latency_ms": 3 },
+    "redis": { "status": "up", "latency_ms": 1 }
+  }
+}
+```
+
+## 环境变量
+
+完整列表见 [`.env.example`](./.env.example)。
+
+### 核心配置
+
+| 变量 | 默认值 | 说明 |
+|---|---|---|
+| `IMKS_ADAPTER` | `local` | `local` \| `redis` \| `nats` |
+| `DATABASE_URL` | `postgres://localhost/imks` | PostgreSQL 连接串 |
+| `APPKS_GRPC_ADDR` | `http://localhost:50051` | appks gRPC 地址 |
+
+## 开发
+
+```bash
+cargo check          # 快速检查语法
+cargo test           # 运行所有测试（111 个）
+cargo test --lib     # 仅库测试（91 个）
+cargo clippy         # Lint 检查
+cargo fmt            # 格式化
+```
+
+## 文档
+
+- [AGENTS.md](./AGENTS.md) — 开发规范
+- [rpc.md](docs/rpc.md) — 认证方案 & Proto 契约
+- [migrate/](./migrate/) — 数据库迁移脚本
+
+## 许可证
+
+[待定]