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

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 响应都遵循统一格式：

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

5. 分页格式

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

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

开发指南

添加新接口文档

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

文档规范

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

更新日志

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