From 913a235e5c32051deacae11c7b3c7bcb1c95bcc1 Mon Sep 17 00:00:00 2001
From: Milky0217 <m943790568@163.com>
Date: Wed, 15 Apr 2026 11:29:20 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20AGENTS.md=20?=
 =?UTF-8?q?=E5=92=8C=20IMPROVEMENTS.md=EF=BC=8C=E8=AE=B0=E5=BD=95=E5=B7=B2?=
 =?UTF-8?q?=E7=9F=A5=E5=85=BC=E5=AE=B9=E6=80=A7=E9=97=AE=E9=A2=98?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

AGENTS.md:
- 添加已知兼容性问题章节
  - actix-ratelimit 0.3.1 与 actix-web 4.x 不兼容
  - actix-web-prom 与当前架构不兼容
- 添加路由配置结构说明（App 配置顺序、middleware 应用方式）
- 添加路由优先级说明

IMPROVEMENTS.md:
- 2.1 缺少请求频率限制：标记 ⚠️，记录兼容性问题及备选方案
- 6.1 缺少性能指标收集：标记 ⚠️，记录兼容性问题及备选方案
- 修正无日志聚合的 checkbox 状态
---
 AGENTS.md       | 37 +++++++++++++++++++++++++++++++++++++
 IMPROVEMENTS.md | 18 +++++++++++++-----
 2 files changed, 50 insertions(+), 5 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 808910c..6848b7e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -152,6 +152,17 @@ FREE_USER_DATA_LIMIT=20
 
 ## 约束条件
 
+### 已知兼容性问题
+⚠️ **actix-ratelimit 0.3.1 与 actix-web 4.x 不兼容**
+- 错误：`Transform<ResourceService>` trait bound 不满足
+- 原因：该 crate 基于 actix-web 3.x 设计
+- 备选：actix-web-lab、手动 HashMap 实现、Nginx 层限流
+
+⚠️ **actix-web-prom 与当前架构不兼容**
+- 错误：`ServiceFactory Response` 类型冲突（expected `ServiceResponse`, found `ServiceResponse<EitherBody<..., ...>>`）
+- 原因：middleware 改变了 App 返回类型，与 `impl Trait` 返回类型冲突
+- 备选：actix-web-lab、手动 atomic 计数器、Nginx access log
+
 ### 禁止事项
 - 在 JWT Claims 中添加 `is_admin`（必须查询数据库）
 - 信任 JWT 中的 `is_paid` 来做配额决策（必须查询数据库）
@@ -175,6 +186,32 @@ FREE_USER_DATA_LIMIT=20
 3. 在 `create_server_config` 中注册（如果是受保护接口，放在 JWT 作用域内）
 4. 如需要，在 `models.rs` 中添加请求/响应结构体
 
+### 路由配置结构
+```rust
+// create_server_config 函数中的 App 配置顺序很重要
+App::new()
+    .app_data(web::Data::new(pool))           // 数据源
+    .app_data(web::Data::new(http_client))
+    .app_data(web::Data::new(app_state))
+    // 公开接口（无 middleware）
+    .service(login)                            // POST /api/login
+    .service(get_weather_details)             // GET /api/weather/details
+    // 受保护接口（JWT middleware）
+    .service(
+        web::scope("")
+            .wrap(from_fn(jwt_middleware))   // JWT 验证
+            .service(post_weather_data)       // POST /api/post-weather-data
+            // ... 其他受保护接口
+    )
+    // 静态文件和健康检查放最后
+    .service(web::resource("/static/{tail:.*}").route(web::get().to(serve_static_files)))
+    .service(health_check)
+```
+
+### 路由优先级
+- `web::scope("/")` 内的路由路径不带前缀（handlers 已有 `#[post("/api/...")]` 等属性）
+- 公开接口和受保护接口分开，便于添加不同的 middleware
+
 ### 修改数据库
 1. 在 `migrations/` 中创建迁移 SQL
 2. 在 PostgreSQL 上手动执行迁移
diff --git a/IMPROVEMENTS.md b/IMPROVEMENTS.md
index 58115c4..8df2cc4 100644
--- a/IMPROVEMENTS.md
+++ b/IMPROVEMENTS.md
@@ -49,14 +49,18 @@
 ## 二、安全性改进
 
 ### 2.1 认证安全
-- [ ] **缺少请求频率限制**
+- [ ] **缺少请求频率限制** ⚠️
   - 风险：API 可能被滥用或遭受暴力攻击
   - 改进：添加 Rate Limiting 中间件
-  - 实现：使用 `actix-limitation` 或自定义中间件
   - 配置：
     - 登录接口：5 次/分钟
     - 数据上传：30 次/分钟
     - 查询接口：100 次/分钟
+  - **状态**：actix-ratelimit 0.3.1 与 actix-web 4.x 不兼容（Transform trait 问题）
+  - **备选方案**：
+    1. `actix-web-lab` - 社区维护的中间件库
+    2. 手动实现 - 使用 `std::collections::HashMap` 记录 IP 请求数
+    3. Nginx/网关层限流
 
 - [ ] **缺少 CSRF 防护**
   - 风险：跨站请求伪造攻击
@@ -204,16 +208,20 @@
   - 完成时间：2026-04-15
   - 修改文件：Cargo.toml, src/main.rs, src/config.rs
 
-- [x] **无日志聚合**
+- [x] **无日志聚合** ✅
   - 需求：集中式日志管理
   - 实现：配置日志收集器（如 ELK Stack）
   - 格式：JSON 格式便于解析
   - 状态：✅ 已完成（JSON + 文件轮转，2026-04-15）
 
-- [ ] **缺少性能指标收集**
+- [ ] **缺少性能指标收集** ⚠️
   - 需求：API 响应时间、错误率等
   - 实现：添加 Prometheus 指标
-  - 工具：`actix-web-prom`
+  - **状态**：actix-web-prom 与当前架构不兼容（ServiceFactory Response 类型冲突）
+  - **备选方案**：
+    1. `actix-web-lab` - 社区维护的中间件库
+    2. 手动实现 - 在代码中直接使用 `std::sync::atomic` 收集请求计数
+    3. Nginx 层收集 - 反向代理层已有 access log
 
 ### 6.2 告警机制
 - [ ] **无异常告警**