# 备货单车辆明细附件上传 — 后端对接说明

> 前端已完成：添加备货单页，每辆车行有「上传附件」入口。本文档仅说明后端需配合的部分。

## 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）备货单如需同等能力，接口字段一致，可一并支持。