143 lines
3.9 KiB
Markdown
143 lines
3.9 KiB
Markdown
# 句容圈代理后台管理系统 API 文档
|
||
|
||
## 概述
|
||
|
||
本文档为句容圈代理后台管理系统的完整API接口文档，采用OpenAPI 3.0标准格式编写，可直接导入到Apifox等API管理工具中使用。
|
||
|
||
## 文档文件
|
||
|
||
- **文档文件**: `apifox-documentation.json`
|
||
- **格式**: OpenAPI 3.0 JSON格式
|
||
- **编码**: UTF-8
|
||
|
||
## 如何导入到Apifox
|
||
|
||
### 方法一：直接导入JSON文件
|
||
|
||
1. 打开Apifox应用
|
||
2. 创建新项目或选择现有项目
|
||
3. 点击「导入」按钮
|
||
4. 选择「OpenAPI」格式
|
||
5. 选择「从文件导入」
|
||
6. 选择 `apifox-documentation.json` 文件
|
||
7. 点击「开始导入」
|
||
|
||
### 方法二：复制JSON内容导入
|
||
|
||
1. 打开 `apifox-documentation.json` 文件
|
||
2. 复制全部内容
|
||
3. 在Apifox中选择「从剪贴板导入」
|
||
4. 粘贴JSON内容
|
||
5. 点击「开始导入」
|
||
|
||
## API接口模块
|
||
|
||
### 1. 认证管理 (Authentication)
|
||
- `POST /auth/login` - 代理登录
|
||
- `GET /auth/me` - 获取当前代理信息
|
||
- `POST /auth/logout` - 代理登出
|
||
|
||
### 2. 验证码管理 (Captcha)
|
||
- `GET /captcha/generate` - 生成图形验证码
|
||
- `POST /captcha/verify` - 验证图形验证码
|
||
|
||
### 3. 代理统计 (Agent Statistics)
|
||
- `GET /agent/stats` - 获取代理统计数据
|
||
- `GET /agent/user-growth-trend` - 获取用户增长趋势
|
||
- `GET /agent/commission-trend` - 获取佣金收入趋势
|
||
- `GET /agent/commission-distribution` - 获取佣金类型分布
|
||
- `GET /agent/recent-users` - 获取最新下级用户
|
||
- `GET /agent/recent-commissions` - 获取最新佣金记录
|
||
|
||
### 4. 用户管理 (User Management)
|
||
- `GET /users` - 获取代理下级用户列表
|
||
- `GET /users/{id}` - 获取用户详情
|
||
- `GET /users/export/data` - 导出用户数据
|
||
|
||
### 5. 佣金管理 (Commission Management)
|
||
- `GET /commissions` - 获取佣金记录列表
|
||
- `GET /commissions/{id}` - 获取佣金记录详情
|
||
- `POST /commissions/{id}/request-payment` - 申请单个佣金发放
|
||
- `POST /commissions/batch-request-payment` - 批量申请佣金发放
|
||
- `GET /commissions/trend/data` - 获取佣金趋势数据
|
||
- `GET /commissions/export/data` - 导出佣金数据
|
||
|
||
### 6. 转账管理 (Transfer Management)
|
||
- `GET /transfers` - 获取转账记录列表
|
||
- `GET /transfers/{id}` - 获取转账记录详情
|
||
- `GET /transfers/trend/data` - 获取转账趋势数据
|
||
- `GET /transfers/export/data` - 导出转账数据
|
||
|
||
### 7. 文件上传 (File Upload)
|
||
- `POST /upload/single` - 单文件上传
|
||
- `POST /upload/multiple` - 多文件上传
|
||
- `POST /upload/avatar` - 头像上传
|
||
- `POST /upload/qrcode` - 二维码上传
|
||
- `POST /upload/idcard` - 身份证上传
|
||
- `POST /upload/license` - 营业执照上传
|
||
- `DELETE /upload/file` - 删除文件
|
||
|
||
## 认证方式
|
||
|
||
系统使用JWT Bearer Token进行身份认证：
|
||
|
||
```
|
||
Authorization: Bearer <your-jwt-token>
|
||
```
|
||
|
||
## 服务器地址
|
||
|
||
- **开发环境**: `http://localhost:3000/api`
|
||
- **生产环境**: `https://agent-api.jurongcircle.com/api`
|
||
|
||
## 响应格式
|
||
|
||
所有API接口都遵循统一的响应格式：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "操作成功",
|
||
"data": {
|
||
// 具体的响应数据
|
||
}
|
||
}
|
||
```
|
||
|
||
## 分页格式
|
||
|
||
列表接口的分页信息格式：
|
||
|
||
```json
|
||
{
|
||
"current_page": 1,
|
||
"per_page": 20,
|
||
"total": 100,
|
||
"total_pages": 5
|
||
}
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
- `200` - 请求成功
|
||
- `400` - 请求参数错误
|
||
- `401` - 未授权或Token过期
|
||
- `403` - 权限不足
|
||
- `404` - 资源不存在
|
||
- `500` - 服务器内部错误
|
||
|
||
## 注意事项
|
||
|
||
1. 所有需要认证的接口都需要在请求头中携带有效的JWT Token
|
||
2. 文件上传接口使用 `multipart/form-data` 格式
|
||
3. 日期参数格式为 `YYYY-MM-DD`
|
||
4. 金额字段统一使用字符串类型，保持精度
|
||
5. 分页参数：`page`（页码，从1开始），`limit`（每页数量，默认20）
|
||
|
||
## 更新日志
|
||
|
||
- **v1.0.0** (2024-01-26) - 初始版本，包含所有核心API接口
|
||
|
||
---
|
||
|
||
如有任何问题，请联系技术支持：support@jurongcircle.com |