forked from erp-dev/erp
490 lines
15 KiB
Markdown
490 lines
15 KiB
Markdown
# 任务配货功能 API 需求文档
|
||
|
||
> **业务背景：** 布行预销售单场景，客户预定布料（如5000米），需要仓库人员配货、扫码录入每条布的米数，确认后转为正式销售单。
|
||
>
|
||
> **前端项目：** app-ui（移动端 Web 应用）
|
||
>
|
||
> **生成日期：** 2026-02-01
|
||
|
||
---
|
||
|
||
## 一、业务流程概述
|
||
|
||
```
|
||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||
│ 创建预销售单 │ -> │ 生成任务配货 │ -> │ 仓库扫码录入 │ -> │ 确认转销售单 │
|
||
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
|
||
│ │ │ │
|
||
▼ ▼ ▼ ▼
|
||
客户预定 任务分配给 扫码录入每条 客户确认数量
|
||
5000米布料 仓库配货人员 布料的实际米数 转为正式销售单
|
||
```
|
||
|
||
### 角色说明
|
||
|
||
| 角色 | 操作 |
|
||
|------|------|
|
||
| 销售人员 | 创建预销售单，确认配货结果，转销售单 |
|
||
| 仓库人员 | 接收任务配货，扫码录入每条布的米数 |
|
||
| 客户 | 确认最终数量（可选，由销售人员代为确认） |
|
||
|
||
### 状态流转
|
||
|
||
```
|
||
预销售单状态：
|
||
待配货(pending) → 配货中(allocating) → 待确认(confirming) → 已完成(completed) / 已取消(cancelled)
|
||
|
||
任务配货状态：
|
||
待接收(pending) → 进行中(in_progress) → 已完成(completed) / 已取消(cancelled)
|
||
```
|
||
|
||
---
|
||
|
||
## 二、需要新增的 API
|
||
|
||
### 2.1 预销售单 API（移动端）
|
||
|
||
> 注：antd-demo 已有预销售单 API，需确认 app-ui 是否复用同一套接口
|
||
|
||
**复用现有接口：**
|
||
- `POST /api/v1/pre-sales-orders/` - 创建预销售单
|
||
- `GET /api/v1/pre-sales-orders/` - 预销售单列表
|
||
- `GET /api/v1/pre-sales-orders/{id}/` - 预销售单详情
|
||
|
||
**需要新增/调整：**
|
||
- 创建预销售单时**自动创建任务配货**（后端处理，或前端调用两个接口）
|
||
- 预销售单需要新增 `status` 字段表示配货状态
|
||
|
||
---
|
||
|
||
### 2.2 任务配货 API（新增）
|
||
|
||
#### 2.2.1 创建任务配货
|
||
|
||
> 可选择在创建预销售单时由后端自动创建，或由前端单独调用
|
||
|
||
- **路径：** `POST /api/v1/task-allocations/`
|
||
- **权限：** 需登录，需员工权限
|
||
|
||
**请求参数：**
|
||
```typescript
|
||
{
|
||
pre_sales_order_id: number; // 必填，关联的预销售单 ID
|
||
assignee_id?: number; // 可选，指派给哪个仓库员工（不填则待分配）
|
||
priority?: number; // 可选，优先级：1=普通，2=加急，默认1
|
||
expected_date?: string; // 可选，期望完成日期（ISO 8601）
|
||
remarks?: string; // 可选，备注
|
||
}
|
||
```
|
||
|
||
**响应数据：**
|
||
```typescript
|
||
{
|
||
code: 200,
|
||
message: "success",
|
||
data: {
|
||
id: number; // 任务配货 ID
|
||
task_no: string; // 任务编号（如 PH20260201000001）
|
||
pre_sales_order_id: number; // 关联预销售单 ID
|
||
pre_sales_order_no: string; // 预销售单编号（只读）
|
||
customer_id: number; // 客户 ID（从预销售单继承）
|
||
customer_name: string; // 客户名称（只读）
|
||
warehouse_id: number; // 仓库 ID（从预销售单继承）
|
||
warehouse_name: string; // 仓库名称（只读）
|
||
assignee_id: number | null; // 被指派的员工 ID
|
||
assignee_name: string | null; // 被指派的员工名称（只读）
|
||
status: number; // 状态：1=待接收，2=进行中，3=已完成，4=已取消
|
||
priority: number; // 优先级
|
||
expected_date: string | null; // 期望完成日期
|
||
remarks: string | null; // 备注
|
||
created_by: number; // 创建者 ID
|
||
created_by_name: string; // 创建者名称（只读）
|
||
created_at: string; // 创建时间
|
||
|
||
// 配货需求（从预销售单明细复制）
|
||
items: TaskAllocationItem[];
|
||
}
|
||
}
|
||
```
|
||
|
||
**任务配货明细 `TaskAllocationItem`：**
|
||
```typescript
|
||
{
|
||
id: number; // 明细 ID
|
||
product_id: number; // 产品 ID
|
||
product_name: string; // 产品名称
|
||
spec: string | null; // 规格
|
||
color: string | null; // 颜色
|
||
required_quantity: string; // 需求数量（如 "5000.00"）
|
||
allocated_quantity: string; // 已配货数量（如 "4800.00"）
|
||
unit: string; // 单位
|
||
status: number; // 明细状态：1=待配货，2=配货中，3=已完成
|
||
|
||
// 扫码录入的布条记录
|
||
rolls: TaskAllocationRoll[];
|
||
}
|
||
```
|
||
|
||
**布条记录 `TaskAllocationRoll`：**
|
||
```typescript
|
||
{
|
||
id: number; // 记录 ID
|
||
roll_code: string; // 布条码/二维码内容
|
||
quantity: string; // 该条的米数（如 "50.00"）
|
||
scanned_by: number; // 扫码人员 ID
|
||
scanned_by_name: string; // 扫码人员名称（只读）
|
||
scanned_at: string; // 扫码时间
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 2.2.2 任务配货列表
|
||
|
||
- **路径：** `GET /api/v1/task-allocations/`
|
||
- **权限：** 需登录，需员工权限
|
||
|
||
**查询参数：**
|
||
```typescript
|
||
{
|
||
limit?: number; // 分页，默认20，最大100
|
||
offset?: number; // 偏移量，默认0
|
||
status?: number; // 按状态筛选：1/2/3/4
|
||
assignee_id?: number; // 按被指派人筛选（仓库人员查自己的任务）
|
||
warehouse_id?: number; // 按仓库筛选
|
||
priority?: number; // 按优先级筛选
|
||
date_from?: string; // 创建时间起始（ISO 8601）
|
||
date_to?: string; // 创建时间结束
|
||
}
|
||
```
|
||
|
||
**响应数据：**
|
||
```typescript
|
||
{
|
||
count: number;
|
||
next: string | null;
|
||
previous: string | null;
|
||
results: TaskAllocation[]; // 任务配货列表（不含 rolls 明细）
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 2.2.3 任务配货详情
|
||
|
||
- **路径：** `GET /api/v1/task-allocations/{id}/`
|
||
- **权限：** 需登录
|
||
|
||
**响应数据：**
|
||
```typescript
|
||
{
|
||
code: 200,
|
||
data: TaskAllocation // 完整数据，包含 items 和 rolls
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 2.2.4 接收任务
|
||
|
||
> 仓库人员接收任务，状态从"待接收"变为"进行中"
|
||
|
||
- **路径：** `POST /api/v1/task-allocations/{id}/accept/`
|
||
- **权限：** 需登录，需仓库员工权限
|
||
|
||
**请求参数：** 无（后端自动设置当前用户为 assignee）
|
||
|
||
**响应数据：**
|
||
```typescript
|
||
{
|
||
code: 200,
|
||
message: "任务已接收",
|
||
data: TaskAllocation
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 2.2.5 扫码录入布条 ⭐
|
||
|
||
> 仓库人员扫码录入每条布的米数
|
||
|
||
- **路径：** `POST /api/v1/task-allocations/{id}/scan/`
|
||
- **权限：** 需登录，需仓库员工权限
|
||
|
||
**请求参数：**
|
||
```typescript
|
||
{
|
||
item_id: number; // 哪个产品明细
|
||
roll_code: string; // 布条码/二维码内容
|
||
quantity: string | number; // 该条的米数
|
||
}
|
||
```
|
||
|
||
**响应数据：**
|
||
```typescript
|
||
{
|
||
code: 200,
|
||
message: "录入成功",
|
||
data: {
|
||
roll: TaskAllocationRoll; // 新增的布条记录
|
||
item: TaskAllocationItem; // 更新后的明细（含最新 allocated_quantity）
|
||
task: {
|
||
id: number;
|
||
total_allocated: string; // 总已配货数量
|
||
total_required: string; // 总需求数量
|
||
progress: number; // 进度百分比（0-100）
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应：**
|
||
```typescript
|
||
// 布条码重复
|
||
{
|
||
code: 400,
|
||
message: "该布条已录入",
|
||
data: {
|
||
existing_roll: TaskAllocationRoll // 已存在的记录
|
||
}
|
||
}
|
||
|
||
// 超出需求数量
|
||
{
|
||
code: 400,
|
||
message: "配货数量已超出需求，是否继续？",
|
||
data: {
|
||
required: "5000.00",
|
||
allocated: "5050.00",
|
||
overflow: "50.00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 2.2.6 删除布条记录
|
||
|
||
> 录错了，删除某条扫码记录
|
||
|
||
- **路径：** `DELETE /api/v1/task-allocations/{id}/rolls/{roll_id}/`
|
||
- **权限：** 需登录，需仓库员工权限
|
||
|
||
**响应数据：**
|
||
```typescript
|
||
{
|
||
code: 200,
|
||
message: "删除成功",
|
||
data: {
|
||
item: TaskAllocationItem; // 更新后的明细
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### 2.2.7 完成配货
|
||
|
||
> 仓库人员完成配货，状态变为"已完成"
|
||
|
||
- **路径：** `POST /api/v1/task-allocations/{id}/complete/`
|
||
- **权限：** 需登录，需仓库员工权限
|
||
|
||
**请求参数：**
|
||
```typescript
|
||
{
|
||
remarks?: string; // 可选，完成备注
|
||
}
|
||
```
|
||
|
||
**响应数据：**
|
||
```typescript
|
||
{
|
||
code: 200,
|
||
message: "配货完成",
|
||
data: TaskAllocation
|
||
}
|
||
```
|
||
|
||
**校验规则：**
|
||
- 所有明细的 `allocated_quantity` 必须 > 0
|
||
- 如果某明细未配货，返回 400 错误
|
||
|
||
---
|
||
|
||
#### 2.2.8 确认配货结果并转销售单 ⭐
|
||
|
||
> 销售人员/客户确认配货数量，将预销售单转为正式销售单
|
||
|
||
- **路径：** `POST /api/v1/task-allocations/{id}/confirm-and-convert/`
|
||
- **权限：** 需登录，需销售员工权限
|
||
|
||
**请求参数：**
|
||
```typescript
|
||
{
|
||
confirmed_items: Array<{
|
||
item_id: number; // 明细 ID
|
||
confirmed_quantity: string; // 确认的数量（可能与实际配货数量不同）
|
||
}>;
|
||
remarks?: string; // 可选，确认备注
|
||
}
|
||
```
|
||
|
||
**响应数据：**
|
||
```typescript
|
||
{
|
||
code: 200,
|
||
message: "已转为销售单",
|
||
data: {
|
||
task_allocation: TaskAllocation; // 更新后的任务配货（状态变更）
|
||
sales_order: {
|
||
id: number;
|
||
human_id: string; // 销售单编号（如 XS20260201000001）
|
||
// ... 其他销售单字段
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2.3 预销售单状态扩展
|
||
|
||
现有预销售单 API 需要新增以下字段：
|
||
|
||
```typescript
|
||
// 响应中新增
|
||
{
|
||
// ... 原有字段 ...
|
||
|
||
allocation_status: number; // 配货状态：1=待配货，2=配货中，3=待确认，4=已完成
|
||
allocation_status_display: string; // 配货状态文字（只读）
|
||
task_allocation_id: number | null; // 关联的任务配货 ID
|
||
converted_sales_order_id: number | null; // 转换后的销售单 ID
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 三、状态枚举值
|
||
|
||
### 3.1 任务配货状态
|
||
|
||
| 值 | 名称 | 说明 |
|
||
|----|------|------|
|
||
| 1 | pending | 待接收 |
|
||
| 2 | in_progress | 进行中 |
|
||
| 3 | completed | 已完成 |
|
||
| 4 | cancelled | 已取消 |
|
||
|
||
### 3.2 任务配货明细状态
|
||
|
||
| 值 | 名称 | 说明 |
|
||
|----|------|------|
|
||
| 1 | pending | 待配货 |
|
||
| 2 | allocating | 配货中 |
|
||
| 3 | completed | 已完成 |
|
||
|
||
### 3.3 预销售单配货状态
|
||
|
||
| 值 | 名称 | 说明 |
|
||
|----|------|------|
|
||
| 1 | pending | 待配货 |
|
||
| 2 | allocating | 配货中 |
|
||
| 3 | confirming | 待确认 |
|
||
| 4 | completed | 已完成 |
|
||
|
||
### 3.4 优先级
|
||
|
||
| 值 | 名称 | 说明 |
|
||
|----|------|------|
|
||
| 1 | normal | 普通 |
|
||
| 2 | urgent | 加急 |
|
||
|
||
---
|
||
|
||
## 四、API 路径汇总
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/api/v1/task-allocations/` | 创建任务配货 |
|
||
| GET | `/api/v1/task-allocations/` | 任务配货列表 |
|
||
| GET | `/api/v1/task-allocations/{id}/` | 任务配货详情 |
|
||
| POST | `/api/v1/task-allocations/{id}/accept/` | 接收任务 |
|
||
| POST | `/api/v1/task-allocations/{id}/scan/` | 扫码录入布条 |
|
||
| DELETE | `/api/v1/task-allocations/{id}/rolls/{roll_id}/` | 删除布条记录 |
|
||
| POST | `/api/v1/task-allocations/{id}/complete/` | 完成配货 |
|
||
| POST | `/api/v1/task-allocations/{id}/confirm-and-convert/` | 确认并转销售单 |
|
||
|
||
---
|
||
|
||
## 五、前端页面规划
|
||
|
||
### 5.1 页面路由
|
||
|
||
| 路由 | 页面 | 角色 |
|
||
|------|------|------|
|
||
| `/workstation/sales/pre-order` | 预销售单列表 | 销售 |
|
||
| `/workstation/sales/pre-order/create` | 创建预销售单 | 销售 |
|
||
| `/workstation/sales/pre-order/:id` | 预销售单详情 | 销售 |
|
||
| `/workstation/warehouse/task-allocation` | 任务配货列表 | 仓库 |
|
||
| `/workstation/warehouse/task-allocation/:id` | 任务配货详情/扫码录入 | 仓库 |
|
||
| `/workstation/warehouse/task-allocation/:id/scan` | 扫码录入页面 | 仓库 |
|
||
| `/workstation/sales/pre-order/:id/confirm` | 确认配货结果 | 销售 |
|
||
|
||
### 5.2 页面功能
|
||
|
||
**仓库人员 - 任务配货扫码页面：**
|
||
```
|
||
┌─────────────────────────────────┐
|
||
│ 任务配货 PH20260201000001 │
|
||
│ 客户：XXX布业 仓库：主仓库 │
|
||
├─────────────────────────────────┤
|
||
│ 产品：涤纶面料-红色 │
|
||
│ 需求：5000.00 米 │
|
||
│ 已配：4800.00 米 [96%] │
|
||
│ ████████████████████░░ │
|
||
├─────────────────────────────────┤
|
||
│ ┌───────────────────────────┐ │
|
||
│ │ [扫码区域/摄像头] │ │
|
||
│ │ │ │
|
||
│ └───────────────────────────┘ │
|
||
│ │
|
||
│ 或手动输入： │
|
||
│ 布条码：[____________] │
|
||
│ 米 数：[____________] │
|
||
│ [录入] │
|
||
├─────────────────────────────────┤
|
||
│ 已录入布条（3条）： │
|
||
│ ┌───────────────────────────┐ │
|
||
│ │ R001 50.00米 张三 10:30 │ │
|
||
│ │ R002 48.50米 张三 10:32 │ │
|
||
│ │ R003 51.50米 张三 10:35 │ │
|
||
│ └───────────────────────────┘ │
|
||
├─────────────────────────────────┤
|
||
│ [完成配货] │
|
||
└─────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 六、确认事项
|
||
|
||
请后端同事确认：
|
||
|
||
1. [ ] 任务配货是否在创建预销售单时自动创建？还是需要手动创建？
|
||
2. [ ] 布条码的格式规范是什么？是否需要校验格式？
|
||
3. [ ] 一条布可能属于多个产品吗？还是一对一关系？
|
||
4. [ ] 配货超出需求数量时，是警告还是阻止？
|
||
5. [ ] 转销售单时，价格如何处理？（预销售单是否有价格字段？）
|
||
6. [ ] 是否需要支持"部分配货"后转销售单？
|
||
7. [ ] 任务配货是否需要支持"退回"操作（从进行中退回到待接收）？
|
||
8. [ ] 预销售单和任务配货是否一对一关系？还是一对多？
|
||
|
||
---
|
||
|
||
**前端负责人：** [待填写]
|
||
**后端负责人：** [待填写]
|
||
**评审日期：** [待填写]
|