接口定义.md 129 KB
叁强鲜配 - 接口定义文档
目录
- 接口规范说明
- 用户模块
- 地址模块
- 区域模块
- 商品模块
- 询价报价模块
- 价格模块
- 购物车模块
- 订单模块
- 支付模块
- 配送模块
- 结算模块
- 发票管理模块
- 数据统计模块
- 日志模块
- 消息通知模块
- 附件模块
- 系统设置模块
- 公共模块
对接补充清单（2026-03-26，已收口）
本章节用于记录“文档 -> 代码”分步对齐的收口结果。
当前结论：web-admin/src/api 与 miniprogram/src/api 已完成与后端路由的 1:1 对齐（静态路径核对通过）。
A. Web 端已调用但文档缺失/不完整
| 方法 | 路径 | 用途 | 现状 |
|---|---|---|---|
| GET | /api/attachment/list |
附件分页查询 | 后端已实现 |
| GET | /api/attachment/business-types |
查询业务类型枚举 | 后端已实现 |
| GET | /api/message/list |
消息列表 | 后端已实现 |
| GET | /api/message/unread-count |
未读消息数 | 后端已实现 |
| POST | /api/message/send |
发送消息 | 后端已实现 |
| POST | /api/message/mark-all-read |
全部标记已读 | 后端已实现 |
| GET | /api/delivery-warning/statistics |
配送预警统计 | 后端已实现 |
| GET | /api/delivery-warning/list |
配送预警列表 | 后端已实现 |
| POST | /api/delivery-warning/handle/{warningId} |
处理配送预警 | 后端已实现（参数名后端为 {warning_id}） |
| GET | /api/invoice/list |
发票列表 | 已对齐（后端已统一为 /api/invoice/list） |
| POST | /api/invoice/create |
创建发票 | 已对齐（后端已统一为 /api/invoice/create） |
| GET | /api/system-config/list |
系统配置列表 | 后端已实现 |
| POST | /api/system-config/create |
新建系统配置 | 后端已实现 |
| POST | /api/system-config/update/{configId} |
更新系统配置 | 已对齐（前端路径拼接已修正） |
| POST | /api/system-config/batch-status |
批量启停配置项 | 已对齐（后端已兼容 JSON body） |
| GET | /api/web/admin/quotation-compare |
报价对比数据 | 已对齐（本轮新增后端接口） |
B. 小程序端已调用但文档缺失/不完整
| 方法 | 路径 | 用途 | 现状 |
|---|---|---|---|
| GET | /api/mini/client/price-list/current |
获取当前生效价目表 | 后端已实现 |
| GET | /api/mini/client/settlements |
结算列表 | 后端已实现 |
| GET | /api/mini/client/settlements/statistics |
结算统计 | 后端已实现 |
| GET | /api/mini/client/refunds |
退款列表 | 后端已实现 |
| GET | /api/mini/client/refunds/statistics |
退款统计 | 后端已实现 |
| GET | /api/mini/supplier/tasks |
供应商配送任务列表 | 后端已实现 |
| GET | /api/mini/deliverer/snatch/pending |
可抢单任务 | 后端已实现 |
| GET | /api/mini/deliverer/snatch/my |
我的抢单记录 | 后端已实现 |
| GET | /api/mini/deliverer/snatch/statistics |
抢单统计 | 后端已实现 |
| POST | /api/order-adjust/create |
订单调整申请/创建 | 后端已实现 |
| POST | /api/payment/wechat/create |
微信支付下单 | 后端已实现 |
| GET | /api/payment/config |
支付配置查询 | 后端已实现 |
| POST | /api/upload/base64 |
Base64 上传 | 后端已实现 |
| DELETE | /api/upload/file |
删除文件 | 后端已实现 |
| GET | /api/upload/info |
文件信息查询 | 后端已实现 |
| GET | /api/mini/client/profile |
小程序客户资料查询 | 已对齐（替代旧 /api/mini/user/profile） |
| PUT | /api/mini/client/profile |
小程序客户资料更新 | 已对齐（替代旧 /api/mini/user/profile） |
C. 后端已实现但需要补录到正文章节（按模块）
- 附件模块：
/api/attachment/* - 消息模块：
/api/message/* - 配送预警模块：
/api/delivery-warning/* - 订单调整模块：
/api/order-adjust/* - 支付模块：
/api/payment/* - 上传模块：
/api/upload/* - 系统配置模块：
/api/system-config/* - 小程序补充模块：
/api/mini/client/refunds*、/api/mini/client/settlements*、/api/mini/supplier/tasks*、/api/mini/deliverer/snatch*
D. 本轮已处理项（代码侧）
Web 登录前缀重复风险
- 已处理：公共路由前缀已调整，避免
/api/api/web/...重复前缀问题。
- 已处理：公共路由前缀已调整，避免
小程序用户资料路径
- 已处理：前端已统一使用
/api/mini/client/profile，替代历史/api/mini/user/profile。
- 已处理：前端已统一使用
报价对比接口缺口
- 已处理：后端新增
GET /api/web/admin/quotation-compare，并与 Web 端调用对齐。
- 已处理：后端新增
系统配置批量状态更新参数口径
- 已处理：后端
POST /api/system-config/batch-status已支持 JSON body（ids,is_active）。
- 已处理：后端
配送预警详情及处理参数口径
- 已处理：后端补充
GET /api/delivery-warning/detail/{warning_id}； - 已处理：
POST /api/delivery-warning/handle/{warning_id}已兼容 body/query 两种传参。
- 已处理：后端补充
E. 当前状态结论
- Web 端：
web-admin/src/api已完成 1:1 路径对齐（静态校验无缺口）。 - 小程序端：
miniprogram/src/api已完成 1:1 路径对齐（静态校验无缺口）。 - 文档建议：后续可将本清单中的补充条目逐步并入各正式章节，减少重复维护。
接口规范说明
基础信息
| 项目 | 说明 |
|---|---|
| 基础URL | https://api.sanqiang.com |
| Web端前缀 | /api/web |
| 小程序端前缀 | /api/mini |
| 数据格式 | JSON |
| 字符编码 | UTF-8 |
通用响应格式
{
"code": 200,
"message": "success",
"data": { },
"timestamp": 1700000000000
}
错误码定义
| 错误码 | HTTP状态码 | 说明 |
|---|---|---|
| 200 | 200 | 成功 |
| 400 | 400 | 请求参数错误 |
| 401 | 401 | 未授权/Token过期 |
| 403 | 403 | 无权限访问 |
| 404 | 404 | 资源不存在 |
| 409 | 409 | 资源冲突（如订单已被锁定） |
| 500 | 500 | 服务器内部错误 |
认证方式
- 使用 Bearer Token 方式进行身份认证
- 登录成功后返回
token和refreshToken - 请求头添加：
Authorization: Bearer <token> - Token有效期：2小时
- RefreshToken有效期：7天
分页参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| page | int | 否 | 1 | 页码 |
| pageSize | int | 否 | 10 | 每页条数 |
排序参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| orderBy | string | 否 | create_at | 排序字段 |
| orderType | string | 否 | desc | 排序方向：asc/desc |
金额单位
- API传输单位：分（整数）
- 前端展示单位：元（除以100，保留2位小数）
时间格式
- 请求/响应：ISO 8601 格式
2026-03-19T10:30:00+08:00 - 数据库存储：DATETIME 类型
- 前端展示格式：
YYYY-MM-DD HH:mm:ss
用户模块
1. Web端登录
请求
POST /api/web/auth/login
Content-Type: application/json
{
"username": "admin",
"password": "admin123"
}
响应
{
"code": 200,
"message": "success",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 7200,
"userInfo": {
"id": "USER_001",
"username": "admin",
"realName": "系统管理员",
"phone": "13800000000",
"role": "admin",
"regionId": null,
"regionName": null,
"avatar": null
}
}
}
2. 小程序端登录
请求
POST /api/mini/auth/login
Content-Type: application/json
{
"username": "client001",
"password": "client123"
}
响应
{
"code": 200,
"message": "success",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 7200,
"userInfo": {
"id": "USER_010",
"username": "client001",
"realName": "王小明",
"phone": "13800138002",
"role": "client",
"regionId": "REGION_001",
"regionName": "城东区域",
"avatar": null
}
}
}
3. 刷新Token
请求
POST /api/web/auth/refresh-token
Content-Type: application/json
{
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
4. 登出
请求
POST /api/web/auth/logout
Authorization: Bearer <token>
请求（小程序端）
POST /api/mini/auth/logout
Authorization: Bearer <token>
5. 获取当前用户信息
请求（Web端）
GET /api/web/auth/current-user
Authorization: Bearer <token>
请求（小程序端）
GET /api/mini/auth/current-user
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"id": "USER_001",
"username": "admin",
"realName": "系统管理员",
"phone": "13800000000",
"role": "admin",
"regionId": null,
"regionName": null,
"isActive": true,
"createAt": "2026-01-15T10:23:45+08:00"
}
}
6. 修改密码（自主修改）
请求
POST /api/web/user/change-password
Authorization: Bearer <token>
Content-Type: application/json
{
"oldPassword": "old123",
"newPassword": "new123"
}
请求（小程序端）
POST /api/mini/user/change-password
Authorization: Bearer <token>
Content-Type: application/json
{
"oldPassword": "old123",
"newPassword": "new123"
}
7. 重置密码（运营操作）
请求
POST /api/web/user/reset-password/{userId}
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"newPassword": "随机生成的密码"
}
}
8. 获取用户列表（Web端）
请求
GET /api/web/users?page=1&pageSize=10&role=supplier®ionId=REGION_001&keyword=张&isActive=true
Authorization: Bearer <token>
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| page | int | 否 | 页码，默认1 |
| pageSize | int | 否 | 每页条数，默认10 |
| role | string | 否 | 角色筛选：admin/supplier/client/deliver |
| regionId | string | 否 | 区域ID |
| keyword | string | 否 | 关键词搜索（用户名/姓名/手机号） |
| isActive | boolean | 否 | 是否激活 |
响应
{
"code": 200,
"data": {
"list": [
{
"id": "USER_010",
"username": "supplier001",
"realName": "张伟",
"phone": "13800138001",
"role": "supplier",
"regionId": "REGION_001",
"regionName": "城东区域",
"isActive": true,
"createAt": "2026-01-15T10:23:45+08:00"
}
],
"total": 86,
"page": 1,
"pageSize": 10,
"totalPages": 9
}
}
9. 创建用户（Web端）
请求
POST /api/web/users
Authorization: Bearer <token>
Content-Type: application/json
{
"username": "client001",
"realName": "李娜",
"phone": "13800138002",
"role": "client",
"regionId": "REGION_001"
}
响应
{
"code": 200,
"data": {
"id": "USER_xxx",
"username": "client001",
"realName": "李娜",
"initialPassword": "随机生成的初始密码"
}
}
10. 更新用户（Web端）
请求
PUT /api/web/users/{userId}
Authorization: Bearer <token>
Content-Type: application/json
{
"realName": "李娜",
"phone": "13800138002",
"regionId": "REGION_001",
"isActive": true
}
11. 删除用户（软删除，Web端）
请求
DELETE /api/web/users/{userId}
Authorization: Bearer <token>
12. 小程序端更新个人基础信息
请求
PUT /api/mini/user/profile
Authorization: Bearer <token>
Content-Type: application/json
{
"realName": "王小明",
"phone": "13800138002"
}
13. 小程序端获取供应商/客户详情
请求（供应商）
GET /api/mini/supplier/profile
Authorization: Bearer <token>
请求（客户）
GET /api/mini/client/profile
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"id": "USER_010",
"username": "supplier001",
"realName": "张伟",
"phone": "13800138001",
"role": "supplier",
"regionId": "REGION_001",
"regionName": "城东区域",
"address": {
"contactPerson": "张伟",
"contactPhone": "13800138001",
"province": "广东省",
"city": "深圳市",
"district": "南山区",
"detailAddress": "科技园XX路XX号"
}
}
}
14. 小程序端更新供应商/客户基础信息
请求
PUT /api/mini/supplier/profile
Authorization: Bearer <token>
Content-Type: application/json
{
"realName": "张伟",
"phone": "13800138001",
"address": {
"contactPerson": "张伟",
"contactPhone": "13800138001",
"province": "广东省",
"city": "深圳市",
"district": "南山区",
"detailAddress": "科技园XX路XX号"
}
}
15. 获取配送员详情
请求
GET /api/mini/deliverer/profile
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"id": "USER_050",
"username": "deliver001",
"realName": "李建",
"phone": "13900139001",
"role": "deliver",
"regionId": "REGION_001",
"regionName": "城东区域",
"rating": 4.9,
"totalDeliveries": 1256,
"todayDeliveries": 8
}
}
16. 小程序端更新配送员基础信息
请求
PUT /api/mini/deliverer/profile
Authorization: Bearer <token>
Content-Type: application/json
{
"realName": "李建",
"phone": "13900139001"
}
17. 小程序端验证码登录（获取手机号一键登录）
请求
POST /api/mini/auth/sms-login
Content-Type: application/json
{
"code": "微信授权code"
}
响应
{
"code": 200,
"message": "success",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 7200,
"isNewUser": false,
"userInfo": {
"id": "USER_010",
"username": "client001",
"realName": "王小明",
"phone": "13800138002",
"role": "client",
"regionId": "REGION_001",
"regionName": "城东区域"
}
}
}
18. 获取用户详情（Web端）
请求
GET /api/web/users/{userId}
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"id": "USER_010",
"username": "supplier001",
"realName": "张伟",
"phone": "13800138001",
"role": "supplier",
"regionId": "REGION_001",
"regionName": "城东区域",
"isActive": true,
"createAt": "2026-01-15T10:23:45+08:00",
"createBy": "SYS_ADMIN_001",
"createName": "系统管理员",
"updateAt": "2026-03-10T14:30:00+08:00"
}
}
19. Web端按区域获取供应商列表
请求
GET /api/web/suppliers?regionId=REGION_001&isActive=true&keyword=&page=1&pageSize=10
Authorization: Bearer <token>
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| regionId | string | 是 | 区域ID |
| isActive | boolean | 否 | 是否激活 |
| keyword | string | 否 | 关键词搜索 |
| page | int | 否 | 页码，默认1 |
| pageSize | int | 否 | 每页条数，默认10 |
响应
{
"code": 200,
"data": {
"list": [
{
"id": "USER_010",
"username": "supplier001",
"realName": "张伟",
"phone": "13800138001",
"regionId": "REGION_001",
"regionName": "城东区域",
"isActive": true,
"address": "福田区XX路XX号",
"createAt": "2026-01-15T10:23:45+08:00"
}
],
"total": 32,
"page": 1,
"pageSize": 10,
"totalPages": 4
}
}
20. Web端按区域获取客户列表
请求
GET /api/web/clients?regionId=REGION_001&isActive=true&keyword=&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "USER_020",
"username": "client001",
"realName": "王小明",
"phone": "13800138002",
"regionId": "REGION_001",
"regionName": "城东区域",
"isActive": true,
"createAt": "2026-01-15T10:23:45+08:00"
}
],
"total": 456,
"page": 1,
"pageSize": 10,
"totalPages": 46
}
}
21. Web端按区域获取配送员列表
请求
GET /api/web/deliverers?regionId=REGION_001&isActive=true&keyword=&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "USER_050",
"username": "deliver001",
"realName": "李建",
"phone": "13900139001",
"regionId": "REGION_001",
"regionName": "城东区域",
"isActive": true,
"totalDeliveries": 1256,
"rating": 4.9,
"createAt": "2026-01-15T10:23:45+08:00"
}
],
"total": 18,
"page": 1,
"pageSize": 10,
"totalPages": 2
}
}
地址模块
1. 获取地址列表（小程序端）
请求（客户）
GET /api/mini/client/addresses
Authorization: Bearer <token>
请求（供应商）
GET /api/mini/supplier/addresses
Authorization: Bearer <token>
响应
{
"code": 200,
"data": [
{
"id": "ADDR_001",
"userId": "USER_010",
"addressType": "delivery",
"contactPerson": "王小明",
"contactPhone": "13800138002",
"province": "广东省",
"city": "深圳市",
"district": "南山区",
"detailAddress": "科技园XX路XX号",
"isDefault": true
},
{
"id": "ADDR_002",
"userId": "USER_010",
"addressType": "pickup",
"contactPerson": "张伟",
"contactPhone": "13800138001",
"province": "广东省",
"city": "深圳市",
"district": "福田区",
"detailAddress": "华强北XX路XX号",
"isDefault": true
}
]
}
2. 获取地址详情（小程序端）
请求
GET /api/mini/client/addresses/{addressId}
Authorization: Bearer <token>
3. 创建地址（小程序端）
请求
POST /api/mini/client/addresses
Authorization: Bearer <token>
Content-Type: application/json
{
"addressType": "delivery",
"contactPerson": "王小明",
"contactPhone": "13800138002",
"province": "广东省",
"city": "深圳市",
"district": "南山区",
"detailAddress": "科技园XX路XX号",
"isDefault": true
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| addressType | string | 是 | 地址类型：pickup-取货地址/delivery-配送地址/both-两者皆是 |
| contactPerson | string | 是 | 联系人 |
| contactPhone | string | 是 | 联系电话 |
| province | string | 是 | 省份 |
| city | string | 是 | 城市 |
| district | string | 否 | 区县 |
| detailAddress | string | 是 | 详细地址 |
| isDefault | boolean | 否 | 是否默认地址 |
4. 更新地址（小程序端）
请求
PUT /api/mini/client/addresses/{addressId}
Authorization: Bearer <token>
Content-Type: application/json
{
"contactPerson": "王小明",
"contactPhone": "13800138002",
"province": "广东省",
"city": "深圳市",
"district": "南山区",
"detailAddress": "科技园XX路XX号",
"isDefault": false
}
5. 删除地址（小程序端）
请求
DELETE /api/mini/client/addresses/{addressId}
Authorization: Bearer <token>
6. 设置默认地址（小程序端）
请求
POST /api/mini/client/addresses/{addressId}/set-default
Authorization: Bearer <token>
7. 获取供应商取货地址列表（小程序端）
请求
GET /api/mini/supplier/pickup-addresses
Authorization: Bearer <token>
区域模块
1. 获取区域列表（Web端）
请求
GET /api/web/regions?isActive=true
Authorization: Bearer <token>
响应
{
"code": 200,
"data": [
{
"id": "REGION_001",
"name": "城东区域",
"code": "CD",
"description": "城东配送区域",
"sortOrder": 1,
"isActive": true,
"supplierCount": 32,
"clientCount": 456,
"deliverCount": 18
}
]
}
2. 创建区域（Web端）
请求
POST /api/web/regions
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "城北区域",
"code": "CB",
"description": "城北配送区域",
"sortOrder": 4
}
3. 更新区域（Web端）
请求
PUT /api/web/regions/{regionId}
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "城北区域",
"description": "城北配送区域",
"sortOrder": 4,
"isActive": true
}
4. 删除区域（Web端）
请求
DELETE /api/web/regions/{regionId}
Authorization: Bearer <token>
5. 获取区域详情（Web端）
请求
GET /api/web/regions/{regionId}
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"id": "REGION_001",
"name": "城东区域",
"code": "CD",
"description": "城东配送区域",
"sortOrder": 1,
"isActive": true,
"statistics": {
"supplierCount": 32,
"clientCount": 456,
"deliverCount": 18,
"todayOrderCount": 128,
"todayOrderAmount": 58200,
"activePriceVersion": "V3"
}
}
}
6. 获取当前用户区域信息（小程序端）
请求
GET /api/mini/common/my-region
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"id": "REGION_001",
"name": "城东区域",
"code": "CD"
}
}
商品模块
1. 获取商品分类列表
请求（Web端）
GET /api/web/product-categories?parentId=&isActive=true
Authorization: Bearer <token>
响应
{
"code": 200,
"data": [
{
"id": "CAT_001",
"name": "蔬菜",
"parentId": null,
"sortOrder": 1,
"isActive": true,
"children": [
{
"id": "CAT_001_1",
"name": "叶菜类",
"parentId": "CAT_001",
"sortOrder": 1,
"isActive": true
}
]
}
]
}
2. 创建商品分类
请求
POST /api/web/product-categories
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "水果",
"parentId": null,
"sortOrder": 2
}
3. 更新商品分类
请求
PUT /api/web/product-categories/{categoryId}
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "水果",
"parentId": null,
"sortOrder": 2,
"isActive": true
}
4. 删除商品分类
请求
DELETE /api/web/product-categories/{categoryId}
Authorization: Bearer <token>
5. 获取商品单位列表
请求（Web端）
GET /api/web/product-units?isActive=true
Authorization: Bearer <token>
响应
{
"code": 200,
"data": [
{ "id": "UNIT_001", "name": "斤", "code": "jin" },
{ "id": "UNIT_002", "name": "公斤", "code": "kg" },
{ "id": "UNIT_003", "name": "个", "code": "ge" },
{ "id": "UNIT_004", "name": "箱", "code": "xiang" },
{ "id": "UNIT_005", "name": "盒", "code": "he" },
{ "id": "UNIT_006", "name": "袋", "code": "dai" }
]
}
6. 创建商品单位
请求
POST /api/web/product-units
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "升",
"code": "L"
}
7. 更新商品单位
请求
PUT /api/web/product-units/{unitId}
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "升",
"code": "L",
"isActive": true
}
8. 删除商品单位
请求
DELETE /api/web/product-units/{unitId}
Authorization: Bearer <token>
9. 获取商品列表
请求（Web端）
GET /api/web/products?categoryId=CAT_001&keyword=猪肉&isActive=true&page=1&pageSize=20
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "PROD_001",
"name": "新鲜猪肉",
"categoryId": "CAT_003",
"categoryName": "肉类",
"unitId": "UNIT_001",
"unitName": "斤",
"description": "优质新鲜猪肉",
"imageUrl": "https://cdn.example.com/products/pork.jpg",
"isActive": true
}
],
"total": 100,
"page": 1,
"pageSize": 20,
"totalPages": 5
}
}
10. 创建商品
请求
POST /api/web/products
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "新鲜猪肉",
"categoryId": "CAT_003",
"unitId": "UNIT_001",
"description": "优质新鲜猪肉",
"imageUrl": "https://cdn.example.com/products/pork.jpg"
}
11. 更新商品
请求
PUT /api/web/products/{productId}
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "新鲜猪肉",
"categoryId": "CAT_003",
"unitId": "UNIT_001",
"description": "优质新鲜猪肉",
"imageUrl": "https://cdn.example.com/products/pork.jpg",
"isActive": true
}
12. 删除商品
请求
DELETE /api/web/products/{productId}
Authorization: Bearer <token>
13. 获取商品详情
请求
GET /api/web/products/{productId}
Authorization: Bearer <token>
14. 客户获取商品列表（小程序端）
请求
GET /api/mini/client/products?categoryId=CAT_001&keyword=&page=1&pageSize=20
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "PROD_001",
"name": "新鲜猪肉",
"categoryName": "肉类",
"unitName": "斤",
"price": 2500,
"imageUrl": "https://cdn.example.com/products/pork.jpg"
}
],
"total": 100,
"page": 1,
"pageSize": 20
}
}
15. 获取客户可购买的商品分类及商品（小程序端）
请求
GET /api/mini/client/product-categories
Authorization: Bearer <token>
响应
{
"code": 200,
"data": [
{
"id": "CAT_001",
"name": "蔬菜",
"products": [
{
"id": "PROD_001",
"name": "新鲜白菜",
"unitName": "斤",
"price": 320
}
]
}
]
}
询价报价模块
1. 获取询价单列表（Web端）
请求
GET /api/web/inquiries?regionId=REGION_001&status=published&keyword=&page=1&pageSize=10
Authorization: Bearer <token>
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| regionId | string | 否 | 区域ID |
| status | string | 否 | 状态：draft/published/closed |
| keyword | string | 否 | 关键词搜索 |
| page | int | 否 | 页码 |
| pageSize | int | 否 | 每页条数 |
响应
{
"code": 200,
"data": {
"list": [
{
"id": "INQ_001",
"title": "2026年3月第3周询价单",
"regionId": "REGION_001",
"regionName": "城东区域",
"status": "published",
"publishTime": "2026-03-17T10:00:00+08:00",
"closeTime": null,
"productCount": 8,
"supplierCount": 3,
"submittedCount": 2,
"remark": "备注信息"
}
],
"total": 50,
"page": 1,
"pageSize": 10
}
}
2. 创建询价单（Web端）
请求
POST /api/web/inquiries
Authorization: Bearer <token>
Content-Type: application/json
{
"title": "2026年3月第4周询价单",
"regionId": "REGION_001",
"productIds": ["PROD_001", "PROD_002", "PROD_003"],
"expireTime": "2026-03-24T18:00:00+08:00",
"remark": "备注信息"
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| title | string | 是 | 询价单标题 |
| regionId | string | 是 | 区域ID |
| productIds | array | 是 | 商品ID列表 |
| expireTime | datetime | 否 | 报价截止时间 |
| remark | string | 否 | 备注 |
3. 更新询价单（Web端）
请求
PUT /api/web/inquiries/{inquiryId}
Authorization: Bearer <token>
Content-Type: application/json
{
"title": "2026年3月第4周询价单",
"productIds": ["PROD_001", "PROD_002", "PROD_003", "PROD_004"],
"expireTime": "2026-03-24T18:00:00+08:00",
"remark": "备注信息"
}
4. 发布询价单（Web端）
请求
POST /api/web/inquiries/{inquiryId}/publish
Authorization: Bearer <token>
5. 关闭询价单（Web端）
请求
POST /api/web/inquiries/{inquiryId}/close
Authorization: Bearer <token>
6. 获取询价单详情（Web端）
请求
GET /api/web/inquiries/{inquiryId}
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"id": "INQ_001",
"title": "2026年3月第3周询价单",
"regionId": "REGION_001",
"regionName": "城东区域",
"status": "published",
"publishTime": "2026-03-17T10:00:00+08:00",
"closeTime": null,
"remark": "备注信息",
"products": [
{
"productId": "PROD_001",
"productName": "新鲜猪肉",
"categoryName": "肉类",
"unitName": "斤"
}
],
"supplierQuotations": [
{
"supplierId": "USER_010",
"supplierName": "张伟供应商",
"status": "approved",
"submittedTime": "2026-03-18T14:00:00+08:00"
}
]
}
}
7. 删除询价单（Web端）
请求
DELETE /api/web/inquiries/{inquiryId}
Authorization: Bearer <token>
8. 供应商获取询价单列表（小程序端）
请求
GET /api/mini/supplier/inquiries?status=published&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "INQ_001",
"title": "2026年3月第3周询价单",
"regionName": "城东区域",
"status": "published",
"publishTime": "2026-03-17T10:00:00+08:00",
"productCount": 8,
"isQuoted": false,
"expireTime": "2026-03-24T10:00:00+08:00",
"remainingHours": 168
}
],
"total": 5,
"page": 1,
"pageSize": 10
}
}
9. 供应商获取询价单详情（小程序端）
请求
GET /api/mini/supplier/inquiries/{inquiryId}
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"id": "INQ_001",
"title": "2026年3月第3周询价单",
"regionName": "城东区域",
"status": "published",
"publishTime": "2026-03-17T10:00:00+08:00",
"expireTime": "2026-03-24T10:00:00+08:00",
"remainingHours": 168,
"isQuoted": false,
"myQuotation": null,
"products": [
{
"productId": "PROD_001",
"productName": "新鲜猪肉",
"categoryName": "肉类",
"unitName": "斤"
}
]
}
}
10. 供应商提交报价（小程序端）
请求
POST /api/mini/supplier/quotations
Authorization: Bearer <token>
Content-Type: application/json
{
"inquiryId": "INQ_001",
"items": [
{ "productId": "PROD_001", "unitId": "UNIT_001", "price": 2500 },
{ "productId": "PROD_002", "unitId": "UNIT_001", "price": 800 }
],
"remark": "报价说明"
}
响应
{
"code": 200,
"data": {
"id": "QUO_001",
"inquiryId": "INQ_001",
"quotationNo": "QT20260319001",
"status": "pending",
"submitTime": "2026-03-19T14:30:00+08:00"
}
}
11. 供应商更新报价（小程序端）
请求
PUT /api/mini/supplier/quotations/{quotationId}
Authorization: Bearer <token>
Content-Type: application/json
{
"items": [
{ "productId": "PROD_001", "unitId": "UNIT_001", "price": 2600 },
{ "productId": "PROD_002", "unitId": "UNIT_001", "price": 850 }
],
"remark": "更新报价说明"
}
12. 供应商获取报价列表（小程序端）
请求
GET /api/mini/supplier/quotations?status=&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "QUO_001",
"quotationNo": "QT20260319001",
"inquiryTitle": "2026年3月第3周询价单",
"totalAmount": 34000,
"status": "pending",
"submitTime": "2026-03-19T14:30:00+08:00",
"reviewNote": null
}
],
"total": 5,
"page": 1,
"pageSize": 10
}
}
13. 供应商获取报价详情（小程序端）
请求
GET /api/mini/supplier/quotations/{quotationId}
Authorization: Bearer <token>
14. 运营获取报价列表（Web端）
请求
GET /api/web/quotations?inquiryId=INQ_001&supplierId=®ionId=REGION_001&status=&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "QUO_001",
"quotationNo": "QT20260319001",
"inquiryId": "INQ_001",
"inquiryTitle": "2026年3月第3周询价单",
"supplierId": "USER_010",
"supplierName": "张伟供应商",
"totalAmount": 34000,
"status": "approved",
"submitTime": "2026-03-19T14:30:00+08:00",
"reviewTime": "2026-03-19T16:00:00+08:00",
"reviewNote": "审核通过"
}
],
"total": 10,
"page": 1,
"pageSize": 10
}
}
15. 运营获取报价详情（Web端）
请求
GET /api/web/quotations/{quotationId}
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"id": "QUO_001",
"quotationNo": "QT20260319001",
"inquiryId": "INQ_001",
"inquiryTitle": "2026年3月第3周询价单",
"supplierId": "USER_010",
"supplierName": "张伟供应商",
"supplierPhone": "13800138001",
"totalAmount": 34000,
"status": "approved",
"submitTime": "2026-03-19T14:30:00+08:00",
"reviewTime": "2026-03-19T16:00:00+08:00",
"reviewNote": "审核通过",
"items": [
{
"id": "QI_001",
"productId": "PROD_001",
"productName": "新鲜猪肉",
"categoryName": "肉类",
"unitId": "UNIT_001",
"unitName": "斤",
"price": 2500
}
]
}
}
16. 运营比价查看（Web端）
请求
GET /api/web/inquiries/{inquiryId}/quotation-comparison
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"inquiryId": "INQ_001",
"inquiryTitle": "2026年3月第3周询价单",
"regionName": "城东区域",
"products": [
{
"productId": "PROD_001",
"productName": "新鲜猪肉",
"unitName": "斤",
"supplierPrices": [
{ "supplierId": "USER_010", "supplierName": "张伟供应商", "price": 2500 },
{ "supplierId": "USER_011", "supplierName": "李明供应商", "price": 2600 }
],
"lowestPrice": 2500,
"lowestSupplierId": "USER_010"
}
],
"suppliers": [
{ "supplierId": "USER_010", "supplierName": "张伟供应商", "totalAmount": 34000 },
{ "supplierId": "USER_011", "supplierName": "李明供应商", "totalAmount": 35600 }
]
}
}
17. 审核报价（Web端）
请求
POST /api/web/quotations/{quotationId}/review
Authorization: Bearer <token>
Content-Type: application/json
{
"status": "approved",
"reviewNote": "审核通过"
}
价格模块
1. 获取价格清单列表（Web端）
请求
GET /api/web/price-lists?regionId=REGION_001&status=active&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "PL_001",
"regionId": "REGION_001",
"regionName": "城东区域",
"supplierId": "USER_010",
"supplierName": "张伟供应商",
"version": 3,
"status": "active",
"effectiveTime": "2026-03-19T00:00:00+08:00",
"publishedTime": "2026-03-19T08:00:00+08:00",
"publishedBy": "系统管理员",
"productCount": 15
}
],
"total": 20,
"page": 1,
"pageSize": 10
}
}
2. 创建价格清单（Web端）
请求
POST /api/web/price-lists
Authorization: Bearer <token>
Content-Type: application/json
{
"regionId": "REGION_001",
"supplierId": "USER_010",
"effectiveTime": "2026-03-20T00:00:00+08:00",
"effectiveType": "immediate",
"expireTime": "2026-03-27T00:00:00+08:00",
"items": [
{ "productId": "PROD_001", "unitId": "UNIT_001", "price": 2500 },
{ "productId": "PROD_002", "unitId": "UNIT_001", "price": 800 }
],
"remark": "价格说明"
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| regionId | string | 是 | 区域ID |
| supplierId | string | 是 | 供应商ID（选定报价的供应商） |
| effectiveTime | datetime | 是 | 生效时间 |
| effectiveType | string | 是 | 生效方式：immediate-立即生效/scheduled-定时生效 |
| expireTime | datetime | 否 | 失效时间（为空表示长期有效） |
| items | array | 是 | 价格项列表 |
| remark | string | 否 | 备注 |
3. 获取价格清单详情（Web端）
请求
GET /api/web/price-lists/{priceListId}
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"id": "PL_001",
"regionId": "REGION_001",
"regionName": "城东区域",
"supplierId": "USER_010",
"supplierName": "张伟供应商",
"version": 3,
"status": "active",
"effectiveTime": "2026-03-19T00:00:00+08:00",
"publishedTime": "2026-03-19T08:00:00+08:00",
"publishedBy": "系统管理员",
"remark": "价格说明",
"items": [
{
"productId": "PROD_001",
"productName": "新鲜猪肉",
"categoryName": "肉类",
"unitId": "UNIT_001",
"unitName": "斤",
"price": 2500
}
]
}
}
4. 更新价格清单（Web端，只有草稿状态可编辑）**
请求
PUT /api/web/price-lists/{priceListId}
Authorization: Bearer <token>
Content-Type: application/json
{
"effectiveTime": "2026-03-20T00:00:00+08:00",
"effectiveType": "immediate",
"items": [
{ "productId": "PROD_001", "unitId": "UNIT_001", "price": 2600 }
],
"remark": "价格说明"
}
5. 发布价格清单（Web端）
请求
POST /api/web/price-lists/{priceListId}/publish
Authorization: Bearer <token>
6. 设为失效（Web端）
请求
POST /api/web/price-lists/{priceListId}/inactive
Authorization: Bearer <token>
7. 删除价格清单（Web端，只有草稿状态可删除）**
请求
DELETE /api/web/price-lists/{priceListId}
Authorization: Bearer <token>
8. 获取区域价格版本历史（Web端）
请求
GET /api/web/price-lists/history?regionId=REGION_001
Authorization: Bearer <token>
响应
{
"code": 200,
"data": [
{
"id": "PL_003",
"version": 3,
"status": "active",
"effectiveTime": "2026-03-19T00:00:00+08:00",
"publishedTime": "2026-03-19T08:00:00+08:00",
"publishedBy": "系统管理员",
"supplierName": "张伟供应商",
"productCount": 15
},
{
"id": "PL_002",
"version": 2,
"status": "inactive",
"effectiveTime": "2026-03-12T00:00:00+08:00",
"publishedTime": "2026-03-12T08:00:00+08:00",
"publishedBy": "系统管理员",
"supplierName": "李明供应商",
"productCount": 12
}
]
}
9. 对比价格版本差异（Web端）
请求
GET /api/web/price-lists/compare?priceListId1=PL_002&priceListId2=PL_003
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"priceList1": {
"id": "PL_002",
"version": 2
},
"priceList2": {
"id": "PL_003",
"version": 3
},
"products": [
{
"productId": "PROD_001",
"productName": "新鲜猪肉",
"price1": 2400,
"price2": 2500,
"change": 100,
"changePercent": 4.17
}
]
}
}
10. 客户获取当前生效价格（小程序端）
请求
GET /api/mini/client/price-list
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"id": "PL_001",
"regionId": "REGION_001",
"regionName": "城东区域",
"version": 3,
"status": "active",
"effectiveTime": "2026-03-19T00:00:00+08:00",
"productCount": 15,
"items": [
{
"productId": "PROD_001",
"productName": "新鲜猪肉",
"categoryName": "肉类",
"unitName": "斤",
"price": 2500
}
]
}
}
11. 客户获取价格清单商品列表（小程序端）
请求
GET /api/mini/client/price-list/products?categoryId=&keyword=&page=1&pageSize=20
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"productId": "PROD_001",
"productName": "新鲜猪肉",
"categoryId": "CAT_003",
"categoryName": "肉类",
"unitName": "斤",
"price": 2500,
"imageUrl": "https://cdn.example.com/products/pork.jpg"
}
],
"total": 100,
"page": 1,
"pageSize": 20
}
}
12. 供应商获取价格版本列表（小程序端）
请求
GET /api/mini/supplier/price-lists
Authorization: Bearer <token>
响应
{
"code": 200,
"data": [
{
"id": "PL_001",
"version": 3,
"status": "active",
"effectiveTime": "2026-03-19T00:00:00+08:00",
"publishedTime": "2026-03-19T08:00:00+08:00",
"productCount": 15,
"isMine": true
}
]
}
13. 供应商获取价格清单详情（小程序端）
请求
GET /api/mini/supplier/price-lists/{priceListId}
Authorization: Bearer <token>
14. 按商品维度查询价格历史（Web端）
请求
GET /api/web/price-lists/product-history?regionId=REGION_001&productId=PROD_001
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"productId": "PROD_001",
"productName": "新鲜猪肉",
"unitName": "斤",
"currentPrice": 2500,
"history": [
{
"id": "PL_003",
"version": 3,
"price": 2500,
"effectiveTime": "2026-03-19T00:00:00+08:00",
"publishedTime": "2026-03-19T08:00:00+08:00",
"supplierName": "张伟供应商",
"publishedBy": "系统管理员"
},
{
"id": "PL_002",
"version": 2,
"price": 2400,
"effectiveTime": "2026-03-12T00:00:00+08:00",
"publishedTime": "2026-03-12T08:00:00+08:00",
"supplierName": "李明供应商",
"publishedBy": "系统管理员"
},
{
"id": "PL_001",
"version": 1,
"price": 2200,
"effectiveTime": "2026-03-05T00:00:00+08:00",
"publishedTime": "2026-03-05T08:00:00+08:00",
"supplierName": "张伟供应商",
"publishedBy": "系统管理员"
}
]
}
}
购物车模块
1. 获取购物车列表（小程序端）
请求
GET /api/mini/client/cart
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "CART_001",
"productId": "PROD_001",
"productName": "新鲜猪肉",
"categoryName": "肉类",
"unitName": "斤",
"price": 2500,
"quantity": 10,
"amount": 25000,
"imageUrl": "https://cdn.example.com/products/pork.jpg"
}
],
"totalAmount": 25000,
"totalCount": 1
}
}
2. 添加商品到购物车（小程序端）
请求
POST /api/mini/client/cart
Authorization: Bearer <token>
Content-Type: application/json
{
"productId": "PROD_001",
"quantity": 10
}
3. 更新购物车商品数量（小程序端）
请求
PUT /api/mini/client/cart/{cartId}
Authorization: Bearer <token>
Content-Type: application/json
{
"quantity": 15
}
4. 删除购物车商品（小程序端）
请求
DELETE /api/mini/client/cart/{cartId}
Authorization: Bearer <token>
5. 清空购物车（小程序端）
请求
DELETE /api/mini/client/cart
Authorization: Bearer <token>
6. 批量删除购物车商品（小程序端）
请求
DELETE /api/mini/client/cart/batch
Authorization: Bearer <token>
Content-Type: application/json
{
"cartIds": ["CART_001", "CART_002"]
}
订单模块
0.5. 客户订单预览（小程序端）
请求
POST /api/mini/client/orders/preview
Authorization: Bearer <token>
Content-Type: application/json
{
"priceListId": "PL_001",
"items": [
{ "productId": "PROD_001", "quantity": 10 },
{ "productId": "PROD_002", "quantity": 20 }
],
"addressId": "ADDR_001"
}
响应
{
"code": 200,
"data": {
"priceListId": "PL_001",
"priceVersion": 3,
"items": [
{
"productId": "PROD_001",
"productName": "新鲜猪肉",
"unitName": "斤",
"unitPrice": 2500,
"quantity": 10,
"amount": 25000
},
{
"productId": "PROD_002",
"productName": "新鲜白菜",
"unitName": "斤",
"unitPrice": 800,
"quantity": 20,
"amount": 16000
}
],
"totalAmount": 41000,
"address": {
"contactPerson": "王小明",
"contactPhone": "13800138002",
"deliveryAddress": "广东省深圳市南山区科技园XX路XX号"
}
}
}
1. 客户创建订单（小程序端）
请求
POST /api/mini/client/orders
Authorization: Bearer <token>
Content-Type: application/json
{
"priceListId": "PL_001",
"items": [
{ "productId": "PROD_001", "unitId": "UNIT_001", "quantity": 10, "unitPrice": 2500 },
{ "productId": "PROD_002", "unitId": "UNIT_001", "quantity": 20, "unitPrice": 800 }
],
"addressId": "ADDR_001",
"paymentMethod": "wechat",
"remark": "订单备注"
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| priceListId | string | 是 | 价格清单ID |
| items | array | 是 | 订单商品列表 |
| addressId | string | 是 | 配送地址ID |
| paymentMethod | string | 是 | 支付方式：wechat/offline |
| remark | string | 否 | 订单备注 |
响应
{
"code": 200,
"data": {
"orderId": "ORDER_001",
"orderNo": "ORD20260319001",
"totalAmount": 41000,
"status": "pending_payment"
}
}
2. 客户从购物车创建订单（小程序端）
请求
POST /api/mini/client/orders/from-cart
Authorization: Bearer <token>
Content-Type: application/json
{
"priceListId": "PL_001",
"cartIds": ["CART_001", "CART_002"],
"addressId": "ADDR_001",
"paymentMethod": "wechat",
"remark": "订单备注"
}
3. 客户获取订单列表（小程序端）
请求
GET /api/mini/client/orders?status=&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "ORDER_001",
"orderNo": "ORD20260319001",
"totalAmount": 41000,
"paidAmount": 0,
"status": "pending_payment",
"paymentMethod": "wechat",
"itemCount": 2,
"createAt": "2026-03-19T10:23:45+08:00"
}
],
"total": 50,
"page": 1,
"pageSize": 10
}
}
4. 客户获取订单详情（小程序端）
请求
GET /api/mini/client/orders/{orderId}
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"id": "ORDER_001",
"orderNo": "ORD20260319001",
"regionId": "REGION_001",
"regionName": "城东区域",
"priceListId": "PL_001",
"priceVersion": 3,
"status": "pending_payment",
"paymentMethod": "wechat",
"totalAmount": 41000,
"paidAmount": 0,
"receivableAmount": 41000,
"refundAmount": 0,
"contactPerson": "王小明",
"contactPhone": "13800138002",
"deliveryAddress": "广东省深圳市南山区科技园XX路XX号",
"remark": "订单备注",
"createAt": "2026-03-19T10:23:45+08:00",
"paymentTime": null,
"items": [
{
"id": "ITEM_001",
"productId": "PROD_001",
"productName": "新鲜猪肉",
"unitName": "斤",
"quantity": 10,
"unitPrice": 2500,
"amount": 25000,
"deliveredQuantity": 0,
"status": "normal"
}
],
"statusLogs": [
{
"status": "pending_payment",
"statusText": "待支付",
"operatorName": "王小明",
"operatorRole": "client",
"createAt": "2026-03-19T10:23:45+08:00",
"reason": null
}
]
}
}
5. 客户发起取消申请（小程序端）
请求
POST /api/mini/client/orders/{orderId}/cancel
Authorization: Bearer <token>
Content-Type: application/json
{
"reason": "不需要了"
}
6. 客户确认收货（小程序端）
请求
POST /api/mini/client/orders/{orderId}/confirm-receive
Authorization: Bearer <token>
6.5. 客户直接取消未支付订单（小程序端）
请求
POST /api/mini/client/orders/{orderId}/direct-cancel
Authorization: Bearer <token>
Content-Type: application/json
{
"reason": "不想要了"
}
说明
- 适用于待支付状态的订单
- 未支付订单取消无需运营审核
- 直接将订单状态改为已取消
7. 运营获取订单列表（Web端）
请求
GET /api/web/orders?regionId=REGION_001&status=pending_delivery&clientId=&orderNo=&startDate=&endDate=&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "ORDER_001",
"orderNo": "ORD20260319001",
"clientId": "USER_010",
"clientName": "王小明",
"regionName": "城东区域",
"totalAmount": 41000,
"paidAmount": 41000,
"receivableAmount": 41000,
"status": "pending_delivery",
"paymentMethod": "wechat",
"paymentStatus": "paid",
"itemCount": 2,
"createAt": "2026-03-19T10:23:45+08:00",
"paymentTime": "2026-03-19T10:25:00+08:00"
}
],
"total": 100,
"page": 1,
"pageSize": 10
}
}
8. 运营获取订单详情（Web端）
请求
GET /api/web/orders/{orderId}
Authorization: Bearer <token>
9. 运营审核取消申请（Web端）
请求
POST /api/web/orders/{orderId}/review-cancel
Authorization: Bearer <token>
Content-Type: application/json
{
"approved": true,
"reviewNote": "同意取消"
}
9.5. 客户查看配送进度（小程序端）
请求
GET /api/mini/client/orders/{orderId}/delivery-progress
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"orderId": "ORDER_001",
"orderNo": "ORD20260319001",
"status": "delivering",
"statusText": "配送中",
"deliverer": {
"id": "USER_050",
"realName": "李建",
"phone": "13900139001"
},
"deliveryTask": {
"id": "DLV_001",
"taskNo": "DLV20260319001",
"status": "delivering",
"statusText": "配送中",
"pickupTime": "2026-03-19T11:00:00+08:00",
"deliveryTime": null,
"pickupImages": ["https://cdn.example.com/pickup/001.jpg"],
"deliveryImages": []
},
"deliveryProgress": [
{
"step": "order_created",
"title": "订单已创建",
"time": "2026-03-19T10:23:45+08:00",
"completed": true
},
{
"step": "payment_success",
"title": "支付成功",
"time": "2026-03-19T10:25:00+08:00",
"completed": true
},
{
"step": "delivery_assigned",
"title": "已分配配送员",
"time": "2026-03-19T10:30:00+08:00",
"completed": true
},
{
"step": "picked_up",
"title": "已取货",
"time": "2026-03-19T11:00:00+08:00",
"completed": true
},
{
"step": "delivering",
"title": "配送中",
"time": "2026-03-19T11:05:00+08:00",
"completed": false
},
{
"step": "delivered",
"title": "已送达",
"time": null,
"completed": false
}
],
"items": [
{
"productName": "新鲜猪肉",
"unitName": "斤",
"quantity": 10,
"deliveredQuantity": 6
}
]
}
}
9.6. 运营调整订单时获取可替代商品列表（Web端）
请求
GET /api/web/products/substitutes?categoryId=CAT_003&keyword=&page=1&pageSize=20
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"productId": "PROD_001",
"productName": "新鲜猪肉",
"categoryName": "肉类",
"unitName": "斤",
"price": 2500,
"stock": 100
},
{
"productId": "PROD_002",
"productName": "新鲜牛肉",
"categoryName": "肉类",
"unitName": "斤",
"price": 4500,
"stock": 50
}
],
"total": 10,
"page": 1,
"pageSize": 20
}
}
10. 运营分配配送（Web端）
请求
POST /api/web/orders/{orderId}/assign-delivery
Authorization: Bearer <token>
Content-Type: application/json
{
"deliverId": "USER_050"
}
11. 运营调整订单（Web端）**
请求
POST /api/web/orders/{orderId}/adjust
Authorization: Bearer <token>
Content-Type: application/json
{
"items": [
{ "orderItemId": "ITEM_001", "quantity": 8, "note": "缺货" },
{ "orderItemId": "ITEM_002", "status": "deleted", "note": "无货取消" }
],
"reason": "部分缺货",
"refundAmount": 3400
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| items | array | 是 | 调整的订单项 |
| items[].orderItemId | string | 是 | 订单项ID |
| items[].quantity | number | 否 | 调整后的数量 |
| items[].status | string | 否 | 状态：normal/reduced/deleted/substituted |
| items[].note | string | 否 | 调整备注 |
| reason | string | 是 | 调整原因 |
| refundAmount | number | 否 | 退款金额（分） |
12. 运营强制完结订单（Web端）**
请求
POST /api/web/orders/{orderId}/force-complete
Authorization: Bearer <token>
Content-Type: application/json
{
"reason": "客户长期未确认，系统自动完结"
}
13. 运营获取订单状态变更日志（Web端）**
请求
GET /api/web/orders/{orderId}/status-logs
Authorization: Bearer <token>
响应
{
"code": 200,
"data": [
{
"id": "LOG_001",
"fromStatus": null,
"fromStatusText": null,
"toStatus": "pending_payment",
"toStatusText": "待支付",
"operatorId": "USER_010",
"operatorName": "王小明",
"operatorRole": "client",
"reason": null,
"note": null,
"createAt": "2026-03-19T10:23:45+08:00"
},
{
"id": "LOG_002",
"fromStatus": "pending_payment",
"fromStatusText": "待支付",
"toStatus": "pending_delivery",
"toStatusText": "待分配配送",
"operatorId": "USER_010",
"operatorName": "王小明",
"operatorRole": "client",
"reason": "支付成功",
"note": "微信支付成功",
"createAt": "2026-03-19T10:25:00+08:00"
}
]
}
14. 运营获取订单调整记录（Web端）**
请求
GET /api/web/orders/{orderId}/adjustments
Authorization: Bearer <token>
响应
{
"code": 200,
"data": [
{
"id": "ADJ_001",
"orderItemId": "ITEM_001",
"productName": "新鲜猪肉",
"adjustType": "reduce",
"beforeQuantity": 10,
"afterQuantity": 8,
"beforeAmount": 25000,
"afterAmount": 20000,
"differenceAmount": -5000,
"reason": "部分缺货",
"operatorName": "系统管理员",
"createAt": "2026-03-19T15:00:00+08:00"
}
]
}
15. 订单锁定（Web端）**
请求
POST /api/web/orders/{orderId}/lock
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"locked": true,
"lockOperatorId": "USER_001",
"lockOperatorName": "系统管理员",
"lockTime": "2026-03-19T15:00:00+08:00"
}
}
16. 订单解锁（Web端）**
请求
POST /api/web/orders/{orderId}/unlock
Authorization: Bearer <token>
17. 强制解锁订单（Web端）**
请求
POST /api/web/orders/{orderId}/force-unlock
Authorization: Bearer <token>
18. 导出待结算订单（Web端）**
请求
GET /api/web/orders/export/pending-settlement?regionId=REGION_001&startDate=&endDate=
Authorization: Bearer <token>
响应
返回Excel文件下载
19. 导出线下结算订单（Web端）**
请求
GET /api/web/orders/export/offline-settlement?regionId=REGION_001&clientId=&startDate=&endDate=
Authorization: Bearer <token>
响应
返回Excel文件下载
支付模块
0.5. 微信退款接口（Web端）
请求
POST /api/web/refunds/wechat-refund/{orderId}
Authorization: Bearer <token>
Content-Type: application/json
{
"refundAmount": 5000,
"reason": "部分缺货退款"
}
响应
{
"code": 200,
"data": {
"refundId": "REFUND_001",
"refundNo": "RF20260319001",
"refundAmount": 5000,
"refundResult": "processing",
"refundTime": "2026-03-19T15:00:00+08:00"
}
}
说明
- 仅支持已支付订单退款
- 退款金额不能超过已支付金额
- 微信退款为异步操作，结果需通过回调或主动查询获取
0.6. 查询微信退款状态（Web端）
请求
GET /api/web/refunds/{refundId}/status
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"refundId": "REFUND_001",
"refundNo": "RF20260319001",
"refundAmount": 5000,
"refundResult": "success",
"refundTime": "2026-03-19T15:00:00+08:00",
"refundNoWechat": "微信退款单号"
}
}
1. 发起微信支付（小程序端）
请求
POST /api/mini/client/orders/{orderId}/wechat-pay
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"orderId": "ORDER_001",
"orderNo": "ORD20260319001",
"wechatPayParams": {
"appId": "wx1234567890",
"timeStamp": "1710822225",
"nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS",
"package": "prepay_id=wx201410272009395522657a690389285100",
"signType": "MD5",
"paySign": "C380BEC2BFD727A4B6845133519F3AD6"
}
}
}
2. 微信支付结果回调通知
请求
POST /api/web/pay/wechat-notify
Content-Type: application/xml
<xml>
<return_code><![CDATA[SUCCESS]]></return_code>
<return_msg><![CDATA[OK]]></return_msg>
<result_code><![CDATA[SUCCESS]]></result_code>
<transaction_id><![CDATA[4208450740201411110007820472]]></transaction_id>
<out_trade_no><![CDATA[ORD20260319001]]></out_trade_no>
<trade_state><![CDATA[SUCCESS]]></trade_state>
<total_fee><![CDATA[41000]]></total_fee>
<cash_fee><![CDATA[41000]]></cash_fee>
<time_end><![CDATA[20260319102500]]></time_end>
</xml>
3. 查询微信支付状态
请求（小程序端）
GET /api/mini/client/orders/{orderId}/pay-status
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"orderId": "ORDER_001",
"orderNo": "ORD20260319001",
"paymentStatus": "paid",
"payTime": "2026-03-19T10:25:00+08:00",
"transactionId": "4208450740201411110007820472"
}
}
4. 获取支付记录列表（Web端）
请求
GET /api/web/pay/records?regionId=REGION_001&status=&startDate=&endDate=&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "PAY_001",
"orderId": "ORDER_001",
"orderNo": "ORD20260319001",
"clientName": "王小明",
"regionName": "城东区域",
"totalFee": 41000,
"cashFee": 41000,
"tradeState": "SUCCESS",
"transactionId": "4208450740201411110007820472",
"payTime": "2026-03-19T10:25:00+08:00"
}
],
"total": 100,
"page": 1,
"pageSize": 10
}
}
配送模块
1. 运营获取配送任务列表（Web端）
请求
GET /api/web/delivery-tasks?regionId=REGION_001&status=pending&orderNo=&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "DLV_001",
"taskNo": "DLV20260319001",
"orderId": "ORDER_001",
"orderNo": "ORD20260319001",
"regionName": "城东区域",
"supplierName": "张伟供应商",
"supplierAddress": "福田区XX路XX号",
"clientName": "王小明",
"clientAddress": "南山区XX路XX号",
"status": "pending",
"totalAmount": 41000,
"itemCount": 2,
"createAt": "2026-03-19T10:25:00+08:00",
"deliverName": null,
"expireTime": "2026-03-19T15:25:00+08:00",
"isExpiring": false
}
],
"total": 50,
"page": 1,
"pageSize": 10
}
}
2. 运营获取配送任务详情（Web端）
请求
GET /api/web/delivery-tasks/{taskId}
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"id": "DLV_001",
"taskNo": "DLV20260319001",
"orderId": "ORDER_001",
"orderNo": "ORD20260319001",
"regionId": "REGION_001",
"regionName": "城东区域",
"supplierId": "USER_010",
"supplierName": "张伟供应商",
"supplierPhone": "13800138001",
"supplierAddress": "福田区XX路XX号",
"deliverId": "USER_050",
"deliverName": "李建",
"deliverPhone": "13900139001",
"status": "picking",
"totalAmount": 41000,
"createAt": "2026-03-19T10:25:00+08:00",
"assignTime": "2026-03-19T10:30:00+08:00",
"pickupTime": "2026-03-19T11:00:00+08:00",
"pickupRemark": "货物完好",
"pickupImages": ["https://cdn.example.com/pickup/001.jpg"],
"deliveryTime": null,
"deliveryRemark": null,
"deliveryImages": [],
"items": [
{
"id": "DLV_ITEM_001",
"productName": "新鲜猪肉",
"unitName": "斤",
"quantity": 10,
"deliveredQuantity": 0,
"clientName": "王小明",
"clientPhone": "13800138002",
"clientAddress": "南山区XX路XX号",
"status": "picking"
}
]
}
}
3. 运营分配配送任务（Web端）
请求
POST /api/web/delivery-tasks/assign
Authorization: Bearer <token>
Content-Type: application/json
{
"orderId": "ORDER_001",
"deliverId": "USER_050"
}
4. 运营批量分配配送任务（Web端）
请求
POST /api/web/delivery-tasks/assign-batch
Authorization: Bearer <token>
Content-Type: application/json
{
"assignments": [
{ "orderId": "ORDER_001", "deliverId": "USER_050" },
{ "orderId": "ORDER_002", "deliverId": "USER_050" }
]
}
5. 运营获取配送时效预警列表（Web端）
请求
GET /api/web/delivery-tasks/warnings?regionId=REGION_001&withinMinutes=60
Authorization: Bearer <token>
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| regionId | string | 否 | 区域ID（不传则查所有区域） |
| withinMinutes | int | 否 | 多少分钟内即将过期，默认60 |
| page | int | 否 | 页码，默认1 |
| pageSize | int | 否 | 每页条数，默认10 |
响应
{
"code": 200,
"data": {
"list": [
{
"id": "DLV_001",
"taskNo": "DLV20260319001",
"orderNo": "ORD20260319001",
"regionId": "REGION_001",
"regionName": "城东区域",
"clientName": "王小明",
"deliverName": "李建",
"status": "pending",
"expireTime": "2026-03-19T11:30:00+08:00",
"remainingMinutes": 25,
"isOverdue": false,
"warningLevel": "warning"
}
],
"total": 15,
"warningCount": 3,
"page": 1,
"pageSize": 10
}
}
| warningLevel | 说明 |
|---|---|
| normal | 正常 |
| warning | 预警（30分钟内） |
| urgent | 紧急（15分钟内） |
| overdue | 已过期 |
6. 运营取消配送任务（Web端）
请求
POST /api/web/delivery-tasks/{taskId}/cancel
Authorization: Bearer <token>
Content-Type: application/json
{
"reason": "客户要求取消"
}
响应
{
"code": 200,
"data": {
"id": "DLV_001",
"status": "cancelled",
"cancelTime": "2026-03-19T14:00:00+08:00"
}
}
6.5. 小程序端查看配送凭证附件（小程序端）
请求
GET /api/mini/delivery-tasks/{taskId}/attachments
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"pickupAttachments": [
{
"id": "ATT_001",
"fileName": "取货照片1.jpg",
"fileUrl": "https://cdn.example.com/pickup/001.jpg",
"uploadTime": "2026-03-19T11:00:00+08:00",
"uploadBy": "李建"
}
],
"deliveryAttachments": [
{
"id": "ATT_002",
"fileName": "送达照片1.jpg",
"fileUrl": "https://cdn.example.com/delivery/001.jpg",
"uploadTime": "2026-03-19T12:00:00+08:00",
"uploadBy": "李建"
}
]
}
}
7. 运营重新分配配送任务（Web端）
请求
POST /api/web/delivery-tasks/{taskId}/reassign
Authorization: Bearer <token>
Content-Type: application/json
{
"deliverId": "USER_051"
}
8. 配送员获取待取货任务（小程序端）
请求
GET /api/mini/deliverer/tasks?status=pending&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "DLV_001",
"taskNo": "DLV20260319001",
"supplierName": "张伟供应商",
"supplierPhone": "13800138001",
"supplierAddress": "福田区XX路XX号",
"clientCount": 1,
"itemCount": 2,
"totalAmount": 41000,
"status": "pending",
"createTime": "2026-03-19T10:30:00+08:00",
"pickupDeadline": "2026-03-19T14:00:00+08:00",
"remainingMinutes": 180
}
],
"total": 5,
"page": 1,
"pageSize": 10
}
}
9. 配送员获取配送中任务（小程序端）
请求
GET /api/mini/deliverer/tasks?status=delivering&page=1&pageSize=10
Authorization: Bearer <token>
10. 配送员获取已完成任务（小程序端）
请求
GET /api/mini/deliverer/tasks?status=completed&page=1&pageSize=10
Authorization: Bearer <token>
11. 配送员获取任务详情（小程序端）
请求
GET /api/mini/deliverer/tasks/{taskId}
Authorization: Bearer <token>
12. 配送员确认取货（小程序端）
请求
POST /api/mini/deliverer/tasks/{taskId}/pickup
Authorization: Bearer <token>
Content-Type: application/json
{
"remark": "货物完好，数量正确",
"imageUrls": ["https://cdn.example.com/pickup/001.jpg", "https://cdn.example.com/pickup/002.jpg"]
}
13. 配送员确认送达（小程序端）
请求
POST /api/mini/deliverer/tasks/{taskId}/deliver
Authorization: Bearer <token>
Content-Type: application/json
{
"items": [
{ "taskItemId": "DLV_ITEM_001", "deliveredQuantity": 10 }
],
"remark": "客户已签收",
"imageUrls": ["https://cdn.example.com/deliver/001.jpg"]
}
14. 配送员获取任务统计（小程序端）
请求
GET /api/mini/deliverer/tasks/statistics
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"todayPending": 2,
"todayDelivering": 3,
"todayCompleted": 8,
"weekCompleted": 45,
"monthCompleted": 180,
"rating": 4.9
}
}
15. 供应商获取取货任务列表（小程序端）
请求
GET /api/mini/supplier/pickup-tasks?status=&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "DLV_001",
"taskNo": "DLV20260319001",
"orderNo": "ORD20260319001",
"deliverName": "李建",
"deliverPhone": "13900139001",
"status": "picking",
"itemCount": 2,
"createTime": "2026-03-19T10:30:00+08:00",
"pickupDeadline": "2026-03-19T14:00:00+08:00"
}
],
"total": 10,
"page": 1,
"pageSize": 10
}
}
16. 供应商获取取货任务详情（小程序端）
请求
GET /api/mini/supplier/pickup-tasks/{taskId}
Authorization: Bearer <token>
17.5. 供应商获取本区域供应商信息（小程序端）
请求
GET /api/mini/common/suppliers
Authorization: Bearer <token>
响应
{
"code": 200,
"data": [
{
"id": "USER_010",
"supplierName": "张伟供应商",
"contactPerson": "张伟",
"contactPhone": "13800138001",
"address": "福田区XX路XX号"
}
]
}
说明
- 返回当前用户所属区域的所有供应商信息
- 配送员可用此接口查询供应商地址
18. 供应商确认取货（小程序端）**
POST /api/mini/supplier/pickup-tasks/{taskId}/confirm Authorization: Bearer Content-Type: application/json
{ "remark": "货物已交接", "imageUrls": ["https://cdn.example.com/handover/001.jpg"] }
---
### 18. 配送员获取时效预警（小程序端）
**请求**
```http
GET /api/mini/deliverer/tasks/warnings
Authorization: Bearer <token>
响应
{
"code": 200,
"data": [
{
"id": "DLV_001",
"taskNo": "DLV20260319001",
"remainingMinutes": 15,
"clientName": "王小明",
"clientAddress": "南山区XX路XX号"
}
]
}
19.5. 配送员申请取消任务（小程序端）
请求
POST /api/mini/deliverer/tasks/{taskId}/cancel
Authorization: Bearer <token>
Content-Type: application/json
{
"reason": "客户联系不上，需改期配送",
"images": ["https://cdn.example.com/cancel/001.jpg"]
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| reason | string | 是 | 取消原因 |
| images | array | 否 | 相关图片凭证 |
响应
{
"code": 200,
"data": {
"taskId": "DLV_001",
"status": "cancelled",
"cancelTime": "2026-03-19T14:00:00+08:00",
"cancelReason": "客户联系不上，需改期配送"
}
}
19.6. 配送员换班交接（小程序端）
请求
POST /api/mini/deliverer/handover
Authorization: Bearer <token>
Content-Type: application/json
{
"handoverType": "shift_out",
"targetDeliverId": "USER_051",
"remark": "下班交接",
"taskIds": ["DLV_001", "DLV_002"]
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| handoverType | string | 是 | 交接类型：shift_out-交班/shift_in-接班 |
| targetDeliverId | string | 否 | 接班人ID（交班时必填） |
| remark | string | 否 | 交接备注 |
| taskIds | array | 是 | 交接的任务ID列表 |
响应
{
"code": 200,
"data": {
"handoverNo": "HO20260319001",
"handoverType": "shift_out",
"handoverTime": "2026-03-19T18:00:00+08:00",
"taskCount": 2,
"targetDeliver": {
"id": "USER_051",
"realName": "王强",
"phone": "13900139002"
}
}
}
结算模块
1. 运营获取线下结算订单列表（Web端）
请求
GET /api/web/settlements?regionId=REGION_001&clientId=&status=pending&startDate=&endDate=&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "SETTLE_001",
"orderId": "ORDER_001",
"orderNo": "ORD20260319001",
"clientId": "USER_010",
"clientName": "王小明",
"regionName": "城东区域",
"amount": 41000,
"paymentMethod": "offline",
"status": "pending",
"orderCreateTime": "2026-03-19T10:23:45+08:00"
}
],
"total": 50,
"page": 1,
"pageSize": 10
}
}
2. 运营获取客户待结算汇总（Web端）
请求
GET /api/web/settlements/client-summary?regionId=REGION_001&clientId=&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"clientId": "USER_010",
"clientName": "王小明",
"regionName": "城东区域",
"pendingCount": 5,
"pendingAmount": 156000,
"lastOrderTime": "2026-03-19T10:23:45+08:00"
}
],
"total": 20,
"page": 1,
"pageSize": 10
}
}
3. 运营确认线下结算（Web端）
请求
POST /api/web/settlements
Authorization: Bearer <token>
Content-Type: application/json
{
"orderId": "ORDER_001",
"settlementMethod": "transfer",
"settlementTime": "2026-03-19T15:00:00+08:00",
"settlementNote": "银行转账",
"attachmentUrl": "https://cdn.example.com/settlements/xxx.jpg"
}
4. 运营批量确认线下结算（Web端）
请求
POST /api/web/settlements/batch
Authorization: Bearer <token>
Content-Type: application/json
{
"orderIds": ["ORDER_001", "ORDER_002"],
"settlementMethod": "transfer",
"settlementTime": "2026-03-19T15:00:00+08:00",
"settlementNote": "银行转账批量结算",
"attachmentUrl": "https://cdn.example.com/settlements/batch_xxx.jpg"
}
5. 运营获取结算记录列表（Web端）
请求
GET /api/web/settlements/records?regionId=REGION_001&clientId=&startDate=&endDate=&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "SETTLE_REC_001",
"orderId": "ORDER_001",
"orderNo": "ORD20260319001",
"clientName": "王小明",
"amount": 41000,
"settlementMethod": "transfer",
"settlementTime": "2026-03-19T15:00:00+08:00",
"settlementNote": "银行转账",
"reviewedBy": "系统管理员",
"reviewedTime": "2026-03-19T15:05:00+08:00",
"attachmentUrl": "https://cdn.example.com/settlements/xxx.jpg"
}
],
"total": 100,
"page": 1,
"pageSize": 10
}
}
6. 运营获取退款记录列表（Web端）
请求
GET /api/web/refunds?status=pending®ionId=&orderNo=&startDate=&endDate=&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "REFUND_001",
"refundNo": "RF20260319001",
"orderId": "ORDER_001",
"orderNo": "ORD20260319001",
"clientName": "王小明",
"regionName": "城东区域",
"refundAmount": 5000,
"refundMethod": "wechat",
"refundResult": "success",
"status": "success",
"refundTime": "2026-03-19T15:00:00+08:00",
"createAt": "2026-03-19T14:00:00+08:00"
}
],
"total": 50,
"page": 1,
"pageSize": 10
}
}
7. 运营获取退款详情（Web端）
请求
GET /api/web/refunds/{refundId}
Authorization: Bearer <token>
8. 运营处理退款（Web端）**
请求
POST /api/web/refunds/{refundId}/process
Authorization: Bearer <token>
Content-Type: application/json
{
"refundMethod": "wechat",
"refundNoWechat": "微信退款单号",
"note": "人工处理成功"
}
9. 运营处理退款失败（Web端）**
请求
POST /api/web/refunds/{refundId}/handle-failure
Authorization: Bearer <token>
Content-Type: application/json
{
"failReason": "微信退款失败，账户余额不足",
"note": "需人工跟进处理"
}
10. 运营获取结算统计（Web端）
请求
GET /api/web/settlements/statistics?regionId=REGION_001&startDate=&endDate=
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"today": {
"onlineIncome": 5862000,
"offlinePending": 8642000,
"offlineCompleted": 25680000,
"refundAmount": 120000,
"orderCount": 1286
},
"week": {
"onlineIncome": 25680000,
"offlinePending": 35680000,
"offlineCompleted": 156800000,
"refundAmount": 856000,
"orderCount": 8560
},
"month": {
"onlineIncome": 125680000,
"offlinePending": 35680000,
"offlineCompleted": 568900000,
"refundAmount": 2580000,
"orderCount": 25860
}
}
}
11. 运营获取区域结算统计（Web端）
请求
GET /api/web/settlements/region-statistics?startDate=&endDate=
Authorization: Bearer <token>
响应
{
"code": 200,
"data": [
{
"regionId": "REGION_001",
"regionName": "城东区域",
"onlineIncome": 56890000,
"offlinePending": 15680000,
"offlineCompleted": 286900000,
"refundAmount": 1280000,
"orderCount": 12860,
"settlementRate": 95.2
},
{
"regionId": "REGION_002",
"regionName": "城西区域",
"onlineIncome": 35680000,
"offlinePending": 12800000,
"offlineCompleted": 156800000,
"refundAmount": 856000,
"orderCount": 8560,
"settlementRate": 92.4
}
]
}
发票管理模块
1. 获取发票列表（Web端）
请求
GET /api/web/invoices?invoiceNo=&clientId=&status=&startDate=&endDate=&page=1&pageSize=10
Authorization: Bearer <token>
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| invoiceNo | string | 否 | 发票号 |
| clientId | string | 否 | 客户ID |
| status | string | 否 | 状态：pending-待开票/issued-已开票/cancelled-已作废 |
| startDate | string | 否 | 开始日期 |
| endDate | string | 否 | 结束日期 |
| page | int | 否 | 页码，默认1 |
| pageSize | int | 否 | 每页条数，默认10 |
响应
{
"code": 200,
"data": {
"list": [
{
"id": "INV_001",
"invoiceNo": "INV20260319001",
"clientId": "USER_010",
"clientName": "AA餐厅",
"orderId": "ORDER_001",
"orderNo": "ORD202603150023",
"amount": 358000,
"taxRate": "6%",
"taxAmount": 21480,
"totalAmount": 379480,
"status": "issued",
"statusText": "已开票",
"issueDate": "2026-03-19",
"cancelledTime": null,
"cancelReason": null
}
],
"total": 50,
"page": 1,
"pageSize": 10,
"totalPages": 5
}
}
2. 获取发票详情（Web端）
请求
GET /api/web/invoices/{invoiceId}
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"id": "INV_001",
"invoiceNo": "INV20260319001",
"clientId": "USER_010",
"clientName": "AA餐厅",
"clientTaxNo": "91440300XXXXXXXXX",
"clientAddress": "深圳市南山区XX路XX号",
"clientPhone": "13800138000",
"bankName": "中国银行深圳分行",
"bankAccount": "621785XXXXXXXXXXXX",
"orderId": "ORDER_001",
"orderNo": "ORD202603150023",
"amount": 358000,
"taxRate": "6%",
"taxAmount": 21480,
"totalAmount": 379480,
"status": "issued",
"statusText": "已开票",
"invoiceDate": "2026-03-19",
"issuedBy": "系统管理员",
"issuedTime": "2026-03-19T10:00:00+08:00",
"cancelledTime": null,
"cancelReason": null,
"cancelledBy": null,
"remark": "增值税普通发票"
}
}
3. 开具发票（Web端）
请求
POST /api/web/invoices
Authorization: Bearer <token>
Content-Type: application/json
{
"clientId": "USER_010",
"orderId": "ORDER_001",
"clientTaxNo": "91440300XXXXXXXXX",
"clientAddress": "深圳市南山区XX路XX号",
"clientPhone": "13800138000",
"bankName": "中国银行深圳分行",
"bankAccount": "621785XXXXXXXXXXXX",
"amount": 358000,
"taxRate": "6",
"remark": "增值税普通发票"
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| clientId | string | 是 | 客户ID |
| orderId | string | 是 | 订单ID |
| clientTaxNo | string | 否 | 客户税号 |
| clientAddress | string | 否 | 开票地址 |
| clientPhone | string | 否 | 联系电话 |
| bankName | string | 否 | 开户银行 |
| bankAccount | string | 否 | 银行账号 |
| amount | number | 是 | 开票金额（分） |
| taxRate | string | 否 | 税率，默认6% |
| remark | string | 否 | 备注 |
响应
{
"code": 200,
"data": {
"id": "INV_001",
"invoiceNo": "INV20260319001",
"status": "issued"
}
}
4. 作废发票（Web端）
请求
POST /api/web/invoices/{invoiceId}/cancel
Authorization: Bearer <token>
Content-Type: application/json
{
"cancelReason": "客户要求作废"
}
5. 下载发票（Web端）
请求
GET /api/web/invoices/{invoiceId}/download
Authorization: Bearer <token>
响应
返回PDF文件下载
6. 获取客户已开票金额汇总（Web端）
请求
GET /api/web/invoices/client-summary?clientId=USER_010
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"clientId": "USER_010",
"clientName": "AA餐厅",
"totalInvoicedAmount": 1256000,
"pendingInvoiceAmount": 358000,
"issuedInvoiceAmount": 898000,
"cancelledInvoiceAmount": 0
}
}
7. 客户申请开票（小程序端）
请求
POST /api/mini/client/invoices
Authorization: Bearer <token>
Content-Type: application/json
{
"orderId": "ORDER_001",
"clientTaxNo": "91440300XXXXXXXXX",
"clientAddress": "深圳市南山区XX路XX号",
"clientPhone": "13800138000",
"bankName": "中国银行深圳分行",
"bankAccount": "621785XXXXXXXXXXXX",
"invoiceType": "ordinary"
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| orderId | string | 是 | 订单ID |
| clientTaxNo | string | 否 | 客户税号 |
| clientAddress | string | 否 | 开票地址 |
| clientPhone | string | 否 | 联系电话 |
| bankName | string | 否 | 开户银行 |
| bankAccount | string | 否 | 银行账号 |
| invoiceType | string | 否 | 发票类型：ordinary-普通发票/vat-增值税专用发票 |
响应
{
"code": 200,
"data": {
"id": "INV_001",
"invoiceNo": "INV20260319001",
"status": "pending"
}
}
8. 客户获取发票列表（小程序端）
请求
GET /api/mini/client/invoices?status=&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "INV_001",
"invoiceNo": "INV20260319001",
"orderId": "ORDER_001",
"orderNo": "ORD202603150023",
"amount": 358000,
"status": "issued",
"statusText": "已开票",
"issueDate": "2026-03-19"
}
],
"total": 5,
"page": 1,
"pageSize": 10
}
}
9. 客户获取发票详情（小程序端）
请求
GET /api/mini/client/invoices/{invoiceId}
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"id": "INV_001",
"invoiceNo": "INV20260319001",
"orderId": "ORDER_001",
"orderNo": "ORD202603150023",
"amount": 358000,
"taxRate": "6%",
"taxAmount": 21480,
"totalAmount": 379480,
"status": "issued",
"statusText": "已开票",
"invoiceDate": "2026-03-19"
}
}
数据统计模块
1. 运营获取工作台统计数据（Web端）
请求
GET /api/web/dashboard/statistics
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"today": {
"orderCount": 1286,
"orderAmount": 5862000,
"orderCountChange": 12.5,
"orderAmountChange": 8.3
},
"pendingDelivery": 156,
"pendingDeliveryChange": -5.2,
"exceptionOrder": 12,
"exceptionOrderChange": -20,
"pendingRefund": 3,
"expiringDelivery": 3,
"userStatistics": {
"supplierCount": 32,
"clientCount": 456,
"deliverCount": 18,
"todayNewSuppliers": 2,
"todayNewClients": 15,
"todayNewDelivers": 1
},
"recentOrders": [
{
"orderNo": "ORD20260319001",
"clientName": "王小明",
"totalAmount": 41000,
"status": "pending_delivery",
"createAt": "2026-03-19T10:23:45+08:00"
}
],
"pendingTasks": [
{
"type": "cancel_review",
"count": 2,
"description": "待审核取消"
},
{
"type": "delivery_assign",
"count": 15,
"description": "待分配配送"
},
{
"type": "delivery_warning",
"count": 3,
"description": "配送时效预警"
},
{
"type": "refund_pending",
"count": 3,
"description": "待处理退款"
}
]
}
}
1.5. 获取区域用户统计（Web端）
请求
GET /api/web/statistics/user-count?regionId=REGION_001
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"supplierCount": 32,
"clientCount": 456,
"deliverCount": 18,
"totalCount": 506,
"todayNewSuppliers": 2,
"todayNewClients": 15,
"todayNewDelivers": 1,
"weekNewSuppliers": 8,
"weekNewClients": 65,
"weekNewDelivers": 5,
"monthNewSuppliers": 25,
"monthNewClients": 256,
"monthNewDelivers": 18
}
}
2. 运营获取数据统计概览（Web端）
请求
GET /api/web/statistics/overview?startDate=&endDate=
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"today": {
"orderCount": 1286,
"orderAmount": 5862000,
"orderCountChange": 12.5,
"orderAmountChange": 8.3
},
"week": {
"orderCount": 8560,
"orderAmount": 38920000,
"orderCountChange": 5.2,
"orderAmountChange": 3.8
},
"month": {
"orderCount": 25860,
"orderAmount": 125680000,
"orderCountChange": 8.1,
"orderAmountChange": 6.5
}
}
}
3. 运营获取订单趋势数据（Web端）
请求
GET /api/web/statistics/order-trend?startDate=&endDate=®ionId=
Authorization: Bearer <token>
响应
{
"code": 200,
"data": [
{ "date": "2026-03-13", "orderCount": 1150, "orderAmount": 5280000 },
{ "date": "2026-03-14", "orderCount": 1230, "orderAmount": 5620000 },
{ "date": "2026-03-15", "orderCount": 1180, "orderAmount": 5420000 },
{ "date": "2026-03-16", "orderCount": 1256, "orderAmount": 5750000 },
{ "date": "2026-03-17", "orderCount": 1286, "orderAmount": 5862000 },
{ "date": "2026-03-18", "orderCount": 1320, "orderAmount": 6020000 },
{ "date": "2026-03-19", "orderCount": 1286, "orderAmount": 5862000 }
]
}
4. 运营获取区域订单排名（Web端）
请求
GET /api/web/statistics/region-ranking?startDate=&endDate=
Authorization: Bearer <token>
响应
{
"code": 200,
"data": [
{ "regionId": "REGION_001", "regionName": "城东区域", "orderCount": 856, "orderAmount": 3892000, "rank": 1 },
{ "regionId": "REGION_002", "regionName": "城西区域", "orderCount": 620, "orderAmount": 2860000, "rank": 2 },
{ "regionId": "REGION_003", "regionName": "城南区域", "orderCount": 480, "orderAmount": 2150000, "rank": 3 }
]
}
5. 运营获取商品销售排名（Web端）
请求
GET /api/web/statistics/product-ranking?startDate=&endDate=®ionId=&limit=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": [
{ "productId": "PROD_001", "productName": "新鲜猪肉", "categoryName": "肉类", "salesQuantity": 5680, "salesAmount": 14200000, "rank": 1 },
{ "productId": "PROD_002", "productName": "新鲜白菜", "categoryName": "蔬菜", "salesQuantity": 4560, "salesAmount": 1460000, "rank": 2 }
]
}
6. 运营获取客户消费排名（Web端）
请求
GET /api/web/statistics/client-ranking?startDate=&endDate=®ionId=&limit=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": [
{ "clientId": "USER_010", "clientName": "王小明", "regionName": "城东区域", "orderCount": 56, "totalAmount": 268000, "rank": 1 },
{ "clientId": "USER_011", "clientName": "李娜", "regionName": "城东区域", "orderCount": 45, "totalAmount": 215000, "rank": 2 }
]
}
7. 运营获取供应商报价统计（Web端）
请求
GET /api/web/statistics/supplier-quotation?regionId=&startDate=&endDate=&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"supplierId": "USER_010",
"supplierName": "张伟供应商",
"regionName": "城东区域",
"inquiryCount": 12,
"quoteCount": 10,
"selectedCount": 6,
"totalQuotationAmount": 4560000,
"winRate": 60.0
}
],
"total": 20,
"page": 1,
"pageSize": 10
}
}
8. 运营获取配送效率统计（Web端）
请求
GET /api/web/statistics/delivery-efficiency?regionId=&startDate=&endDate=
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"today": {
"avgDeliveryMinutes": 45,
"onTimeRate": 96.8,
"deliverCount": 28,
"completedCount": 1286
},
"week": {
"avgDeliveryMinutes": 42,
"onTimeRate": 97.2,
"deliverCount": 186,
"completedCount": 8560
},
"month": {
"avgDeliveryMinutes": 40,
"onTimeRate": 97.5,
"deliverCount": 856,
"completedCount": 25860
}
}
}
9. 运营获取收入统计（Web端）
请求
GET /api/web/statistics/income?regionId=&startDate=&endDate=
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"today": {
"onlineIncome": 3862000,
"offlineIncome": 2000000,
"pendingSettlement": 1245000,
"refundAmount": 128000,
"totalIncome": 5862000,
"onlineRatio": 66.0,
"offlineRatio": 34.0
},
"week": {
"onlineIncome": 25680000,
"offlineIncome": 13240000,
"pendingSettlement": 8642000,
"refundAmount": 856000,
"totalIncome": 38920000
},
"month": {
"onlineIncome": 125680000,
"offlineIncome": 56890000,
"pendingSettlement": 35680000,
"refundAmount": 2580000,
"totalIncome": 182570000
}
}
}
日志模块
1. 运营获取登录日志列表（Web端）
请求
GET /api/web/logs/login?username=&role=&loginResult=&startDate=&endDate=&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "LOGIN_001",
"userId": "USER_001",
"username": "admin",
"realName": "系统管理员",
"role": "admin",
"loginTime": "2026-03-19T10:00:00+08:00",
"logoutTime": "2026-03-19T18:30:00+08:00",
"ipAddress": "192.168.1.100",
"userAgent": "Mozilla/5.0...",
"loginResult": "success",
"failReason": null
}
],
"total": 100,
"page": 1,
"pageSize": 10
}
}
2. 运营获取操作日志列表（Web端）
请求
GET /api/web/logs/operation?module=&operation=&operatorId=&startDate=&endDate=&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "OP_001",
"module": "order",
"moduleText": "订单",
"operation": "adjust",
"operationText": "订单调整",
"targetId": "ORDER_001",
"targetType": "订单",
"operatorId": "USER_001",
"operatorName": "系统管理员",
"operatorRole": "admin",
"ipAddress": "192.168.1.100",
"requestMethod": "POST",
"requestUrl": "/api/web/orders/ORDER_001/adjust",
"createAt": "2026-03-19T15:00:00+08:00"
}
],
"total": 500,
"page": 1,
"pageSize": 10
}
}
3. 运营获取操作日志详情（Web端）
请求
GET /api/web/logs/operation/{logId}
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"id": "OP_001",
"module": "order",
"moduleText": "订单",
"operation": "adjust",
"operationText": "订单调整",
"targetId": "ORDER_001",
"targetType": "订单",
"operatorId": "USER_001",
"operatorName": "系统管理员",
"operatorRole": "admin",
"ipAddress": "192.168.1.100",
"requestMethod": "POST",
"requestUrl": "/api/web/orders/ORDER_001/adjust",
"requestParams": "{\"items\":[...],\"reason\":\"部分缺货\"}",
"responseResult": "{\"code\":200,\"message\":\"success\"}",
"createAt": "2026-03-19T15:00:00+08:00"
}
}
4. 获取审计日志列表（Web端）
请求
GET /api/web/audit-logs?module=order&operation=create&operatorId=&targetId=&startDate=&endDate=&page=1&pageSize=10
Authorization: Bearer <token>
消息通知模块
1. 运营获取消息列表（Web端）
请求
GET /api/web/messages?type=&isRead=&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "MSG_001",
"type": "delivery_warning",
"title": "配送时效预警",
"content": "您有3个配送单将在1小时内过期",
"isRead": false,
"createAt": "2026-03-19T10:00:00+08:00"
}
],
"total": 20,
"unreadCount": 5,
"page": 1,
"pageSize": 10
}
}
2. 运营标记消息已读（Web端）
请求
POST /api/web/messages/{messageId}/read
Authorization: Bearer <token>
3. 运营标记全部消息已读（Web端）
请求
POST /api/web/messages/read-all
Authorization: Bearer <token>
4. 运营获取未读消息数量（Web端）
请求
GET /api/web/messages/unread-count
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"total": 5,
"cancelReview": 1,
"deliveryWarning": 2,
"refundPending": 2
}
}
4.5. 运营发送消息通知（Web端）
请求
POST /api/web/messages/send
Authorization: Bearer <token>
Content-Type: application/json
{
"receiverType": "client",
"receiverIds": ["USER_010", "USER_011"],
"messageType": "settlement_reminder",
"title": "结算提醒",
"content": "您有3笔订单待线下结算，请尽快处理",
"relatedOrderIds": ["ORDER_001", "ORDER_002", "ORDER_003"]
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| receiverType | string | 是 | 接收者类型：all_client-全部客户/all_supplier-全部供应商/all_deliver-全部配送员/client-指定客户/supplier-指定供应商/deliver-指定配送员 |
| receiverIds | array | 否 | 指定接收者ID列表（receiverType为client/supplier/deliver时必填） |
| messageType | string | 是 | 消息类型：settlement_reminder-结算提醒/general_notice-系统通知 |
| title | string | 是 | 消息标题 |
| content | string | 是 | 消息内容 |
| relatedOrderIds | array | 否 | 关联订单ID列表 |
响应
{
"code": 200,
"data": {
"sentCount": 2,
"failedCount": 0
}
}
5. 运营删除消息（Web端）
请求
DELETE /api/web/messages/{messageId}
Authorization: Bearer <token>
6. 小程序端获取消息列表
请求
GET /api/mini/messages?type=&isRead=&page=1&pageSize=10
Authorization: Bearer <token>
7. 小程序端标记消息已读
请求
POST /api/mini/messages/{messageId}/read
Authorization: Bearer <token>
8. 小程序端获取未读消息数量
请求
GET /api/mini/messages/unread-count
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"total": 3,
"orderStatus": 1,
"deliveryStatus": 2
}
}
9. 小程序端删除消息
请求
DELETE /api/mini/messages/{messageId}
Authorization: Bearer <token>
10. 客户获取可开发票订单列表（小程序端）
请求
GET /api/mini/client/invoices/available-orders?page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"orderId": "ORDER_001",
"orderNo": "ORD202603150023",
"orderAmount": 358000,
"paidAmount": 358000,
"createTime": "2026-03-15T10:23:45+08:00",
"invoicedAmount": 0,
"invoiceableAmount": 358000
}
],
"total": 10,
"page": 1,
"pageSize": 10
}
}
11. 客户申请发票（小程序端）
请求
POST /api/mini/client/invoices
Authorization: Bearer <token>
Content-Type: application/json
{
"orderId": "ORDER_001",
"invoiceType": "ordinary",
"clientTaxNo": "91440300XXXXXXXXX",
"clientAddress": "深圳市南山区XX路XX号",
"clientPhone": "13800138000",
"bankName": "中国银行深圳分行",
"bankAccount": "621785XXXXXXXXXXXX"
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| orderId | string | 是 | 订单ID |
| invoiceType | string | 是 | 发票类型：ordinary-普通发票/vat-增值税专用发票 |
| clientTaxNo | string | 否 | 客户税号 |
| clientAddress | string | 否 | 开票地址 |
| clientPhone | string | 否 | 联系电话 |
| bankName | string | 否 | 开户银行 |
| bankAccount | string | 否 | 银行账号 |
响应
{
"code": 200,
"data": {
"id": "INV_001",
"invoiceNo": "INV20260319001",
"status": "pending"
}
}
12. 客户获取发票列表（小程序端）
请求
GET /api/mini/client/invoices?status=&page=1&pageSize=10
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"list": [
{
"id": "INV_001",
"invoiceNo": "INV20260319001",
"orderId": "ORDER_001",
"orderNo": "ORD202603150023",
"amount": 358000,
"status": "issued",
"statusText": "已开票",
"issueDate": "2026-03-19"
}
],
"total": 5,
"page": 1,
"pageSize": 10
}
}
13. 客户获取发票详情（小程序端）
请求
GET /api/mini/client/invoices/{invoiceId}
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"id": "INV_001",
"invoiceNo": "INV20260319001",
"orderId": "ORDER_001",
"orderNo": "ORD202603150023",
"clientTaxNo": "91440300XXXXXXXXX",
"clientAddress": "深圳市南山区XX路XX号",
"clientPhone": "13800138000",
"bankName": "中国银行深圳分行",
"bankAccount": "621785XXXXXXXXXXXX",
"amount": 358000,
"taxRate": "6%",
"taxAmount": 21480,
"totalAmount": 379480,
"status": "issued",
"statusText": "已开票",
"invoiceDate": "2026-03-19",
"issuedBy": "系统管理员"
}
}
14. 客户获取已开票金额汇总（小程序端）
请求
GET /api/mini/client/invoices/summary
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"totalInvoicedAmount": 1256000,
"pendingInvoiceAmount": 358000,
"issuedInvoiceAmount": 898000
}
}
15. 配送员获取时效预警列表（小程序端）
请求
GET /api/mini/deliverer/tasks/expiring?withinMinutes=60
Authorization: Bearer <token>
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| withinMinutes | int | 否 | 多少分钟内即将过期，默认60 |
响应
{
"code": 200,
"data": {
"list": [
{
"id": "DLV_001",
"taskNo": "DLV20260319001",
"orderNo": "ORD20260319001",
"clientName": "王小明",
"clientPhone": "13800138002",
"clientAddress": "南山区XX路XX号",
"remainingMinutes": 25,
"warningLevel": "warning"
}
],
"total": 3
}
}
| warningLevel | 说明 |
|---|---|
| warning | 预警（30分钟内） |
| urgent | 紧急（15分钟内） |
| overdue | 已过期 |
16. 运营获取密码修改历史（Web端）
请求
GET /api/web/users/password-history?userId=&startDate=&endDate=&page=1&pageSize=10
Authorization: Bearer <token>
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userId | string | 否 | 用户ID |
| startDate | string | 否 | 开始日期 |
| endDate | string | 否 | 结束日期 |
| page | int | 否 | 页码，默认1 |
| pageSize | int | 否 | 每页条数，默认10 |
响应
{
"code": 200,
"data": {
"list": [
{
"id": "PWH_001",
"userId": "USER_010",
"username": "supplier001",
"realName": "张伟",
"operationType": "reset",
"operationTypeText": "重置",
"operatorId": "SYS_ADMIN_001",
"operatorName": "系统管理员",
"ipAddress": "192.168.1.100",
"createAt": "2026-03-19T10:00:00+08:00"
}
],
"total": 50,
"page": 1,
"pageSize": 10
}
}
17. 多文件上传（通用）
请求
POST /api/common/upload/multiple
Content-Type: multipart/form-data
Authorization: Bearer <token>
FormData: {
files: [File, File, ...],
businessType: "delivery_pickup",
businessId: "DLV_001"
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| files | File[] | 是 | 文件列表（最多10个） |
| businessType | string | 否 | 业务类型 |
| businessId | string | 否 | 业务ID |
响应
{
"code": 200,
"data": {
"list": [
{
"id": "ATT_001",
"fileName": "取货照片1.jpg",
"fileUrl": "https://cdn.sanqiang.com/uploads/xxx1.jpg",
"fileSize": 102400,
"fileType": "image/jpeg"
},
{
"id": "ATT_002",
"fileName": "取货照片2.jpg",
"fileUrl": "https://cdn.sanqiang.com/uploads/xxx2.jpg",
"fileSize": 98256,
"fileType": "image/jpeg"
}
],
"uploadedCount": 2,
"failedCount": 0
}
}
18. 运营获取配送员效率统计（Web端）
请求
GET /api/web/statistics/deliverer-efficiency?regionId=&delivererId=&startDate=&endDate=
Authorization: Bearer <token>
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| regionId | string | 否 | 区域ID |
| delivererId | string | 否 | 配送员ID |
| startDate | string | 否 | 开始日期 |
| endDate | string | 否 | 结束日期 |
响应
{
"code": 200,
"data": {
"list": [
{
"delivererId": "USER_050",
"delivererName": "李建",
"totalTasks": 128,
"completedTasks": 125,
"cancelledTasks": 3,
"avgDeliveryMinutes": 42,
"onTimeRate": 97.5,
"rating": 4.9,
"totalAmount": 5680000
}
],
"total": 18,
"page": 1,
"pageSize": 10
}
}
19. 配送员获取个人效率统计（小程序端）
请求
GET /api/mini/deliverer/statistics/efficiency
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"today": {
"completedCount": 8,
"avgDeliveryMinutes": 38,
"onTimeRate": 98.5
},
"week": {
"completedCount": 45,
"avgDeliveryMinutes": 40,
"onTimeRate": 97.8
},
"month": {
"completedCount": 180,
"avgDeliveryMinutes": 42,
"onTimeRate": 97.2
},
"rating": 4.9,
"totalCompleted": 1256,
"totalDistance": 1580
}
}
20. 运营创建数据字典（Web端）
请求
POST /api/web/dicts
Authorization: Bearer <token>
Content-Type: application/json
{
"type": "product_tag",
"items": [
{ "value": "hot", "label": "热销", "sortOrder": 1 },
{ "value": "new", "label": "新品", "sortOrder": 2 },
{ "value": "recommend", "label": "推荐", "sortOrder": 3 }
]
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| type | string | 是 | 字典类型 |
| items | array | 是 | 字典项列表 |
| items[].value | string | 是 | 字典值 |
| items[].label | string | 是 | 字典标签 |
| items[].sortOrder | int | 否 | 排序 |
响应
{
"code": 200,
"data": {
"type": "product_tag",
"createdCount": 3
}
}
21. 运营更新数据字典（Web端）
请求
PUT /api/web/dicts/{type}
Authorization: Bearer <token>
Content-Type: application/json
{
"items": [
{ "value": "hot", "label": "热销", "sortOrder": 1 },
{ "value": "new", "label": "新品上架", "sortOrder": 2 },
{ "value": "recommend", "label": "推荐", "sortOrder": 3 },
{ "value": "special", "label": "特价", "sortOrder": 4, "isActive": false }
]
}
响应
{
"code": 200,
"data": {
"type": "product_tag",
"updatedCount": 4
}
}
22. 运营删除数据字典项（Web端）
请求
DELETE /api/web/dicts/{type}/items/{value}
Authorization: Bearer <token>
响应
{
"code": 200,
"message": "删除成功"
}
附件模块
1. 获取附件列表（Web端）
请求
GET /api/web/attachments?businessType=&businessId=®ionId=&keyword=&startDate=&endDate=&page=1&pageSize=10
Authorization: Bearer <token>
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| businessType | string | 否 | 业务类型 |
| businessId | string | 否 | 业务ID |
| regionId | string | 否 | 区域ID |
| keyword | string | 否 | 文件名关键词搜索 |
| startDate | string | 否 | 开始日期 |
| endDate | string | 否 | 结束日期 |
| page | int | 否 | 页码，默认1 |
| pageSize | int | 否 | 每页条数，默认10 |
响应
{
"code": 200,
"data": {
"list": [
{
"id": "ATT_001",
"businessType": "delivery_pickup",
"businessTypeText": "取货凭证",
"businessId": "DLV_001",
"fileName": "取货照片1.jpg",
"fileUrl": "https://cdn.example.com/attachments/xxx.jpg",
"fileSize": 102400,
"fileType": "image/jpeg",
"uploadBy": "李建",
"createAt": "2026-03-19T11:00:00+08:00"
}
],
"total": 20,
"page": 1,
"pageSize": 10
}
}
2. 上传附件（Web端）
请求
POST /api/web/attachments
Content-Type: multipart/form-data
Authorization: Bearer <token>
FormData: {
file: File,
businessType: "delivery_pickup",
businessId: "DLV_001"
}
响应
{
"code": 200,
"data": {
"id": "ATT_001",
"fileName": "取货照片1.jpg",
"fileUrl": "https://cdn.example.com/attachments/xxx.jpg",
"fileSize": 102400,
"fileType": "image/jpeg"
}
}
3. 删除附件（Web端）
请求
DELETE /api/web/attachments/{attachmentId}
Authorization: Bearer <token>
4. 小程序端上传配送凭证
请求
POST /api/mini/deliverer/tasks/{taskId}/upload-proof
Content-Type: multipart/form-data
Authorization: Bearer <token>
FormData: {
file: File,
proofType: "pickup",
remark: "货物完好"
}
| proofType | 说明 |
|---|---|
| pickup | 取货凭证 |
| delivery | 送达凭证 |
系统设置模块
1. 获取系统配置（Web端）
请求
GET /api/web/system/config
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"deliveryExpireWarningMinutes": 60,
"orderAutoCompleteDays": 7,
"priceEffectiveType": "immediate",
"maxRefundDays": 30
}
}
2. 更新系统配置（Web端）
请求
PUT /api/web/system/config
Authorization: Bearer <token>
Content-Type: application/json
{
"deliveryExpireWarningMinutes": 60,
"orderAutoCompleteDays": 7,
"priceEffectiveType": "immediate",
"maxRefundDays": 30,
"systemName": "叁强鲜配",
"companyName": "叁强公司",
"contactPhone": "400-888-8888"
}
3. 获取安全设置（Web端）
请求
GET /api/web/system/security-config
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"passwordComplexity": "medium",
"passwordComplexityText": "中等",
"passwordExpireDays": 90,
"passwordExpireDaysText": "90天",
"sessionTimeoutMinutes": 30,
"sessionTimeoutText": "30分钟"
}
}
4. 更新安全设置（Web端）
请求
PUT /api/web/system/security-config
Authorization: Bearer <token>
Content-Type: application/json
{
"passwordComplexity": "complex",
"passwordExpireDays": 60,
"sessionTimeoutMinutes": 60
}
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| passwordComplexity | string | 否 | 密码复杂度：simple-简单/medium-中等/complex-复杂 |
| passwordExpireDays | int | 否 | 密码过期天数：30/60/90/0(永不过期) |
| sessionTimeoutMinutes | int | 否 | 会话超时时间(分钟)：15/30/60/120 |
5. 获取数据字典（Web端）
请求
GET /api/web/dicts?type=order_status
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"order_status": [
{ "value": "pending_payment", "label": "待支付" },
{ "value": "pending_delivery", "label": "待分配配送" },
{ "value": "delivering", "label": "配送中" },
{ "value": "completed", "label": "已完成" },
{ "value": "cancelled", "label": "已取消" }
]
}
}
6. 获取系统配置（小程序端）
请求
GET /api/mini/system/config
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"deliveryExpireWarningMinutes": 60,
"orderAutoCompleteDays": 7,
"systemName": "叁强鲜配",
"companyName": "叁强公司",
"contactPhone": "400-888-8888"
}
}
7. 获取数据字典（小程序端）
请求
GET /api/mini/dicts?type=order_status
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"order_status": [
{ "value": "pending_payment", "label": "待支付" },
{ "value": "pending_delivery", "label": "待分配配送" },
{ "value": "delivering", "label": "配送中" },
{ "value": "completed", "label": "已完成" },
{ "value": "cancelled", "label": "已取消" }
]
}
}
公共模块
1. 获取字典数据
请求
GET /api/common/dicts?type=order_status
Authorization: Bearer <token>
2. 文件上传
请求
POST /api/common/upload
Content-Type: multipart/form-data
Authorization: Bearer <token>
FormData: { file: File }
响应
{
"code": 200,
"data": {
"url": "https://cdn.sanqiang.com/uploads/xxx.jpg",
"fileName": "xxx.jpg",
"fileSize": 102400,
"fileType": "image/jpeg"
}
}
3. 获取当前用户区域信息（小程序端）
请求
GET /api/mini/common/my-region
Authorization: Bearer <token>
4. 获取附件列表（Web端）
请求
GET /api/web/attachments?businessType=delivery_pickup&businessId=ORDER_001
Authorization: Bearer <token>
5. 获取审计日志（Web端）
请求
GET /api/web/audit-logs?module=order&operation=create&page=1
Authorization: Bearer <token>
6. 获取区域统计（Web端）
请求
GET /api/web/regions/statistics?regionId=REGION_001
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"todayOrderCount": 128,
"todayOrderAmount": 5862000,
"weekOrderCount": 856,
"weekOrderAmount": 38920000,
"monthOrderCount": 2560,
"monthOrderAmount": 125680000,
"supplierCount": 32,
"clientCount": 456,
"deliverCount": 18,
"activePriceVersion": "V3"
}
}
21. 客户催单（小程序端）
请求
POST /api/mini/client/orders/{orderId}/urge
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"orderId": "ORDER_001",
"urgeCount": 2,
"lastUrgeTime": "2026-03-19T14:30:00+08:00",
"message": "催单成功，配送员将尽快处理"
}
}
说明
- 每个订单每天最多催单3次
- 催单后发送消息通知运营和配送员
22. 运营获取可替代商品列表（Web端）
请求
GET /api/web/products/substitutes?orderItemId=ITEM_001&categoryId=&keyword=&page=1&pageSize=20
Authorization: Bearer <token>
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| orderItemId | string | 是 | 原订单项ID |
| categoryId | string | 否 | 商品分类ID |
| keyword | string | 否 | 关键词搜索 |
| page | int | 否 | 页码，默认1 |
| pageSize | int | 否 | 每页条数，默认20 |
响应
{
"code": 200,
"data": {
"originalItem": {
"productId": "PROD_001",
"productName": "新鲜猪肉",
"categoryName": "肉类",
"unitName": "斤",
"price": 2500,
"quantity": 10
},
"list": [
{
"productId": "PROD_002",
"productName": "新鲜牛肉",
"categoryName": "肉类",
"unitName": "斤",
"price": 4500,
"stock": 50
}
],
"total": 5,
"page": 1,
"pageSize": 20
}
}
附录
角色说明
| 角色标识 | 说明 | 端 |
|---|---|---|
| admin | 运营人员 | Web |
| supplier | 供应商 | 小程序 |
| client | 客户 | 小程序 |
| deliver | 配送员 | 小程序 |
状态说明
询价单状态
| 状态 | 说明 |
|---|---|
| draft | 草稿 |
| published | 已发布 |
| closed | 已关闭 |
报价单状态
| 状态 | 说明 |
|---|---|
| pending | 待审核 |
| approved | 已通过 |
| rejected | 已拒绝 |
价格清单状态
| 状态 | 说明 |
|---|---|
| draft | 草稿 |
| pending | 待生效 |
| active | 生效中 |
| inactive | 已失效 |
订单状态
| 状态 | 说明 |
|---|---|
| pending_payment | 待支付 |
| pending_review_cancel | 待审核取消 |
| pending_delivery | 待分配配送 |
| delivering | 配送中 |
| partial_delivered | 部分送达 |
| pending_confirm | 待确认收货 |
| completed | 已完结 |
| cancelled | 已取消 |
订单项状态
| 状态 | 说明 |
|---|---|
| normal | 正常 |
| reduced | 已减量 |
| deleted | 已删除 |
| substituted | 已替代 |
配送任务状态
| 状态 | 说明 |
|---|---|
| pending | 待取货 |
| picking | 取货中 |
| delivering | 配送中 |
| completed | 已完成 |
| cancelled | 已取消 |
配送任务明细状态
| 状态 | 说明 |
|---|---|
| pending | 待配送 |
| picking | 取货中 |
| picked | 已取货 |
| delivering | 配送中 |
| delivered | 已送达 |
结算状态
| 状态 | 说明 |
|---|---|
| pending | 待确认 |
| completed | 已完成 |
退款状态
| 状态 | 说明 |
|---|---|
| pending | 待处理 |
| success | 成功 |
| failed | 失败 |
退款结果
| 状态 | 说明 |
|---|---|
| success | 成功 |
| failed | 失败 |
| processing | 处理中 |
支付方式
| 状态 | 说明 |
|---|---|
| 微信支付 | |
| offline | 线下结算 |
登录结果
| 状态 | 说明 |
|---|---|
| success | 成功 |
| failed | 失败 |
业务类型说明
附件业务类型
| 类型 | 说明 |
|---|---|
| delivery_pickup | 取货凭证 |
| delivery_delivery | 送达凭证 |
| settlement_file | 结算文件 |
| refund_file | 退款凭证 |
| invoice | 发票文件 |
地址类型
| 类型 | 说明 |
|---|---|
| pickup | 取货地址 |
| delivery | 配送地址 |
| both | 两者皆是 |
订单调整类型
| 类型 | 说明 |
|---|---|
| reduce | 减量 |
| delete | 删除 |
| substitute | 替代 |
| add | 补录 |
密码操作类型
| 类型 | 说明 |
|---|---|
| modify | 自主修改 |
| reset | 重置 |
结算方式
| 类型 | 说明 |
|---|---|
| transfer | 转账 |
| cash | 现金 |
| other | 其他 |
退款方式
| 类型 | 说明 |
|---|---|
| 微信原路退回 | |
| offline | 线下冲销 |
模块说明
| 模块 | 说明 |
|---|---|
| user | 用户 |
| region | 区域 |
| inquiry | 询价 |
| quotation | 报价 |
| price | 价格 |
| order | 订单 |
| delivery | 配送 |
| settlement | 结算 |
| refund | 退款 |
| pay | 支付 |
操作类型说明
| 操作 | 说明 |
|---|---|
| create | 创建 |
| update | 更新 |
| delete | 删除 |
| login | 登录 |
| logout | 登出 |
| publish | 发布 |
| cancel | 取消 |
| refund | 退款 |
| settle | 结算 |
| adjust | 调整 |
| assign | 分配 |
| pickup | 取货 |
| deliver | 送达 |
| review | 审核 |
| approve | 批准 |
| reject | 拒绝 |
消息类型说明
| 类型 | 说明 |
|---|---|
| order_status | 订单状态变更 |
| delivery_warning | 配送时效预警 |
| refund_result | 退款结果通知 |
| settlement_reminder | 结算提醒 |
| cancel_review | 取消审核通知 |
| price_publish | 价格发布通知 |
| inquiry_publish | 询价发布通知 |
| quotation_selected | 报价被选用通知 |
| cancel_approved | 取消审核通过通知 |
| cancel_rejected | 取消审核驳回通知 |
| delivery_assigned | 配送分配通知 |
| delivery_completed | 配送完成通知 |
发票状态说明
| 类型 | 说明 |
|---|---|
| pending | 待开票 |
| issued | 已开票 |
| cancelled | 已作废 |
发票类型说明
| 类型 | 说明 |
|---|---|
| ordinary | 普通发票 |
| vat | 增值税专用发票 |
配送时效预警级别说明
配送时效预警级别说明
| 级别 | 说明 | 时间范围 |
|---|---|---|
| normal | 正常 | > 60分钟 |
| warning | 预警 | 30-60分钟 |
| urgent | 紧急 | 15-30分钟 |
| overdue | 已过期 | < 0分钟 |
交接类型说明
| 类型 | 说明 |
|---|---|
| shift_out | 交班 |
| shift_in | 接班 |
业务错误码
HTTP状态码
| 错误码 | HTTP状态码 | 说明 | 使用场景 |
|---|---|---|---|
| 200 | 200 | 成功 | 正常请求成功 |
| 400 | 400 | 请求参数错误 | 参数校验失败、格式错误等 |
| 401 | 401 | 未授权 | 未登录、Token过期、Token无效 |
| 403 | 403 | 无权限 | 权限不足、账号被禁用 |
| 404 | 404 | 资源不存在 | 查询的资源不存在 |
| 409 | 409 | 资源冲突 | 订单已锁定、数据重复等 |
| 500 | 500 | 服务器错误 | 系统内部异常 |
业务错误码
| 错误码 | 说明 | 适用场景 |
|---|---|---|
| 1001 | 价格版本已过期 | 下单时使用的价格版本已失效 |
| 1002 | 订单已被锁定 | 订单被其他用户锁定 |
| 1003 | 配送任务已被接单 | 配送任务已被其他配送员接收 |
| 1004 | 库存不足 | 商品库存无法满足订单需求 |
| 1005 | 超出催单次数限制 | 当天催单次数已达上限（3次） |
| 2001 | 订单状态不允许此操作 | 当前状态不支持该操作 |
| 2002 | 配送任务状态不允许此操作 | 当前状态不支持该操作 |
| 2003 | 询价单状态不允许此操作 | 当前状态不支持该操作 |
| 2004 | 报价单状态不允许此操作 | 当前状态不支持该操作 |
| 2005 | 价格清单状态不允许此操作 | 当前状态不支持该操作 |
| 3001 | 报价已过期 | 提交报价时询价单已关闭 |
| 3002 | 报价时间已截止 | 超出报价截止时间 |
| 3003 | 报价已提交，不能修改 | 报价已进入审核流程 |
| 4001 | 价格版本正在生效中 | 存在待生效版本，无法发布新版本 |
| 4002 | 商品不在询价范围内 | 提交报价的商品不在询价清单中 |
| 5001 | 退款金额超出已支付金额 | 退款金额大于实际支付 |
| 5002 | 退款处理中 | 退款正在处理中，请勿重复提交 |
| 5003 | 订单未支付，无法退款 | 未支付订单不能发起退款 |
| 6001 | 用户名已存在 | 创建用户时用户名重复 |
| 6002 | 账号已被禁用 | 用户状态为禁用 |
| 6003 | 原密码错误 | 修改密码时原密码不正确 |
| 6004 | 新密码不能与原密码相同 | 修改密码时新密码与原密码相同 |
| 7001 | 区域不存在 | 指定的区域ID无效 |
| 7002 | 商品不存在 | 指定的商品ID无效 |
| 7003 | 订单不存在 | 指定的订单ID无效 |
| 7004 | 配送任务不存在 | 指定的配送任务ID无效 |
校验错误码
| 错误码 | 说明 | 适用场景 |
|---|---|---|
| 40001 | 必填参数为空 | 缺少必填参数 |
| 40002 | 参数类型错误 | 参数类型不匹配 |
| 40003 | 参数格式错误 | 格式不符合要求 |
| 40004 | 参数长度超限 | 超出长度限制 |
| 40005 | 参数值不在范围内 | 超出允许范围 |
| 40006 | 枚举值不正确 | 不在允许列表中 |
| 40007 | URL格式错误 | 不是合法的URL |
| 40008 | 日期格式错误 | 不是合法的日期格式 |
| 40009 | 金额格式错误 | 小数位数超出限制 |
| 40010 | 数量精度错误 | 小数位数超出限制 |
异常响应格式
通用错误响应
{
"code": 400,
"message": "参数校验失败",
"data": null,
"timestamp": 1700000000000,
"errors": [
{
"field": "username",
"message": "用户名不能为空"
}
]
}
业务异常响应
{
"code": 1002,
"message": "订单已被锁定",
"data": {
"orderId": "ORDER_001",
"lockOperator": "张三",
"lockTime": "2026-03-19T10:00:00+08:00"
},
"timestamp": 1700000000000
}
权限异常响应
{
"code": 403,
"message": "无权限访问该资源",
"data": null,
"timestamp": 1700000000000
}
认证异常响应
{
"code": 401,
"message": "Token已过期，请重新登录",
"data": null,
"timestamp": 1700000000000
}
异常处理流程
┌─────────────────┐
│ 请求到达 │
└────────┬────────┘
▼
┌─────────────────┐
│ 参数校验 │──失败──▶ 返回400错误 + errors
└────────┬────────┘
│成功
▼
┌─────────────────┐
│ 认证校验 │──失败──▶ 返回401错误
└────────┬────────┘
│成功
▼
┌─────────────────┐
│ 权限校验 │──失败──▶ 返回403错误
└────────┬────────┘
│成功
▼
┌─────────────────┐
│ 业务规则校验 │──失败──▶ 返回业务错误码
└────────┬────────┘
│成功
▼
┌─────────────────┐
│ 业务处理 │──失败──▶ 返回500错误
└────────┬────────┘
│成功
▼
┌─────────────────┐
│ 返回成功响应 │
└─────────────────┘
日志记录要求
| 级别 | 记录内容 | 示例 |
|---|---|---|
| INFO | 正常业务操作 | 登录、订单创建、状态变更 |
| WARN | 业务异常 | 库存不足、支付失败、参数校验失败 |
| ERROR | 系统异常 | 数据库错误、第三方接口超时、空指针异常 |
日志记录规范
// INFO级别 - 业务操作
log.info("用户登录成功, userId={}, username={}", userId, username);
log.info("订单创建成功, orderId={}, orderNo={}", orderId, orderNo);
// WARN级别 - 业务异常
log.warn("库存不足, productId={}, required={}, available={}", productId, required, available);
log.warn("支付失败, orderId={}, error={}", orderId, errorMessage);
// ERROR级别 - 系统异常
log.error("数据库操作失败, sql={}, error={}", sql, e.getMessage(), e);
log.error("微信支付接口异常, orderId={}, error={}", orderId, e.getMessage(), e);
第三方接口异常处理
微信支付
| 异常类型 | 处理方式 |
|---|---|
| 接口超时 | 重试3次，每次间隔2秒 |
| 返回失败 | 记录错误码，提示用户 |
| 退款失败 | 标记状态为failed，触发人工处理流程 |
地图服务
| 异常类型 | 处理方式 |
|---|---|
| 接口超时 | 使用缓存数据或默认坐标 |
| 地理编码失败 | 返回原始地址，提示用户确认 |
新增接口 - 配送员工作台统计（小程序端）
20. 配送员获取个人效率统计（小程序端）
请求
GET /api/mini/deliverer/statistics/efficiency
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"today": {
"completedCount": 8,
"avgDeliveryMinutes": 38,
"onTimeRate": 98.5
},
"week": {
"completedCount": 45,
"avgDeliveryMinutes": 40,
"onTimeRate": 97.8
},
"month": {
"completedCount": 180,
"avgDeliveryMinutes": 42,
"onTimeRate": 97.2
},
"rating": 4.9,
"totalCompleted": 1256,
"totalDistance": 1580
}
}
新增接口 - 供应商工作台统计（小程序端）
18. 供应商获取工作台统计数据（小程序端）
请求
GET /api/mini/supplier/dashboard/statistics
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"inquiry": {
"pendingQuotation": 2,
"quoted": 5
},
"price": {
"activeVersion": 3,
"effectiveTime": "2026-03-17T00:00:00+08:00"
},
"pickup": {
"pendingCount": 3,
"processingCount": 1,
"todayCompleted": 8
},
"delivery": {
"pendingPickup": 5,
"pickedUp": 2,
"todayCompleted": 8
}
}
}
新增接口 - 客户工作台统计（小程序端）
10.5. 客户获取工作台统计数据（小程序端）
请求
GET /api/mini/client/dashboard/statistics
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"order": {
"pendingPayment": 1,
"delivering": 2,
"completed": 45,
"pendingSettlement": 256000
},
"price": {
"activeVersion": 3,
"effectiveTime": "2026-03-17T00:00:00+08:00",
"productCount": 15
},
"cart": {
"itemCount": 3,
"totalAmount": 12500
}
}
}
新增接口 - 发票下载（Web端/小程序端）
10. 下载发票PDF（Web端）
请求
GET /api/web/invoices/{invoiceId}/download
Authorization: Bearer <token>
响应
返回PDF文件流
Content-Type: application/pdf
Content-Disposition: attachment; filename="INV20260319001.pdf"
15.5. 客户下载发票PDF（小程序端）
请求
GET /api/mini/client/invoices/{invoiceId}/download
Authorization: Bearer <token>
响应
返回PDF文件流
新增接口 - 小程序端系统配置
8. 获取小程序版本信息（小程序端）
请求
GET /api/mini/system/version
响应
{
"code": 200,
"data": {
"version": "1.2.0",
"buildNumber": 120,
"updateContent": "修复若干bug，优化性能",
"forceUpdate": false,
"downloadUrl": "https://download.example.com/app.apk",
"minSupportedVersion": "1.0.0"
}
}
新增接口 - 公共模块（地理编码）
8. 地理编码 - 地址转坐标（Web端/小程序端）
请求
GET /api/common/geocoder/address-to-coord?address=广东省深圳市南山区科技园
Authorization: Bearer <token>
响应
{
"code": 200,
"data": {
"address": "广东省深圳市南山区科技园",
"province": "广东省",
"city": "深圳市",
"district": "南山区",
"latitude": 22.543,
"longitude": 113.952
}
}
新增接口 - 供应商/客户信息（小程序端）
18.5. 供应商获取本区域供应商列表（小程序端）
请求
GET /api/mini/common/suppliers
Authorization: Bearer <token>
响应
{
"code": 200,
"data": [
{
"id": "USER_010",
"supplierName": "张伟供应商",
"contactPerson": "张伟",
"contactPhone": "13800138001",
"address": "福田区XX路XX号",
"latitude": 22.543,
"longitude": 113.952
}
]
}
说明
- 返回当前用户所属区域的所有供应商信息
- 配送员可用此接口查询供应商地址用于导航