erpnew/docs/api_v1_pre_order_api.md

API v1：预销售单 / 预采购单（前端对接）

本文档面向前端，描述预销售单（PreSalesOrder）与预采购单（PrePurchaseOrder）的 API、字段与参数。

• API 前缀：/api/v1/
• 认证：接口均要求登录（IsAuthenticated）。
• 权限：要求当前用户绑定员工（request.user.employee），否则返回 403。

分页（Limit/Offset）

预销售单列表、预采购单列表均使用 DRF LimitOffsetPagination：

• limit：返回条数，默认 20，最大 100
• offset：偏移量，默认 0

分页响应结构：

{
  "count": 123,
  "next": "http://.../api/v1/pre-sales-orders/?limit=20&offset=20",
  "previous": null,
  "results": [
    { "id": 1, "human_id": "YS...", "items": [] }
  ]
}

列表查询参数（已支持）

预销售单列表 GET /pre-sales-orders/：

• limit / offset
• customer / customer_id（int）
• warehouse / warehouse_id（int）
• kind（int）
• human_id__icontains（string）
• created_at_from（datetime 或 date）
• created_at_to（datetime 或 date）

预采购单列表 GET /pre-purchase-orders/：

• limit / offset
• supplier / supplier_id（int）
• warehouse / warehouse_id（int）
• kind（int）
• human_id__icontains（string）
• created_at_from（datetime 或 date）
• created_at_to（datetime 或 date）

---

预销售单 PreSalesOrder

1) 列表

• GET /api/v1/pre-sales-orders/?limit=20&offset=0
• 查询参数：
  • limit（可选，int，默认 20，最大 100）
  • offset（可选，int，默认 0）
• 响应：200 OK，分页结构，results 为预销售单数组

2) 创建

• POST /api/v1/pre-sales-orders/

请求体参数（JSON）：

• customer / customer_id（必填，int）：客户 ID
• warehouse / warehouse_id（必填，int）：仓库 ID
• kind（可选，int）：预销售单类型
  • 1：大货
  • 2：样板
  • 默认 1
• remarks（可选，string）
• items（必填，array，非空）：明细列表

items[] 字段：

• product_id / product（必填，int）：产品 ID
• quantity（必填，string 或 number）：数量（会被转换为 Decimal）
• unit（可选，string）：单位；为空时会尝试使用产品默认单位
• product_name（可选，string）：产品名称（弱关联承载）
• color（可选，string）
• spec（可选，string）
• quantity_of_rolls（可选，string）：各条数数量（原样保存）
• num_of_rolls（可选，int）：条数，必须 > 0，默认 1
• order_quantity（可选，int）：下单数量，必须为非负整数
• remarks（可选，string）：明细备注

响应：201 CREATED，返回预销售单详情（含 items）。

示例请求：

{
  "customer": 1,
  "warehouse": 2,
  "kind": 1,
  "remarks": "预销售单备注",
  "items": [
    {
      "product_id": 10,
      "quantity": "12.5",
      "unit": "米",
      "order_quantity": 7,
      "remarks": "明细备注"
    }
  ]
}

3) 详情

• GET /api/v1/pre-sales-orders/{id}/
• 响应：200 OK，返回预销售单详情

4) 更新（全量/部分）

• PUT /api/v1/pre-sales-orders/{id}/
• PATCH /api/v1/pre-sales-orders/{id}/

请求体参数：

• customer / customer_id（可选，int）
• warehouse / warehouse_id（可选，int）
• kind（可选，int）
• remarks（可选，string）
• items（必填，array，非空）：更新时必须提供，否则会返回 400

响应：200 OK，返回更新后的详情。

5) 删除

• DELETE /api/v1/pre-sales-orders/{id}/
• 响应：204 NO CONTENT

预销售单字段说明（响应）

预销售单对象字段（results[] 与详情一致）：

• id（int）：主键
• human_id（string）：人类可读编号（如 YSYYYYMMDD000001）
• merchant（int）：所属商户 ID
• merchant（int）：商户 ID（调试字段）
• customer（int）：客户 ID
• customer_name（string，只读）
• warehouse（int）：仓库 ID
• warehouse_name（string，只读）
• operator（int|null）：经办人（员工）ID（创建时由后端从登录用户推导）
• operator_name（string，只读）
• kind（int）：类型（1/2）
• remarks（string|null）
• created_at（datetime string）
• items（array）：明细（只读）

items[] 字段（响应）：

• id（int）
• product_id（int|null）
• product_name（string）
• color（string|null）
• quantity（string|null，通常为两位小数，如 "20.00"）
• unit（string）
• spec（string|null）
• remarks（string|null）

---

预采购单 PrePurchaseOrder

1) 列表

• GET /api/v1/pre-purchase-orders/?limit=20&offset=0
• 查询参数：
  • limit（可选，int，默认 20，最大 100）
  • offset（可选，int，默认 0）
• 响应：200 OK，分页结构

2) 创建

• POST /api/v1/pre-purchase-orders/

请求体参数（JSON）：

• supplier / supplier_id（必填，int）：供应商 ID
• warehouse / warehouse_id（必填，int）：仓库 ID
• kind（可选，int）：预采购单类型
  • 1：大货
  • 2：样板
  • 默认 1
• remarks（可选，string）
• items（必填，array，非空）：明细列表（字段同预销售明细）

响应：201 CREATED，返回预采购单详情（含 items）。

示例请求：

{
  "supplier": 1,
  "warehouse": 2,
  "kind": 1,
  "remarks": "预采购单备注",
  "items": [
    {
      "product_id": 10,
      "quantity": "12.5",
      "unit": "米",
      "order_quantity": 7,
      "remarks": "明细备注"
    }
  ]
}

3) 详情

• GET /api/v1/pre-purchase-orders/{id}/
• 响应：200 OK

4) 更新（全量/部分）

• PUT /api/v1/pre-purchase-orders/{id}/
• PATCH /api/v1/pre-purchase-orders/{id}/

请求体参数：

• supplier / supplier_id（可选，int）
• warehouse / warehouse_id（可选，int）
• kind（可选，int）
• remarks（可选，string）
• items（必填，array，非空）：更新时必须提供，否则会返回 400

响应：200 OK

5) 删除

• DELETE /api/v1/pre-purchase-orders/{id}/
• 响应：204 NO CONTENT

预采购单字段说明（响应）

预采购单对象字段（results[] 与详情一致）：

• id（int）
• human_id（string）：人类可读编号（如 YCYYYYMMDD000001）
• merchant（int）
• merchant（int）：商户 ID（调试字段）
• supplier（int）
• supplier_name（string，只读）
• warehouse（int）
• warehouse_name（string，只读）
• operator（int|null）
• operator_name（string，只读）
• kind（int，1/2）
• remarks（string|null）
• created_at
• items（array，只读）

items[] 字段同预销售明细响应。

---

错误响应约定（两类接口通用）

• 400 BAD REQUEST：参数校验失败
  • 示例：{"error": "items 需要为非空数组"}
• 401 UNAUTHORIZED：未登录
• 403 FORBIDDEN：无员工信息/无权限
  • 示例：{"error": "无权限访问"}
• 404 NOT FOUND：订单不存在
  • 示例：{"error": "预销售单不存在"} / {"error": "预采购单不存在"}