forked from erp-dev/erp
274 lines
7.1 KiB
Markdown
274 lines
7.1 KiB
Markdown
# API v1：预销售单 / 预采购单（前端对接）
|
||
|
||
本文档面向前端，描述预销售单（PreSalesOrder）与预采购单（PrePurchaseOrder）的 API、字段与参数。
|
||
|
||
- API 前缀：`/api/v1/`
|
||
- 认证：接口均要求登录（`IsAuthenticated`）。
|
||
- 权限：要求当前用户绑定员工（`request.user.employee`），否则返回 `403`。
|
||
|
||
## 分页（Limit/Offset）
|
||
|
||
预销售单列表、预采购单列表均使用 DRF `LimitOffsetPagination`：
|
||
|
||
- `limit`：返回条数，默认 `20`，最大 `100`
|
||
- `offset`：偏移量，默认 `0`
|
||
|
||
分页响应结构：
|
||
|
||
```json
|
||
{
|
||
"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`）。
|
||
|
||
示例请求：
|
||
|
||
```json
|
||
{
|
||
"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`）。
|
||
|
||
示例请求：
|
||
|
||
```json
|
||
{
|
||
"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": "预采购单不存在"}`
|