1022 lines
21 KiB
Markdown
1022 lines
21 KiB
Markdown
# 订单管理系统标准 API 文档
|
||
|
||
- 项目名称：订单管理系统
|
||
- 文档版本：V1.0
|
||
- 文档类型：标准 API 文档
|
||
- 适用范围：WEB 业务员端、小程序管理层端、小程序司机端、WEB 管理后台
|
||
- 编写日期：2026-05-05
|
||
|
||
---
|
||
|
||
## 1. 文档说明
|
||
|
||
本文档用于描述订单管理系统的标准接口规范，包括接口分组、请求方法、路径、鉴权要求、请求参数、响应参数、错误码、状态码、字段说明和示例。
|
||
|
||
### 1.1 统一约定
|
||
|
||
- 接口采用 `HTTP/HTTPS + JSON`。
|
||
- 除登录接口外，所有接口均需携带身份凭证。
|
||
- 列表接口统一支持分页。
|
||
- 成功响应统一返回 `code = 0`。
|
||
- 失败响应统一返回非 0 状态码，并返回明确错误信息。
|
||
- 涉及敏感字段时，按角色做脱敏或隐藏。
|
||
|
||
### 1.2 通用响应体
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
### 1.3 分页响应体
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"total": 100,
|
||
"page_no": 1,
|
||
"page_size": 20,
|
||
"list": []
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 鉴权与权限
|
||
|
||
### 2.1 鉴权方式
|
||
|
||
- 登录成功后返回 `token`。
|
||
- 后续请求通过请求头携带 `Authorization: Bearer <token>`。
|
||
|
||
### 2.2 权限范围
|
||
|
||
- 业务员：仅可访问本人订单、本人客户、本人相关提醒。
|
||
- 管理层：可访问全量订单、审批、利润、报表等。
|
||
- 司机：仅可访问自己的任务和任务相关信息。
|
||
- 管理员：可访问系统基础资料、配置、用户、角色、菜单等。
|
||
|
||
### 2.3 字段级权限
|
||
|
||
- 成本、利润、回扣、报价等财务数据仅管理层和管理员可见。
|
||
- 司机端不得查看客户敏感信息。
|
||
- 未授权字段应在接口层直接屏蔽，不应返回前端后再隐藏。
|
||
|
||
---
|
||
|
||
## 3. 统一错误码
|
||
|
||
| 错误码 | 说明 |
|
||
| --- | --- |
|
||
| 0 | 成功 |
|
||
| 40001 | 参数错误 |
|
||
| 40002 | 未登录或登录失效 |
|
||
| 40003 | 无权限 |
|
||
| 40004 | 资源不存在 |
|
||
| 40005 | 状态不允许当前操作 |
|
||
| 40006 | 数据重复 |
|
||
| 40007 | 业务规则校验失败 |
|
||
| 40008 | 文件上传失败 |
|
||
| 40009 | 第三方接口调用失败 |
|
||
| 50000 | 系统异常 |
|
||
|
||
---
|
||
|
||
## 4. 状态码规范
|
||
|
||
### 4.1 订单状态
|
||
|
||
| 状态值 | 状态名称 |
|
||
| --- | --- |
|
||
| draft | 草稿 |
|
||
| pending_approve | 待审核 |
|
||
| approved | 已通过 |
|
||
| rejected | 已退回 |
|
||
| pending_factory | 待下发工厂 |
|
||
| pending_driver | 待司机接单 |
|
||
| accepted | 已接单 |
|
||
| picked_up | 已揽货 |
|
||
| delivered | 已送达 |
|
||
| production | 生产中 |
|
||
| shipped | 已发货 |
|
||
| completed | 已完成 |
|
||
| settled | 已结算 |
|
||
| canceled | 已取消 |
|
||
|
||
### 4.2 任务状态
|
||
|
||
| 状态值 | 状态名称 |
|
||
| --- | --- |
|
||
| pending | 待接单 |
|
||
| accepted | 已接单 |
|
||
| picked_up | 已揽货 |
|
||
| delivered | 已送达 |
|
||
| canceled | 已取消 |
|
||
|
||
### 4.3 提醒状态
|
||
|
||
| 状态值 | 状态名称 |
|
||
| --- | --- |
|
||
| pending | 待发送 |
|
||
| sent | 已发送 |
|
||
| read | 已读 |
|
||
| canceled | 已取消 |
|
||
|
||
### 4.4 审批结果
|
||
|
||
| 状态值 | 状态名称 |
|
||
| --- | --- |
|
||
| pass | 通过 |
|
||
| reject | 退回 |
|
||
| refuse | 拒绝 |
|
||
|
||
---
|
||
|
||
## 5. 接口分组
|
||
|
||
- 认证接口
|
||
- 订单接口
|
||
- 审批接口
|
||
- 客户接口
|
||
- 产品接口
|
||
- 工厂/供应商接口
|
||
- 司机任务接口
|
||
- 物流与 AI 接口
|
||
- 提醒接口
|
||
- 报表接口
|
||
- 配置接口
|
||
- 审计日志接口
|
||
|
||
---
|
||
|
||
## 6. 认证接口
|
||
|
||
### 6.1 用户登录
|
||
|
||
**接口名称：** 用户登录
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**路径：** `/api/auth/login`
|
||
|
||
**是否鉴权：** 否
|
||
|
||
#### 请求参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| username | string | 是 | 登录账号 |
|
||
| password | string | 是 | 登录密码 |
|
||
| role_type | string | 是 | 角色类型 |
|
||
|
||
#### 响应参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| user_id | number | 用户ID |
|
||
| real_name | string | 姓名 |
|
||
| role_id | number | 角色ID |
|
||
| role_name | string | 角色名称 |
|
||
| token | string | 登录凭证 |
|
||
| menus | array | 菜单列表 |
|
||
| permissions | array | 权限列表 |
|
||
|
||
#### 示例响应
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"user_id": 1,
|
||
"real_name": "张三",
|
||
"role_id": 2,
|
||
"role_name": "业务员",
|
||
"token": "xxxxx",
|
||
"menus": [],
|
||
"permissions": []
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6.2 当前用户信息
|
||
|
||
**接口名称：** 当前用户信息
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**路径：** `/api/auth/me`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
#### 响应参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| user_id | number | 用户ID |
|
||
| username | string | 账号 |
|
||
| real_name | string | 姓名 |
|
||
| mobile | string | 手机号 |
|
||
| role_id | number | 角色ID |
|
||
| role_name | string | 角色名称 |
|
||
| menus | array | 菜单列表 |
|
||
| permissions | array | 权限列表 |
|
||
|
||
---
|
||
|
||
### 6.3 退出登录
|
||
|
||
**接口名称：** 退出登录
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**路径：** `/api/auth/logout`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
---
|
||
|
||
## 7. 订单接口
|
||
|
||
### 7.1 创建订单
|
||
|
||
**接口名称：** 销售单录入
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**路径：** `/api/orders`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
#### 请求参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| customer_name | string | 是 | 客户姓名 |
|
||
| customer_mobile | string | 是 | 客户手机号 |
|
||
| customer_address | string | 否 | 客户地址 |
|
||
| order_source | string | 否 | 订单来源标签 |
|
||
| delivery_type | string | 否 | 发货类型 |
|
||
| factory_id | number | 否 | 工厂ID |
|
||
| remark | string | 否 | 备注 |
|
||
| rebate_total | number | 否 | 回扣总额 |
|
||
| freight_total | number | 否 | 运费总额 |
|
||
| tax_total | number | 否 | 税费总额 |
|
||
| other_fee_total | number | 否 | 其他费用总额 |
|
||
| items | array | 是 | 订单明细 |
|
||
|
||
#### items 明细字段
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| product_id | number | 否 | 产品ID |
|
||
| product_name | string | 是 | 产品名称 |
|
||
| specification | string | 是 | 规格 |
|
||
| unit | string | 是 | 单位 |
|
||
| quantity | number | 是 | 数量 |
|
||
| sale_price | number | 是 | 销售单价 |
|
||
| cost_price | number | 是 | 成本单价 |
|
||
| rebate_amount | number | 否 | 回扣金额 |
|
||
| freight_amount | number | 否 | 运费分摊 |
|
||
| tax_amount | number | 否 | 税费分摊 |
|
||
| other_fee_amount | number | 否 | 其他费用分摊 |
|
||
| remark | string | 否 | 备注 |
|
||
|
||
#### 响应参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| order_id | number | 订单ID |
|
||
| order_no | string | 订单编号 |
|
||
| order_status | string | 订单状态 |
|
||
| profit_total | number | 利润 |
|
||
| profit_rate | number | 利润率 |
|
||
|
||
#### 业务规则
|
||
|
||
- 新客户按姓名 + 手机号自动写入客户库。
|
||
- 新订单默认进入草稿状态。
|
||
- 订单保存后需记录创建人和时间。
|
||
|
||
---
|
||
|
||
### 7.2 提交订单审核
|
||
|
||
**接口名称：** 订单提交审核
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**路径：** `/api/orders/{order_id}/submit`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
#### 路径参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| order_id | number | 订单ID |
|
||
|
||
#### 响应参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| order_id | number | 订单ID |
|
||
| order_status | string | 状态 |
|
||
| submitted_at | string | 提交时间 |
|
||
|
||
---
|
||
|
||
### 7.3 订单详情
|
||
|
||
**接口名称：** 订单详情
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**路径：** `/api/orders/{order_id}`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
#### 路径参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| order_id | number | 订单ID |
|
||
|
||
#### 响应参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| order_id | number | 订单ID |
|
||
| order_no | string | 订单编号 |
|
||
| customer_id | number | 客户ID |
|
||
| customer_name | string | 客户姓名 |
|
||
| customer_mobile | string | 客户手机号 |
|
||
| salesman_id | number | 业务员ID |
|
||
| order_source | string | 来源标签 |
|
||
| order_status | string | 订单状态 |
|
||
| delivery_type | string | 发货类型 |
|
||
| factory_id | number | 工厂ID |
|
||
| sale_price_total | number | 销售价总额 |
|
||
| cost_price_total | number | 成本价总额 |
|
||
| rebate_total | number | 回扣总额 |
|
||
| freight_total | number | 运费总额 |
|
||
| tax_total | number | 税费总额 |
|
||
| other_fee_total | number | 其他费用总额 |
|
||
| profit_total | number | 利润 |
|
||
| profit_rate | number | 利润率 |
|
||
| items | array | 明细 |
|
||
| approve_logs | array | 审批记录 |
|
||
| logistics_info | object | 物流信息 |
|
||
| remark | string | 备注 |
|
||
|
||
---
|
||
|
||
### 7.4 订单列表
|
||
|
||
**接口名称：** 订单列表
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**路径：** `/api/orders`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
#### 查询参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| order_status | string | 订单状态 |
|
||
| customer_name | string | 客户姓名 |
|
||
| customer_mobile | string | 客户手机号 |
|
||
| salesman_id | number | 业务员ID |
|
||
| factory_id | number | 工厂ID |
|
||
| order_source | string | 订单来源 |
|
||
| start_time | string | 开始时间 |
|
||
| end_time | string | 结束时间 |
|
||
| page_no | number | 页码 |
|
||
| page_size | number | 每页条数 |
|
||
|
||
#### 响应参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| total | number | 总数 |
|
||
| page_no | number | 页码 |
|
||
| page_size | number | 每页条数 |
|
||
| list | array | 数据列表 |
|
||
|
||
---
|
||
|
||
### 7.5 订单取消
|
||
|
||
**接口名称：** 订单取消
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**路径：** `/api/orders/{order_id}/cancel`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
#### 请求参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| order_id | number | 是 | 订单ID |
|
||
| cancel_reason | string | 是 | 取消原因 |
|
||
| cancel_opinion | string | 否 | 取消意见 |
|
||
|
||
#### 响应参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| order_id | number | 订单ID |
|
||
| order_status | string | 取消后状态 |
|
||
| canceled_at | string | 取消时间 |
|
||
|
||
#### 业务规则
|
||
|
||
- 草稿、待审核订单可直接取消。
|
||
- 已通过订单需何总确认。
|
||
- 已进入履约阶段的订单需特殊审批。
|
||
|
||
---
|
||
|
||
### 7.6 订单状态变更
|
||
|
||
**接口名称：** 订单状态变更
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**路径：** `/api/orders/{order_id}/status`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
#### 请求参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| order_id | number | 是 | 订单ID |
|
||
| target_status | string | 是 | 目标状态 |
|
||
| remark | string | 否 | 备注 |
|
||
|
||
#### 响应参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| order_id | number | 订单ID |
|
||
| order_status | string | 变更后状态 |
|
||
|
||
---
|
||
|
||
## 8. 审批接口
|
||
|
||
### 8.1 销售单最终审批
|
||
|
||
**接口名称：** 销售单最终审批
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**路径：** `/api/orders/{order_id}/approve`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
#### 请求参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| order_id | number | 是 | 订单ID |
|
||
| approve_result | string | 是 | 审批结果 |
|
||
| approve_opinion | string | 否 | 审批意见 |
|
||
|
||
#### 响应参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| order_id | number | 订单ID |
|
||
| order_status | string | 审批后状态 |
|
||
| profit_total | number | 利润 |
|
||
| profit_rate | number | 利润率 |
|
||
| approve_time | string | 审批时间 |
|
||
|
||
#### 业务规则
|
||
|
||
- 审核时需展示利润计算过程。
|
||
- 审批结果为通过或退回。
|
||
|
||
---
|
||
|
||
### 8.2 取消审批
|
||
|
||
**接口名称：** 取消审批
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**路径：** `/api/orders/{order_id}/cancel-approve`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
#### 请求参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| order_id | number | 是 | 订单ID |
|
||
| approve_result | string | 是 | 审批结果 |
|
||
| approve_opinion | string | 否 | 审批意见 |
|
||
|
||
#### 响应参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| order_id | number | 订单ID |
|
||
| order_status | string | 变更后状态 |
|
||
|
||
---
|
||
|
||
## 9. 客户接口
|
||
|
||
### 9.1 新增客户
|
||
|
||
**接口名称：** 客户新增
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**路径：** `/api/customers`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
#### 请求参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| customer_name | string | 是 | 客户姓名 |
|
||
| mobile | string | 是 | 手机号 |
|
||
| address | string | 否 | 地址 |
|
||
| settlement_type | string | 否 | 结算方式 |
|
||
| settlement_days | number | 否 | 月结天数 |
|
||
| settlement_start_type | string | 否 | 账期起算口径 |
|
||
| customer_type | string | 否 | 客户类型 |
|
||
| salesman_id | number | 否 | 归属业务员ID |
|
||
| credit_limit | number | 否 | 信用额度 |
|
||
| remark | string | 否 | 备注 |
|
||
|
||
#### 响应参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| customer_id | number | 客户ID |
|
||
| customer_name | string | 客户姓名 |
|
||
| mobile | string | 手机号 |
|
||
|
||
---
|
||
|
||
### 9.2 客户列表
|
||
|
||
**接口名称：** 客户列表
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**路径：** `/api/customers`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
#### 查询参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| customer_name | string | 客户姓名 |
|
||
| mobile | string | 手机号 |
|
||
| customer_type | string | 客户类型 |
|
||
| settlement_type | string | 结算方式 |
|
||
| salesman_id | number | 业务员ID |
|
||
| page_no | number | 页码 |
|
||
| page_size | number | 每页条数 |
|
||
|
||
---
|
||
|
||
### 9.3 客户详情
|
||
|
||
**接口名称：** 客户详情
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**路径：** `/api/customers/{customer_id}`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
#### 响应参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| customer_id | number | 客户ID |
|
||
| customer_name | string | 客户姓名 |
|
||
| mobile | string | 手机号 |
|
||
| address | string | 地址 |
|
||
| settlement_type | string | 结算方式 |
|
||
| settlement_days | number | 月结天数 |
|
||
| settlement_start_type | string | 账期起算口径 |
|
||
| customer_type | string | 客户类型 |
|
||
| salesman_id | number | 归属业务员ID |
|
||
| credit_limit | number | 信用额度 |
|
||
| arrears_amount | number | 欠款金额 |
|
||
| status | string | 状态 |
|
||
| remark | string | 备注 |
|
||
|
||
---
|
||
|
||
### 9.4 客户导入
|
||
|
||
**接口名称：** 客户批量导入
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**路径：** `/api/customers/import`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
#### 请求参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| file_url | string | 是 | 导入文件地址 |
|
||
| import_mode | string | 否 | 导入模式 |
|
||
|
||
#### 响应参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| total_count | number | 总条数 |
|
||
| success_count | number | 成功条数 |
|
||
| duplicate_count | number | 重复条数 |
|
||
| fail_count | number | 失败条数 |
|
||
| fail_list | array | 失败明细 |
|
||
|
||
---
|
||
|
||
## 10. 产品接口
|
||
|
||
### 10.1 新增产品
|
||
|
||
**接口名称：** 产品新增
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**路径：** `/api/products`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
#### 请求参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| product_name | string | 是 | 产品名称 |
|
||
| specification | string | 是 | 规格 |
|
||
| unit | string | 是 | 单位 |
|
||
| category | string | 是 | 分类 |
|
||
| cost_price | number | 是 | 成本价 |
|
||
| sale_price | number | 是 | 售价 |
|
||
| status | string | 是 | 状态 |
|
||
| remark | string | 否 | 备注 |
|
||
|
||
---
|
||
|
||
### 10.2 产品列表
|
||
|
||
**接口名称：** 产品列表
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**路径：** `/api/products`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
#### 查询参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| product_name | string | 产品名称 |
|
||
| specification | string | 规格 |
|
||
| category | string | 分类 |
|
||
| status | string | 状态 |
|
||
| page_no | number | 页码 |
|
||
| page_size | number | 每页条数 |
|
||
|
||
---
|
||
|
||
### 10.3 产品详情
|
||
|
||
**接口名称：** 产品详情
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**路径：** `/api/products/{product_id}`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
---
|
||
|
||
## 11. 工厂/供应商接口
|
||
|
||
### 11.1 新增工厂/供应商
|
||
|
||
**接口名称：** 工厂新增
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**路径：** `/api/suppliers`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
#### 请求参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| supplier_name | string | 是 | 名称 |
|
||
| supplier_type | string | 是 | 类型 |
|
||
| contact_name | string | 否 | 联系人 |
|
||
| contact_mobile | string | 否 | 联系电话 |
|
||
| address | string | 否 | 地址 |
|
||
| template_type | string | 否 | 模板类型 |
|
||
| status | string | 是 | 状态 |
|
||
| remark | string | 否 | 备注 |
|
||
|
||
---
|
||
|
||
### 11.2 工厂列表
|
||
|
||
**接口名称：** 工厂列表
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**路径：** `/api/suppliers`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
---
|
||
|
||
### 11.3 下发文本生成
|
||
|
||
**接口名称：** 工厂下发文本生成
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**路径：** `/api/orders/{order_id}/supplier-text`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
#### 请求参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| order_id | number | 是 | 订单ID |
|
||
| supplier_id | number | 是 | 工厂/供应商ID |
|
||
|
||
#### 响应参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| text_content | string | 可复制文本 |
|
||
| template_type | string | 模板类型 |
|
||
|
||
---
|
||
|
||
## 12. 司机任务接口
|
||
|
||
### 12.1 任务列表
|
||
|
||
**接口名称：** 司机任务列表
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**路径：** `/api/driver/tasks`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
#### 查询参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| status | string | 任务状态 |
|
||
| page_no | number | 页码 |
|
||
| page_size | number | 每页条数 |
|
||
|
||
---
|
||
|
||
### 12.2 任务详情
|
||
|
||
**接口名称：** 司机任务详情
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**路径：** `/api/driver/tasks/{task_id}`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
---
|
||
|
||
### 12.3 接单
|
||
|
||
**接口名称：** 司机接单
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**路径：** `/api/driver/tasks/{task_id}/accept`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
### 12.4 确认揽货
|
||
|
||
**接口名称：** 司机确认揽货
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**路径：** `/api/driver/tasks/{task_id}/pickup`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
### 12.5 确认送达
|
||
|
||
**接口名称：** 司机确认送达
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**路径：** `/api/driver/tasks/{task_id}/deliver`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
---
|
||
|
||
## 13. 物流与 AI 接口
|
||
|
||
### 13.1 物流查询
|
||
|
||
**接口名称：** 物流查询
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**路径：** `/api/logistics/{order_id}/trace`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
### 13.2 AI 图片识别
|
||
|
||
**接口名称：** AI 图片识别
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**路径：** `/api/ai/recognize`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
### 13.3 AI 识别结果修正
|
||
|
||
**接口名称：** AI 识别结果修正
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**路径：** `/api/ai/recognize/{log_id}/correct`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
---
|
||
|
||
## 14. 提醒接口
|
||
|
||
### 14.1 欠款提醒检查
|
||
|
||
**接口名称：** 欠款提醒检查
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**路径：** `/api/reminders/arrears/check`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
### 14.2 长时间未下单提醒检查
|
||
|
||
**接口名称：** 长时间未下单提醒检查
|
||
|
||
**请求方式：** `POST`
|
||
|
||
**路径：** `/api/reminders/inactive-customers/check`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
---
|
||
|
||
## 15. 报表接口
|
||
|
||
### 15.1 业绩统计
|
||
|
||
**接口名称：** 业绩统计
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**路径：** `/api/reports/performance`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
### 15.2 报表导出
|
||
|
||
**接口名称：** 业绩报表导出
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**路径：** `/api/reports/performance/export`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
---
|
||
|
||
## 16. 配置接口
|
||
|
||
### 16.1 配置查询
|
||
|
||
**接口名称：** 配置查询
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**路径：** `/api/configs/{config_key}`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
### 16.2 配置更新
|
||
|
||
**接口名称：** 配置更新
|
||
|
||
**请求方式：** `PUT`
|
||
|
||
**路径：** `/api/configs/{config_key}`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
---
|
||
|
||
## 17. 审计日志接口
|
||
|
||
### 17.1 日志列表
|
||
|
||
**接口名称：** 审计日志列表
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**路径：** `/api/audit-logs`
|
||
|
||
**是否鉴权：** 是
|
||
|
||
#### 查询参数
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| biz_type | string | 业务类型 |
|
||
| biz_id | number | 业务ID |
|
||
| operator_name | string | 操作人 |
|
||
| start_time | string | 开始时间 |
|
||
| end_time | string | 结束时间 |
|
||
| page_no | number | 页码 |
|
||
| page_size | number | 每页条数 |
|
||
|
||
---
|
||
|
||
## 18. 接口补充说明
|
||
|
||
### 18.1 错误处理
|
||
|
||
- 所有接口错误都必须返回统一结构。
|
||
- 不能仅返回文本消息。
|
||
- 第三方失败需记录原始异常并转换为 `40009`。
|
||
|
||
### 18.2 状态流转限制
|
||
|
||
- 若目标状态不允许，返回 `40005`。
|
||
- 若资源不存在，返回 `40004`。
|
||
- 若重复提交，返回 `40006`。
|
||
|
||
### 18.3 字段保留策略
|
||
|
||
- 订单、审批、物流、识别、附件等均保留历史快照。
|
||
- 不建议直接修改历史快照字段，除非业务上确有修正记录。
|
||
|
||
---
|
||
|
||
## 19. 字段映射检查表
|
||
|
||
为了统一《确定版需求说明书》《数据库.sql》《系统标准API文档》的字段口径，新增《字段映射检查表.md》作为三份文档之间的字段对照依据。
|
||
|
||
字段映射检查表定义了：
|
||
|
||
- 核心业务对象的统一字段名
|
||
- 数据库字段命名
|
||
- API 字段命名
|
||
- 状态字段统一口径
|
||
- 三份文档的对齐说明
|
||
|
||
后续接口联调、前后端协作、数据库建模均以三份文档及《字段映射检查表.md》为准。
|