docs: 更新后端 API 文档

- 补充 handlers 目录:添加 meta.rs、favorites.rs
- 新增服务状态页说明(/、/health)
- 完善 API 接口列表:
  - 公开接口:添加 /health、/refresh-token
  - 受保护接口:添加 /api/favorites 系列、/api/user/quota
  - 支付接口:添加 /api/payment/create-order、/api/payment/mock-confirm
This commit is contained in:
2026-04-19 21:10:17 +08:00
parent fb791a2a7c
commit fe0e831210

View File

@@ -29,13 +29,16 @@ src/
├── db.rs # 数据库操作(通过 sqlx 执行原始 SQL
├── models.rs # 数据结构Claims、User、WeatherData 等)
├── config.rs # 配置加载支持多环境config/*.toml
├── error.rs # 错误处理
└── handlers/ # 路由处理器模块
├── mod.rs # 模块导出
├── auth.rs # 登录相关 (login)
├── weather.rs # 天气数据 CRUD
├── meta.rs # 根路径状态页 (/), 健康检查
├── auth.rs # 登录相关 (login, refresh-token)
├── weather.rs # 天气数据 CRUD
├── user.rs # 用户相关
├── admin.rs # 管理员功能
├── payment.rs # 支付相关
├── favorites.rs # 收藏功能
├── health.rs # 健康检查 (/health)
└── static_files.rs # 静态文件服务
@@ -60,6 +63,29 @@ deploy.sh # 部署脚本
---
## 服务状态页
### 根路径 `/`
访问根路径返回服务状态 HTML 页面,显示:
- 服务名称
- 数据库连接状态
- **版本号**(从 `Cargo.toml` 编译时嵌入)
### 健康检查 `/health`
返回 JSON 格式健康状态:
```json
{
"status": "ok",
"database": "connected",
"version": "0.3.0"
}
```
---
## PDF 报表生成
### 功能位置
@@ -214,7 +240,10 @@ created_at TIMESTAMPTZ创建时间
| 接口 | 说明 |
|------|------|
| `GET /` | 服务状态页(显示版本、数据库连接状态) |
| `GET /health` | 健康检查 |
| `POST /api/login` | 微信登录 |
| `POST /api/refresh-token` | 刷新 access_token |
| `GET /weather/details` | 获取天气详情(支持 JWT 或 temp_token |
| `GET /static/{tail:*}` | 静态文件 |
@@ -224,9 +253,14 @@ created_at TIMESTAMPTZ创建时间
|------|------|
| `POST /api/post-weather-data` | 上传天气数据(带配额检查) |
| `GET /api/user/profile` | 获取当前用户信息 |
| `PUT /api/user/profile` | 保存用户信息 |
| `GET /weather` | 分页列出用户的天气数据 |
| `POST /api/generate-temp-token/{resource_id}` | 生成 10 分钟分享令牌 |
| `DELETE /weather/delete/{id}` | 删除天气记录 |
| `GET /api/favorites` | 获取收藏列表 |
| `POST /api/favorites/{id}` | 添加收藏 |
| `DELETE /api/favorites/{id}` | 删除收藏 |
| `GET /api/user/quota` | 获取用户配额 |
### 管理员接口(需要 JWT + is_admin
@@ -235,6 +269,13 @@ 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` | 模拟支付确认(测试用) |
---
## 代码模式