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

---

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