# 订单管理系统标准 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》为准。