taiyi/dingdanquanliucheng
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
dd8a489a8b
dingdanquanliucheng/系统标准API文档.md

1022 lines
21 KiB
Markdown
Raw Normal View History

完成项目规划
2026-05-06 11:57:56 +08:00
# 订单管理系统标准 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》为准。
Reference in New Issue Copy Permalink