niumalll/docs/API接口文档.md

# 活牛采购智能数字化系统 - API接口文档

## 版本历史
| 版本 | 日期 | 作者 | 变更说明 |
|------|------|------|----------|
| v1.0 | 2024-12-20 | API架构师 | 初版API接口文档 |

## 1. API概览

### 1.1 基础信息

- **Base URL**: `http://localhost:4330/v1` (本地开发环境即测试环境)
- **协议**: HTTPS/HTTP
- **数据格式**: JSON
- **字符编码**: UTF-8
- **API版本**: v1

### 1.2 认证方式

#### JWT Token认证
```http
Authorization: Bearer <access_token>
```

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

### 1.3 通用响应格式

#### 成功响应
```json
{
  "code": 200,
  "message": "success",
  "data": {
    // 具体数据
  },
  "timestamp": "2024-12-20T10:30:00Z",
  "request_id": "req_1234567890"
}
```

#### 错误响应
```json
{
  "code": 400,
  "message": "参数错误",
  "error": {
    "type": "VALIDATION_ERROR",
    "details": [
      {
        "field": "phone",
        "message": "手机号格式不正确"
      }
    ]
  },
  "timestamp": "2024-12-20T10:30:00Z",
  "request_id": "req_1234567890"
}
```

### 1.4 状态码说明

| 状态码 | 说明 | 描述 |
|--------|------|------|
| 200 | OK | 请求成功 |
| 201 | Created | 资源创建成功 |
| 400 | Bad Request | 请求参数错误 |
| 401 | Unauthorized | 未授权，需要登录 |
| 403 | Forbidden | 禁止访问，权限不足 |
| 404 | Not Found | 资源不存在 |
| 409 | Conflict | 资源冲突 |
| 422 | Unprocessable Entity | 请求格式正确，但语义错误 |
| 429 | Too Many Requests | 请求过于频繁 |
| 500 | Internal Server Error | 服务器内部错误 |

## 2. 用户认证模块

### 2.1 用户注册

#### 接口信息
- **URL**: `/auth/register`
- **Method**: `POST`
- **描述**: 用户注册接口

#### 请求参数
```json
{
  "phone": "13800138000",
  "password": "password123",
  "name": "张三",
  "role": "client",
  "verification_code": "123456"
}
```

#### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| phone | string | 是 | 手机号，11位数字 |
| password | string | 是 | 密码，6-20位字符 |
| name | string | 是 | 姓名，2-50个字符 |
| role | string | 是 | 用户角色：client/supplier/driver/trader |
| verification_code | string | 是 | 短信验证码 |

#### 响应示例
```json
{
  "code": 201,
  "message": "注册成功",
  "data": {
    "user_id": 12345,
    "phone": "13800138000",
    "name": "张三",
    "role": "client",
    "status": "active"
  }
}
```

### 2.2 用户登录

#### 接口信息
- **URL**: `/auth/login`
- **Method**: `POST`
- **描述**: 用户登录接口

#### 请求参数
```json
{
  "phone": "13800138000",
  "password": "password123",
  "device_info": {
    "device_id": "device_123",
    "device_type": "mobile",
    "app_version": "1.0.0"
  }
}
```

#### 响应示例
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 7200,
    "user": {
      "id": 12345,
      "phone": "13800138000",
      "name": "张三",
      "role": "client",
      "avatar": "https://cdn.niumall.com/avatars/12345.jpg"
    }
  }
}
```

### 2.3 刷新Token

#### 接口信息
- **URL**: `/auth/refresh`
- **Method**: `POST`
- **描述**: 刷新访问令牌

#### 请求参数
```json
{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

#### 响应示例
```json
{
  "code": 200,
  "message": "Token刷新成功",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 7200
  }
}
```

### 2.4 发送验证码

#### 接口信息
- **URL**: `/auth/send-code`
- **Method**: `POST`
- **描述**: 发送短信验证码

#### 请求参数
```json
{
  "phone": "13800138000",
  "type": "register"
}
```

#### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| phone | string | 是 | 手机号 |
| type | string | 是 | 验证码类型：register/login/reset_password |

#### 响应示例
```json
{
  "code": 200,
  "message": "验证码发送成功",
  "data": {
    "expires_in": 300
  }
}
```

## 3. 用户管理模块

### 3.1 获取用户信息

#### 接口信息
- **URL**: `/users/profile`
- **Method**: `GET`
- **描述**: 获取当前用户详细信息
- **认证**: 需要

#### 响应示例
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 12345,
    "phone": "13800138000",
    "name": "张三",
    "role": "client",
    "status": "active",
    "avatar": "https://cdn.niumall.com/avatars/12345.jpg",
    "profile": {
      "company_name": "北京牛肉贸易有限公司",
      "business_license": "https://cdn.niumall.com/licenses/12345.jpg",
      "license_number": "91110000123456789X",
      "legal_person": "张三",
      "contact_address": "北京市朝阳区xxx街道xxx号",
      "bank_account": "6222021234567890",
      "bank_name": "中国工商银行北京分行"
    },
    "created_at": "2024-01-01T00:00:00Z",
    "last_login_at": "2024-12-20T10:00:00Z"
  }
}
```

### 3.2 更新用户信息

#### 接口信息
- **URL**: `/users/profile`
- **Method**: `PUT`
- **描述**: 更新用户信息
- **认证**: 需要

#### 请求参数
```json
{
  "name": "张三丰",
  "avatar": "https://cdn.niumall.com/avatars/new_12345.jpg",
  "profile": {
    "company_name": "北京优质牛肉贸易有限公司",
    "contact_address": "北京市朝阳区新地址xxx号",
    "emergency_contact": "李四",
    "emergency_phone": "13900139000"
  }
}
```

#### 响应示例
```json
{
  "code": 200,
  "message": "更新成功",
  "data": {
    "updated_fields": ["name", "avatar", "profile.company_name", "profile.contact_address"]
  }
}
```

### 3.3 修改密码

#### 接口信息
- **URL**: `/users/change-password`
- **Method**: `POST`
- **描述**: 修改用户密码
- **认证**: 需要

#### 请求参数
```json
{
  "old_password": "old_password123",
  "new_password": "new_password456",
  "confirm_password": "new_password456"
}
```

#### 响应示例
```json
{
  "code": 200,
  "message": "密码修改成功",
  "data": {}
}
```

## 4. 订单管理模块

### 4.1 创建订单

#### 接口信息
- **URL**: `/orders`
- **Method**: `POST`
- **描述**: 创建新订单
- **认证**: 需要
- **权限**: client, trader

#### 请求参数
```json
{
  "cattle_type": "西门塔尔牛",
  "quantity": 50,
  "weight_range": "400-500kg",
  "unit_price": 28.50,
  "price_type": "per_kg",
  "delivery_address": "河北省石家庄市xxx屠宰场",
  "delivery_time": "2024-12-25T08:00:00Z",
  "special_requirements": "要求健康证明齐全，无疫病",
  "quality_standards": {
    "min_weight": 400,
    "max_weight": 500,
    "health_certificate": true,
    "quarantine_certificate": true
  }
}
```

#### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cattle_type | string | 是 | 牛只品种 |
| quantity | integer | 是 | 数量（头） |
| weight_range | string | 否 | 重量范围 |
| unit_price | decimal | 是 | 单价（元/kg或元/头） |
| price_type | string | 是 | 计价方式：per_kg/per_head |
| delivery_address | string | 是 | 交货地址 |
| delivery_time | datetime | 是 | 要求交货时间 |
| special_requirements | string | 否 | 特殊要求 |
| quality_standards | object | 否 | 质量标准 |

#### 响应示例
```json
{
  "code": 201,
  "message": "订单创建成功",
  "data": {
    "id": 67890,
    "order_no": "ORD202412200001",
    "status": "draft",
    "cattle_type": "西门塔尔牛",
    "quantity": 50,
    "unit_price": 28.50,
    "total_amount": 712500.00,
    "delivery_time": "2024-12-25T08:00:00Z",
    "created_at": "2024-12-20T10:30:00Z"
  }
}
```

### 4.2 获取订单列表

#### 接口信息
- **URL**: `/orders`
- **Method**: `GET`
- **描述**: 获取订单列表
- **认证**: 需要

#### 查询参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| limit | integer | 否 | 每页数量，默认20，最大100 |
| status | string | 否 | 订单状态筛选 |
| cattle_type | string | 否 | 牛只品种筛选 |
| start_date | date | 否 | 开始日期 |
| end_date | date | 否 | 结束日期 |
| keyword | string | 否 | 关键词搜索（订单号、供应商名称等） |

#### 响应示例
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "orders": [
      {
        "id": 67890,
        "order_no": "ORD202412200001",
        "status": "confirmed",
        "cattle_type": "西门塔尔牛",
        "quantity": 50,
        "unit_price": 28.50,
        "total_amount": 712500.00,
        "client": {
          "id": 12345,
          "name": "张三",
          "company_name": "北京牛肉贸易有限公司"
        },
        "supplier": {
          "id": 54321,
          "name": "李四",
          "company_name": "内蒙古优质牧场"
        },
        "delivery_time": "2024-12-25T08:00:00Z",
        "created_at": "2024-12-20T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 156,
      "pages": 8
    }
  }
}
```

### 4.3 获取订单详情

#### 接口信息
- **URL**: `/orders/{order_id}`
- **Method**: `GET`
- **描述**: 获取订单详细信息
- **认证**: 需要

#### 路径参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| order_id | integer | 是 | 订单ID |

#### 响应示例
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 67890,
    "order_no": "ORD202412200001",
    "status": "transporting",
    "cattle_type": "西门塔尔牛",
    "quantity": 50,
    "weight_range": "400-500kg",
    "estimated_weight": 22500.00,
    "actual_weight": 22800.00,
    "unit_price": 28.50,
    "price_type": "per_kg",
    "total_amount": 712500.00,
    "final_amount": 649800.00,
    "client": {
      "id": 12345,
      "name": "张三",
      "phone": "138****8000",
      "company_name": "北京牛肉贸易有限公司"
    },
    "supplier": {
      "id": 54321,
      "name": "李四",
      "phone": "139****9000",
      "company_name": "内蒙古优质牧场"
    },
    "trader": {
      "id": 11111,
      "name": "王五",
      "phone": "137****7000",
      "company_name": "中原牛肉贸易公司"
    },
    "pickup_address": "内蒙古呼和浩特市xxx牧场",
    "delivery_address": "河北省石家庄市xxx屠宰场",
    "pickup_time": "2024-12-23T06:00:00Z",
    "delivery_time": "2024-12-25T08:00:00Z",
    "actual_delivery_time": null,
    "special_requirements": "要求健康证明齐全，无疫病",
    "quality_standards": {
      "min_weight": 400,
      "max_weight": 500,
      "health_certificate": true,
      "quarantine_certificate": true
    },
    "transport_task": {
      "id": 98765,
      "task_no": "TRK202412200001",
      "status": "transporting",
      "driver": {
        "id": 33333,
        "name": "赵六",
        "phone": "136****6000"
      },
      "vehicle_no": "京A12345",
      "current_location": {
        "latitude": 39.9042,
        "longitude": 116.4074,
        "address": "北京市朝阳区xxx路段",
        "updated_at": "2024-12-20T10:25:00Z"
      }
    },
    "attachments": [
      {
        "id": 1001,
        "file_name": "合同.pdf",
        "file_url": "https://cdn.niumall.com/contracts/1001.pdf",
        "attachment_type": "contract",
        "created_at": "2024-12-20T10:35:00Z"
      }
    ],
    "status_logs": [
      {
        "from_status": "draft",
        "to_status": "pending",
        "operator": "张三",
        "remark": "提交订单",
        "created_at": "2024-12-20T10:30:00Z"
      },
      {
        "from_status": "pending",
        "to_status": "confirmed",
        "operator": "李四",
        "remark": "确认接单",
        "created_at": "2024-12-20T11:00:00Z"
      }
    ],
    "created_at": "2024-12-20T10:30:00Z",
    "updated_at": "2024-12-20T11:00:00Z"
  }
}
```

### 4.4 更新订单状态

#### 接口信息
- **URL**: `/orders/{order_id}/status`
- **Method**: `PUT`
- **描述**: 更新订单状态
- **认证**: 需要

#### 请求参数
```json
{
  "status": "confirmed",
  "remark": "确认接单，预计3天内发货"
}
```

#### 响应示例
```json
{
  "code": 200,
  "message": "订单状态更新成功",
  "data": {
    "order_id": 67890,
    "old_status": "pending",
    "new_status": "confirmed",
    "updated_at": "2024-12-20T11:00:00Z"
  }
}
```

### 4.5 取消订单

#### 接口信息
- **URL**: `/orders/{order_id}/cancel`
- **Method**: `POST`
- **描述**: 取消订单
- **认证**: 需要

#### 请求参数
```json
{
  "cancel_reason": "客户需求变更，暂时不需要采购"
}
```

#### 响应示例
```json
{
  "code": 200,
  "message": "订单取消成功",
  "data": {
    "order_id": 67890,
    "status": "cancelled",
    "cancel_reason": "客户需求变更，暂时不需要采购",
    "cancelled_at": "2024-12-20T11:30:00Z"
  }
}
```

## 5. 运输管理模块

### 5.1 创建运输任务

#### 接口信息
- **URL**: `/transport/tasks`
- **Method**: `POST`
- **描述**: 创建运输任务
- **认证**: 需要
- **权限**: supplier, trader, admin

#### 请求参数
```json
{
  "order_id": 67890,
  "driver_id": 33333,
  "vehicle_no": "京A12345",
  "vehicle_type": "厢式货车",
  "vehicle_capacity": 25.0,
  "planned_start_time": "2024-12-23T06:00:00Z",
  "planned_end_time": "2024-12-25T08:00:00Z",
  "transport_fee": 8000.00,
  "notes": "注意保持车厢通风，定时检查牛只状态"
}
```

#### 响应示例
```json
{
  "code": 201,
  "message": "运输任务创建成功",
  "data": {
    "id": 98765,
    "task_no": "TRK202412200001",
    "order_id": 67890,
    "status": "assigned",
    "driver": {
      "id": 33333,
      "name": "赵六",
      "phone": "136****6000"
    },
    "vehicle_no": "京A12345",
    "planned_start_time": "2024-12-23T06:00:00Z",
    "planned_end_time": "2024-12-25T08:00:00Z",
    "transport_fee": 8000.00,
    "created_at": "2024-12-20T11:45:00Z"
  }
}
```

### 5.2 获取运输任务列表

#### 接口信息
- **URL**: `/transport/tasks`
- **Method**: `GET`
- **描述**: 获取运输任务列表
- **认证**: 需要

#### 查询参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| limit | integer | 否 | 每页数量，默认20 |
| status | string | 否 | 任务状态筛选 |
| driver_id | integer | 否 | 司机ID筛选 |
| start_date | date | 否 | 开始日期 |
| end_date | date | 否 | 结束日期 |

#### 响应示例
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "tasks": [
      {
        "id": 98765,
        "task_no": "TRK202412200001",
        "order_no": "ORD202412200001",
        "status": "transporting",
        "driver": {
          "id": 33333,
          "name": "赵六",
          "phone": "136****6000"
        },
        "vehicle_no": "京A12345",
        "start_location": "内蒙古呼和浩特市xxx牧场",
        "end_location": "河北省石家庄市xxx屠宰场",
        "planned_start_time": "2024-12-23T06:00:00Z",
        "actual_start_time": "2024-12-23T06:15:00Z",
        "estimated_arrival_time": "2024-12-25T07:30:00Z",
        "progress": 65.5,
        "current_location": {
          "latitude": 39.9042,
          "longitude": 116.4074,
          "address": "北京市朝阳区xxx路段"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "pages": 3
    }
  }
}
```

### 5.3 获取运输任务详情

#### 接口信息
- **URL**: `/transport/tasks/{task_id}`
- **Method**: `GET`
- **描述**: 获取运输任务详细信息
- **认证**: 需要

#### 响应示例
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 98765,
    "task_no": "TRK202412200001",
    "order": {
      "id": 67890,
      "order_no": "ORD202412200001",
      "cattle_type": "西门塔尔牛",
      "quantity": 50
    },
    "status": "transporting",
    "driver": {
      "id": 33333,
      "name": "赵六",
      "phone": "136****6000",
      "driver_license": "1101051234567890"
    },
    "vehicle_no": "京A12345",
    "vehicle_type": "厢式货车",
    "vehicle_capacity": 25.0,
    "start_location": "内蒙古呼和浩特市xxx牧场",
    "end_location": "河北省石家庄市xxx屠宰场",
    "start_coordinates": {
      "latitude": 40.8414,
      "longitude": 111.7519
    },
    "end_coordinates": {
      "latitude": 38.0428,
      "longitude": 114.5149
    },
    "planned_distance": 580.5,
    "actual_distance": 592.3,
    "planned_start_time": "2024-12-23T06:00:00Z",
    "actual_start_time": "2024-12-23T06:15:00Z",
    "planned_end_time": "2024-12-25T08:00:00Z",
    "estimated_arrival_time": "2024-12-25T07:30:00Z",
    "transport_fee": 8000.00,
    "fuel_cost": 1200.00,
    "toll_cost": 350.00,
    "current_location": {
      "latitude": 39.9042,
      "longitude": 116.4074,
      "address": "北京市朝阳区xxx路段",
      "speed": 65.5,
      "direction": 135.2,
      "updated_at": "2024-12-20T10:25:00Z"
    },
    "cattle_status": {
      "normal_count": 49,
      "stressed_count": 1,
      "sick_count": 0,
      "dead_count": 0,
      "temperature": 18.5,
      "humidity": 65.2
    },
    "route_progress": 65.5,
    "events": [
      {
        "id": 2001,
        "event_type": "departure",
        "event_title": "车辆出发",
        "event_description": "装车完成，开始运输",
        "occurred_at": "2024-12-23T06:15:00Z",
        "location": {
          "latitude": 40.8414,
          "longitude": 111.7519,
          "address": "内蒙古呼和浩特市xxx牧场"
        }
      },
      {
        "id": 2002,
        "event_type": "rest_stop",
        "event_title": "休息停车",
        "event_description": "司机休息，检查牛只状态",
        "occurred_at": "2024-12-23T12:30:00Z",
        "location": {
          "latitude": 40.1436,
          "longitude": 113.9854,
          "address": "山西省大同市服务区"
        }
      }
    ],
    "created_at": "2024-12-20T11:45:00Z",
    "updated_at": "2024-12-20T10:25:00Z"
  }
}
```

### 5.4 更新位置信息

#### 接口信息
- **URL**: `/transport/tasks/{task_id}/location`
- **Method**: `POST`
- **描述**: 更新运输任务位置信息
- **认证**: 需要
- **权限**: driver

#### 请求参数
```json
{
  "latitude": 39.9042,
  "longitude": 116.4074,
  "altitude": 45.2,
  "accuracy": 5.0,
  "speed": 65.5,
  "direction": 135.2,
  "cattle_status": "normal",
  "temperature": 18.5,
  "humidity": 65.2,
  "recorded_at": "2024-12-20T10:25:00Z"
}
```

#### 响应示例
```json
{
  "code": 200,
  "message": "位置信息更新成功",
  "data": {
    "task_id": 98765,
    "location": {
      "latitude": 39.9042,
      "longitude": 116.4074,
      "address": "北京市朝阳区xxx路段",
      "updated_at": "2024-12-20T10:25:00Z"
    },
    "progress": 65.5,
    "estimated_arrival_time": "2024-12-25T07:30:00Z"
  }
}
```

### 5.5 上报运输事件

#### 接口信息
- **URL**: `/transport/tasks/{task_id}/events`
- **Method**: `POST`
- **描述**: 上报运输过程中的事件
- **认证**: 需要

#### 请求参数
```json
{
  "event_type": "emergency",
  "event_title": "牛只异常",
  "event_description": "发现一头牛只出现应激反应，已进行处理",
  "severity": "medium",
  "latitude": 39.9042,
  "longitude": 116.4074,
  "photos": [
    "https://cdn.niumall.com/events/photo1.jpg",
    "https://cdn.niumall.com/events/photo2.jpg"
  ],
  "occurred_at": "2024-12-20T10:30:00Z"
}
```

#### 响应示例
```json
{
  "code": 201,
  "message": "事件上报成功",
  "data": {
    "id": 2003,
    "task_id": 98765,
    "event_type": "emergency",
    "event_title": "牛只异常",
    "severity": "medium",
    "is_resolved": false,
    "occurred_at": "2024-12-20T10:30:00Z",
    "created_at": "2024-12-20T10:32:00Z"
  }
}
```

## 6. 质量管理模块

### 6.1 创建质量检验记录

#### 接口信息
- **URL**: `/quality/inspections`
- **Method**: `POST`
- **描述**: 创建质量检验记录
- **认证**: 需要
- **权限**: client, supplier, admin

#### 请求参数
```json
{
  "order_id": 67890,
  "inspection_type": "post_delivery",
  "total_count": 50,
  "qualified_count": 48,
  "unqualified_count": 2,
  "dead_count": 0,
  "sick_count": 1,
  "total_weight": 22800.00,
  "average_weight": 456.0,
  "overall_grade": "B",
  "quality_score": 85.5,
  "health_score": 90.0,
  "appearance_score": 82.0,
  "inspection_items": {
    "weight_check": {
      "passed": true,
      "notes": "重量符合要求"
    },
    "health_check": {
      "passed": true,
      "notes": "整体健康状况良好，1头轻微应激"
    },
    "appearance_check": {
      "passed": true,
      "notes": "外观良好，毛色正常"
    }
  },
  "defect_details": [
    {
      "cattle_no": "C001",
      "defect_type": "应激反应",
      "description": "轻微应激，建议休息观察"
    }
  ],
  "photos": [
    "https://cdn.niumall.com/inspections/photo1.jpg",
    "https://cdn.niumall.com/inspections/photo2.jpg"
  ],
  "is_passed": true,
  "recommendations": "整体质量良好，建议加强运输过程中的应激管理",
  "inspection_date": "2024-12-25T09:00:00Z"
}
```

#### 响应示例
```json
{
  "code": 201,
  "message": "质量检验记录创建成功",
  "data": {
    "id": 5001,
    "order_id": 67890,
    "inspection_type": "post_delivery",
    "overall_grade": "B",
    "quality_score": 85.5,
    "is_passed": true,
    "inspector": {
      "id": 12345,
      "name": "张三"
    },
    "inspection_date": "2024-12-25T09:00:00Z",
    "created_at": "2024-12-25T09:30:00Z"
  }
}
```

### 6.2 获取质量检验记录

#### 接口信息
- **URL**: `/quality/inspections`
- **Method**: `GET`
- **描述**: 获取质量检验记录列表
- **认证**: 需要

#### 查询参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| order_id | integer | 否 | 订单ID筛选 |
| inspection_type | string | 否 | 检验类型筛选 |
| is_passed | boolean | 否 | 是否通过筛选 |
| start_date | date | 否 | 开始日期 |
| end_date | date | 否 | 结束日期 |

#### 响应示例
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "inspections": [
      {
        "id": 5001,
        "order": {
          "id": 67890,
          "order_no": "ORD202412200001",
          "cattle_type": "西门塔尔牛"
        },
        "inspection_type": "post_delivery",
        "total_count": 50,
        "qualified_count": 48,
        "overall_grade": "B",
        "quality_score": 85.5,
        "is_passed": true,
        "inspector": {
          "id": 12345,
          "name": "张三"
        },
        "inspection_date": "2024-12-25T09:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 25,
      "pages": 2
    }
  }
}
```

## 7. 财务管理模块

### 7.1 创建财务结算

#### 接口信息
- **URL**: `/finance/settlements`
- **Method**: `POST`
- **描述**: 创建财务结算单
- **认证**: 需要
- **权限**: client, trader, admin

#### 请求参数
```json
{
  "order_id": 67890,
  "order_amount": 649800.00,
  "prepaid_amount": 100000.00,
  "transport_fee": 8000.00,
  "insurance_fee": 2000.00,
  "service_fee": 5000.00,
  "penalty_amount": 0.00,
  "discount_amount": 10000.00,
  "tax_amount": 32490.00,
  "settlement_type": "full_payment",
  "payment_terms": "货到付款，验收合格后3日内付清",
  "settlement_date": "2024-12-25",
  "due_date": "2024-12-28"
}
```

#### 响应示例
```json
{
  "code": 201,
  "message": "财务结算单创建成功",
  "data": {
    "id": 8001,
    "settlement_no": "STL202412250001",
    "order_id": 67890,
    "final_amount": 687290.00,
    "status": "draft",
    "settlement_date": "2024-12-25",
    "due_date": "2024-12-28",
    "created_at": "2024-12-25T10:00:00Z"
  }
}
```

### 7.2 创建支付记录

#### 接口信息
- **URL**: `/finance/payments`
- **Method**: `POST`
- **描述**: 创建支付记录
- **认证**: 需要

#### 请求参数
```json
{
  "settlement_id": 8001,
  "order_id": 67890,
  "payee_id": 54321,
  "payment_amount": 687290.00,
  "payment_method": "bank_transfer",
  "payer_bank_account": "6222021234567890",
  "payer_bank_name": "中国工商银行北京分行",
  "payee_bank_account": "6228481234567890",
  "payee_bank_name": "中国农业银行呼和浩特分行",
  "notes": "订单ORD202412200001货款结算",
  "receipt_url": "https://cdn.niumall.com/receipts/receipt_8001.jpg"
}
```

#### 响应示例
```json
{
  "code": 201,
  "message": "支付记录创建成功",
  "data": {
    "id": 9001,
    "payment_no": "PAY202412250001",
    "settlement_id": 8001,
    "payment_amount": 687290.00,
    "payment_method": "bank_transfer",
    "status": "pending",
    "created_at": "2024-12-25T11:00:00Z"
  }
}
```

### 7.3 获取财务统计

#### 接口信息
- **URL**: `/finance/statistics`
- **Method**: `GET`
- **描述**: 获取财务统计数据
- **认证**: 需要

#### 查询参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| start_date | date | 是 | 开始日期 |
| end_date | date | 是 | 结束日期 |
| type | string | 否 | 统计类型：daily/monthly/yearly |

#### 响应示例
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "summary": {
      "total_orders": 156,
      "total_amount": 12580000.00,
      "paid_amount": 10250000.00,
      "pending_amount": 2330000.00,
      "average_order_amount": 80641.03
    },
    "by_status": {
      "completed": {
        "count": 120,
        "amount": 10250000.00
      },
      "pending": {
        "count": 25,
        "amount": 2100000.00
      },
      "cancelled": {
        "count": 11,
        "amount": 230000.00
      }
    },
    "by_cattle_type": {
      "西门塔尔牛": {
        "count": 85,
        "amount": 7200000.00
      },
      "安格斯牛": {
        "count": 45,
        "amount": 3800000.00
      },
      "夏洛莱牛": {
        "count": 26,
        "amount": 1580000.00
      }
    },
    "monthly_trend": [
      {
        "month": "2024-10",
        "orders": 45,
        "amount": 3800000.00
      },
      {
        "month": "2024-11",
        "orders": 52,
        "amount": 4200000.00
      },
      {
        "month": "2024-12",
        "orders": 59,
        "amount": 4580000.00
      }
    ]
  }
}
```

## 8. 文件上传模块

### 8.1 获取上传凭证

#### 接口信息
- **URL**: `/upload/token`
- **Method**: `POST`
- **描述**: 获取文件上传凭证
- **认证**: 需要

#### 请求参数
```json
{
  "file_name": "contract.pdf",
  "file_type": "application/pdf",
  "file_size": 2048576,
  "upload_type": "contract"
}
```

#### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file_name | string | 是 | 文件名 |
| file_type | string | 是 | 文件MIME类型 |
| file_size | integer | 是 | 文件大小（字节） |
| upload_type | string | 是 | 上传类型：avatar/contract/certificate/photo/video |

#### 响应示例
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "upload_url": "https://upload.niumall.com/upload",
    "file_url": "https://cdn.niumall.com/contracts/20241225/contract_12345.pdf",
    "upload_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 3600,
    "max_file_size": 10485760,
    "allowed_types": ["application/pdf", "image/jpeg", "image/png"]
  }
}
```

### 8.2 确认上传完成

#### 接口信息
- **URL**: `/upload/confirm`
- **Method**: `POST`
- **描述**: 确认文件上传完成
- **认证**: 需要

#### 请求参数
```json
{
  "file_url": "https://cdn.niumall.com/contracts/20241225/contract_12345.pdf",
  "file_name": "contract.pdf",
  "file_size": 2048576,
  "upload_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

#### 响应示例
```json
{
  "code": 200,
  "message": "文件上传确认成功",
  "data": {
    "file_id": "file_12345",
    "file_url": "https://cdn.niumall.com/contracts/20241225/contract_12345.pdf",
    "status": "uploaded"
  }
}
```

## 9. 消息通知模块

### 9.1 获取通知列表

#### 接口信息
- **URL**: `/notifications`
- **Method**: `GET`
- **描述**: 获取用户通知列表
- **认证**: 需要

#### 查询参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| limit | integer | 否 | 每页数量，默认20 |
| is_read | boolean | 否 | 是否已读筛选 |
| notification_type | string | 否 | 通知类型筛选 |

#### 响应示例
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "notifications": [
      {
        "id": 10001,
        "title": "订单状态更新",
        "content": "您的订单ORD202412200001已确认，供应商正在准备货物",
        "notification_type": "order",
        "priority": "medium",
        "is_read": false,
        "related_type": "order",
        "related_id": 67890,
        "created_at": "2024-12-20T11:00:00Z"
      },
      {
        "id": 10002,
        "title": "运输状态更新",
        "content": "您的货物已开始运输，预计2024-12-25 07:30到达",
        "notification_type": "transport",
        "priority": "high",
        "is_read": false,
        "related_type": "transport_task",
        "related_id": 98765,
        "created_at": "2024-12-23T06:15:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "pages": 3
    },
    "unread_count": 12
  }
}
```

### 9.2 标记通知已读

#### 接口信息
- **URL**: `/notifications/{notification_id}/read`
- **Method**: `PUT`
- **描述**: 标记通知为已读
- **认证**: 需要

#### 响应示例
```json
{
  "code": 200,
  "message": "通知已标记为已读",
  "data": {
    "notification_id": 10001,
    "is_read": true,
    "read_at": "2024-12-20T12:00:00Z"
  }
}
```

### 9.3 批量标记已读

#### 接口信息
- **URL**: `/notifications/read-all`
- **Method**: `PUT`
- **描述**: 批量标记通知为已读
- **认证**: 需要

#### 请求参数
```json
{
  "notification_ids": [10001, 10002, 10003]
}
```

#### 响应示例
```json
{
  "code": 200,
  "message": "批量标记成功",
  "data": {
    "updated_count": 3,
    "updated_at": "2024-12-20T12:00:00Z"
  }
}
```

## 10. 系统管理模块

### 10.1 获取系统配置

#### 接口信息
- **URL**: `/system/configs`
- **Method**: `GET`
- **描述**: 获取系统配置信息
- **认证**: 需要

#### 查询参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| category | string | 否 | 配置分类筛选 |
| is_public | boolean | 否 | 是否公开配置 |

#### 响应示例
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "configs": {
      "app": {
        "app_name": "活牛采购智能数字化系统",
        "app_version": "1.0.0",
        "api_version": "v1"
      },
      "business": {
        "max_order_quantity": 1000,
        "min_order_amount": 10000,
        "default_transport_fee_rate": 0.05,
        "quality_grade_standards": {
          "A": "优质",
          "B": "良好",
          "C": "一般",
          "D": "较差"
        }
      },
      "payment": {
        "supported_methods": ["bank_transfer", "alipay", "wechat_pay"],
        "max_payment_amount": 10000000,
        "payment_timeout": 1800
      }
    }
  }
}
```

### 10.2 获取操作日志

#### 接口信息
- **URL**: `/system/logs`
- **Method**: `GET`
- **描述**: 获取系统操作日志
- **认证**: 需要
- **权限**: admin

#### 查询参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| limit | integer | 否 | 每页数量，默认50 |
| user_id | integer | 否 | 用户ID筛选 |
| operation_type | string | 否 | 操作类型筛选 |
| start_date | date | 否 | 开始日期 |
| end_date | date | 否 | 结束日期 |

#### 响应示例
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "logs": [
      {
        "id": 50001,
        "user": {
          "id": 12345,
          "name": "张三",
          "role": "client"
        },
        "operation_type": "CREATE_ORDER",
        "operation_module": "order",
        "operation_description": "创建订单ORD202412200001",
        "request_method": "POST",
        "request_url": "/api/v1/orders",
        "response_status": 201,
        "ip_address": "192.168.1.100",
        "execution_time": 245,
        "created_at": "2024-12-20T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 2580,
      "pages": 52
    }
  }
}
```

## 11. 错误码说明

### 11.1 通用错误码

| 错误码 | 错误类型 | 说明 |
|--------|----------|------|
| 10001 | INVALID_PARAMETER | 参数错误 |
| 10002 | MISSING_PARAMETER | 缺少必需参数 |
| 10003 | INVALID_FORMAT | 参数格式错误 |
| 10004 | PARAMETER_OUT_OF_RANGE | 参数超出范围 |

### 11.2 认证相关错误码

| 错误码 | 错误类型 | 说明 |
|--------|----------|------|
| 20001 | INVALID_TOKEN | Token无效 |
| 20002 | TOKEN_EXPIRED | Token已过期 |
| 20003 | INSUFFICIENT_PERMISSIONS | 权限不足 |
| 20004 | ACCOUNT_LOCKED | 账户被锁定 |
| 20005 | INVALID_CREDENTIALS | 用户名或密码错误 |

### 11.3 业务相关错误码

| 错误码 | 错误类型 | 说明 |
|--------|----------|------|
| 30001 | ORDER_NOT_FOUND | 订单不存在 |
| 30002 | ORDER_STATUS_INVALID | 订单状态无效 |
| 30003 | INSUFFICIENT_INVENTORY | 库存不足 |
| 30004 | PAYMENT_FAILED | 支付失败 |
| 30005 | TRANSPORT_TASK_NOT_FOUND | 运输任务不存在 |

### 11.4 系统相关错误码

| 错误码 | 错误类型 | 说明 |
|--------|----------|------|
| 50001 | DATABASE_ERROR | 数据库错误 |
| 50002 | EXTERNAL_SERVICE_ERROR | 外部服务错误 |
| 50003 | FILE_UPLOAD_FAILED | 文件上传失败 |
| 50004 | RATE_LIMIT_EXCEEDED | 请求频率超限 |

## 12. SDK和示例代码

### 12.1 JavaScript SDK示例

```javascript
// 初始化SDK
const NiumallAPI = require('@niumall/api-sdk');
const client = new NiumallAPI({
  baseURL: 'https://api.niumall.com/v1',
  accessToken: 'your_access_token'
});

// 创建订单
async function createOrder() {
  try {
    const order = await client.orders.create({
      cattle_type: '西门塔尔牛',
      quantity: 50,
      unit_price: 28.50,
      price_type: 'per_kg',
      delivery_address: '河北省石家庄市xxx屠宰场',
      delivery_time: '2024-12-25T08:00:00Z'
    });
    console.log('订单创建成功:', order);
  } catch (error) {
    console.error('创建订单失败:', error);
  }
}

// 获取订单列表
async function getOrders() {
  try {
    const orders = await client.orders.list({
      page: 1,
      limit: 20,
      status: 'confirmed'
    });
    console.log('订单列表:', orders);
  } catch (error) {
    console.error('获取订单失败:', error);
  }
}
```

### 12.2 Python SDK示例

```python
from niumall_api import NiumallClient
from datetime import datetime

# 初始化客户端
client = NiumallClient(
    base_url='https://api.niumall.com/v1',
    access_token='your_access_token'
)

# 创建订单
def create_order():
    try:
        order = client.orders.create({
            'cattle_type': '西门塔尔牛',
            'quantity': 50,
            'unit_price': 28.50,
            'price_type': 'per_kg',
            'delivery_address': '河北省石家庄市xxx屠宰场',
            'delivery_time': '2024-12-25T08:00:00Z'
        })
        print(f'订单创建成功: {order}')
    except Exception as e:
        print(f'创建订单失败: {e}')

# 获取运输任务详情
def get_transport_task(task_id):
    try:
        task = client.transport.get_task(task_id)
        print(f'运输任务详情: {task}')
        return task
    except Exception as e:
        print(f'获取运输任务失败: {e}')
        return None
```

## 13. 环境配置

### 13.1 环境信息

- **本地开发环境**: `http://localhost:4330/v1`
- **生产环境**: `https://wapi.yunniushi.cn/v1`

### 13.2 测试账号

- **采购人**: test_client / 123456
- **供应商**: test_supplier / 123456  
- **司机**: test_driver / 123456
- **管理员**: test_admin / 123456

### 13.3 环境切换配置

```javascript
// 环境配置示例
const environments = {
  development: {
    baseURL: 'http://localhost:4330/v1',
    apiVersion: 'v1'
  },
  production: {
    baseURL: 'https://wapi.yunniushi.cn/v1',
    apiVersion: 'v1'
  }
};

// 根据环境变量切换配置
const currentEnv = process.env.NODE_ENV || 'development';
const config = environments[currentEnv];
```

### 13.4 Postman集合

我们提供了完整的Postman集合，包含所有API接口的测试用例：

- **集合下载**: [Niumall API Collection](https://api.niumall.com/docs/postman/collection.json)
- **环境配置**: [Niumall API Environment](https://api.niumall.com/docs/postman/environment.json)

### 13.5 API测试工具

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

1. **Postman**: 图形化接口测试工具
2. **curl**: 命令行工具
3. **Insomnia**: 轻量级REST客户端
4. **Swagger UI**: 在线API文档和测试

---

**文档维护**：本文档由API团队负责维护，接口变更时及时更新。

**技术支持**：如有疑问，请联系技术支持团队 tech-support@niumall.com

**最后更新时间**：2024年12月20日