# 冷库库存转代卖

> 运营端转代卖两个接口 + 仓库小程序最终扎数确认，含口径规则与报错文案

- 类型：前端对接
- 分类：冷库暂存花材
- 端：运营后台 / 仓库小程序
- 后端服务：admin / supplier
- 更新：2026-07-31
- 网页版：https://doc.xfun.fun/cold-convert-sale-api

客服将客户不想要的冷库暂存花材转为平台代卖。运营后台新增 2 个接口，仓库小程序在现有出库流程上增加最终扎数确认。所有接口均为 POST + JSON，通用约定（登录态、返回结构 R<T>）与现有冷库暂存接口一致。

## 业务流程与规则

### 两阶段流程

- **① 运营后台（客服）**：暂存列表操作「转代卖」→ 先调 [预填信息接口](#cold-convert-sale-info) 弹窗展示可转扎数上限 → 客服填写扎数、备注后调 [确认转代卖](#cold-convert-sale)，生成一条 **待出库**的转代卖任务并锁定库存。
- **② 仓库小程序**：在暂存出库列表看到该任务（`outType=3`），点击出库时 **必须填写最终出库扎数**（其余照片必传、备注选填等同现有出库）。
- 待出库期间客服可[撤销](#cold-out-cancel)（复用现有撤销接口），撤销后库存解锁：包裹回暂存中、裸花回待发货。

> [!NOTE]
> **权限**复用现有权限点：预填信息 = 冷库查看权限，确认转代卖 = 冷库操作权限，不新增权限项。

### 两种暂存类型的口径差异

|  | 裸花暂存（storeType=2） | 包裹暂存（storeType=1） |
|----|----|----|
| 转出粒度 | **支持部分转出**，按扎数扣减 | **整库存转出**，全部在库包裹一起锁定 |
| 可转上限（预填接口 `maxBunchNum`） | 当前剩余暂存扎数，必有值 | 发货单总扎数（打包时点快照），**可能为 null** —— 前端显示「-」且提交时不做前端校验 |
| 客服填写扎数校验 | ≤ 剩余暂存扎数 | 快照有值时 ≤ 快照；快照为 null 不校验 |
| 仓库出库最终扎数 | ≤ 客服审批扎数，且 ≤ 当前剩余；扣完出清，**有剩余则回「待发货」继续暂存**（需客服重新确认发货） | ≤ 客服审批扎数；包裹全部置已出库 |

> [!WARNING]
> **不支持转代卖的情况**城市仓货架暂存（ware_id\>0，跨多客户）直接拦截；已存在待出库任务的库存需先完成或撤销。

## 枚举变更速查

### outType 出库方式（新增值）

| 值 | 含义 |
|----|----|
| 1 | 关联发货单 |
| 2 | 直接出库 |
| 3 | 转代卖 **新增** |

历史出库记录、暂存出库列表等所有带 `outType` 的接口天然支持值 3，筛选参数无需改动。任务状态枚举不变：10 待出库 · 20 已出库 · 30 已撤销

## 运营后台端（客服）

### POST /cold/convert-sale/info · 转代卖预填信息

**新增**

点「转代卖」弹窗前调用，返回暂存类型与可转扎数上限。同时做资格预检——不满足条件（城市仓货架、已有待出库任务、没有在库包裹等）会直接报错，前端 toast 错误信息即可，避免弹窗填完提交才被拒。

#### 请求参数

| 字段          | 类型 | 必填 | 说明                           |
|---------------|------|------|--------------------------------|
| `coldStockId` | Long | 是   | 冷库库存 id（暂存列表行的 id） |

#### 返回 data

| 字段 | 类型 | 说明 |
|----|----|----|
| `storeType` | Integer | 暂存类型 1:包裹 2:裸花 |
| `maxBunchNum` | Integer | 可转扎数上限。裸花=当前剩余暂存扎数；包裹=发货单总扎数快照，**可为 null**（前端显示「-」，输入框不做上限校验） |

#### 示例

```text
// 请求
{ "coldStockId": 1024 }

// 返回（裸花）
{ "code": 200, "data": { "storeType": 2, "maxBunchNum": 15 } }

// 返回（包裹，快照查不到）
{ "code": 200, "data": { "storeType": 1, "maxBunchNum": null } }
```

### POST /cold/convert-sale · 确认转代卖

**新增**

生成待出库的转代卖任务。包裹暂存会锁定该库存 **全部在库包裹**；实际出库由仓库小程序完成。返回 data 为任务 id。

#### 请求参数

| 字段          | 类型    | 必填 | 说明                                  |
|---------------|---------|------|---------------------------------------|
| `coldStockId` | Long    | 是   | 冷库库存 id                           |
| `bunchNum`    | Integer | 是   | 转代卖扎数，正整数（≥1）              |
| `remark`      | String  | 否   | 备注（转代卖原因或操作说明），≤255 字 |

#### 业务报错文案（toast 展示即可）

- 「城市仓货架暂存不支持转代卖」
- 「存在待出库任务，请先完成或撤销后再转代卖」（包裹）
- 「该库存没有可转代卖的在库包裹」（包裹）
- 「转代卖扎数不能大于发货单总扎数X扎」（包裹，快照有值时）
- 「转代卖扎数不能大于当前剩余暂存X扎」（裸花）

#### 示例

```text
// 请求
{ "coldStockId": 1024, "bunchNum": 10, "remark": "客户不要了，转平台代卖" }

// 返回
{ "code": 200, "data": 88 }   // data = 出库任务 id
```

### POST /cold/out/cancel · 撤销出库任务

**复用**

转代卖任务待出库期间的撤销 **完全复用现有撤销接口**，入参出参不变。撤销后：包裹解锁回「暂存中」，裸花库存回「待发货」；历史出库记录中该任务显示 `outType=3` 及撤销信息。

### POST /cold/out/records · 历史出库记录

**字段变更**

入参不变（`outType` 筛选传 3 即可查转代卖记录）。返回行新增/调整字段：

| 字段 | 类型 | 变更 | 说明 |
|----|----|----|----|
| `finishBunchNum` | Integer | **新增** | 仓库确认最终出库扎数（转代卖任务，已出库后有值；其他任务为 null） |
| `outType` | Integer | 枚举扩展 | 1:关联发货单 2:直接出库 **3:转代卖** |
| `outBunchNum` | Integer | 语义扩展 | 原为裸花暂存出库扎数；**转代卖任务为客服填写的转代卖扎数，包裹暂存也有值** |

### POST /cold/stock/page · 暂存列表

**字段变更**

返回行新增字段，用于在列表上给待出库的转代卖库存打标签：

| 字段 | 类型 | 变更 | 说明 |
|----|----|----|----|
| `outTaskType` | Integer | **新增** | 最新任务的出库方式 1:关联发货单 2:直接出库 3:转代卖（无任务时为 null；=3 时前端显示「转代卖」标签） |

## 仓库小程序端

### POST /cold/mini/out/finish · 点击出库

**字段变更**

入参新增 `bunchNum`。任务为转代卖（`outType=3`）时前端必须让仓库人员填写最终出库扎数；其他任务类型不传。照片必传、备注选填等原有规则不变。

#### 入参新增字段

| 字段 | 类型 | 必填 | 说明 |
|----|----|----|----|
| `bunchNum` | Integer | 转代卖任务必填 | 最终出库扎数，正整数。裸花任务出库后：扣完 → 库存出清；有剩余 → 剩余扎数回「待发货」继续暂存 |

#### 业务报错文案

- 「请填写最终出库扎数」（转代卖任务未填或 ≤0）
- 「最终出库扎数不能大于客服审批的转代卖扎数X扎」
- 「最终出库扎数不能大于当前剩余暂存扎数」（裸花，并发或超量）

#### 示例

```text
// 转代卖任务出库请求
{
  "outTaskId": 88,
  "imageUrls": "https://cdn.example.com/a.jpg,https://cdn.example.com/b.jpg",
  "remark": "已搬到代卖区",
  "bunchNum": 8
}
```

### POST /cold/mini/out/page · 暂存出库列表

**字段变更**

入参不变，转代卖任务会自然出现在待出库/已出库列表中。返回行新增/调整字段：

| 字段 | 类型 | 变更 | 说明 |
|----|----|----|----|
| `finishBunchNum` | Integer | **新增** | 仓库确认最终出库扎数（转代卖任务，已出库后有值） |
| `outType` | Integer | 枚举扩展 | 1:关联发货单 2:直接出库 **3:转代卖**（=3 时点击出库需弹出最终扎数输入） |
| `outBunchNum` | Integer | 语义扩展 | 转代卖任务为客服填写的转代卖扎数（包裹暂存也有值），可作为最终扎数输入框的默认值/上限提示 |

> [!NOTE]
> **转代卖任务展示建议**待出库卡片显示「转代卖 · 客服审批 X 扎」；已出库卡片显示「转代卖 · 实际出库 finishBunchNum 扎」。物流相关字段（`linkSendNo`、`expressName`）转代卖任务为空。

对应提交 `3129cb28da 裸花转代卖` · 测试环境已部署（admin + supplier）