erpnew/docs/api_task_allocation_proposal.md

任务配货功能 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/
• 权限： 需登录，需员工权限

请求参数：

{
  pre_sales_order_id: number;     // 必填，关联的预销售单 ID
  assignee_id?: number;           // 可选，指派给哪个仓库员工（不填则待分配）
  priority?: number;              // 可选，优先级：1=普通，2=加急，默认1
  expected_date?: string;         // 可选，期望完成日期（ISO 8601）
  remarks?: string;               // 可选，备注
}

响应数据：

{
  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：

{
  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：

{
  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/
• 权限： 需登录，需员工权限

查询参数：

{
  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;               // 创建时间结束
}

响应数据：

{
  count: number;
  next: string | null;
  previous: string | null;
  results: TaskAllocation[];      // 任务配货列表（不含 rolls 明细）
}

---

2.2.3 任务配货详情

• 路径： GET /api/v1/task-allocations/{id}/
• 权限： 需登录

响应数据：

{
  code: 200,
  data: TaskAllocation            // 完整数据，包含 items 和 rolls
}

---

2.2.4 接收任务

仓库人员接收任务，状态从"待接收"变为"进行中"

• 路径： POST /api/v1/task-allocations/{id}/accept/
• 权限： 需登录，需仓库员工权限

请求参数： 无（后端自动设置当前用户为 assignee）

响应数据：

{
  code: 200,
  message: "任务已接收",
  data: TaskAllocation
}

---

2.2.5 扫码录入布条 ⭐

仓库人员扫码录入每条布的米数

• 路径： POST /api/v1/task-allocations/{id}/scan/
• 权限： 需登录，需仓库员工权限

请求参数：

{
  item_id: number;                // 哪个产品明细
  roll_code: string;              // 布条码/二维码内容
  quantity: string | number;      // 该条的米数
}

响应数据：

{
  code: 200,
  message: "录入成功",
  data: {
    roll: TaskAllocationRoll;     // 新增的布条记录
    item: TaskAllocationItem;     // 更新后的明细（含最新 allocated_quantity）
    task: {
      id: number;
      total_allocated: string;    // 总已配货数量
      total_required: string;     // 总需求数量
      progress: number;           // 进度百分比（0-100）
    }
  }
}

错误响应：

// 布条码重复
{
  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}/
• 权限： 需登录，需仓库员工权限

响应数据：

{
  code: 200,
  message: "删除成功",
  data: {
    item: TaskAllocationItem;     // 更新后的明细
  }
}

---

2.2.7 完成配货

仓库人员完成配货，状态变为"已完成"

• 路径： POST /api/v1/task-allocations/{id}/complete/
• 权限： 需登录，需仓库员工权限

请求参数：

{
  remarks?: string;               // 可选，完成备注
}

响应数据：

{
  code: 200,
  message: "配货完成",
  data: TaskAllocation
}

校验规则：

• 所有明细的 allocated_quantity 必须 > 0
• 如果某明细未配货，返回 400 错误

---

2.2.8 确认配货结果并转销售单 ⭐

销售人员/客户确认配货数量，将预销售单转为正式销售单

• 路径： POST /api/v1/task-allocations/{id}/confirm-and-convert/
• 权限： 需登录，需销售员工权限

请求参数：

{
  confirmed_items: Array<{
    item_id: number;              // 明细 ID
    confirmed_quantity: string;   // 确认的数量（可能与实际配货数量不同）
  }>;
  remarks?: string;               // 可选，确认备注
}

响应数据：

{
  code: 200,
  message: "已转为销售单",
  data: {
    task_allocation: TaskAllocation;  // 更新后的任务配货（状态变更）
    sales_order: {
      id: number;
      human_id: string;           // 销售单编号（如 XS20260201000001）
      // ... 其他销售单字段
    }
  }
}

---

2.3 预销售单状态扩展

现有预销售单 API 需要新增以下字段：

// 响应中新增
{
  // ... 原有字段 ...
  
  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. 预销售单和任务配货是否一对一关系？还是一对多？

---

前端负责人： [待填写]
后端负责人： [待填写]
评审日期： [待填写]