Files

mapleaf 6d76281c6b refactor(backend): 优化API文档、认证路由和分页查询，统一响应格式并添加字段验证

2025-09-23 18:38:37 +08:00

37 KiB

Raw Blame History

活牛采购智能数字化系统 - 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认证

Authorization: Bearer <access_token>

认证流程

用户登录获取access_token和refresh_token
请求头携带access_token
token过期时使用refresh_token刷新
refresh_token过期需重新登录

1.3 通用响应格式

成功响应

{
  "code": 200,
  "message": "success",
  "data": {
    // 具体数据
  },
  "timestamp": "2024-12-20T10:30:00Z",
  "request_id": "req_1234567890"
}

错误响应

{
  "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
描述: 用户注册接口

请求参数

{
  "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	是	短信验证码

响应示例

{
  "code": 201,
  "message": "注册成功",
  "data": {
    "user_id": 12345,
    "phone": "13800138000",
    "name": "张三",
    "role": "client",
    "status": "active"
  }
}

2.2 用户登录

接口信息

URL: /auth/login
Method: POST
描述: 用户登录接口

请求参数

{
  "phone": "13800138000",
  "password": "password123",
  "device_info": {
    "device_id": "device_123",
    "device_type": "mobile",
    "app_version": "1.0.0"
  }
}

响应示例

{
  "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
描述: 刷新访问令牌

请求参数

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

响应示例

{
  "code": 200,
  "message": "Token刷新成功",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 7200
  }
}

2.4 发送验证码

接口信息

URL: /auth/send-code
Method: POST
描述: 发送短信验证码

请求参数

{
  "phone": "13800138000",
  "type": "register"
}

参数说明

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

响应示例

{
  "code": 200,
  "message": "验证码发送成功",
  "data": {
    "expires_in": 300
  }
}

3. 用户管理模块

3.1 获取用户信息

接口信息

URL: /users/profile
Method: GET
描述: 获取当前用户详细信息
认证: 需要

响应示例

{
  "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
描述: 更新用户信息
认证: 需要

请求参数

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

响应示例

{
  "code": 200,
  "message": "更新成功",
  "data": {
    "updated_fields": ["name", "avatar", "profile.company_name", "profile.contact_address"]
  }
}

3.3 修改密码

接口信息

URL: /users/change-password
Method: POST
描述: 修改用户密码
认证: 需要

请求参数

{
  "old_password": "old_password123",
  "new_password": "new_password456",
  "confirm_password": "new_password456"
}

响应示例

{
  "code": 200,
  "message": "密码修改成功",
  "data": {}
}

4. 订单管理模块

4.1 创建订单

接口信息

URL: /orders
Method: POST
描述: 创建新订单
认证: 需要
权限: client, trader

请求参数

{
  "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	否	质量标准

响应示例

{
  "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	否	关键词搜索（订单号、供应商名称等）

响应示例

{
  "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

响应示例

{
  "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
描述: 更新订单状态
认证: 需要

请求参数

{
  "status": "confirmed",
  "remark": "确认接单，预计3天内发货"
}

响应示例

{
  "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
描述: 取消订单
认证: 需要

请求参数

{
  "cancel_reason": "客户需求变更，暂时不需要采购"
}

响应示例

{
  "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

请求参数

{
  "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": "注意保持车厢通风，定时检查牛只状态"
}

响应示例

{
  "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	否	结束日期

响应示例

{
  "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
描述: 获取运输任务详细信息
认证: 需要

响应示例

{
  "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

请求参数

{
  "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"
}

响应示例

{
  "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
描述: 上报运输过程中的事件
认证: 需要

请求参数

{
  "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"
}

响应示例

{
  "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

请求参数

{
  "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"
}

响应示例

{
  "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	否	结束日期

响应示例

{
  "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

请求参数

{
  "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"
}

响应示例

{
  "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
描述: 创建支付记录
认证: 需要

请求参数

{
  "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"
}

响应示例

{
  "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

响应示例

{
  "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
描述: 获取文件上传凭证
认证: 需要

请求参数

{
  "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

响应示例

{
  "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
描述: 确认文件上传完成
认证: 需要

请求参数

{
  "file_url": "https://cdn.niumall.com/contracts/20241225/contract_12345.pdf",
  "file_name": "contract.pdf",
  "file_size": 2048576,
  "upload_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

响应示例

{
  "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	否	通知类型筛选

响应示例

{
  "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
描述: 标记通知为已读
认证: 需要

响应示例

{
  "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
描述: 批量标记通知为已读
认证: 需要

请求参数

{
  "notification_ids": [10001, 10002, 10003]
}

响应示例

{
  "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	否	是否公开配置

响应示例

{
  "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	否	结束日期

响应示例

{
  "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示例

// 初始化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示例

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 环境切换配置

// 环境配置示例
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
环境配置: Niumall API Environment

13.5 API测试工具

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

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

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

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

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

37 KiB Raw Blame History Unescape Escape

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

版本历史

1. API概览

1.1 基础信息

1.2 认证方式

JWT Token认证

认证流程

1.3 通用响应格式

成功响应

错误响应

1.4 状态码说明

2. 用户认证模块

2.1 用户注册

接口信息

请求参数

参数说明

响应示例

2.2 用户登录

接口信息

请求参数

响应示例

2.3 刷新Token

接口信息

请求参数

响应示例

2.4 发送验证码

接口信息

请求参数

参数说明

响应示例

3. 用户管理模块

3.1 获取用户信息

接口信息

响应示例

3.2 更新用户信息

接口信息

请求参数

响应示例

3.3 修改密码

接口信息

请求参数

响应示例

4. 订单管理模块

4.1 创建订单

接口信息

请求参数

参数说明

响应示例

4.2 获取订单列表

接口信息

查询参数

响应示例

4.3 获取订单详情

接口信息

路径参数

响应示例

4.4 更新订单状态

接口信息

请求参数

响应示例

4.5 取消订单

接口信息

请求参数

响应示例

5. 运输管理模块

5.1 创建运输任务

接口信息

请求参数

响应示例

5.2 获取运输任务列表

接口信息

查询参数

响应示例

5.3 获取运输任务详情

接口信息

响应示例

5.4 更新位置信息

接口信息

请求参数

37 KiB

Raw Blame History