# 句容圈代理后台管理系统 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