1546 lines
27 KiB
Markdown
1546 lines
27 KiB
Markdown
# API 细化设计
|
||
|
||
## 1. 通用规范
|
||
|
||
### 1.1 基础约定
|
||
|
||
| 项 | 约定 |
|
||
| --- | --- |
|
||
| Base URL | `/api` |
|
||
| 协议 | HTTP/HTTPS + JSON |
|
||
| 鉴权 | `Authorization: Bearer <token>` |
|
||
| 时间格式 | `YYYY-MM-DD HH:mm:ss` |
|
||
| 日期格式 | `YYYY-MM-DD` |
|
||
| 金额格式 | number，保留 2 位小数 |
|
||
| 数量格式 | number，最多 4 位小数 |
|
||
|
||
### 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": []
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.4 错误码
|
||
|
||
| code | 含义 | 典型场景 |
|
||
| --- | --- | --- |
|
||
| 0 | 成功 | 正常返回 |
|
||
| 40001 | 参数错误 | 必填缺失、格式错误、金额非法 |
|
||
| 40002 | 未登录或登录失效 | token 缺失、过期、无效 |
|
||
| 40003 | 无权限 | 角色无权限、越权访问他人数据 |
|
||
| 40004 | 资源不存在 | ID 不存在或已逻辑删除 |
|
||
| 40005 | 状态不允许当前操作 | 重复提交、非法状态流转 |
|
||
| 40006 | 数据重复 | 客户姓名 + 手机号重复、编号重复 |
|
||
| 40007 | 业务规则校验失败 | 利润计算异常、欠款规则不满足 |
|
||
| 40008 | 文件上传失败 | OSS 上传失败 |
|
||
| 40009 | 第三方接口调用失败 | 阿里云 OCR/模型失败、快递 100 失败 |
|
||
| 50000 | 系统异常 | 未预期异常 |
|
||
|
||
## 2. 枚举定义
|
||
|
||
### 2.1 角色类型
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `salesman` | 业务员 |
|
||
| `manager` | 管理层 |
|
||
| `driver` | 司机 |
|
||
| `admin` | 管理员 |
|
||
|
||
### 2.2 订单状态
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `draft` | 草稿 |
|
||
| `pending_approve` | 待审核 |
|
||
| `approved` | 已通过，待生成/确认下发工厂文本 |
|
||
| `rejected` | 已退回 |
|
||
| `pending_factory` | 待下发工厂或已确认下发工厂待处理 |
|
||
| `pending_driver` | 待司机接单 |
|
||
| `accepted` | 已接单 |
|
||
| `picked_up` | 已揽货 |
|
||
| `delivered` | 已送达 |
|
||
| `production` | 生产中 |
|
||
| `shipped` | 已发货 |
|
||
| `completed` | 已完成 |
|
||
| `settled` | 已结算 |
|
||
| `cancel_pending` | 取消申请中 |
|
||
| `canceled` | 已取消 |
|
||
|
||
### 2.3 任务状态
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `pending` | 待接单 |
|
||
| `accepted` | 已接单 |
|
||
| `picked_up` | 已揽货 |
|
||
| `delivered` | 已送达 |
|
||
| `canceled` | 已取消 |
|
||
|
||
### 2.4 审批结果
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `pass` | 通过 |
|
||
| `reject` | 退回 |
|
||
| `refuse` | 拒绝 |
|
||
|
||
### 2.5 欠款生成模式
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `shipped` | 订单进入已发货时生成欠款 |
|
||
| `delivered` | 订单进入已送达时生成欠款，默认值 |
|
||
|
||
### 2.6 提醒状态
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `pending` | 待发送 |
|
||
| `sent` | 已发送 |
|
||
| `read` | 已读 |
|
||
| `canceled` | 已取消 |
|
||
|
||
## 3. 认证接口
|
||
|
||
### 3.1 登录
|
||
|
||
| 项 | 内容 |
|
||
| --- | --- |
|
||
| Method | `POST` |
|
||
| Path | `/api/auth/login` |
|
||
| Auth | 否 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"username": "sales01",
|
||
"password": "123456",
|
||
"role_type": "salesman"
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"user_id": 1,
|
||
"username": "sales01",
|
||
"real_name": "张三",
|
||
"mobile": "13800000000",
|
||
"role_id": 2,
|
||
"role_name": "业务员",
|
||
"role_code": "salesman",
|
||
"token": "jwt-token",
|
||
"menus": [],
|
||
"permissions": []
|
||
}
|
||
```
|
||
|
||
#### 错误场景
|
||
|
||
| 场景 | code |
|
||
| --- | --- |
|
||
| 账号或密码为空 | 40001 |
|
||
| 账号不存在或密码错误 | 40002 |
|
||
| 账号停用 | 40003 |
|
||
| 登录角色与账号角色不匹配 | 40003 |
|
||
|
||
### 3.2 当前用户
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `GET` | `/api/auth/me` | 是 |
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"user_id": 1,
|
||
"username": "sales01",
|
||
"real_name": "张三",
|
||
"mobile": "13800000000",
|
||
"role_id": 2,
|
||
"role_name": "业务员",
|
||
"role_code": "salesman",
|
||
"menus": [],
|
||
"permissions": []
|
||
}
|
||
```
|
||
|
||
### 3.3 退出登录
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/auth/logout` | 是 |
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
## 4. 订单接口
|
||
|
||
### 4.1 创建订单
|
||
|
||
| Method | Path | Auth | 权限 |
|
||
| --- | --- | --- | --- |
|
||
| `POST` | `/api/orders` | 是 | 业务员、管理员 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"customer_name": "李四",
|
||
"customer_mobile": "13900000000",
|
||
"customer_address": "江苏省xx市xx路",
|
||
"order_source": "线下",
|
||
"delivery_type": "物流",
|
||
"factory_id": 1001,
|
||
"commission_amount": 50.00,
|
||
"rebate_total": 5.00,
|
||
"freight_total": 10.00,
|
||
"tax_total": 3.00,
|
||
"other_fee_total": 2.00,
|
||
"remark": "备注",
|
||
"items": [
|
||
{
|
||
"product_id": 2001,
|
||
"product_name": "产品A",
|
||
"specification": "10kg",
|
||
"unit": "袋",
|
||
"quantity": 1,
|
||
"sale_price": 100.00,
|
||
"cost_price": 60.00,
|
||
"rebate_amount": 5.00,
|
||
"freight_amount": 10.00,
|
||
"tax_amount": 3.00,
|
||
"other_fee_amount": 2.00,
|
||
"remark": "明细备注"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"order_id": 9001,
|
||
"order_no": "SO202605140001",
|
||
"order_status": "draft",
|
||
"sale_price_total": 100.00,
|
||
"cost_price_total": 60.00,
|
||
"profit_total": 20.00,
|
||
"profit_rate": 20.00,
|
||
"commission_amount": 50.00
|
||
}
|
||
```
|
||
|
||
#### 规则
|
||
|
||
| 规则 | 说明 |
|
||
| --- | --- |
|
||
| 新客户同步 | 姓名 + 手机号不存在时自动创建客户 |
|
||
| 默认状态 | `draft` |
|
||
| 利润公式 | 销售额 - 成本 - 回扣 - 运费 - 税费 - 其他费用 |
|
||
| 固定提成 | 只保存，不参与利润公式 |
|
||
|
||
#### 错误场景
|
||
|
||
| 场景 | code |
|
||
| --- | --- |
|
||
| 客户姓名或手机号为空 | 40001 |
|
||
| 明细为空 | 40001 |
|
||
| 数量小于等于 0 | 40001 |
|
||
| 金额小于 0 | 40001 |
|
||
| 工厂不存在 | 40004 |
|
||
|
||
### 4.2 提交审核
|
||
|
||
| Method | Path | Auth | 权限 |
|
||
| --- | --- | --- | --- |
|
||
| `POST` | `/api/orders/{order_id}/submit` | 是 | 订单创建人、管理员 |
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"order_id": 9001,
|
||
"order_status": "pending_approve",
|
||
"submitted_at": "2026-05-14 10:00:00"
|
||
}
|
||
```
|
||
|
||
#### 错误场景
|
||
|
||
| 场景 | code |
|
||
| --- | --- |
|
||
| 订单不存在 | 40004 |
|
||
| 非本人订单 | 40003 |
|
||
| 当前状态不是 `draft/rejected` | 40005 |
|
||
| 明细不完整 | 40007 |
|
||
|
||
### 4.3 订单详情
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `GET` | `/api/orders/{order_id}` | 是 |
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"order_id": 9001,
|
||
"order_no": "SO202605140001",
|
||
"customer_id": 3001,
|
||
"customer_name": "李四",
|
||
"customer_mobile": "13900000000",
|
||
"customer_address": "江苏省xx市xx路",
|
||
"salesman_id": 1,
|
||
"salesman_name": "张三",
|
||
"order_source": "线下",
|
||
"order_status": "approved",
|
||
"delivery_type": "物流",
|
||
"factory_id": 1001,
|
||
"factory_name": "工厂A",
|
||
"sale_price_total": 100.00,
|
||
"cost_price_total": 60.00,
|
||
"rebate_total": 5.00,
|
||
"freight_total": 10.00,
|
||
"tax_total": 3.00,
|
||
"other_fee_total": 2.00,
|
||
"profit_total": 20.00,
|
||
"profit_rate": 20.00,
|
||
"commission_amount": 50.00,
|
||
"items": [],
|
||
"approve_logs": [],
|
||
"logistics_info": {
|
||
"task": {},
|
||
"trace_list": []
|
||
},
|
||
"attachments": [],
|
||
"remark": "备注"
|
||
}
|
||
```
|
||
|
||
#### 字段权限
|
||
|
||
| 角色 | 字段控制 |
|
||
| --- | --- |
|
||
| 业务员 | 不返回成本、回扣、利润、利润率等敏感字段，除非明确授权 |
|
||
| 管理层 | 返回完整财务字段 |
|
||
| 司机 | 不使用此接口查看订单详情，只通过司机任务详情 |
|
||
| 管理员 | 返回完整字段 |
|
||
|
||
### 4.4 订单列表
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `GET` | `/api/orders` | 是 |
|
||
|
||
#### Query
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| 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 | 每页条数 |
|
||
|
||
#### List Item
|
||
|
||
```json
|
||
{
|
||
"order_id": 9001,
|
||
"order_no": "SO202605140001",
|
||
"customer_name": "李四",
|
||
"customer_mobile": "13900000000",
|
||
"salesman_name": "张三",
|
||
"order_status": "approved",
|
||
"sale_price_total": 100.00,
|
||
"profit_total": 20.00,
|
||
"commission_amount": 50.00,
|
||
"created_at": "2026-05-14 10:00:00"
|
||
}
|
||
```
|
||
|
||
### 4.5 取消订单
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/orders/{order_id}/cancel` | 是 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"cancel_reason": "客户取消",
|
||
"cancel_opinion": "客户临时取消订单"
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"order_id": 9001,
|
||
"order_status": "cancel_pending",
|
||
"previous_status": "approved",
|
||
"canceled_at": null
|
||
}
|
||
```
|
||
|
||
#### 状态规则
|
||
|
||
| 当前状态 | 结果 |
|
||
| --- | --- |
|
||
| `draft` | 直接 `canceled` |
|
||
| `pending_approve` | 直接 `canceled` |
|
||
| `approved` 及后续履约状态 | `cancel_pending` |
|
||
| `canceled/settled` | 返回 `40005` |
|
||
|
||
### 4.6 状态变更
|
||
|
||
| Method | Path | Auth | 权限 |
|
||
| --- | --- | --- | --- |
|
||
| `POST` | `/api/orders/{order_id}/status` | 是 | 管理层、管理员、系统内部 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"target_status": "shipped",
|
||
"remark": "工厂已发货"
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"order_id": 9001,
|
||
"order_status": "shipped"
|
||
}
|
||
```
|
||
|
||
### 4.7 生成下发工厂文本
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/orders/{order_id}/supplier-text` | 是 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"supplier_id": 1001
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"order_id": 9001,
|
||
"supplier_id": 1001,
|
||
"template_type": "default",
|
||
"text_content": "下发文本内容"
|
||
}
|
||
```
|
||
|
||
### 4.8 确认下发工厂
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/orders/{order_id}/supplier-text/confirm` | 是 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"supplier_id": 1001,
|
||
"text_content": "实际确认下发文本",
|
||
"remark": "已复制给工厂"
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"order_id": 9001,
|
||
"order_status": "pending_factory",
|
||
"confirmed_at": "2026-05-14 11:00:00"
|
||
}
|
||
```
|
||
|
||
#### 错误场景
|
||
|
||
| 场景 | code |
|
||
| --- | --- |
|
||
| 订单不是 `approved` | 40005 |
|
||
| 工厂不存在 | 40004 |
|
||
|
||
## 5. 审批接口
|
||
|
||
### 5.1 最终审批
|
||
|
||
| Method | Path | Auth | 权限 |
|
||
| --- | --- | --- | --- |
|
||
| `POST` | `/api/orders/{order_id}/approve` | 是 | 管理层 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"approve_result": "pass",
|
||
"approve_opinion": "同意"
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"order_id": 9001,
|
||
"order_status": "approved",
|
||
"profit_total": 20.00,
|
||
"profit_rate": 20.00,
|
||
"approve_time": "2026-05-14 10:30:00"
|
||
}
|
||
```
|
||
|
||
#### 规则
|
||
|
||
| approve_result | 结果 |
|
||
| --- | --- |
|
||
| `pass` | 状态变为 `approved` |
|
||
| `reject` | 状态变为 `rejected` |
|
||
|
||
### 5.2 取消审批
|
||
|
||
| Method | Path | Auth | 权限 |
|
||
| --- | --- | --- | --- |
|
||
| `POST` | `/api/orders/{order_id}/cancel-approve` | 是 | 管理层 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"approve_result": "pass",
|
||
"approve_opinion": "同意取消"
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"order_id": 9001,
|
||
"order_status": "canceled"
|
||
}
|
||
```
|
||
|
||
#### 规则
|
||
|
||
| approve_result | 结果 |
|
||
| --- | --- |
|
||
| `pass` | `canceled` |
|
||
| `refuse` | 回到取消前状态 |
|
||
|
||
## 6. 客户接口
|
||
|
||
### 6.1 新增客户
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/customers` | 是 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"customer_name": "李四",
|
||
"mobile": "13900000000",
|
||
"address": "地址",
|
||
"settlement_type": "monthly",
|
||
"settlement_days": 30,
|
||
"settlement_start_type": "delivered",
|
||
"customer_type": "普通客户",
|
||
"salesman_id": 1,
|
||
"credit_limit": 10000.00,
|
||
"remark": "备注"
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"customer_id": 3001,
|
||
"customer_name": "李四",
|
||
"mobile": "13900000000"
|
||
}
|
||
```
|
||
|
||
### 6.2 客户列表
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `GET` | `/api/customers` | 是 |
|
||
|
||
#### Query
|
||
|
||
| 字段 | 类型 |
|
||
| --- | --- |
|
||
| customer_name | string |
|
||
| mobile | string |
|
||
| customer_type | string |
|
||
| settlement_type | string |
|
||
| salesman_id | number |
|
||
| page_no | number |
|
||
| page_size | number |
|
||
|
||
### 6.3 客户详情
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `GET` | `/api/customers/{customer_id}` | 是 |
|
||
|
||
### 6.4 客户导入
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/customers/import` | 是 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"file_url": "https://oss.example.com/import/customer.xlsx",
|
||
"import_mode": "skip_duplicate"
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"total_count": 100,
|
||
"success_count": 90,
|
||
"duplicate_count": 5,
|
||
"fail_count": 5,
|
||
"fail_list": [
|
||
{
|
||
"row_no": 12,
|
||
"reason": "手机号为空"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 7. 产品与分类接口
|
||
|
||
### 7.1 产品分类列表
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `GET` | `/api/product-categories` | 是 |
|
||
|
||
#### Query
|
||
|
||
| 字段 | 类型 |
|
||
| --- | --- |
|
||
| category_name | string |
|
||
| status | number |
|
||
| page_no | number |
|
||
| page_size | number |
|
||
|
||
### 7.2 新增产品分类
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/product-categories` | 是 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"category_name": "工业品",
|
||
"category_code": "industry",
|
||
"sort_no": 1,
|
||
"status": 1,
|
||
"remark": "备注"
|
||
}
|
||
```
|
||
|
||
### 7.3 更新产品分类
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `PUT` | `/api/product-categories/{category_id}` | 是 |
|
||
|
||
### 7.4 新增产品
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/products` | 是 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"product_name": "产品A",
|
||
"specification": "10kg",
|
||
"unit": "袋",
|
||
"category_id": 1,
|
||
"category": "工业品",
|
||
"cost_price": 60.00,
|
||
"sale_price": 100.00,
|
||
"status": 1,
|
||
"remark": "备注"
|
||
}
|
||
```
|
||
|
||
### 7.5 产品列表
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `GET` | `/api/products` | 是 |
|
||
|
||
### 7.6 产品详情
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `GET` | `/api/products/{product_id}` | 是 |
|
||
|
||
## 8. 工厂/供应商接口
|
||
|
||
### 8.1 新增工厂/供应商
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/suppliers` | 是 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"supplier_name": "工厂A",
|
||
"supplier_type": "factory",
|
||
"contact_name": "王五",
|
||
"contact_mobile": "13800000001",
|
||
"address": "地址",
|
||
"template_type": "default",
|
||
"status": 1,
|
||
"remark": "备注"
|
||
}
|
||
```
|
||
|
||
### 8.2 工厂/供应商列表
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `GET` | `/api/suppliers` | 是 |
|
||
|
||
## 9. 司机任务接口
|
||
|
||
### 9.1 管理端创建司机任务
|
||
|
||
| Method | Path | Auth | 权限 |
|
||
| --- | --- | --- | --- |
|
||
| `POST` | `/api/logistics/tasks` | 是 | 管理层、管理员 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"order_id": 9001,
|
||
"driver_id": 10,
|
||
"pickup_address": "取货地址",
|
||
"delivery_address": "送达地址",
|
||
"pickup_content": "产品A 1袋",
|
||
"quantity": 1,
|
||
"factory_id": 1001,
|
||
"remark": "备注"
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"task_id": 5001,
|
||
"task_no": "LT202605140001",
|
||
"status": "pending"
|
||
}
|
||
```
|
||
|
||
### 9.2 管理端任务列表
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `GET` | `/api/logistics/tasks` | 是 |
|
||
|
||
### 9.3 司机任务列表
|
||
|
||
| Method | Path | Auth | 权限 |
|
||
| --- | --- | --- | --- |
|
||
| `GET` | `/api/driver/tasks` | 是 | 司机 |
|
||
|
||
### 9.4 司机任务详情
|
||
|
||
| Method | Path | Auth | 权限 |
|
||
| --- | --- | --- | --- |
|
||
| `GET` | `/api/driver/tasks/{task_id}` | 是 | 司机本人 |
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"task_id": 5001,
|
||
"order_id": 9001,
|
||
"task_no": "LT202605140001",
|
||
"status": "pending",
|
||
"pickup_address": "取货地址",
|
||
"delivery_address": "送达地址",
|
||
"pickup_content": "产品A 1袋",
|
||
"quantity": 1,
|
||
"factory_id": 1001,
|
||
"factory_name": "工厂A",
|
||
"salesman_name": "张三"
|
||
}
|
||
```
|
||
|
||
### 9.5 接单
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/driver/tasks/{task_id}/accept` | 是 |
|
||
|
||
### 9.6 确认揽货
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/driver/tasks/{task_id}/pickup` | 是 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"photo_files": [
|
||
{
|
||
"file_url": "https://oss.example.com/a.jpg",
|
||
"file_name": "a.jpg"
|
||
}
|
||
],
|
||
"video_files": [],
|
||
"remark": "已揽货"
|
||
}
|
||
```
|
||
|
||
### 9.7 确认送达
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/driver/tasks/{task_id}/deliver` | 是 |
|
||
|
||
## 10. 文件接口
|
||
|
||
### 10.1 获取 OSS 上传凭证
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/files/upload-token` | 是 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"biz_type": "logistics_task",
|
||
"biz_id": 5001,
|
||
"file_name": "pickup.jpg",
|
||
"file_type": "image/jpeg",
|
||
"file_size": 102400
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"upload_url": "https://oss-upload-url",
|
||
"file_url": "https://oss-public-url/pickup.jpg",
|
||
"headers": {},
|
||
"expire_at": "2026-05-14 12:00:00"
|
||
}
|
||
```
|
||
|
||
### 10.2 保存附件记录
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/files/attachments` | 是 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"biz_type": "logistics_task",
|
||
"biz_id": 5001,
|
||
"file_name": "pickup.jpg",
|
||
"file_url": "https://oss.example.com/pickup.jpg",
|
||
"file_type": "image/jpeg",
|
||
"file_size": 102400
|
||
}
|
||
```
|
||
|
||
## 11. 物流与 AI 接口
|
||
|
||
### 11.1 物流轨迹查询
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `GET` | `/api/logistics/{order_id}/trace` | 是 |
|
||
|
||
### 11.2 新增物流节点
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/logistics/{order_id}/trace` | 是 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"task_id": 5001,
|
||
"node_time": "2026-05-14 12:00:00",
|
||
"node_desc": "司机已揽货",
|
||
"node_type": "picked_up",
|
||
"source_platform": "manual"
|
||
}
|
||
```
|
||
|
||
### 11.3 AI 图片识别
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/ai/recognize` | 是 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"image_url": "https://oss.example.com/ocr.jpg",
|
||
"biz_type": "sales_order",
|
||
"biz_id": 9001
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"log_id": 7001,
|
||
"raw_result": {},
|
||
"confidence": 0.92,
|
||
"suggested_result": {}
|
||
}
|
||
```
|
||
|
||
### 11.4 AI 结果修正
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/ai/recognize/{log_id}/correct` | 是 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"corrected_result": {
|
||
"customer_name": "李四",
|
||
"tracking_no": "SF123"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 12. 提醒接口
|
||
|
||
### 12.1 提醒列表
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `GET` | `/api/reminders` | 是 |
|
||
|
||
#### Query
|
||
|
||
| 字段 | 类型 |
|
||
| --- | --- |
|
||
| reminder_type | string |
|
||
| status | string |
|
||
| receiver_user_id | number |
|
||
| page_no | number |
|
||
| page_size | number |
|
||
|
||
### 12.2 标记已读
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/reminders/{reminder_id}/read` | 是 |
|
||
|
||
### 12.3 欠款提醒检查
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/reminders/arrears/check` | 是 |
|
||
|
||
### 12.4 沉默客户提醒检查
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `POST` | `/api/reminders/inactive-customers/check` | 是 |
|
||
|
||
## 13. 报表接口
|
||
|
||
### 13.1 业绩统计
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `GET` | `/api/reports/performance` | 是 |
|
||
|
||
#### Query
|
||
|
||
| 字段 | 类型 |
|
||
| --- | --- |
|
||
| stat_type | string |
|
||
| start_date | string |
|
||
| end_date | string |
|
||
| category_id | number |
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"stat_type": "month",
|
||
"list": [
|
||
{
|
||
"stat_period": "2026-05",
|
||
"order_count": 10,
|
||
"order_amount": 10000.00,
|
||
"category_amounts": [
|
||
{
|
||
"category_id": 1,
|
||
"category_name": "工业品",
|
||
"amount": 6000.00
|
||
}
|
||
],
|
||
"commission_amount": 500.00
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 13.2 报表导出
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `GET` | `/api/reports/performance/export` | 是 |
|
||
|
||
## 14. 配置接口
|
||
|
||
### 14.1 配置查询
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `GET` | `/api/configs/{config_key}` | 是 |
|
||
|
||
### 14.2 配置更新
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `PUT` | `/api/configs/{config_key}` | 是 |
|
||
|
||
#### 常用配置键
|
||
|
||
| config_key | 说明 | 示例 |
|
||
| --- | --- | --- |
|
||
| `arrears_generate_mode` | 欠款生成模式 | `delivered` |
|
||
| `logistics_timeout_hours` | 物流超时小时数 | `48` |
|
||
| `inactive_customer_days` | 沉默客户周期 | `90` |
|
||
| `inactive_customer_amount_threshold` | 沉默客户金额阈值 | `1000` |
|
||
| `report_category_mapping` | 报表分类映射 | JSON |
|
||
|
||
## 15. 审计日志接口
|
||
|
||
### 15.1 审计日志列表
|
||
|
||
| Method | Path | Auth |
|
||
| --- | --- | --- |
|
||
| `GET` | `/api/audit-logs` | 是 |
|
||
|
||
#### Query
|
||
|
||
| 字段 | 类型 |
|
||
| --- | --- |
|
||
| biz_type | string |
|
||
| biz_id | number |
|
||
| operator_name | string |
|
||
| operate_type | string |
|
||
| start_time | string |
|
||
| end_time | string |
|
||
| page_no | number |
|
||
| page_size | number |
|
||
|
||
## 16. 系统管理接口
|
||
|
||
以下接口为后台用户、角色、菜单和权限配置页面的一期必备接口。所有接口仅 `admin` 可调用，管理层如需部分授权，需要在角色权限里单独配置。
|
||
|
||
### 16.1 用户列表
|
||
|
||
| Method | Path | Auth | 权限 |
|
||
| --- | --- | --- | --- |
|
||
| `GET` | `/api/system/users` | 是 | 管理员 |
|
||
|
||
#### Query
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| username | string | 否 | 账号模糊查询 |
|
||
| real_name | string | 否 | 姓名模糊查询 |
|
||
| mobile | string | 否 | 手机号模糊查询 |
|
||
| role_id | number | 否 | 角色 ID |
|
||
| status | number | 否 | 1 启用，0 停用 |
|
||
| page_no | number | 否 | 默认 1 |
|
||
| page_size | number | 否 | 默认 20 |
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"total": 1,
|
||
"page_no": 1,
|
||
"page_size": 20,
|
||
"list": [
|
||
{
|
||
"user_id": 1,
|
||
"username": "sales01",
|
||
"real_name": "张三",
|
||
"mobile": "13800000000",
|
||
"role_id": 2,
|
||
"role_name": "业务员",
|
||
"role_code": "salesman",
|
||
"status": 1,
|
||
"created_at": "2026-05-14 10:00:00",
|
||
"updated_at": "2026-05-14 10:00:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 错误场景
|
||
|
||
| 场景 | code |
|
||
| --- | --- |
|
||
| 非管理员访问 | 40003 |
|
||
| 分页参数非法 | 40001 |
|
||
|
||
### 16.2 新增用户
|
||
|
||
| Method | Path | Auth | 权限 |
|
||
| --- | --- | --- | --- |
|
||
| `POST` | `/api/system/users` | 是 | 管理员 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"username": "driver01",
|
||
"password": "Init@123456",
|
||
"real_name": "王司机",
|
||
"mobile": "13700000000",
|
||
"role_id": 3,
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"user_id": 10,
|
||
"username": "driver01",
|
||
"real_name": "王司机",
|
||
"mobile": "13700000000",
|
||
"role_id": 3,
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
#### 规则
|
||
|
||
| 规则 | 说明 |
|
||
| --- | --- |
|
||
| 账号唯一 | `username` 不允许重复 |
|
||
| 密码存储 | 后端只保存加密后的密码摘要 |
|
||
| 角色有效 | `role_id` 必须存在且启用 |
|
||
| 审计 | 成功新增后写入 `audit_log` |
|
||
|
||
#### 错误场景
|
||
|
||
| 场景 | code |
|
||
| --- | --- |
|
||
| 必填字段缺失 | 40001 |
|
||
| 账号重复 | 40006 |
|
||
| 角色不存在或停用 | 40004 |
|
||
|
||
### 16.3 更新用户
|
||
|
||
| Method | Path | Auth | 权限 |
|
||
| --- | --- | --- | --- |
|
||
| `PUT` | `/api/system/users/{user_id}` | 是 | 管理员 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"real_name": "王司机",
|
||
"mobile": "13700000001",
|
||
"role_id": 3,
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"user_id": 10,
|
||
"updated": true
|
||
}
|
||
```
|
||
|
||
#### 错误场景
|
||
|
||
| 场景 | code |
|
||
| --- | --- |
|
||
| 用户不存在 | 40004 |
|
||
| 角色不存在或停用 | 40004 |
|
||
| 停用当前登录管理员本人 | 40007 |
|
||
|
||
### 16.4 重置密码
|
||
|
||
| Method | Path | Auth | 权限 |
|
||
| --- | --- | --- | --- |
|
||
| `POST` | `/api/system/users/{user_id}/reset-password` | 是 | 管理员 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"new_password": "New@123456"
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"user_id": 10,
|
||
"reset": true
|
||
}
|
||
```
|
||
|
||
#### 错误场景
|
||
|
||
| 场景 | code |
|
||
| --- | --- |
|
||
| 用户不存在 | 40004 |
|
||
| 密码强度不符合规则 | 40001 |
|
||
|
||
### 16.5 角色列表
|
||
|
||
| Method | Path | Auth | 权限 |
|
||
| --- | --- | --- | --- |
|
||
| `GET` | `/api/system/roles` | 是 | 管理员 |
|
||
|
||
#### Query
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| role_name | string | 否 | 角色名称 |
|
||
| role_code | string | 否 | 角色编码 |
|
||
| status | number | 否 | 1 启用，0 停用 |
|
||
| page_no | number | 否 | 默认 1 |
|
||
| page_size | number | 否 | 默认 20 |
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"total": 4,
|
||
"page_no": 1,
|
||
"page_size": 20,
|
||
"list": [
|
||
{
|
||
"role_id": 1,
|
||
"role_name": "管理员",
|
||
"role_code": "admin",
|
||
"status": 1,
|
||
"remark": "系统管理",
|
||
"created_at": "2026-05-14 10:00:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 16.6 新增角色
|
||
|
||
| Method | Path | Auth | 权限 |
|
||
| --- | --- | --- | --- |
|
||
| `POST` | `/api/system/roles` | 是 | 管理员 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"role_name": "业务员",
|
||
"role_code": "salesman",
|
||
"status": 1,
|
||
"remark": "业务录单和本人订单查询"
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"role_id": 2,
|
||
"role_name": "业务员",
|
||
"role_code": "salesman",
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
#### 错误场景
|
||
|
||
| 场景 | code |
|
||
| --- | --- |
|
||
| 角色编码重复 | 40006 |
|
||
| 必填字段缺失 | 40001 |
|
||
|
||
### 16.7 更新角色
|
||
|
||
| Method | Path | Auth | 权限 |
|
||
| --- | --- | --- | --- |
|
||
| `PUT` | `/api/system/roles/{role_id}` | 是 | 管理员 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"role_name": "业务员",
|
||
"status": 1,
|
||
"remark": "业务录单和本人订单查询"
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"role_id": 2,
|
||
"updated": true
|
||
}
|
||
```
|
||
|
||
#### 错误场景
|
||
|
||
| 场景 | code |
|
||
| --- | --- |
|
||
| 角色不存在 | 40004 |
|
||
| 停用内置管理员角色 | 40007 |
|
||
| 角色下仍有启用用户时停用 | 40007 |
|
||
|
||
### 16.8 菜单树
|
||
|
||
| Method | Path | Auth | 权限 |
|
||
| --- | --- | --- | --- |
|
||
| `GET` | `/api/system/menus` | 是 | 管理员 |
|
||
|
||
#### Query
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| status | number | 否 | 1 启用，0 停用 |
|
||
| menu_type | string | 否 | `catalog/page/button` |
|
||
|
||
#### Response
|
||
|
||
```json
|
||
[
|
||
{
|
||
"menu_id": 1,
|
||
"parent_id": 0,
|
||
"menu_name": "订单管理",
|
||
"menu_path": "/orders",
|
||
"menu_type": "page",
|
||
"permission_code": "order:list",
|
||
"icon": "order",
|
||
"sort_no": 10,
|
||
"status": 1,
|
||
"children": []
|
||
}
|
||
]
|
||
```
|
||
|
||
### 16.9 新增菜单
|
||
|
||
| Method | Path | Auth | 权限 |
|
||
| --- | --- | --- | --- |
|
||
| `POST` | `/api/system/menus` | 是 | 管理员 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"parent_id": 0,
|
||
"menu_name": "订单管理",
|
||
"menu_path": "/orders",
|
||
"menu_type": "page",
|
||
"permission_code": "order:list",
|
||
"icon": "order",
|
||
"sort_no": 10,
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"menu_id": 20,
|
||
"menu_name": "订单管理",
|
||
"permission_code": "order:list",
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
#### 错误场景
|
||
|
||
| 场景 | code |
|
||
| --- | --- |
|
||
| 父级菜单不存在 | 40004 |
|
||
| 权限编码重复 | 40006 |
|
||
| 菜单类型非法 | 40001 |
|
||
|
||
### 16.10 更新菜单
|
||
|
||
| Method | Path | Auth | 权限 |
|
||
| --- | --- | --- | --- |
|
||
| `PUT` | `/api/system/menus/{menu_id}` | 是 | 管理员 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"parent_id": 0,
|
||
"menu_name": "订单管理",
|
||
"menu_path": "/orders",
|
||
"menu_type": "page",
|
||
"permission_code": "order:list",
|
||
"icon": "order",
|
||
"sort_no": 10,
|
||
"status": 1
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"menu_id": 20,
|
||
"updated": true
|
||
}
|
||
```
|
||
|
||
#### 错误场景
|
||
|
||
| 场景 | code |
|
||
| --- | --- |
|
||
| 菜单不存在 | 40004 |
|
||
| 将菜单父级设置为自身或子级 | 40007 |
|
||
| 权限编码重复 | 40006 |
|
||
|
||
### 16.11 角色授权
|
||
|
||
| Method | Path | Auth | 权限 |
|
||
| --- | --- | --- | --- |
|
||
| `PUT` | `/api/system/roles/{role_id}/menus` | 是 | 管理员 |
|
||
|
||
#### Request
|
||
|
||
```json
|
||
{
|
||
"menu_ids": [1, 2, 3, 20],
|
||
"permission_codes": ["order:list", "order:create", "order:submit"]
|
||
}
|
||
```
|
||
|
||
#### Response
|
||
|
||
```json
|
||
{
|
||
"role_id": 2,
|
||
"menu_count": 4,
|
||
"permission_count": 3,
|
||
"updated": true
|
||
}
|
||
```
|
||
|
||
#### 规则
|
||
|
||
| 规则 | 说明 |
|
||
| --- | --- |
|
||
| 覆盖保存 | 每次提交以本次 `menu_ids` 和 `permission_codes` 为准 |
|
||
| 登录刷新 | 权限变更后，用户下一次登录或刷新 `/api/auth/me` 生效 |
|
||
| 审计 | 记录角色授权前后差异 |
|
||
|
||
#### 错误场景
|
||
|
||
| 场景 | code |
|
||
| --- | --- |
|
||
| 角色不存在 | 40004 |
|
||
| 菜单不存在或停用 | 40004 |
|
||
| 给内置角色移除必要基础权限 | 40007 |
|