# 句容圈代理后台管理系统 API 文档

本目录包含了句容圈代理后台管理系统的完整 API 文档，使用 Swagger/OpenAPI 3.0 规范编写。

## 文档结构

### APIs 目录
包含各个模块的 API 接口文档：

- `auth.js` - 认证管理接口（登录、获取用户信息、登出）
- `agent.js` - 代理统计接口（统计数据、趋势分析、最新记录）
- `captcha.js` - 验证码接口（生成验证码、验证验证码）
- `commissions.js` - 佣金管理接口（佣金列表、详情、申请发放）
- `transfers.js` - 转账管理接口（转账记录查询）
- `upload.js` - 文件上传接口（各类文件上传、删除）
- `users.js` - 用户管理接口（用户列表、详情、数据导出）

### Schemas 目录
包含数据模型定义：

- `agent.js` - 代理数据模型
- `user.js` - 用户数据模型
- `commission.js` - 佣金记录数据模型
- `transfer.js` - 转账记录数据模型
- `security.js` - 安全认证配置

## 使用说明

### 1. 集成到项目

在你的 Express 应用中集成 Swagger UI：

```javascript
const swaggerJsdoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: '句容圈代理后台管理系统 API',
      version: '1.0.0',
      description: '句容圈代理后台管理系统的 RESTful API 文档',
    },
    servers: [
      {
        url: 'http://localhost:3000/api',
        description: '开发环境',
      },
    ],
  },
  apis: [
    './docs/apis/*.js',
    './docs/schemas/*.js',
  ],
};

const specs = swaggerJsdoc(options);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
```

### 2. 访问文档

启动服务器后，访问 `http://localhost:3000/api-docs` 查看完整的 API 文档。

### 3. 认证说明

大部分 API 接口需要 JWT 认证，请在请求头中添加：

```
Authorization: Bearer <your-jwt-token>
```

### 4. 响应格式

所有 API 响应都遵循统一格式：

```json
{
  "success": true,
  "data": {},
  "message": "操作成功"
}
```

### 5. 分页格式

列表接口支持分页，响应格式：

```json
{
  "success": true,
  "data": {
    "items": [],
    "total": 100,
    "page": 1,
    "limit": 10,
    "totalPages": 10
  }
}
```

## 开发指南

### 添加新接口文档

1. 在 `apis/` 目录下创建或编辑对应的文件
2. 使用 Swagger JSDoc 注释格式编写文档
3. 如需要新的数据模型，在 `schemas/` 目录下添加

### 文档规范

- 使用中文描述
- 包含完整的请求参数和响应示例
- 标明必需参数和可选参数
- 提供错误响应说明
- 使用合适的 HTTP 状态码

## 更新日志

- v1.0.0 - 初始版本，包含所有核心 API 接口文档