aiotagro/niumalll
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b8c9e5c95904fb3f1f9b519b8d0a634d6d314a4f
niumalll/docs/API接口文档更新.md

11 KiB
Raw Blame History

牛商城后端系统 - API接口文档 (更新版)

版本历史

版本 日期 作者 变更说明
v1.0 2024-12-20 API架构师 初版API接口文档
v1.1 2025-01-20 系统工程师 基于实际代码实现更新文档

1. API概览

1.1 基础信息

  • Base URL: http://localhost:3000/api (开发环境)
  • 协议: HTTP/HTTPS
  • 数据格式: JSON
  • 字符编码: UTF-8
  • API版本: v1

1.2 认证方式

JWT Token认证

Authorization: Bearer <access_token>

认证流程

  1. 用户登录获取access_token
  2. 请求头携带access_token
  3. token过期需重新登录

1.3 通用响应格式

成功响应

{
  "success": true,
  "message": "操作成功",
  "data": {
    // 具体数据
  }
}

分页响应

{
  "success": true,
  "message": "获取成功",
  "data": {
    "list": [],
    "total": 100,
    "page": 1,
    "pageSize": 10
  }
}

错误响应

{
  "success": false,
  "message": "错误描述",
  "code": 400
}

1.4 状态码说明

状态码 说明 描述
200 OK 请求成功
400 Bad Request 请求参数错误
401 Unauthorized 未授权，需要登录
403 Forbidden 禁止访问，权限不足
404 Not Found 资源不存在
500 Internal Server Error 服务器内部错误

2. 认证模块 (AuthController)

2.1 用户登录

接口信息

  • URL: /auth/login
  • Method: POST
  • 描述: 用户登录接口，支持用户名/邮箱登录
  • 认证: 不需要

请求参数

{
  "username": "admin",
  "password": "123456"
}

参数说明

参数 类型 必填 说明
username string 是 用户名或邮箱
password string 是 密码

响应示例

{
  "success": true,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "username": "admin",
      "userType": "admin",
      "email": "admin@example.com"
    }
  }
}

2.2 小程序登录

接口信息

  • URL: /auth/miniprogram-login
  • Method: POST
  • 描述: 微信小程序登录接口
  • 认证: 不需要

请求参数

{
  "code": "wx_code_from_miniprogram",
  "userInfo": {
    "nickName": "用户昵称",
    "avatarUrl": "头像URL"
  }
}

2.3 获取当前用户信息

接口信息

  • URL: /auth/current-user
  • Method: GET
  • 描述: 获取当前登录用户信息
  • 认证: 需要

响应示例

{
  "success": true,
  "message": "获取成功",
  "data": {
    "id": 1,
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "username": "admin",
    "userType": "admin",
    "email": "admin@example.com"
  }
}

3. 用户管理模块 (UserController)

3.1 获取用户列表

接口信息

  • URL: /users
  • Method: GET
  • 描述: 获取用户列表，支持分页和筛选
  • 认证: 需要

查询参数

参数 类型 必填 说明
page integer 否 页码，默认1
pageSize integer 否 每页数量，默认10
userType string 否 用户类型筛选
status string 否 用户状态筛选

响应示例

{
  "success": true,
  "message": "获取成功",
  "data": {
    "list": [
      {
        "id": 1,
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "username": "admin",
        "realName": "管理员",
        "phone": "13800138000",
        "email": "admin@example.com",
        "userType": "admin",
        "status": "active",
        "avatar": "https://example.com/avatar.jpg",
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 10
  }
}

3.2 获取用户详情

接口信息

  • URL: /users/{id}
  • Method: GET
  • 描述: 根据用户ID获取用户详细信息
  • 认证: 需要

路径参数

参数 类型 必填 说明
id integer 是 用户ID

响应示例

{
  "success": true,
  "message": "获取成功",
  "data": {
    "id": 1,
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "username": "admin",
    "realName": "管理员",
    "phone": "13800138000",
    "email": "admin@example.com",
    "userType": "admin",
    "status": "active",
    "avatar": "https://example.com/avatar.jpg",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
}

3.3 更新用户信息

接口信息

  • URL: /users/{id}
  • Method: PUT
  • 描述: 更新用户基本信息
  • 认证: 需要

路径参数

参数 类型 必填 说明
id integer 是 用户ID

请求参数

{
  "realName": "新的真实姓名",
  "phone": "13900139000",
  "email": "newemail@example.com",
  "avatar": "https://example.com/new-avatar.jpg"
}

响应示例

{
  "success": true,
  "message": "更新成功",
  "data": {
    "id": 1,
    "realName": "新的真实姓名",
    "phone": "13900139000",
    "email": "newemail@example.com",
    "avatar": "https://example.com/new-avatar.jpg",
    "updatedAt": "2024-01-20T10:30:00.000Z"
  }
}

3.4 更新用户状态

接口信息

  • URL: /users/{id}/status
  • Method: PUT
  • 描述: 更新用户状态（启用/禁用）
  • 认证: 需要

路径参数

参数 类型 必填 说明
id integer 是 用户ID

请求参数

{
  "status": "inactive"
}

参数说明

参数 类型 必填 说明
status string 是 用户状态：active(启用)、inactive(禁用)

响应示例

{
  "success": true,
  "message": "状态更新成功",
  "data": {
    "id": 1,
    "status": "inactive",
    "updatedAt": "2024-01-20T10:30:00.000Z"
  }
}

4. 运输管理模块 (TransportController)

4.1 获取运输列表

接口信息

  • URL: /transports
  • Method: GET
  • 描述: 获取运输记录列表
  • 认证: 需要

4.2 获取运输详情

接口信息

  • URL: /transports/{id}
  • Method: GET
  • 描述: 获取运输记录详情
  • 认证: 需要

4.3 更新运输状态

接口信息

  • URL: /transports/{id}/status
  • Method: PUT
  • 描述: 更新运输状态
  • 认证: 需要

4.4 获取运输统计

接口信息

  • URL: /transports/stats
  • Method: GET
  • 描述: 获取运输统计数据
  • 认证: 需要

5. 订单管理模块 (OrderController)

5.1 获取订单列表

接口信息

  • URL: /orders
  • Method: GET
  • 描述: 获取订单列表
  • 认证: 需要

5.2 创建订单

接口信息

  • URL: /orders
  • Method: POST
  • 描述: 创建新订单
  • 认证: 需要

5.3 获取订单详情

接口信息

  • URL: /orders/{id}
  • Method: GET
  • 描述: 获取订单详情
  • 认证: 需要

5.4 更新订单状态

接口信息

  • URL: /orders/{id}/status
  • Method: PUT
  • 描述: 更新订单状态
  • 认证: 需要

6. 供应商管理模块 (SupplierController)

6.1 获取供应商列表

接口信息

  • URL: /suppliers
  • Method: GET
  • 描述: 获取供应商列表
  • 认证: 需要

6.2 获取供应商详情

接口信息

  • URL: /suppliers/{id}
  • Method: GET
  • 描述: 获取供应商详情
  • 认证: 需要

6.3 获取供应商统计

接口信息

  • URL: /suppliers/stats
  • Method: GET
  • 描述: 获取供应商统计数据
  • 认证: 需要

7. 司机管理模块 (DriverController)

7.1 获取司机列表

接口信息

  • URL: /drivers
  • Method: GET
  • 描述: 获取司机列表
  • 认证: 需要

7.2 获取司机详情

接口信息

  • URL: /drivers/{id}
  • Method: GET
  • 描述: 获取司机详情
  • 认证: 需要

7.3 获取司机统计

接口信息

  • URL: /drivers/stats
  • Method: GET
  • 描述: 获取司机统计数据
  • 认证: 需要

8. 车辆管理模块 (VehicleController)

8.1 获取车辆列表

接口信息

  • URL: /vehicles
  • Method: GET
  • 描述: 获取车辆列表
  • 认证: 需要

8.2 获取车辆详情

接口信息

  • URL: /vehicles/{id}
  • Method: GET
  • 描述: 获取车辆详情
  • 认证: 需要

9. 支付管理模块 (PaymentController)

9.1 获取支付记录

接口信息

  • URL: /payments
  • Method: GET
  • 描述: 获取支付记录列表
  • 认证: 需要

9.2 创建支付订单

接口信息

  • URL: /payments
  • Method: POST
  • 描述: 创建支付订单
  • 认证: 需要

10. 错误码说明

10.1 通用错误码

错误码 说明 描述
400 请求参数错误 请求参数格式不正确或缺少必要参数
401 未授权 用户未登录或token无效
403 权限不足 用户没有访问该资源的权限
404 资源不存在 请求的资源不存在
500 服务器内部错误 服务器处理请求时发生错误

10.2 业务错误码

错误码 说明 描述
1001 用户不存在 指定的用户ID不存在
1002 用户名或密码错误 登录时用户名或密码不正确
1003 用户已被禁用 用户账户已被管理员禁用
2001 订单不存在 指定的订单ID不存在
2002 订单状态错误 订单当前状态不允许该操作

11. 开发指南

11.1 环境配置

开发环境

  • Node.js 18+
  • MySQL 8.0+
  • Redis 6.0+

环境变量

NODE_ENV=development
PORT=3000
DB_HOST=localhost
DB_PORT=3306
DB_NAME=niumall
DB_USER=root
DB_PASSWORD=password
JWT_SECRET=your-jwt-secret
JWT_EXPIRES_IN=24h

11.2 测试指南

单元测试

npm test -- tests/unit

集成测试

npm test -- tests/integration

11.3 API调试工具

推荐使用以下工具进行API测试：

  • Postman
  • Insomnia
  • curl
  • Thunder Client (VS Code插件)

文档维护：本文档基于实际代码实现编写，与系统保持同步更新。

技术支持：如有疑问，请联系开发团队。

最后更新时间：2025年1月20日