docs: 更新支付系统和支付宝集成文档，修复Rust edition版本号
This commit is contained in:
73
AGENTS.md
73
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。
|
||||
|
||||
### 支付模式
|
||||
|
||||
|
||||
Reference in New Issue
Block a user