art-design/docs/后端对接-备货单车辆附件上传.md

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

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

1. 功能说明

备货单（stock_orders）的车辆明细（stock_order_items），每辆车需要支持上传若干附件（如该车相关单据）。附件随车辆一起保存、详情回显。

2. 数据库（已就绪）

stock_order_items 表已新增 attachment 字段。

• 字段名：attachment
• 类型：建议 varchar / text / json，存 JSON 字符串
• 含义：该车辆的附件列表

3. 字段格式约定

attachment 存「对象数组」的 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：

{
  // ...备货单级字段（含 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）响应：

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