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:
45
AGENTS.md
45
AGENTS.md
@@ -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` | 模拟支付确认(测试用) |
|
||||
|
||||
---
|
||||
|
||||
## 代码模式
|
||||
|
||||
Reference in New Issue
Block a user