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