erpnew/docs/pre_order_api_field_analysis.md

预销售单/预采购单 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：精简默认响应（推荐）

移除以下字段的默认返回，减少数据传输量：

单据主体移除：

{
  "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 移除：

{
  "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 这三个明细字段是否有业务场景需要？如果暂时不用，前端类型定义中会保留但标记为可选。

---

前端负责人： [待填写]
后端负责人： [待填写]
预计完成： [待填写]