105 lines
3.6 KiB
Markdown
105 lines
3.6 KiB
Markdown
# 备货单车辆明细附件上传 — 后端对接说明
|
||
|
||
> 前端已完成：添加备货单页，每辆车行有「上传附件」入口。本文档仅说明后端需配合的部分。
|
||
|
||
## 1. 功能说明
|
||
|
||
备货单（`stock_orders`）的车辆明细（`stock_order_items`），**每辆车**需要支持上传若干附件（如该车相关单据）。附件随车辆一起保存、详情回显。
|
||
|
||
## 2. 数据库（已就绪）
|
||
|
||
`stock_order_items` 表已新增 `attachment` 字段。
|
||
|
||
- 字段名：`attachment`
|
||
- 类型：建议 `varchar` / `text` / `json`，存 **JSON 字符串**
|
||
- 含义：该车辆的附件列表
|
||
|
||
## 3. 字段格式约定
|
||
|
||
`attachment` 存「对象数组」的 JSON：
|
||
|
||
```json
|
||
[
|
||
{ "url": "https://xxx.com/file.pdf", "original_name": "装箱单.pdf" }
|
||
]
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `url` | string | 文件访问地址（即 `/ticket/upload` 返回的 `file_url`） |
|
||
| `original_name` | string | 原始文件名 |
|
||
|
||
- 每辆车 0~N 个附件；无附件时为空数组 `[]` 或 `null`。
|
||
|
||
> **重要**：此格式与备货单级 `contract` 字段**完全一致**（`contract` 也是 `[{url, original_name}]`）。后端可直接复用现有处理 `contract` 的读写逻辑，区别仅在于：`attachment` 挂在 `veh_list` 每一项、落到 `stock_order_items` 表。
|
||
|
||
## 4. 需要修改的接口
|
||
|
||
均在前端调用路径 `/crm/stock/order/` 下。
|
||
|
||
### 4.1 新增 `POST /crm/stock/order/store`
|
||
- 请求体 `veh_list` 每一项现在多一个 `attachment` 字段（`[{url, original_name}]`）。
|
||
- 解析 `veh_list` 入库时，把每项 `attachment` 写入对应 `stock_order_items` 行的 `attachment` 字段（JSON 序列化）。
|
||
|
||
### 4.2 编辑 `POST /crm/stock/order/update`
|
||
- 同 `store`。
|
||
|
||
### 4.3 详情 `GET /crm/stock/order/show`
|
||
- 返回的 `veh_list` 每一项需带上 `attachment`（`[{url, original_name}]`）。
|
||
|
||
### 4.4 详情 `GET /crm/stock/order/detail`
|
||
- 同 `show`，返回 `veh_list` 每一项带 `attachment`。
|
||
|
||
## 5. 请求 / 响应示例
|
||
|
||
**提交（store / update）payload：**
|
||
|
||
```jsonc
|
||
{
|
||
// ...备货单级字段（含 contract / pi_doc / transaction_slip）
|
||
"veh_list": [
|
||
{
|
||
"sku_id": "123",
|
||
"model_snapshot": "丰田 卡罗拉",
|
||
// ...其他车辆字段
|
||
"attachment": [
|
||
{ "url": "https://xxx/a.pdf", "original_name": "装箱单.pdf" }
|
||
]
|
||
}
|
||
],
|
||
"account_list": [],
|
||
"approval_status": 0
|
||
}
|
||
```
|
||
|
||
**详情（show / detail）响应：**
|
||
|
||
```jsonc
|
||
{
|
||
"veh_list": [
|
||
{
|
||
"sku_id": "123",
|
||
"model_snapshot": "丰田 卡罗拉",
|
||
"attachment": [
|
||
{ "url": "https://xxx/a.pdf", "original_name": "装箱单.pdf" }
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 6. 上传接口（无需改动）
|
||
|
||
`/ticket/upload`（通用文件上传）保持原样。前端已用它上传文件，拿到 `{ file_url, file_name, original_name }`，再自行拼成 `{ url, original_name }` 存进 `attachment`。**后端无需在上传接口做任何业务关联。**
|
||
|
||
## 7. 验收标准
|
||
|
||
1. 前端添加备货单、每辆车上传附件 → 提交 → `stock_order_items.attachment` 正确落库（JSON 数组）。
|
||
2. 调 `show` / `detail`，返回的 `veh_list` 每项 `attachment` 与落库内容一致。
|
||
3. （编辑页后续加 UI 后）编辑备货单时，已存附件可回显、可增删。
|
||
|
||
## 8. 备注
|
||
|
||
- 本次前端只在「添加备货单」页加了上传 UI；编辑页（`stocking_edit`）共用同一套提交/回填逻辑，数据层已支持 `attachment`，编辑页 UI 后续补，**不影响后端接口契约**。
|
||
- 终版（final）备货单如需同等能力，接口字段一致，可一并支持。
|