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

544 lines
11 KiB
Markdown
Raw Normal View History

refactor(docs): 简化README结构，更新技术栈和项目结构描述
2025-09-20 15:19:59 +08:00
# 牛商城后端系统 - 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日
Reference in New Issue Copy Permalink