docs: 后端对接说明-备货单车辆附件上传

Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-06 14:51:46 +08:00
parent b3f6d591b5
commit 6e23f83e78
1 changed files with 104 additions and 0 deletions
@@ -0,0 +1,104 @@
+# 备货单车辆明细附件上传 — 后端对接说明
+
+> 前端已完成：添加备货单页，每辆车行有「上传附件」入口。本文档仅说明后端需配合的部分。
+
+## 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）备货单如需同等能力，接口字段一致，可一并支持。