# 牛商城后端系统 - 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认证
```http
Authorization: Bearer <access_token>
```

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

### 1.3 通用响应格式

#### 成功响应
```json
{
  "success": true,
  "message": "操作成功",
  "data": {
    // 具体数据
  }
}
```

#### 分页响应
```json
{
  "success": true,
  "message": "获取成功",
  "data": {
    "list": [],
    "total": 100,
    "page": 1,
    "pageSize": 10
  }
}
```

#### 错误响应
```json
{
  "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`
- **描述**: 用户登录接口，支持用户名/邮箱登录
- **认证**: 不需要

#### 请求参数
```json
{
  "username": "admin",
  "password": "123456"
}
```

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

#### 响应示例
```json
{
  "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`
- **描述**: 微信小程序登录接口
- **认证**: 不需要

#### 请求参数
```json
{
  "code": "wx_code_from_miniprogram",
  "userInfo": {
    "nickName": "用户昵称",
    "avatarUrl": "头像URL"
  }
}
```

### 2.3 获取当前用户信息

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

#### 响应示例
```json
{
  "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 | 否 | 用户状态筛选 |

#### 响应示例
```json
{
  "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 |

#### 响应示例
```json
{
  "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 |

#### 请求参数
```json
{
  "realName": "新的真实姓名",
  "phone": "13900139000",
  "email": "newemail@example.com",
  "avatar": "https://example.com/new-avatar.jpg"
}
```

#### 响应示例
```json
{
  "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 |

#### 请求参数
```json
{
  "status": "inactive"
}
```

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

#### 响应示例
```json
{
  "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+

#### 环境变量
```env
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 测试指南

#### 单元测试
```bash
npm test -- tests/unit
```

#### 集成测试
```bash
npm test -- tests/integration
```

### 11.3 API调试工具

推荐使用以下工具进行API测试：
- Postman
- Insomnia
- curl
- Thunder Client (VS Code插件)

---

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

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

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