From 375f0affcf745b7610d297d2e1af097d90656995 Mon Sep 17 00:00:00 2001
From: Milky0217 <m943790568@163.com>
Date: Fri, 24 Apr 2026 09:19:48 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E6=94=AF=E4=BB=98?=
 =?UTF-8?q?=E7=B3=BB=E7=BB=9F=E5=92=8C=E6=94=AF=E4=BB=98=E5=AE=9D=E9=9B=86?=
 =?UTF-8?q?=E6=88=90=E6=96=87=E6=A1=A3=EF=BC=8C=E4=BF=AE=E5=A4=8DRust=20ed?=
 =?UTF-8?q?ition=E7=89=88=E6=9C=AC=E5=8F=B7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 73 +++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 55 insertions(+), 18 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 6ffa2c3..8374199 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,7 +10,7 @@
 
 | 技术 | 版本 | 说明 |
 |------|------|------|
-| Rust | edition 2024 | 主力语言 |
+| Rust | edition 2021 | 主力语言 |
 | actix-web | 4.11 | Web 框架 |
 | sqlx | 0.8.6 | PostgreSQL 连接 |
 | serde | 1.0 | 序列化 |
@@ -30,18 +30,19 @@ src/
 ├── models.rs            # 数据结构（Claims、User、WeatherData 等）
 ├── config.rs            # 配置加载（支持多环境：config/*.toml）
 ├── error.rs             # 错误处理
+├── alipay.rs            # 支付宝签名模块（RSA2 sign/verify、URL encode）
 └── handlers/            # 路由处理器模块
     ├── mod.rs           # 模块导出
     ├── meta.rs         # 根路径状态页 (/), 健康检查
-    ├── auth.rs          # 登录相关 (login, refresh-token)
+    ├── auth.rs          # 登录相关 (login, refresh-token, mock-login)
     ├── weather.rs       # 天气数据 CRUD
     ├── user.rs          # 用户相关
     ├── admin.rs         # 管理员功能
-    ├── payment.rs       # 支付相关
+    ├── payment.rs       # 支付相关（支付宝网页支付）
     ├── favorites.rs     # 收藏功能
     ├── health.rs        # 健康检查 (/health)
     └── static_files.rs  # 静态文件服务
-
+```
 config/
 ├── default.toml         # 默认配置（所有环境的共同默认值）
 ├── development.toml    # 开发/测试环境配置
@@ -212,6 +213,19 @@ expires_at          TIMESTAMPTZ（过期时间）
 created_at          TIMESTAMPTZ（创建时间）
 ```
 
+#### payment_orders 表
+
+```sql
+id                  SERIAL PRIMARY KEY
+order_no            VARCHAR UNIQUE（订单号，格式：ASD{timestamp}{random}）
+user_id             INTEGER（外键，关联 users 表）
+package_type        VARCHAR（套餐类型：monthly/quarterly/annual/permanent）
+amount               DECIMAL(10,2)（金额，单位：元）
+status              VARCHAR（订单状态：pending/paid/cancelled/expired）
+paid_at             TIMESTAMPTZ（支付时间，可空）
+created_at          TIMESTAMPTZ（创建时间）
+```
+
 ---
 
 ## 认证流程
@@ -236,13 +250,14 @@ created_at          TIMESTAMPTZ（创建时间）
 
 ## API 接口
 
-### 公开接口（无需认证）
+### 公开接口
 
 | 接口 | 说明 |
 |------|------|
 | `GET /` | 服务状态页（显示版本、数据库连接状态） |
 | `GET /health` | 健康检查 |
-| `POST /api/login` | 微信登录 |
+| `POST /api/login` | 微信登录，返回双 Token |
+| `GET /api/mock-login` | Mock 登录（沙箱测试用，受 `MOCK_LOGIN_ENABLED` 环境变量控制） |
 | `POST /api/refresh-token` | 刷新 access_token |
 | `GET /weather/details` | 获取天气详情（支持 JWT 或 temp_token） |
 | `GET /static/{tail:*}` | 静态文件 |
@@ -269,14 +284,17 @@ created_at          TIMESTAMPTZ（创建时间）
 | `PUT /api/admin/users/{id}/payment` | 更新用户支付状态 |
 | `GET /api/admin/users/{id}` | 获取用户信息 |
 
-### 支付接口（需要 JWT）
+### 支付接口
 
 | 接口 | 说明 |
 |------|------|
-| `POST /api/payment/create-order` | 创建订单 |
-| `POST /api/payment/mock-confirm` | 模拟支付确认（测试用） |
-| `GET /payment/page` | 支付引导页面（生成订单并引导打开支付链接） |
-| `GET /payment/pay` | 支付宝电脑网站支付页面（占位，接入支付宝后替换） |
+| `GET /payment` | 套餐选择页（无需认证，外部浏览器访问） |
+| `GET /payment/page` | 支付页面（需 JWT，支持 URL 参数 `jwt` 或 Cookie） |
+| `POST /api/payment/create-order` | 创建订单（需 JWT） |
+| `GET /payment/pay` | 唤起支付宝支付（需 JWT + order_no） |
+| `POST /payment/notify` | 支付宝异步回调通知（需 RSA 签名验证，无认证） |
+| `GET /payment/success` | 支付成功页（需 order_no） |
+| `POST /api/payment/mock-confirm` | 模拟支付确认（沙箱测试用） |
 
 ### 支付宝配置（可选）
 
@@ -418,20 +436,39 @@ ORDER BY "desc"
 
 ## 支付系统
 
-### 支付流程
+### 支付流程（真实支付宝）
 
 小程序内无法直接接入支付宝支付，采用以下方案：
 
 ```
-小程序 → 后端 /payment/page → 重定向到 /payment/pay → 支付宝
+小程序 → outter页面 → 外部浏览器 → /payment?jwt=xxx
 ```
 
 1. 用户在小程序选择套餐 → 点击「立即开通」
-2. 小程序调用 `POST /api/payment/create-order` 创建订单
-3. 小程序跳转 `outter` 页面，URL 指向 `/payment/page?package=xxx`
-4. 后端验证 JWT，创建订单，返回自动跳转 HTML（利用 outter 页面复制链接提示用户在浏览器打开）
-5. 用户在浏览器打开 `/payment/pay?order_no=xxx&package_type=xxx`
-6. 后端调用支付宝接口，返回支付表单或跳转链接
+2. 小程序调用 `POST /api/payment/create-order` 创建订单（需 JWT）
+3. 小程序跳转 `outter` 页面，URL 指向 `/payment?jwt=xxx&package=xxx`（outter 页面复制链接到剪贴板）
+4. 用户切换到外部浏览器，打开 `/payment?jwt=xxx`
+5. 后端验证 JWT，返回套餐选择页（已携带 package 参数则预选套餐）
+6. 用户选择套餐，点击「去支付」→ 跳转到 `/payment/pay?order_no=xxx&package_type=xxx`
+7. 后端调用 `alipay.trade.page.pay` API，生成支付表单或跳转 URL
+8. 支付宝沙箱/正式环境支付页面展示
+9. 支付完成后，支付宝异步通知 `/payment/notify`
+10. 后端验证签名，确认订单状态
+11. 跳转成功页 `/payment/success?order_no=xxx`
+
+### Mock 登录（沙箱测试）
+
+沙箱环境下无法获取真实微信 code，使用 Mock 登录获取测试 JWT：
+
+```bash
+# 获取 mock JWT（需服务器设置 MOCK_LOGIN_ENABLED=true）
+curl http://127.0.0.1:8080/api/mock-login
+
+# 返回格式
+{"success":true,"token":"eyJ0eX...","refresh_token":"MTAxOj...aW9u","user_id":101}
+```
+
+Mock 登录支持 `user_id` 参数指定已有用户，或自动创建新用户。环境变量 `MOCK_LOGIN_ENABLED=false` 时返回 403。
 
 ### 支付模式