forked from erp-dev/erp
165 lines
4.8 KiB
Markdown
165 lines
4.8 KiB
Markdown
# 预销售单/预采购单 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` 这三个明细字段是否有业务场景需要？如果暂时不用，前端类型定义中会保留但标记为可选。
|
||
|
||
---
|
||
|
||
**前端负责人：** [待填写]
|
||
**后端负责人：** [待填写]
|
||
**预计完成：** [待填写]
|