chore(infra): add gRPC layer, update protobufs, remove immediate module

- Add gRPC service modules: auth, channel, channel settings, member, permission - Update protobuf definitions and generated code - Remove immediate/ real-time module (superseded by IM service) - Update etcd discovery and registration - Update cache, error, config, and build infrastructure - Add ADR documentation - Update OpenAPI spec
2026-06-10 18:49:42 +08:00
parent 9eb77ab98b
commit 1000f8a80d
57 changed files with 22524 additions and 2703 deletions
@@ -0,0 +1,50 @@
+# ADR-NNN: 标题 / Title
+
+## 状态 / Status
+
+**Accepted** | Superseded | Deprecated
+
+**日期 / Date**: YYYY-MM-DD
+
+## 背景 / Context
+
+描述问题背景和驱动因素。
+
+Describe the context and driving factors.
+
+## 决策 / Decision
+
+描述做出的决策。
+
+Describe the decision that was made.
+
+## 考虑的方案 / Considered Options
+
+1. **方案 A** — 描述 / Description
+2. **方案 B** — 描述 / Description
+3. **方案 C** — 描述 / Description
+
+## 后果 / Consequences
+
+### 正面 / Positive
+
+- 优点 1 / Advantage 1
+- 优点 2 / Advantage 2
+
+### 负面 / Negative
+
+- 缺点 1 / Disadvantage 1
+- 缺点 2 / Disadvantage 2
+
+### 风险 / Risks
+
+- 风险 1 / Risk 1
+- 风险 2 / Risk 2
+
+## 相关决策 / Related Decisions
+
+- [ADR-XXX](xxx-related-decision.md)
+
+## 参考 / References
+
+- [链接 / Link](url)
@@ -0,0 +1,48 @@
+# ADR-001: 选择 Actix-web 作为 Web 框架 / Choice of Actix-web as Web Framework
+
+## 状态 / Status
+
+**Accepted**
+
+**日期 / Date**: 2024-01-01
+
+## 背景 / Context
+
+appks 是一个协作开发平台后端，需要一个高性能、可靠的 Rust Web 框架来处理 HTTP 请求、WebSocket 连接和中间件。
+
+appks is a collaborative development platform backend that needs a high-performance, reliable Rust web framework for HTTP requests, WebSocket connections, and middleware.
+
+## 决策 / Decision
+
+选择 **Actix-web** 作为 Web 框架。
+
+Chose **Actix-web** as the web framework.
+
+## 考虑的方案 / Considered Options
+
+1. **Actix-web** — 成熟的 actor 模型框架，性能优异
+2. **Axum** — Tokio 生态新兴框架，Tower 集成
+3. **Rocket** — 易用性优先的框架
+
+## 后果 / Consequences
+
+### 正面 / Positive
+
+- 优异的性能表现 / Excellent performance
+- 成熟的生态系统 / Mature ecosystem
+- 良好的 WebSocket 支持 / Good WebSocket support
+- 活跃的社区维护 / Active community maintenance
+
+### 负面 / Negative
+
+- 学习曲线较陡 / Steeper learning curve
+- Actor 模型需要适应 / Actor model requires adaptation
+
+### 风险 / Risks
+
+- 框架版本升级可能带来 breaking changes / Framework upgrades may bring breaking changes
+
+## 参考 / References
+
+- [Actix-web 官方文档](https://actix.rs/)
+- [TechEmpower Web Framework Benchmarks](https://www.techempower.com/benchmarks/)
@@ -0,0 +1,49 @@
+# ADR-002: 两级缓存架构 / Two-Tier Caching Architecture
+
+## 状态 / Status
+
+**Accepted**
+
+**日期 / Date**: 2024-01-01
+
+## 背景 / Context
+
+平台需要缓存机制来减少数据库负载，提高响应速度。需要在性能和一致性之间取得平衡。
+
+The platform needs a caching mechanism to reduce database load and improve response times. A balance between performance and consistency is required.
+
+## 决策 / Decision
+
+采用 **两级缓存架构**：L1 (内存 LRU-TTL) + L2 (Redis)。
+
+Adopted **two-tier caching**: L1 (in-memory LRU-TTL) + L2 (Redis).
+
+## 考虑的方案 / Considered Options
+
+1. **纯 Redis** — 简单但网络延迟高
+2. **纯内存缓存** — 快但不跨实例共享
+3. **两级缓存** — 兼顾速度和共享
+
+## 后果 / Consequences
+
+### 正面 / Positive
+
+- L1 提供极低延迟 / L1 provides ultra-low latency
+- L2 提供跨实例共享 / L2 provides cross-instance sharing
+- 减少数据库负载 / Reduces database load
+
+### 负面 / Negative
+
+- 缓存一致性复杂 / Cache consistency is complex
+- 内存占用增加 / Increased memory usage
+
+### 风险 / Risks
+
+- 缓存雪崩 / Cache avalanche
+- 缓存穿透 / Cache penetration
+
+## 实现细节 / Implementation Details
+
+- **L1**: `DashMap + Mutex<LruTracker>`, TTL 5 分钟
+- **L2**: Redis via r2d2, TTL 可配置
+- **策略**: L1 miss → L2 miss → 数据库查询
@@ -0,0 +1,45 @@
+# ADR-003: 使用 NATS JetStream 作为消息队列 / NATS JetStream for Messaging
+
+## 状态 / Status
+
+**Accepted**
+
+**日期 / Date**: 2024-01-01
+
+## 背景 / Context
+
+平台的实时 IM 系统需要可靠的消息传递机制，支持发布/订阅模式和消息持久化。
+
+The platform's real-time IM system needs reliable messaging with pub/sub patterns and message persistence.
+
+## 决策 / Decision
+
+使用 **NATS JetStream** 作为消息队列。
+
+Use **NATS JetStream** as the message queue.
+
+## 考虑的方案 / Considered Options
+
+1. **NATS JetStream** — 轻量级、高性能
+2. **Apache Kafka** — 高吞吐但运维复杂
+3. **RabbitMQ** — 功能丰富但性能较低
+
+## 后果 / Consequences
+
+### 正面 / Positive
+
+- 轻量级部署 / Lightweight deployment
+- 高性能消息传递 / High-performance messaging
+- 内置持久化 / Built-in persistence
+- 良好的 Rust 客户端支持 / Good Rust client support
+
+### 负面 / Negative
+
+- 生态系统不如 Kafka 成熟 / Ecosystem less mature than Kafka
+- 监控工具有限 / Limited monitoring tools
+
+## 实现细节 / Implementation Details
+
+- Publisher: 发布事件到 JetStream
+- Subscriber: 订阅并处理事件
+- Stream prefix: 可配置的流前缀
@@ -0,0 +1,46 @@
+# ADR-004: 使用 etcd 进行服务发现 / etcd for Service Discovery
+
+## 状态 / Status
+
+**Accepted**
+
+**日期 / Date**: 2024-01-01
+
+## 背景 / Context
+
+平台依赖多个外部 gRPC 微服务（Git、Email），需要动态发现机制来连接这些服务。
+
+The platform depends on multiple external gRPC microservices (Git, Email) and needs dynamic discovery to connect to them.
+
+## 决策 / Decision
+
+使用 **etcd** 进行服务发现和注册。
+
+Use **etcd** for service discovery and registration.
+
+## 考虑的方案 / Considered Options
+
+1. **etcd** — Kubernetes 生态标准，强一致性
+2. **Consul** — 功能丰富但较重
+3. **ZooKeeper** — 经典但运维复杂
+4. **静态配置** — 简单但不灵活
+
+## 后果 / Consequences
+
+### 正面 / Positive
+
+- 与 Kubernetes 生态一致 / Aligned with Kubernetes ecosystem
+- 强一致性保证 / Strong consistency guarantees
+- 租约机制支持健康检查 / Lease mechanism supports health checks
+- Watch 机制支持实时更新 / Watch mechanism supports real-time updates
+
+### 负面 / Negative
+
+- 额外的基础设施依赖 / Additional infrastructure dependency
+- 运维复杂度增加 / Increased operational complexity
+
+## 实现细节 / Implementation Details
+
+- **注册**: `register.rs` — 自注册 + 租约保活
+- **发现**: `discovery.rs` — Watch 动态连接
+- **客户端**: tonic/prost gRPC 客户端
@@ -0,0 +1,68 @@
+# ADR-005: 统一错误处理策略 / Unified Error Handling Strategy
+
+## 状态 / Status
+
+**Accepted**
+
+**日期 / Date**: 2024-01-01
+
+## 背景 / Context
+
+平台需要统一的错误处理机制，确保错误信息对用户友好，同时保留足够的调试信息。
+
+The platform needs a unified error handling mechanism that provides user-friendly error messages while retaining sufficient debugging information.
+
+## 决策 / Decision
+
+使用 **AppError 枚举 + AppResult 类型别名** 作为统一错误处理策略。
+
+Use **AppError enum + AppResult type alias** as the unified error handling strategy.
+
+## 考虑的方案 / Considered Options
+
+1. **自定义枚举 (AppError)** — 类型安全、可扩展
+2. **anyhow** — 简单但类型信息丢失
+3. **thiserror + 手动实现** — 灵活但工作量大
+
+## 后果 / Consequences
+
+### 正面 / Positive
+
+- 类型安全的错误处理 / Type-safe error handling
+- 统一的错误响应格式 / Unified error response format
+- 便于错误分类和监控 / Easy error classification and monitoring
+- 与 actix-web 集成良好 / Good integration with actix-web
+
+### 负面 / Negative
+
+- 需要维护错误枚举 / Need to maintain error enum
+- 新增错误类型需要更新枚举 / New error types require enum updates
+
+## 实现细节 / Implementation Details
+
+```rust
+// AppError 定义
+#[derive(Debug, thiserror::Error)]
+pub enum AppError {
+    #[error("User not found")]
+    UserNotFound,
+    #[error("Invalid password")]
+    InvalidPassword,
+    #[error("Database error: {0}")]
+    Database(#[from] sqlx::Error),
+    // ...
+}
+
+// AppResult 类型别名
+pub type AppResult<T> = Result<T, AppError>;
+```
+
+## 错误码映射 / Error Code Mapping
+
+| Postgres Code | 含义 | HTTP Status |
+|---|---|---|
+| 23505 | 唯一约束违反 | 409 Conflict |
+| 23503 | 外键约束违反 | 400 Bad Request |
+| 23514 | 检查约束违反 | 400 Bad Request |
+| 23502 | 非空约束违反 | 400 Bad Request |
+| 23P01 | 排他约束违反 | 409 Conflict |