# 叁强鲜配 - 接口定义文档 ## 目录 - [接口规范说明](#接口规范说明) - [用户模块](#用户模块) - [地址模块](#地址模块) - [区域模块](#区域模块) - [商品模块](#商品模块) - [询价报价模块](#询价报价模块) - [价格模块](#价格模块) - [购物车模块](#购物车模块) - [订单模块](#订单模块) - [支付模块](#支付模块) - [配送模块](#配送模块) - [结算模块](#结算模块) - [发票管理模块](#发票管理模块) - [数据统计模块](#数据统计模块) - [日志模块](#日志模块) - [消息通知模块](#消息通知模块) - [附件模块](#附件模块) - [系统设置模块](#系统设置模块) - [公共模块](#公共模块) --- ## 对接补充清单（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. 本轮已处理项（代码侧） 1. **Web 登录前缀重复风险** - 已处理：公共路由前缀已调整，避免 `/api/api/web/...` 重复前缀问题。 2. **小程序用户资料路径** - 已处理：前端已统一使用 `/api/mini/client/profile`，替代历史 `/api/mini/user/profile`。 3. **报价对比接口缺口** - 已处理：后端新增 `GET /api/web/admin/quotation-compare`，并与 Web 端调用对齐。 4. **系统配置批量状态更新参数口径** - 已处理：后端 `POST /api/system-config/batch-status` 已支持 JSON body（`ids`, `is_active`）。 5. **配送预警详情及处理参数口径** - 已处理：后端补充 `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 | ### 通用响应格式 ```json { "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有效期：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端登录 **请求** ```http POST /api/web/auth/login Content-Type: application/json { "username": "admin", "password": "admin123" } ``` **响应** ```json { "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. 小程序端登录 **请求** ```http POST /api/mini/auth/login Content-Type: application/json { "username": "client001", "password": "client123" } ``` **响应** ```json { "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 **请求** ```http POST /api/web/auth/refresh-token Content-Type: application/json { "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } ``` --- ### 4. 登出 **请求** ```http POST /api/web/auth/logout Authorization: Bearer ``` **请求（小程序端）** ```http POST /api/mini/auth/logout Authorization: Bearer ``` --- ### 5. 获取当前用户信息 **请求（Web端）** ```http GET /api/web/auth/current-user Authorization: Bearer ``` **请求（小程序端）** ```http GET /api/mini/auth/current-user Authorization: Bearer ``` **响应** ```json { "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. 修改密码（自主修改） **请求** ```http POST /api/web/user/change-password Authorization: Bearer Content-Type: application/json { "oldPassword": "old123", "newPassword": "new123" } ``` **请求（小程序端）** ```http POST /api/mini/user/change-password Authorization: Bearer Content-Type: application/json { "oldPassword": "old123", "newPassword": "new123" } ``` --- ### 7. 重置密码（运营操作） **请求** ```http POST /api/web/user/reset-password/{userId} Authorization: Bearer ``` **响应** ```json { "code": 200, "data": { "newPassword": "随机生成的密码" } } ``` --- ### 8. 获取用户列表（Web端） **请求** ```http GET /api/web/users?page=1&pageSize=10&role=supplier®ionId=REGION_001&keyword=张&isActive=true Authorization: Bearer ``` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | page | int | 否 | 页码，默认1 | | pageSize | int | 否 | 每页条数，默认10 | | role | string | 否 | 角色筛选：admin/supplier/client/deliver | | regionId | string | 否 | 区域ID | | keyword | string | 否 | 关键词搜索（用户名/姓名/手机号） | | isActive | boolean | 否 | 是否激活 | **响应** ```json { "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端） **请求** ```http POST /api/web/users Authorization: Bearer Content-Type: application/json { "username": "client001", "realName": "李娜", "phone": "13800138002", "role": "client", "regionId": "REGION_001" } ``` **响应** ```json { "code": 200, "data": { "id": "USER_xxx", "username": "client001", "realName": "李娜", "initialPassword": "随机生成的初始密码" } } ``` --- ### 10. 更新用户（Web端） **请求** ```http PUT /api/web/users/{userId} Authorization: Bearer Content-Type: application/json { "realName": "李娜", "phone": "13800138002", "regionId": "REGION_001", "isActive": true } ``` --- ### 11. 删除用户（软删除，Web端） **请求** ```http DELETE /api/web/users/{userId} Authorization: Bearer ``` --- ### 12. 小程序端更新个人基础信息 **请求** ```http PUT /api/mini/user/profile Authorization: Bearer Content-Type: application/json { "realName": "王小明", "phone": "13800138002" } ``` --- ### 13. 小程序端获取供应商/客户详情 **请求（供应商）** ```http GET /api/mini/supplier/profile Authorization: Bearer ``` **请求（客户）** ```http GET /api/mini/client/profile Authorization: Bearer ``` **响应** ```json { "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. 小程序端更新供应商/客户基础信息 **请求** ```http PUT /api/mini/supplier/profile Authorization: Bearer Content-Type: application/json { "realName": "张伟", "phone": "13800138001", "address": { "contactPerson": "张伟", "contactPhone": "13800138001", "province": "广东省", "city": "深圳市", "district": "南山区", "detailAddress": "科技园XX路XX号" } } ``` --- ### 15. 获取配送员详情 **请求** ```http GET /api/mini/deliverer/profile Authorization: Bearer ``` **响应** ```json { "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. 小程序端更新配送员基础信息 **请求** ```http PUT /api/mini/deliverer/profile Authorization: Bearer Content-Type: application/json { "realName": "李建", "phone": "13900139001" } ``` --- ### 17. 小程序端验证码登录（获取手机号一键登录） **请求** ```http POST /api/mini/auth/sms-login Content-Type: application/json { "code": "微信授权code" } ``` **响应** ```json { "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端） **请求** ```http GET /api/web/users/{userId} Authorization: Bearer ``` **响应** ```json { "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端按区域获取供应商列表 **请求** ```http GET /api/web/suppliers?regionId=REGION_001&isActive=true&keyword=&page=1&pageSize=10 Authorization: Bearer ``` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | regionId | string | 是 | 区域ID | | isActive | boolean | 否 | 是否激活 | | keyword | string | 否 | 关键词搜索 | | page | int | 否 | 页码，默认1 | | pageSize | int | 否 | 每页条数，默认10 | **响应** ```json { "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端按区域获取客户列表 **请求** ```http GET /api/web/clients?regionId=REGION_001&isActive=true&keyword=&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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端按区域获取配送员列表 **请求** ```http GET /api/web/deliverers?regionId=REGION_001&isActive=true&keyword=&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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. 获取地址列表（小程序端） **请求（客户）** ```http GET /api/mini/client/addresses Authorization: Bearer ``` **请求（供应商）** ```http GET /api/mini/supplier/addresses Authorization: Bearer ``` **响应** ```json { "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. 获取地址详情（小程序端） **请求** ```http GET /api/mini/client/addresses/{addressId} Authorization: Bearer ``` --- ### 3. 创建地址（小程序端） **请求** ```http POST /api/mini/client/addresses Authorization: Bearer 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. 更新地址（小程序端） **请求** ```http PUT /api/mini/client/addresses/{addressId} Authorization: Bearer Content-Type: application/json { "contactPerson": "王小明", "contactPhone": "13800138002", "province": "广东省", "city": "深圳市", "district": "南山区", "detailAddress": "科技园XX路XX号", "isDefault": false } ``` --- ### 5. 删除地址（小程序端） **请求** ```http DELETE /api/mini/client/addresses/{addressId} Authorization: Bearer ``` --- ### 6. 设置默认地址（小程序端） **请求** ```http POST /api/mini/client/addresses/{addressId}/set-default Authorization: Bearer ``` --- ### 7. 获取供应商取货地址列表（小程序端） **请求** ```http GET /api/mini/supplier/pickup-addresses Authorization: Bearer ``` --- ## 区域模块 ### 1. 获取区域列表（Web端） **请求** ```http GET /api/web/regions?isActive=true Authorization: Bearer ``` **响应** ```json { "code": 200, "data": [ { "id": "REGION_001", "name": "城东区域", "code": "CD", "description": "城东配送区域", "sortOrder": 1, "isActive": true, "supplierCount": 32, "clientCount": 456, "deliverCount": 18 } ] } ``` --- ### 2. 创建区域（Web端） **请求** ```http POST /api/web/regions Authorization: Bearer Content-Type: application/json { "name": "城北区域", "code": "CB", "description": "城北配送区域", "sortOrder": 4 } ``` --- ### 3. 更新区域（Web端） **请求** ```http PUT /api/web/regions/{regionId} Authorization: Bearer Content-Type: application/json { "name": "城北区域", "description": "城北配送区域", "sortOrder": 4, "isActive": true } ``` --- ### 4. 删除区域（Web端） **请求** ```http DELETE /api/web/regions/{regionId} Authorization: Bearer ``` --- ### 5. 获取区域详情（Web端） **请求** ```http GET /api/web/regions/{regionId} Authorization: Bearer ``` **响应** ```json { "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. 获取当前用户区域信息（小程序端） **请求** ```http GET /api/mini/common/my-region Authorization: Bearer ``` **响应** ```json { "code": 200, "data": { "id": "REGION_001", "name": "城东区域", "code": "CD" } } ``` --- ## 商品模块 ### 1. 获取商品分类列表 **请求（Web端）** ```http GET /api/web/product-categories?parentId=&isActive=true Authorization: Bearer ``` **响应** ```json { "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. 创建商品分类 **请求** ```http POST /api/web/product-categories Authorization: Bearer Content-Type: application/json { "name": "水果", "parentId": null, "sortOrder": 2 } ``` --- ### 3. 更新商品分类 **请求** ```http PUT /api/web/product-categories/{categoryId} Authorization: Bearer Content-Type: application/json { "name": "水果", "parentId": null, "sortOrder": 2, "isActive": true } ``` --- ### 4. 删除商品分类 **请求** ```http DELETE /api/web/product-categories/{categoryId} Authorization: Bearer ``` --- ### 5. 获取商品单位列表 **请求（Web端）** ```http GET /api/web/product-units?isActive=true Authorization: Bearer ``` **响应** ```json { "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. 创建商品单位 **请求** ```http POST /api/web/product-units Authorization: Bearer Content-Type: application/json { "name": "升", "code": "L" } ``` --- ### 7. 更新商品单位 **请求** ```http PUT /api/web/product-units/{unitId} Authorization: Bearer Content-Type: application/json { "name": "升", "code": "L", "isActive": true } ``` --- ### 8. 删除商品单位 **请求** ```http DELETE /api/web/product-units/{unitId} Authorization: Bearer ``` --- ### 9. 获取商品列表 **请求（Web端）** ```http GET /api/web/products?categoryId=CAT_001&keyword=猪肉&isActive=true&page=1&pageSize=20 Authorization: Bearer ``` **响应** ```json { "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. 创建商品 **请求** ```http POST /api/web/products Authorization: Bearer Content-Type: application/json { "name": "新鲜猪肉", "categoryId": "CAT_003", "unitId": "UNIT_001", "description": "优质新鲜猪肉", "imageUrl": "https://cdn.example.com/products/pork.jpg" } ``` --- ### 11. 更新商品 **请求** ```http PUT /api/web/products/{productId} Authorization: Bearer Content-Type: application/json { "name": "新鲜猪肉", "categoryId": "CAT_003", "unitId": "UNIT_001", "description": "优质新鲜猪肉", "imageUrl": "https://cdn.example.com/products/pork.jpg", "isActive": true } ``` --- ### 12. 删除商品 **请求** ```http DELETE /api/web/products/{productId} Authorization: Bearer ``` --- ### 13. 获取商品详情 **请求** ```http GET /api/web/products/{productId} Authorization: Bearer ``` --- ### 14. 客户获取商品列表（小程序端） **请求** ```http GET /api/mini/client/products?categoryId=CAT_001&keyword=&page=1&pageSize=20 Authorization: Bearer ``` **响应** ```json { "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. 获取客户可购买的商品分类及商品（小程序端） **请求** ```http GET /api/mini/client/product-categories Authorization: Bearer ``` **响应** ```json { "code": 200, "data": [ { "id": "CAT_001", "name": "蔬菜", "products": [ { "id": "PROD_001", "name": "新鲜白菜", "unitName": "斤", "price": 320 } ] } ] } ``` --- ## 询价报价模块 ### 1. 获取询价单列表（Web端） **请求** ```http GET /api/web/inquiries?regionId=REGION_001&status=published&keyword=&page=1&pageSize=10 Authorization: Bearer ``` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | regionId | string | 否 | 区域ID | | status | string | 否 | 状态：draft/published/closed | | keyword | string | 否 | 关键词搜索 | | page | int | 否 | 页码 | | pageSize | int | 否 | 每页条数 | **响应** ```json { "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端） **请求** ```http POST /api/web/inquiries Authorization: Bearer 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端） **请求** ```http PUT /api/web/inquiries/{inquiryId} Authorization: Bearer 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端） **请求** ```http POST /api/web/inquiries/{inquiryId}/publish Authorization: Bearer ``` --- ### 5. 关闭询价单（Web端） **请求** ```http POST /api/web/inquiries/{inquiryId}/close Authorization: Bearer ``` --- ### 6. 获取询价单详情（Web端） **请求** ```http GET /api/web/inquiries/{inquiryId} Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http DELETE /api/web/inquiries/{inquiryId} Authorization: Bearer ``` --- ### 8. 供应商获取询价单列表（小程序端） **请求** ```http GET /api/mini/supplier/inquiries?status=published&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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. 供应商获取询价单详情（小程序端） **请求** ```http GET /api/mini/supplier/inquiries/{inquiryId} Authorization: Bearer ``` **响应** ```json { "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. 供应商提交报价（小程序端） **请求** ```http POST /api/mini/supplier/quotations Authorization: Bearer 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": "报价说明" } ``` **响应** ```json { "code": 200, "data": { "id": "QUO_001", "inquiryId": "INQ_001", "quotationNo": "QT20260319001", "status": "pending", "submitTime": "2026-03-19T14:30:00+08:00" } } ``` --- ### 11. 供应商更新报价（小程序端） **请求** ```http PUT /api/mini/supplier/quotations/{quotationId} Authorization: Bearer Content-Type: application/json { "items": [ { "productId": "PROD_001", "unitId": "UNIT_001", "price": 2600 }, { "productId": "PROD_002", "unitId": "UNIT_001", "price": 850 } ], "remark": "更新报价说明" } ``` --- ### 12. 供应商获取报价列表（小程序端） **请求** ```http GET /api/mini/supplier/quotations?status=&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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. 供应商获取报价详情（小程序端） **请求** ```http GET /api/mini/supplier/quotations/{quotationId} Authorization: Bearer ``` --- ### 14. 运营获取报价列表（Web端） **请求** ```http GET /api/web/quotations?inquiryId=INQ_001&supplierId=®ionId=REGION_001&status=&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/quotations/{quotationId} Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/inquiries/{inquiryId}/quotation-comparison Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http POST /api/web/quotations/{quotationId}/review Authorization: Bearer Content-Type: application/json { "status": "approved", "reviewNote": "审核通过" } ``` --- ## 价格模块 ### 1. 获取价格清单列表（Web端） **请求** ```http GET /api/web/price-lists?regionId=REGION_001&status=active&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http POST /api/web/price-lists Authorization: Bearer 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端） **请求** ```http GET /api/web/price-lists/{priceListId} Authorization: Bearer ``` **响应** ```json { "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端，只有草稿状态可编辑）** **请求** ```http PUT /api/web/price-lists/{priceListId} Authorization: Bearer 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端） **请求** ```http POST /api/web/price-lists/{priceListId}/publish Authorization: Bearer ``` --- ### 6. 设为失效（Web端） **请求** ```http POST /api/web/price-lists/{priceListId}/inactive Authorization: Bearer ``` --- ### 7. 删除价格清单（Web端，只有草稿状态可删除）** **请求** ```http DELETE /api/web/price-lists/{priceListId} Authorization: Bearer ``` --- ### 8. 获取区域价格版本历史（Web端） **请求** ```http GET /api/web/price-lists/history?regionId=REGION_001 Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/price-lists/compare?priceListId1=PL_002&priceListId2=PL_003 Authorization: Bearer ``` **响应** ```json { "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. 客户获取当前生效价格（小程序端） **请求** ```http GET /api/mini/client/price-list Authorization: Bearer ``` **响应** ```json { "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. 客户获取价格清单商品列表（小程序端） **请求** ```http GET /api/mini/client/price-list/products?categoryId=&keyword=&page=1&pageSize=20 Authorization: Bearer ``` **响应** ```json { "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. 供应商获取价格版本列表（小程序端） **请求** ```http GET /api/mini/supplier/price-lists Authorization: Bearer ``` **响应** ```json { "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. 供应商获取价格清单详情（小程序端） **请求** ```http GET /api/mini/supplier/price-lists/{priceListId} Authorization: Bearer ``` --- ### 14. 按商品维度查询价格历史（Web端） **请求** ```http GET /api/web/price-lists/product-history?regionId=REGION_001&productId=PROD_001 Authorization: Bearer ``` **响应** ```json { "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. 获取购物车列表（小程序端） **请求** ```http GET /api/mini/client/cart Authorization: Bearer ``` **响应** ```json { "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. 添加商品到购物车（小程序端） **请求** ```http POST /api/mini/client/cart Authorization: Bearer Content-Type: application/json { "productId": "PROD_001", "quantity": 10 } ``` --- ### 3. 更新购物车商品数量（小程序端） **请求** ```http PUT /api/mini/client/cart/{cartId} Authorization: Bearer Content-Type: application/json { "quantity": 15 } ``` --- ### 4. 删除购物车商品（小程序端） **请求** ```http DELETE /api/mini/client/cart/{cartId} Authorization: Bearer ``` --- ### 5. 清空购物车（小程序端） **请求** ```http DELETE /api/mini/client/cart Authorization: Bearer ``` --- ### 6. 批量删除购物车商品（小程序端） **请求** ```http DELETE /api/mini/client/cart/batch Authorization: Bearer Content-Type: application/json { "cartIds": ["CART_001", "CART_002"] } ``` --- ## 订单模块 ### 0.5. 客户订单预览（小程序端） **请求** ```http POST /api/mini/client/orders/preview Authorization: Bearer Content-Type: application/json { "priceListId": "PL_001", "items": [ { "productId": "PROD_001", "quantity": 10 }, { "productId": "PROD_002", "quantity": 20 } ], "addressId": "ADDR_001" } ``` **响应** ```json { "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. 客户创建订单（小程序端） **请求** ```http POST /api/mini/client/orders Authorization: Bearer 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 | 否 | 订单备注 | **响应** ```json { "code": 200, "data": { "orderId": "ORDER_001", "orderNo": "ORD20260319001", "totalAmount": 41000, "status": "pending_payment" } } ``` --- ### 2. 客户从购物车创建订单（小程序端） **请求** ```http POST /api/mini/client/orders/from-cart Authorization: Bearer Content-Type: application/json { "priceListId": "PL_001", "cartIds": ["CART_001", "CART_002"], "addressId": "ADDR_001", "paymentMethod": "wechat", "remark": "订单备注" } ``` --- ### 3. 客户获取订单列表（小程序端） **请求** ```http GET /api/mini/client/orders?status=&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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. 客户获取订单详情（小程序端） **请求** ```http GET /api/mini/client/orders/{orderId} Authorization: Bearer ``` **响应** ```json { "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. 客户发起取消申请（小程序端） **请求** ```http POST /api/mini/client/orders/{orderId}/cancel Authorization: Bearer Content-Type: application/json { "reason": "不需要了" } ``` --- ### 6. 客户确认收货（小程序端） **请求** ```http POST /api/mini/client/orders/{orderId}/confirm-receive Authorization: Bearer ``` --- ### 6.5. 客户直接取消未支付订单（小程序端） **请求** ```http POST /api/mini/client/orders/{orderId}/direct-cancel Authorization: Bearer Content-Type: application/json { "reason": "不想要了" } ``` **说明** - 适用于待支付状态的订单 - 未支付订单取消无需运营审核 - 直接将订单状态改为已取消 --- ### 7. 运营获取订单列表（Web端） **请求** ```http GET /api/web/orders?regionId=REGION_001&status=pending_delivery&clientId=&orderNo=&startDate=&endDate=&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/orders/{orderId} Authorization: Bearer ``` --- ### 9. 运营审核取消申请（Web端） **请求** ```http POST /api/web/orders/{orderId}/review-cancel Authorization: Bearer Content-Type: application/json { "approved": true, "reviewNote": "同意取消" } ``` --- ### 9.5. 客户查看配送进度（小程序端） **请求** ```http GET /api/mini/client/orders/{orderId}/delivery-progress Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/products/substitutes?categoryId=CAT_003&keyword=&page=1&pageSize=20 Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http POST /api/web/orders/{orderId}/assign-delivery Authorization: Bearer Content-Type: application/json { "deliverId": "USER_050" } ``` --- ### 11. 运营调整订单（Web端）** **请求** ```http POST /api/web/orders/{orderId}/adjust Authorization: Bearer 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端）** **请求** ```http POST /api/web/orders/{orderId}/force-complete Authorization: Bearer Content-Type: application/json { "reason": "客户长期未确认，系统自动完结" } ``` --- ### 13. 运营获取订单状态变更日志（Web端）** **请求** ```http GET /api/web/orders/{orderId}/status-logs Authorization: Bearer ``` **响应** ```json { "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端）** **请求** ```http GET /api/web/orders/{orderId}/adjustments Authorization: Bearer ``` **响应** ```json { "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端）** **请求** ```http POST /api/web/orders/{orderId}/lock Authorization: Bearer ``` **响应** ```json { "code": 200, "data": { "locked": true, "lockOperatorId": "USER_001", "lockOperatorName": "系统管理员", "lockTime": "2026-03-19T15:00:00+08:00" } } ``` --- ### 16. 订单解锁（Web端）** **请求** ```http POST /api/web/orders/{orderId}/unlock Authorization: Bearer ``` --- ### 17. 强制解锁订单（Web端）** **请求** ```http POST /api/web/orders/{orderId}/force-unlock Authorization: Bearer ``` --- ### 18. 导出待结算订单（Web端）** **请求** ```http GET /api/web/orders/export/pending-settlement?regionId=REGION_001&startDate=&endDate= Authorization: Bearer ``` **响应** 返回Excel文件下载 --- ### 19. 导出线下结算订单（Web端）** **请求** ```http GET /api/web/orders/export/offline-settlement?regionId=REGION_001&clientId=&startDate=&endDate= Authorization: Bearer ``` **响应** 返回Excel文件下载 --- ## 支付模块 ### 0.5. 微信退款接口（Web端） **请求** ```http POST /api/web/refunds/wechat-refund/{orderId} Authorization: Bearer Content-Type: application/json { "refundAmount": 5000, "reason": "部分缺货退款" } ``` **响应** ```json { "code": 200, "data": { "refundId": "REFUND_001", "refundNo": "RF20260319001", "refundAmount": 5000, "refundResult": "processing", "refundTime": "2026-03-19T15:00:00+08:00" } } ``` **说明** - 仅支持已支付订单退款 - 退款金额不能超过已支付金额 - 微信退款为异步操作，结果需通过回调或主动查询获取 --- ### 0.6. 查询微信退款状态（Web端） **请求** ```http GET /api/web/refunds/{refundId}/status Authorization: Bearer ``` **响应** ```json { "code": 200, "data": { "refundId": "REFUND_001", "refundNo": "RF20260319001", "refundAmount": 5000, "refundResult": "success", "refundTime": "2026-03-19T15:00:00+08:00", "refundNoWechat": "微信退款单号" } } ``` --- ### 1. 发起微信支付（小程序端） **请求** ```http POST /api/mini/client/orders/{orderId}/wechat-pay Authorization: Bearer ``` **响应** ```json { "code": 200, "data": { "orderId": "ORDER_001", "orderNo": "ORD20260319001", "wechatPayParams": { "appId": "wx1234567890", "timeStamp": "1710822225", "nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS", "package": "prepay_id=wx201410272009395522657a690389285100", "signType": "MD5", "paySign": "C380BEC2BFD727A4B6845133519F3AD6" } } } ``` --- ### 2. 微信支付结果回调通知 **请求** ```http POST /api/web/pay/wechat-notify Content-Type: application/xml ``` --- ### 3. 查询微信支付状态 **请求（小程序端）** ```http GET /api/mini/client/orders/{orderId}/pay-status Authorization: Bearer ``` **响应** ```json { "code": 200, "data": { "orderId": "ORDER_001", "orderNo": "ORD20260319001", "paymentStatus": "paid", "payTime": "2026-03-19T10:25:00+08:00", "transactionId": "4208450740201411110007820472" } } ``` --- ### 4. 获取支付记录列表（Web端） **请求** ```http GET /api/web/pay/records?regionId=REGION_001&status=&startDate=&endDate=&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/delivery-tasks?regionId=REGION_001&status=pending&orderNo=&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/delivery-tasks/{taskId} Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http POST /api/web/delivery-tasks/assign Authorization: Bearer Content-Type: application/json { "orderId": "ORDER_001", "deliverId": "USER_050" } ``` --- ### 4. 运营批量分配配送任务（Web端） **请求** ```http POST /api/web/delivery-tasks/assign-batch Authorization: Bearer Content-Type: application/json { "assignments": [ { "orderId": "ORDER_001", "deliverId": "USER_050" }, { "orderId": "ORDER_002", "deliverId": "USER_050" } ] } ``` --- ### 5. 运营获取配送时效预警列表（Web端） **请求** ```http GET /api/web/delivery-tasks/warnings?regionId=REGION_001&withinMinutes=60 Authorization: Bearer ``` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | regionId | string | 否 | 区域ID（不传则查所有区域） | | withinMinutes | int | 否 | 多少分钟内即将过期，默认60 | | page | int | 否 | 页码，默认1 | | pageSize | int | 否 | 每页条数，默认10 | **响应** ```json { "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端） **请求** ```http POST /api/web/delivery-tasks/{taskId}/cancel Authorization: Bearer Content-Type: application/json { "reason": "客户要求取消" } ``` **响应** ```json { "code": 200, "data": { "id": "DLV_001", "status": "cancelled", "cancelTime": "2026-03-19T14:00:00+08:00" } } ``` --- ### 6.5. 小程序端查看配送凭证附件（小程序端） **请求** ```http GET /api/mini/delivery-tasks/{taskId}/attachments Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http POST /api/web/delivery-tasks/{taskId}/reassign Authorization: Bearer Content-Type: application/json { "deliverId": "USER_051" } ``` --- ### 8. 配送员获取待取货任务（小程序端） **请求** ```http GET /api/mini/deliverer/tasks?status=pending&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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. 配送员获取配送中任务（小程序端） **请求** ```http GET /api/mini/deliverer/tasks?status=delivering&page=1&pageSize=10 Authorization: Bearer ``` --- ### 10. 配送员获取已完成任务（小程序端） **请求** ```http GET /api/mini/deliverer/tasks?status=completed&page=1&pageSize=10 Authorization: Bearer ``` --- ### 11. 配送员获取任务详情（小程序端） **请求** ```http GET /api/mini/deliverer/tasks/{taskId} Authorization: Bearer ``` --- ### 12. 配送员确认取货（小程序端） **请求** ```http POST /api/mini/deliverer/tasks/{taskId}/pickup Authorization: Bearer Content-Type: application/json { "remark": "货物完好，数量正确", "imageUrls": ["https://cdn.example.com/pickup/001.jpg", "https://cdn.example.com/pickup/002.jpg"] } ``` --- ### 13. 配送员确认送达（小程序端） **请求** ```http POST /api/mini/deliverer/tasks/{taskId}/deliver Authorization: Bearer Content-Type: application/json { "items": [ { "taskItemId": "DLV_ITEM_001", "deliveredQuantity": 10 } ], "remark": "客户已签收", "imageUrls": ["https://cdn.example.com/deliver/001.jpg"] } ``` --- ### 14. 配送员获取任务统计（小程序端） **请求** ```http GET /api/mini/deliverer/tasks/statistics Authorization: Bearer ``` **响应** ```json { "code": 200, "data": { "todayPending": 2, "todayDelivering": 3, "todayCompleted": 8, "weekCompleted": 45, "monthCompleted": 180, "rating": 4.9 } } ``` --- ### 15. 供应商获取取货任务列表（小程序端） **请求** ```http GET /api/mini/supplier/pickup-tasks?status=&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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. 供应商获取取货任务详情（小程序端） **请求** ```http GET /api/mini/supplier/pickup-tasks/{taskId} Authorization: Bearer ``` --- ### 17.5. 供应商获取本区域供应商信息（小程序端） **请求** ```http GET /api/mini/common/suppliers Authorization: Bearer ``` **响应** ```json { "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 ``` **响应** ```json { "code": 200, "data": [ { "id": "DLV_001", "taskNo": "DLV20260319001", "remainingMinutes": 15, "clientName": "王小明", "clientAddress": "南山区XX路XX号" } ] } ``` --- ### 19.5. 配送员申请取消任务（小程序端） **请求** ```http POST /api/mini/deliverer/tasks/{taskId}/cancel Authorization: Bearer Content-Type: application/json { "reason": "客户联系不上，需改期配送", "images": ["https://cdn.example.com/cancel/001.jpg"] } ``` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | reason | string | 是 | 取消原因 | | images | array | 否 | 相关图片凭证 | **响应** ```json { "code": 200, "data": { "taskId": "DLV_001", "status": "cancelled", "cancelTime": "2026-03-19T14:00:00+08:00", "cancelReason": "客户联系不上，需改期配送" } } ``` --- ### 19.6. 配送员换班交接（小程序端） **请求** ```http POST /api/mini/deliverer/handover Authorization: Bearer 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列表 | **响应** ```json { "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端） **请求** ```http GET /api/web/settlements?regionId=REGION_001&clientId=&status=pending&startDate=&endDate=&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/settlements/client-summary?regionId=REGION_001&clientId=&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http POST /api/web/settlements Authorization: Bearer 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端） **请求** ```http POST /api/web/settlements/batch Authorization: Bearer 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端） **请求** ```http GET /api/web/settlements/records?regionId=REGION_001&clientId=&startDate=&endDate=&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/refunds?status=pending®ionId=&orderNo=&startDate=&endDate=&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/refunds/{refundId} Authorization: Bearer ``` --- ### 8. 运营处理退款（Web端）** **请求** ```http POST /api/web/refunds/{refundId}/process Authorization: Bearer Content-Type: application/json { "refundMethod": "wechat", "refundNoWechat": "微信退款单号", "note": "人工处理成功" } ``` --- ### 9. 运营处理退款失败（Web端）** **请求** ```http POST /api/web/refunds/{refundId}/handle-failure Authorization: Bearer Content-Type: application/json { "failReason": "微信退款失败，账户余额不足", "note": "需人工跟进处理" } ``` --- ### 10. 运营获取结算统计（Web端） **请求** ```http GET /api/web/settlements/statistics?regionId=REGION_001&startDate=&endDate= Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/settlements/region-statistics?startDate=&endDate= Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/invoices?invoiceNo=&clientId=&status=&startDate=&endDate=&page=1&pageSize=10 Authorization: Bearer ``` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | invoiceNo | string | 否 | 发票号 | | clientId | string | 否 | 客户ID | | status | string | 否 | 状态：pending-待开票/issued-已开票/cancelled-已作废 | | startDate | string | 否 | 开始日期 | | endDate | string | 否 | 结束日期 | | page | int | 否 | 页码，默认1 | | pageSize | int | 否 | 每页条数，默认10 | **响应** ```json { "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端） **请求** ```http GET /api/web/invoices/{invoiceId} Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http POST /api/web/invoices Authorization: Bearer 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 | 否 | 备注 | **响应** ```json { "code": 200, "data": { "id": "INV_001", "invoiceNo": "INV20260319001", "status": "issued" } } ``` --- ### 4. 作废发票（Web端） **请求** ```http POST /api/web/invoices/{invoiceId}/cancel Authorization: Bearer Content-Type: application/json { "cancelReason": "客户要求作废" } ``` --- ### 5. 下载发票（Web端） **请求** ```http GET /api/web/invoices/{invoiceId}/download Authorization: Bearer ``` **响应** 返回PDF文件下载 --- ### 6. 获取客户已开票金额汇总（Web端） **请求** ```http GET /api/web/invoices/client-summary?clientId=USER_010 Authorization: Bearer ``` **响应** ```json { "code": 200, "data": { "clientId": "USER_010", "clientName": "AA餐厅", "totalInvoicedAmount": 1256000, "pendingInvoiceAmount": 358000, "issuedInvoiceAmount": 898000, "cancelledInvoiceAmount": 0 } } ``` --- ### 7. 客户申请开票（小程序端） **请求** ```http POST /api/mini/client/invoices Authorization: Bearer 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-增值税专用发票 | **响应** ```json { "code": 200, "data": { "id": "INV_001", "invoiceNo": "INV20260319001", "status": "pending" } } ``` --- ### 8. 客户获取发票列表（小程序端） **请求** ```http GET /api/mini/client/invoices?status=&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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. 客户获取发票详情（小程序端） **请求** ```http GET /api/mini/client/invoices/{invoiceId} Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/dashboard/statistics Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/statistics/user-count?regionId=REGION_001 Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/statistics/overview?startDate=&endDate= Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/statistics/order-trend?startDate=&endDate=®ionId= Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/statistics/region-ranking?startDate=&endDate= Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/statistics/product-ranking?startDate=&endDate=®ionId=&limit=10 Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/statistics/client-ranking?startDate=&endDate=®ionId=&limit=10 Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/statistics/supplier-quotation?regionId=&startDate=&endDate=&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/statistics/delivery-efficiency?regionId=&startDate=&endDate= Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/statistics/income?regionId=&startDate=&endDate= Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/logs/login?username=&role=&loginResult=&startDate=&endDate=&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/logs/operation?module=&operation=&operatorId=&startDate=&endDate=&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/logs/operation/{logId} Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/audit-logs?module=order&operation=create&operatorId=&targetId=&startDate=&endDate=&page=1&pageSize=10 Authorization: Bearer ``` --- ## 消息通知模块 ### 1. 运营获取消息列表（Web端） **请求** ```http GET /api/web/messages?type=&isRead=&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http POST /api/web/messages/{messageId}/read Authorization: Bearer ``` --- ### 3. 运营标记全部消息已读（Web端） **请求** ```http POST /api/web/messages/read-all Authorization: Bearer ``` --- ### 4. 运营获取未读消息数量（Web端） **请求** ```http GET /api/web/messages/unread-count Authorization: Bearer ``` **响应** ```json { "code": 200, "data": { "total": 5, "cancelReview": 1, "deliveryWarning": 2, "refundPending": 2 } } ``` --- ### 4.5. 运营发送消息通知（Web端） **请求** ```http POST /api/web/messages/send Authorization: Bearer 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列表 | **响应** ```json { "code": 200, "data": { "sentCount": 2, "failedCount": 0 } } ``` --- ### 5. 运营删除消息（Web端） **请求** ```http DELETE /api/web/messages/{messageId} Authorization: Bearer ``` --- ### 6. 小程序端获取消息列表 **请求** ```http GET /api/mini/messages?type=&isRead=&page=1&pageSize=10 Authorization: Bearer ``` --- ### 7. 小程序端标记消息已读 **请求** ```http POST /api/mini/messages/{messageId}/read Authorization: Bearer ``` --- ### 8. 小程序端获取未读消息数量 **请求** ```http GET /api/mini/messages/unread-count Authorization: Bearer ``` **响应** ```json { "code": 200, "data": { "total": 3, "orderStatus": 1, "deliveryStatus": 2 } } ``` --- ### 9. 小程序端删除消息 **请求** ```http DELETE /api/mini/messages/{messageId} Authorization: Bearer ``` --- ### 10. 客户获取可开发票订单列表（小程序端） **请求** ```http GET /api/mini/client/invoices/available-orders?page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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. 客户申请发票（小程序端） **请求** ```http POST /api/mini/client/invoices Authorization: Bearer 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 | 否 | 银行账号 | **响应** ```json { "code": 200, "data": { "id": "INV_001", "invoiceNo": "INV20260319001", "status": "pending" } } ``` --- ### 12. 客户获取发票列表（小程序端） **请求** ```http GET /api/mini/client/invoices?status=&page=1&pageSize=10 Authorization: Bearer ``` **响应** ```json { "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. 客户获取发票详情（小程序端） **请求** ```http GET /api/mini/client/invoices/{invoiceId} Authorization: Bearer ``` **响应** ```json { "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. 客户获取已开票金额汇总（小程序端） **请求** ```http GET /api/mini/client/invoices/summary Authorization: Bearer ``` **响应** ```json { "code": 200, "data": { "totalInvoicedAmount": 1256000, "pendingInvoiceAmount": 358000, "issuedInvoiceAmount": 898000 } } ``` --- ### 15. 配送员获取时效预警列表（小程序端） **请求** ```http GET /api/mini/deliverer/tasks/expiring?withinMinutes=60 Authorization: Bearer ``` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | withinMinutes | int | 否 | 多少分钟内即将过期，默认60 | **响应** ```json { "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端） **请求** ```http GET /api/web/users/password-history?userId=&startDate=&endDate=&page=1&pageSize=10 Authorization: Bearer ``` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | userId | string | 否 | 用户ID | | startDate | string | 否 | 开始日期 | | endDate | string | 否 | 结束日期 | | page | int | 否 | 页码，默认1 | | pageSize | int | 否 | 每页条数，默认10 | **响应** ```json { "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. 多文件上传（通用） **请求** ```http POST /api/common/upload/multiple Content-Type: multipart/form-data Authorization: Bearer FormData: { files: [File, File, ...], businessType: "delivery_pickup", businessId: "DLV_001" } ``` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | files | File[] | 是 | 文件列表（最多10个） | | businessType | string | 否 | 业务类型 | | businessId | string | 否 | 业务ID | **响应** ```json { "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端） **请求** ```http GET /api/web/statistics/deliverer-efficiency?regionId=&delivererId=&startDate=&endDate= Authorization: Bearer ``` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | regionId | string | 否 | 区域ID | | delivererId | string | 否 | 配送员ID | | startDate | string | 否 | 开始日期 | | endDate | string | 否 | 结束日期 | **响应** ```json { "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. 配送员获取个人效率统计（小程序端） **请求** ```http GET /api/mini/deliverer/statistics/efficiency Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http POST /api/web/dicts Authorization: Bearer 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 | 否 | 排序 | **响应** ```json { "code": 200, "data": { "type": "product_tag", "createdCount": 3 } } ``` --- ### 21. 运营更新数据字典（Web端） **请求** ```http PUT /api/web/dicts/{type} Authorization: Bearer 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 } ] } ``` **响应** ```json { "code": 200, "data": { "type": "product_tag", "updatedCount": 4 } } ``` --- ### 22. 运营删除数据字典项（Web端） **请求** ```http DELETE /api/web/dicts/{type}/items/{value} Authorization: Bearer ``` **响应** ```json { "code": 200, "message": "删除成功" } ``` --- ## 附件模块 ### 1. 获取附件列表（Web端） **请求** ```http GET /api/web/attachments?businessType=&businessId=®ionId=&keyword=&startDate=&endDate=&page=1&pageSize=10 Authorization: Bearer ``` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | businessType | string | 否 | 业务类型 | | businessId | string | 否 | 业务ID | | regionId | string | 否 | 区域ID | | keyword | string | 否 | 文件名关键词搜索 | | startDate | string | 否 | 开始日期 | | endDate | string | 否 | 结束日期 | | page | int | 否 | 页码，默认1 | | pageSize | int | 否 | 每页条数，默认10 | **响应** ```json { "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端） **请求** ```http POST /api/web/attachments Content-Type: multipart/form-data Authorization: Bearer FormData: { file: File, businessType: "delivery_pickup", businessId: "DLV_001" } ``` **响应** ```json { "code": 200, "data": { "id": "ATT_001", "fileName": "取货照片1.jpg", "fileUrl": "https://cdn.example.com/attachments/xxx.jpg", "fileSize": 102400, "fileType": "image/jpeg" } } ``` --- ### 3. 删除附件（Web端） **请求** ```http DELETE /api/web/attachments/{attachmentId} Authorization: Bearer ``` --- ### 4. 小程序端上传配送凭证 **请求** ```http POST /api/mini/deliverer/tasks/{taskId}/upload-proof Content-Type: multipart/form-data Authorization: Bearer FormData: { file: File, proofType: "pickup", remark: "货物完好" } ``` | proofType | 说明 | |-----------|------| | pickup | 取货凭证 | | delivery | 送达凭证 | --- ## 系统设置模块 ### 1. 获取系统配置（Web端） **请求** ```http GET /api/web/system/config Authorization: Bearer ``` **响应** ```json { "code": 200, "data": { "deliveryExpireWarningMinutes": 60, "orderAutoCompleteDays": 7, "priceEffectiveType": "immediate", "maxRefundDays": 30 } } ``` --- ### 2. 更新系统配置（Web端） **请求** ```http PUT /api/web/system/config Authorization: Bearer Content-Type: application/json { "deliveryExpireWarningMinutes": 60, "orderAutoCompleteDays": 7, "priceEffectiveType": "immediate", "maxRefundDays": 30, "systemName": "叁强鲜配", "companyName": "叁强公司", "contactPhone": "400-888-8888" } ``` --- ### 3. 获取安全设置（Web端） **请求** ```http GET /api/web/system/security-config Authorization: Bearer ``` **响应** ```json { "code": 200, "data": { "passwordComplexity": "medium", "passwordComplexityText": "中等", "passwordExpireDays": 90, "passwordExpireDaysText": "90天", "sessionTimeoutMinutes": 30, "sessionTimeoutText": "30分钟" } } ``` --- ### 4. 更新安全设置（Web端） **请求** ```http PUT /api/web/system/security-config Authorization: Bearer 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端） **请求** ```http GET /api/web/dicts?type=order_status Authorization: Bearer ``` **响应** ```json { "code": 200, "data": { "order_status": [ { "value": "pending_payment", "label": "待支付" }, { "value": "pending_delivery", "label": "待分配配送" }, { "value": "delivering", "label": "配送中" }, { "value": "completed", "label": "已完成" }, { "value": "cancelled", "label": "已取消" } ] } } ``` --- ### 6. 获取系统配置（小程序端） **请求** ```http GET /api/mini/system/config Authorization: Bearer ``` **响应** ```json { "code": 200, "data": { "deliveryExpireWarningMinutes": 60, "orderAutoCompleteDays": 7, "systemName": "叁强鲜配", "companyName": "叁强公司", "contactPhone": "400-888-8888" } } ``` --- ### 7. 获取数据字典（小程序端） **请求** ```http GET /api/mini/dicts?type=order_status Authorization: Bearer ``` **响应** ```json { "code": 200, "data": { "order_status": [ { "value": "pending_payment", "label": "待支付" }, { "value": "pending_delivery", "label": "待分配配送" }, { "value": "delivering", "label": "配送中" }, { "value": "completed", "label": "已完成" }, { "value": "cancelled", "label": "已取消" } ] } } ``` --- ## 公共模块 ### 1. 获取字典数据 **请求** ```http GET /api/common/dicts?type=order_status Authorization: Bearer ``` --- ### 2. 文件上传 **请求** ```http POST /api/common/upload Content-Type: multipart/form-data Authorization: Bearer FormData: { file: File } ``` **响应** ```json { "code": 200, "data": { "url": "https://cdn.sanqiang.com/uploads/xxx.jpg", "fileName": "xxx.jpg", "fileSize": 102400, "fileType": "image/jpeg" } } ``` --- ### 3. 获取当前用户区域信息（小程序端） **请求** ```http GET /api/mini/common/my-region Authorization: Bearer ``` --- ### 4. 获取附件列表（Web端） **请求** ```http GET /api/web/attachments?businessType=delivery_pickup&businessId=ORDER_001 Authorization: Bearer ``` --- ### 5. 获取审计日志（Web端） **请求** ```http GET /api/web/audit-logs?module=order&operation=create&page=1 Authorization: Bearer ``` --- ### 6. 获取区域统计（Web端） **请求** ```http GET /api/web/regions/statistics?regionId=REGION_001 Authorization: Bearer ``` **响应** ```json { "code": 200, "data": { "todayOrderCount": 128, "todayOrderAmount": 5862000, "weekOrderCount": 856, "weekOrderAmount": 38920000, "monthOrderCount": 2560, "monthOrderAmount": 125680000, "supplierCount": 32, "clientCount": 456, "deliverCount": 18, "activePriceVersion": "V3" } } ``` --- ### 21. 客户催单（小程序端） **请求** ```http POST /api/mini/client/orders/{orderId}/urge Authorization: Bearer ``` **响应** ```json { "code": 200, "data": { "orderId": "ORDER_001", "urgeCount": 2, "lastUrgeTime": "2026-03-19T14:30:00+08:00", "message": "催单成功，配送员将尽快处理" } } ``` **说明** - 每个订单每天最多催单3次 - 催单后发送消息通知运营和配送员 --- ### 22. 运营获取可替代商品列表（Web端） **请求** ```http GET /api/web/products/substitutes?orderItemId=ITEM_001&categoryId=&keyword=&page=1&pageSize=20 Authorization: Bearer ``` | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | orderItemId | string | 是 | 原订单项ID | | categoryId | string | 否 | 商品分类ID | | keyword | string | 否 | 关键词搜索 | | page | int | 否 | 页码，默认1 | | pageSize | int | 否 | 每页条数，默认20 | **响应** ```json { "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 | 处理中 | #### 支付方式 | 状态 | 说明 | |------|------| | wechat | 微信支付 | | offline | 线下结算 | #### 登录结果 | 状态 | 说明 | |------|------| | success | 成功 | | failed | 失败 | --- ### 业务类型说明 #### 附件业务类型 | 类型 | 说明 | |------|------| | delivery_pickup | 取货凭证 | | delivery_delivery | 送达凭证 | | settlement_file | 结算文件 | | refund_file | 退款凭证 | | invoice | 发票文件 | #### 地址类型 | 类型 | 说明 | |------|------| | pickup | 取货地址 | | delivery | 配送地址 | | both | 两者皆是 | #### 订单调整类型 | 类型 | 说明 | |------|------| | reduce | 减量 | | delete | 删除 | | substitute | 替代 | | add | 补录 | #### 密码操作类型 | 类型 | 说明 | |------|------| | modify | 自主修改 | | reset | 重置 | #### 结算方式 | 类型 | 说明 | |------|------| | transfer | 转账 | | cash | 现金 | | other | 其他 | #### 退款方式 | 类型 | 说明 | |------|------| | wechat | 微信原路退回 | | 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 | 数量精度错误 | 小数位数超出限制 | --- ### 异常响应格式 #### 通用错误响应 ```json { "code": 400, "message": "参数校验失败", "data": null, "timestamp": 1700000000000, "errors": [ { "field": "username", "message": "用户名不能为空" } ] } ``` #### 业务异常响应 ```json { "code": 1002, "message": "订单已被锁定", "data": { "orderId": "ORDER_001", "lockOperator": "张三", "lockTime": "2026-03-19T10:00:00+08:00" }, "timestamp": 1700000000000 } ``` #### 权限异常响应 ```json { "code": 403, "message": "无权限访问该资源", "data": null, "timestamp": 1700000000000 } ``` #### 认证异常响应 ```json { "code": 401, "message": "Token已过期，请重新登录", "data": null, "timestamp": 1700000000000 } ``` --- ### 异常处理流程 ``` ┌─────────────────┐ │ 请求到达 │ └────────┬────────┘ ▼ ┌─────────────────┐ │ 参数校验 │──失败──▶ 返回400错误 + errors └────────┬────────┘ │成功 ▼ ┌─────────────────┐ │ 认证校验 │──失败──▶ 返回401错误 └────────┬────────┘ │成功 ▼ ┌─────────────────┐ │ 权限校验 │──失败──▶ 返回403错误 └────────┬────────┘ │成功 ▼ ┌─────────────────┐ │ 业务规则校验 │──失败──▶ 返回业务错误码 └────────┬────────┘ │成功 ▼ ┌─────────────────┐ │ 业务处理 │──失败──▶ 返回500错误 └────────┬────────┘ │成功 ▼ ┌─────────────────┐ │ 返回成功响应 │ └─────────────────┘ ``` --- ### 日志记录要求 | 级别 | 记录内容 | 示例 | |------|----------|------| | INFO | 正常业务操作 | 登录、订单创建、状态变更 | | WARN | 业务异常 | 库存不足、支付失败、参数校验失败 | | ERROR | 系统异常 | 数据库错误、第三方接口超时、空指针异常 | #### 日志记录规范 ```java // 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. 配送员获取个人效率统计（小程序端） **请求** ```http GET /api/mini/deliverer/statistics/efficiency Authorization: Bearer ``` **响应** ```json { "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. 供应商获取工作台统计数据（小程序端） **请求** ```http GET /api/mini/supplier/dashboard/statistics Authorization: Bearer ``` **响应** ```json { "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. 客户获取工作台统计数据（小程序端） **请求** ```http GET /api/mini/client/dashboard/statistics Authorization: Bearer ``` **响应** ```json { "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端） **请求** ```http GET /api/web/invoices/{invoiceId}/download Authorization: Bearer ``` **响应** 返回PDF文件流 ``` Content-Type: application/pdf Content-Disposition: attachment; filename="INV20260319001.pdf" ``` ### 15.5. 客户下载发票PDF（小程序端） **请求** ```http GET /api/mini/client/invoices/{invoiceId}/download Authorization: Bearer ``` **响应** 返回PDF文件流 --- ### 新增接口 - 小程序端系统配置 ### 8. 获取小程序版本信息（小程序端） **请求** ```http GET /api/mini/system/version ``` **响应** ```json { "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端/小程序端） **请求** ```http GET /api/common/geocoder/address-to-coord?address=广东省深圳市南山区科技园 Authorization: Bearer ``` **响应** ```json { "code": 200, "data": { "address": "广东省深圳市南山区科技园", "province": "广东省", "city": "深圳市", "district": "南山区", "latitude": 22.543, "longitude": 113.952 } } ``` --- ### 新增接口 - 供应商/客户信息（小程序端） ### 18.5. 供应商获取本区域供应商列表（小程序端） **请求** ```http GET /api/mini/common/suppliers Authorization: Bearer ``` **响应** ```json { "code": 200, "data": [ { "id": "USER_010", "supplierName": "张伟供应商", "contactPerson": "张伟", "contactPhone": "13800138001", "address": "福田区XX路XX号", "latitude": 22.543, "longitude": 113.952 } ] } ``` **说明** - 返回当前用户所属区域的所有供应商信息 - 配送员可用此接口查询供应商地址用于导航 ---