zuowei/erpnew
1
0
Fork 0
forked from erp-dev/erp
Code Pull Requests Activity

feat: allocation record for pre sales order

Browse Source
This commit is contained in:
colaftc
2026-02-01 22:57:16 +08:00
parent a633a617d5
commit ac065e115e
14 changed files with 1955 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

489
docs/api_task_allocation_proposal.md Normal file
View File

@@ -0,0 +1,489 @@
# 任务配货功能 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. [ ] 预销售单和任务配货是否一对一关系？还是一对多？
---
**前端负责人：** [待填写]
**后端负责人：** [待填写]
**评审日期：** [待填写]