feat: allocation record for pre sales order

docs/pre_order_api_field_analysis.md

@@ -0,0 +1,164 @@
+# 预销售单/预采购单 API 字段分析报告
+
+> **文档目的：** 对比 API 响应字段与前端实际使用情况，优化接口返回数据
+> 
+> **生成日期：** 2026-02-01
+
+---
+
+## 一、问题概述
+
+- **业务场景：** 预销售单/预采购单的列表、详情展示
+- **涉及 API：**
+  - `GET /api/v1/pre-sales-orders/`
+  - `GET /api/v1/pre-sales-orders/{id}/`
+  - `GET /api/v1/pre-purchase-orders/`
+  - `GET /api/v1/pre-purchase-orders/{id}/`
+- **问题类型：** API 返回了前端未使用的冗余字段
+
+---
+
+## 二、单据主体字段分析
+
+### 2.1 API 返回但前端未使用的字段（建议移除或设为可选）
+
+| 字段 | 类型 | 说明 | 前端使用情况 |
+|------|------|------|-------------|
+| `merchant` | int | 商户 ID | ❌ 未使用，前端用户已在自己商户下 |
+| `merchant_name` | string | 商户名称 | ❌ 未使用 |
+| `created_by` | int\|null | 创建者用户 ID | ❌ 未使用，只用 username |
+| `operator` | int\|null | 经办人 ID | ❌ 未使用，只用 name |
+| `updated_at` | datetime | 更新时间 | ❌ 未使用 |
+
+### 2.2 前端实际使用的字段
+
+| 字段 | 使用场景 |
+|------|----------|
+| `id` | 主键，编辑/删除操作 |
+| `human_id` | 列表显示、详情标题 |
+| `customer` / `supplier` | 表单回显（编辑时） |
+| `customer_name` / `supplier_name` | 列表列、详情显示 |
+| `warehouse` | 表单回显（编辑时） |
+| `warehouse_name` | 列表列、详情显示 |
+| `created_by_username` | 详情抽屉显示 |
+| `operator_name` | 列表列、详情显示 |
+| `kind` | 列表列（标签）、详情显示 |
+| `remarks` | 列表列、详情显示 |
+| `created_at` | 列表列（格式化显示） |
+| `items` | 详情明细表格 |
+
+---
+
+## 三、明细 items 字段分析
+
+### 3.1 API 返回但前端未使用的字段
+
+| 字段 | 类型 | 说明 | 前端使用情况 |
+|------|------|------|-------------|
+| `quantity_of_rolls` | string\|null | 各条数数量 | ❌ 页面未显示 |
+| `num_of_rolls` | int | 条数 | ❌ 页面未显示 |
+| `order_quantity` | int\|null | 下单数量 | ❌ 页面未显示 |
+| `created_at` | datetime | 明细创建时间 | ❌ 页面未显示 |
+| `updated_at` | datetime | 明细更新时间 | ❌ 页面未显示 |
+
+### 3.2 前端实际使用的字段
+
+| 字段 | 使用场景 |
+|------|----------|
+| `id` | 表格 row key |
+| `product_id` | 编辑时回显 |
+| `product_name` | 明细表格列 |
+| `spec` | 明细表格列 |
+| `color` | 明细表格列 |
+| `quantity` | 明细表格列 |
+| `unit` | 明细表格列 |
+| `remarks` | 明细表格列 |
+
+---
+
+## 四、建议方案
+
+### 方案 A：精简默认响应（推荐）
+
+移除以下字段的默认返回，减少数据传输量：
+
+**单据主体移除：**
+```diff
+{
+  "id": 1,
+  "human_id": "YS20260201000001",
+- "merchant": 1,
+- "merchant_name": "XX商户",
+  "customer": 123,
+  "customer_name": "客户A",
+  "warehouse": 1,
+  "warehouse_name": "主仓库",
+- "created_by": 10,
+  "created_by_username": "admin",
+- "operator": 5,
+  "operator_name": "张三",
+  "kind": 1,
+  "remarks": "备注",
+  "created_at": "2026-02-01T10:00:00Z",
+- "updated_at": "2026-02-01T10:00:00Z",
+  "items": [...]
+}
+```
+
+**明细 items 移除：**
+```diff
+{
+  "id": 1,
+  "product_id": 100,
+  "product_name": "产品A",
+  "color": "红色",
+  "quantity": "20.00",
+  "unit": "米",
+  "spec": "规格1",
+- "quantity_of_rolls": null,
+- "num_of_rolls": 1,
+- "order_quantity": null,
+  "remarks": "明细备注"
+- "created_at": "2026-02-01T10:00:00Z",
+- "updated_at": "2026-02-01T10:00:00Z"
+}
+```
+
+### 方案 B：支持 fields 参数按需返回
+
+如果其他客户端可能需要这些字段，可以支持 `fields` 查询参数：
+
+```
+GET /api/v1/pre-sales-orders/?fields=id,human_id,customer_name,items
+```
+
+---
+
+## 五、预估收益
+
+假设每条单据平均 5 个明细项：
+
+| 优化项 | 移除字段数 | 预估节省字节 |
+|--------|-----------|-------------|
+| 单据主体 | 5 个字段 | ~150 bytes/单据 |
+| 明细项 | 5 个字段 × 5 项 | ~250 bytes/单据 |
+| **总计** | - | ~400 bytes/单据 |
+
+列表页默认 20 条：**节省约 8KB/请求**
+
+---
+
+## 六、确认事项
+
+请后端同事确认：
+
+1. [ ] 上述"未使用字段"是否可以从默认响应中移除？
+2. [ ] 是否有其他客户端（如小程序、管理后台）依赖这些字段？
+3. [ ] 如果有其他依赖，是否采用方案 B（fields 参数）？
+4. [ ] `quantity_of_rolls`、`num_of_rolls`、`order_quantity` 这三个明细字段是否有业务场景需要？如果暂时不用，前端类型定义中会保留但标记为可选。
+
+---
+
+**前端负责人：** [待填写]  
+**后端负责人：** [待填写]  
+**预计完成：** [待填写]