# 冷库暂存花材接口

> 改版前后接口逐项增删改对照

- 类型：版本差异
- 分类：冷库暂存花材
- 更新：2026-07-15
- 网页版：https://doc.xfun.fun/%E5%86%B7%E5%BA%93%E6%9A%82%E5%AD%98%E8%8A%B1%E6%9D%90%E6%8E%A5%E5%8F%A3%E6%96%87%E6%A1%A3-%E6%96%B0%E6%97%A7%E7%89%88%E6%9C%AC%E5%B7%AE%E5%BC%82

| | 旧版 · 首次部署 | 新版 · 当前线上 |
|----|----|----|
| 接口数 | 26（旧页面误标 28） | 24 |
| 依据提交 | `dc00890ece` | `b5f20cfd24` |

变化统计：删除接口 **5** 个 · 新增接口 **3** 个 · **13** 个接口有字段/描述变化 · 枚举变化 **7** 组（删 3 组、改 4 组）。

两版之间经历了一次方案重构：**取消暂存需求提报和次日出库确认**（改为线下沟通 + 联系记录留痕）、**出库由“运营端操作即完成”改为两段式**（客服建待出库任务 → 仓库 PDA 逐包扫码 / 小程序整单确认，期间可撤销）、**冷库状态收敛到冷库明细表**（包裹表仅新增 40 拆箱重打，不再有 15/30 中间态）、裸花登记改为全二维码识别。

## 运营端（删 4 · 改 9）

### POST /cold/demand/save · 暂存需求提报

**删除** · 运营端

「暂存需求提报」功能整体取消：客服与仓库改为线下沟通，暂存以仓库扫码登记为准，系统不做需求提报。

#### 入参明细（9 个字段） · 返回 R\<Long\>

| 变化 | 字段              | 类型    | 必填 | 说明                                    |
|------|-------------------|---------|------|-----------------------------------------|
| 删除 | purchaserId       | Long    | 必填 | 客户(采购方)id                          |
| 删除 | sendNo            | String  | 选填 | 发货单号                                |
| 删除 | storeType         | Integer | 必填 | 暂存类型 1包裹 2裸花                    |
| 删除 | expectPackageNum  | Integer | 选填 | 预计暂存包裹件数                        |
| 删除 | expectBunchNum    | Integer | 选填 | 预计裸花扎数                            |
| 删除 | shipWay           | Integer | 必填 | 发货方式 1指定日期 2客户通知            |
| 删除 | planShipDate      | String  | 选填 | 计划发货日期 yyyy-MM-dd(指定日期时必填) |
| 删除 | suggestLocationNo | String  | 选填 | 建议暂存货位号                          |
| 删除 | serviceRemark     | String  | 选填 | 客服备注                                |

### POST /cold/demand/page · 暂存需求提报列表

**删除** · 运营端

同上，需求提报功能整体取消。

#### 入参明细（2 个字段） · 返回 R\<PageVO\<ColdDemandDto\>\>

| 变化 | 字段         | 类型    | 必填 | 说明                                    |
|------|--------------|---------|------|-----------------------------------------|
| 删除 | demandStatus | Integer | 选填 | 需求状态 10待仓库登记 20已登记 30已作废 |
| 删除 | storeType    | Integer | 选填 | 暂存类型 1包裹 2裸花                    |

### POST /cold/demand/register · 仓库登记

**删除** · 运营端

同上，需求登记转库存的环节随需求提报一起取消，入库统一走扫码。

#### 入参明细（4 个字段） · 返回 R\<Long\>

| 变化 | 字段       | 类型    | 必填 | 说明                             |
|------|------------|---------|------|----------------------------------|
| 删除 | demandId   | Long    | 必填 | 暂存需求id                       |
| 删除 | locationNo | String  | 选填 | 实际暂存货位号(空则沿用建议货位) |
| 删除 | bunchNum   | Integer | 选填 | 裸花实际扎数(裸花暂存必填)       |
| 删除 | remark     | String  | 选填 | 备注(空则沿用客服备注)           |

### POST /cold/stock/confirm · 次日出库确认

**删除** · 运营端

「次日出库确认」流程取消：合肥客服线下联系客户，系统只保留联系记录留痕（/cold/contact/save），不再驱动状态迁移。

#### 入参明细（5 个字段） · 返回 R\<Void\>

| 变化 | 字段 | 类型 | 必填 | 说明 |
|----|----|----|----|----|
| 删除 | coldStockId | Long | 必填 | 冷库库存id |
| 删除 | shipConfirm | Integer | 必填 | 确认结果 1今日出库 2继续暂存 3联系不上 4取消暂存 |
| 删除 | nextPlanShipDate | String | 选填 | 下次计划发货日期(继续暂存) yyyy-MM-dd |
| 删除 | content | String | 选填 | 确认备注/联系内容 |
| 删除 | imageUrls | String | 选填 | 图片url(逗号分隔) |

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

**变更 13 处** · 运营端

#### 接口级变化

| 属性 | 旧版                             | 新版                                 |
|------|----------------------------------|--------------------------------------|
| 描述 | 客服查看仓库登记后的库存。分页。 | 客服查看仓库扫码入库后的库存。分页。 |

#### 返回字段变化

| 变化 | 字段 | 类型 |  | 说明 |
|----|----|----|----|----|
| 新增 | expressName | String | — | 发货物流名称(原发货单物流,直接出库沿用展示) |
| 新增 | linkReceiveName | String | — | 关联发货单收货人 |
| 新增 | linkReceiveTel | String | — | 关联发货单收货电话 |
| 新增 | linkReceiveAddress | String | — | 关联发货单收货地址 |
| 新增 | linkShelfSn | Integer | — | 关联发货单主货位号 |
| 新增 | linkSubShelfSn | String | — | 关联发货单子货位号 |
| 新增 | linkZoneShelf | String | — | 关联发货单区-货位号 |
| 新增 | outTaskId | Long | — | 最新出库任务id(outTaskStatus=10 时用于撤销) |
| 删除 | financeStatus | Integer | — | 合并发货账务状态 0待处理 10已处理 |
| 修改 | purchaserMobile | 说明变更 | 客户手机号 → 客户注册手机号 |
| 修改 | linkPurchaserMobile | 说明变更 | 关联发货单客户电话 → 关联发货单客户注册手机号 |
| 修改 | outTaskStatus | 说明变更 | 出库任务状态 → 出库任务状态(最新非撤销任务),见枚举 |

### POST /cold/stock/stat · 冷库暂存库存统计

**变更 6 处** · 运营端

#### 接口级变化

| 属性 | 旧版 | 新版 |
|----|----|----|
| 描述 | 顶部统计卡片。入参同 /cold/stock/page(同筛选条件统计)。 | 顶部统计卡片。**全局口径**,不随列表筛选条件联动(在库客户数/在库包裹数为当前全量,今日出库客户数与小程序首页同口径)。 |

#### 入参变化

| 变化 | 字段         | 类型    | 必填 | 说明       |
|------|--------------|---------|------|------------|
| 删除 | keyword      | String  | 选填 | 同库存列表 |
| 删除 | storeType    | Integer | 选填 | 同库存列表 |
| 删除 | stockStatus  | Integer | 选填 | 同库存列表 |
| 删除 | storeRoundNo | String  | 选填 | 同库存列表 |
| 删除 | planShipDate | String  | 选填 | 同库存列表 |

### POST /cold/contact/save · 新增联系记录

**变更 1 处** · 运营端

#### 入参变化

| 变化 | 字段 | 类型 | 必填 | 说明 |
|----|----|----|----|----|
| 修改 | shipConfirm | 说明变更 | 联系结果 1今日出库 2继续暂存 3联系不上 4取消暂存 → 联系结果 1今日出库 2继续暂存 3联系不上 |

### POST /cold/out/today-send-order · 查询当天发货单

**变更 7 处** · 运营端

#### 接口级变化

| 属性 | 旧版 | 新版 |
|----|----|----|
| 描述 | 按客户账号 + 当前场次查询。入参仅 coldStockId。 | 默认按冷库库存客户 + 当前场次查询发货单；可按客户注册手机号搜索其他客户的当天发货单。 |
| 返回类型 | R\<ColdSendOrderDto\> | R\<List\<ColdSendOrderDto\>\> |

#### 入参变化

| 变化 | 字段   | 类型   | 必填 | 说明                                         |
|------|--------|--------|------|----------------------------------------------|
| 新增 | mobile | String | 选填 | 客户注册手机号，不传时查暂存客户自己的发货单 |

#### 返回字段变化

| 变化 | 字段 | 类型 |  | 说明 |
|----|----|----|----|----|
| 新增 | shelfSn | Integer | — | 主货位号 |
| 新增 | subShelfSn | String | — | 子货位号 |
| 新增 | zoneShelf | String | — | 区-货位号 |
| 修改 | purchaserMobile | 说明变更 | 客户手机号 → 客户注册手机号 |

### POST /cold/out/link · 关联当天发货单出库

**变更 1 处** · 运营端

#### 接口级变化

| 属性 | 旧版 | 新版 |
|----|----|----|
| 描述 | 含拆箱重打。**操作即完成冷库出库**:任务直接落「已出库(20)」,冷库明细置已出库;非拆箱重打时包裹 express_status 30→10(打包完成)并回填当天发货单信息, **随当天发货单走正常物流出库扫码**,重量/运费/面单由正常发货流程采集。整批出库后库存「已出库(50)」;部分出库剩余回「待发货(10)」并清空发货确认。 | 含拆箱重打。常规出库生成待出库任务并锁定所选包裹，实际出库由 PDA 逐包扫码或小程序点击出库完成。拆箱重打时操作即完成出库，不可撤销。 |

### POST /cold/out/direct · 直接出库

**变更 3 处** · 运营端

#### 接口级变化

| 属性 | 旧版 | 新版 |
|----|----|----|
| 描述 | 不关联当天发货单。**操作即终态**:任务直接落「已出库(20)」,包裹 express_status 30→20(发货完成),实际重量/运费置0走线下对账。整批出库后库存「已出库(50)」;部分出库剩余回「待发货(10)」并清空发货确认。 | 不关联当天发货单。生成待出库任务并锁定所选包裹，实际出库由 PDA 逐包扫码或小程序点击出库完成。发货物流由服务端根据原发货单解析，前端不传。 |

#### 入参变化

| 变化 | 字段        | 类型   | 必填 | 说明                                         |
|------|-------------|--------|------|----------------------------------------------|
| 删除 | expressId   | Long   | 必填 | 发货物流id(必须为启用中的物流)               |
| 删除 | expressName | String | 选填 | 发货物流名称,由服务端按物流id回填,前端可不传 |

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

**变更 1 处** · 运营端

#### 接口级变化

| 属性 | 旧版 | 新版 |
|----|----|----|
| 描述 | **当天反出库**:仅可撤销当天完成的出库任务;拆箱重打不可撤;关联出库的包裹一旦被正常物流扫码发货(express_status=20)不可撤。撤销后包裹退回冷库暂存(30)并还原原场次,冷库明细回暂存中,库存回「待发货(10)」并回滚出库计数。历史遗留的「待出库」任务仍支持旧撤销逻辑。 | 仅可撤销待出库(10)且尚无包裹完成出库的任务。撤销后任务置已撤销(30)，释放锁定包裹；无其他待出库任务时，库存回退为待发货(10)。 |

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

**变更 10 处** · 运营端

#### 入参变化

| 变化 | 字段 | 类型 | 必填 | 说明 |
|----|----|----|----|----|
| 修改 | taskStatus | 说明变更 | 任务状态 20已出库 30已撤销(空=全部;10/15为旧流程遗留) → 任务状态 10待出库 20已出库 30已撤销(空=全部) |

#### 返回字段变化

| 变化 | 字段 | 类型 |  | 说明 |
|----|----|----|----|----|
| 新增 | linkReceiveName | String | — | 关联发货单收货人 |
| 新增 | linkReceiveTel | String | — | 关联发货单收货电话 |
| 新增 | linkReceiveAddress | String | — | 关联发货单收货地址 |
| 新增 | linkShelfSn | Integer | — | 关联发货单主货位号 |
| 新增 | linkSubShelfSn | String | — | 关联发货单子货位号 |
| 新增 | linkZoneShelf | String | — | 关联发货单区-货位号 |
| 修改 | purchaserMobile | 说明变更 | 暂存客户手机号 → 暂存客户注册手机号 |
| 修改 | linkPurchaserMobile | 说明变更 | 关联发货单客户电话 → 关联发货单客户注册手机号 |
| 修改 | taskStatus | 说明变更 | 任务状态 20已出库 30已撤销(10/15为旧流程遗留) → 任务状态,见枚举 |

### POST /cold/stock/pending-packages · 未入库包裹清单

**变更 2 处** · 运营端

#### 接口级变化

| 属性 | 旧版 | 新版 |
|----|----|----|
| 描述 | 发货单下已打包(状态10)但尚未扫入冷库的包裹清单,供客服核对预计/已入/未入件数并催办物流入库。sendNo 与 coldStockId 二选一(传 coldStockId 时取其原发货单号)。 | 发货单下已打包(状态10)但尚未扫入冷库的包裹清单,供客服核对已入/未入件数并催办物流入库。sendNo 与 coldStockId 二选一(传 coldStockId 时取其原发货单号)。 |

#### 返回字段变化

| 变化 | 字段             | 类型    |     | 说明                               |
|------|------------------|---------|-----|------------------------------------|
| 删除 | expectPackageNum | Integer | —   | 客服提报预计暂存件数(无提报单为空) |

## PDA端（增 1 · 改 2）

### POST /cold/pda/out/scan · 扫码出库

**新增** · PDA端

出库改为「两段式」：运营端只生成待出库任务，仓库 PDA 逐包扫码执行实际出库（最后一包扫完任务自动完成）。

#### 入参明细（4 个字段） · 返回 Response\<ColdScanOutResultVo\>

| 变化 | 字段        | 类型   | 必填 | 说明                        |
|------|-------------|--------|------|-----------------------------|
| 新增 | outTaskId   | Long   | 必填 | 出库任务id                  |
| 新增 | codeContent | String | 必填 | 包裹码(包裹id)              |
| 新增 | userId      | Long   | 注入 | 后端注入,前端不传           |
| 新增 | userName    | String | 注入 | 后端根据登录人解析,前端不传 |

### POST /cold/pda/scan · 扫码入库

**变更 1 处** · PDA端

#### 入参变化

| 变化 | 字段 | 类型 | 必填 | 说明 |
|----|----|----|----|----|
| 修改 | userName | 说明变更 | 操作人姓名 → 后端根据登录人解析,前端不传 |
| 修改 | userName | 注入变更 | - → inject |

### POST /cold/pda/stock/detail · 库存详情

**变更 3 处** · PDA端

#### 返回字段变化

| 变化 | 字段            | 类型   |     | 说明             |
|------|-----------------|--------|-----|------------------|
| 新增 | purchaserId     | Long   | —   | 客户id           |
| 新增 | remark          | String | —   | 客户备注         |
| 新增 | scanPackageCode | String | —   | 本次扫码的包裹码 |

## 小程序端（删 1 · 增 2 · 改 2）

### POST /cold/mini/customer/search · 客户搜索

**删除** · 小程序端

早期「手动选客户登记裸花」交互的残留：最终方案裸花登记全部由花材二维码识别客户，无手动搜索场景，且该接口可模糊枚举客户手机号，属无消费方的风险面。

#### 入参明细（1 个字段） · 返回 Response\<List\<ColdCustomerVo\>\>

| 变化 | 字段    | 类型   | 必填 | 说明                 |
|------|---------|--------|------|----------------------|
| 删除 | keyword | String | 必填 | 关键词(手机号或昵称) |

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

**新增** · 小程序端

两段式出库的小程序执行入口：裸花任务整单完成，包裹任务批量完成剩余待出库包裹。

#### 入参明细（3 个字段） · 返回 Response\<String\>

| 变化 | 字段      | 类型   | 必填 | 说明                        |
|------|-----------|--------|------|-----------------------------|
| 新增 | outTaskId | Long   | 必填 | 出库任务id                  |
| 新增 | userId    | Long   | 注入 | 后端注入,前端不传           |
| 新增 | userName  | String | 注入 | 后端根据登录人解析,前端不传 |

### POST /cold/mini/package/scan · 包裹扫码入库

**新增** · 小程序端

仓管小程序也支持包裹扫码入库（质检员/区域负责人/仓库管理员，不受物流商配置限制），与 PDA 扫码入库互补。

#### 入参明细（5 个字段） · 返回 Response\<ColdScanResultVo\>

| 变化 | 字段        | 类型   | 必填 | 说明                                     |
|------|-------------|--------|------|------------------------------------------|
| 新增 | codeContent | String | 必填 | 扫码内容(包裹id)                         |
| 新增 | coldStockId | Long   | 选填 | 累计入库的冷库库存id(连续扫同一客户时传) |
| 新增 | locationNo  | String | 选填 | 暂存货位号(新建库存时使用)               |
| 新增 | userName    | String | 注入 | 后端根据登录人解析,前端不传              |
| 新增 | userId      | Long   | 注入 | 后端注入,前端不传                        |

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

**变更 4 处** · 小程序端

#### 接口级变化

| 属性 | 旧版 | 新版 |
|----|----|----|
| 描述 | 今日出库任务查询视图(运营端操作即完成,列表以已出库为主)。分页。 | 待出库/已出库任务列表(默认不含已撤销)，含包裹扫码进度。分页。 |

#### 入参变化

| 变化 | 字段 | 类型 | 必填 | 说明 |
|----|----|----|----|----|
| 修改 | taskStatus | 说明变更 | 任务状态 20已出库(空=全部;10/15为旧流程遗留) → 任务状态 10待出库 20已出库(空=全部) |

#### 返回字段变化

| 变化 | 字段 | 类型 |  | 说明 |
|----|----|----|----|----|
| 新增 | scannedPackageNum | Integer | — | 已扫码出库包裹数(包裹暂存,展示扫码进度;拆箱重打任务恒0,前端按 boxRepackFlag 隐藏) |
| 修改 | taskStatus | 说明变更 | 任务状态 20已出库 30已撤销(10/15为旧流程遗留) → 任务状态,见枚举 |

### POST /cold/mini/bare/register · 裸花暂存登记

**变更 5 处** · 小程序端

#### 入参变化

| 变化 | 字段 | 类型 | 必填 | 说明 |
|----|----|----|----|----|
| 删除 | purchaserId | Long | 选填 | 客户id,由二维码识别,可不传 |
| 删除 | locationNo | String | 选填 | 暂存货位号,由二维码识别,可不传 |
| 删除 | storeRoundNo | String | 选填 | 暂存场次 yyyy-MM-dd,由二维码识别,可不传 |
| 删除 | bunchNum | Integer | 选填 | 裸花扎数,由二维码关联订单汇总,可不传 |
| 修改 | userName | 说明变更 | 操作人姓名 → 后端根据登录人解析,前端不传 |
| 修改 | userName | 注入变更 | - → inject |

## 枚举字典变化（全局）（删 3 组 · 改 4 组）

| 变化 | 枚举 | 旧版 | 新版 |
|----|----|----|----|
| 删除 | shipWay 发货方式 | 1 指定日期 · 2 客户通知 | （整组删除） |
| 删除 | demandStatus 需求状态 | 10 待仓库登记 · 20 已登记 · 30 已作废 | （整组删除） |
| 删除 | financeStatus 合并发货账务状态 | 0 待处理 · 10 已处理 | （整组删除） |
| 修改 | stockStatus 库存状态 | 0 待入库 · 10 待发货 · 20 待关联 · 50 已出库(30 已关联/40 待出库为旧流程遗留,新逻辑不再写入) | 10 待发货 · 40 待出库 · 50 已出库 |
| 修改 | shipConfirm 发货确认/联系结果 | 1 今日出库 · 2 继续暂存 · 3 联系不上 · 4 取消暂存 | 1 今日出库 · 2 继续暂存 · 3 联系不上 |
| 修改 | taskStatus 出库任务状态 | 20 已出库 · 30 已撤销(运营端操作即终态;10 待出库/15 出库中为旧流程遗留) | 10 待出库(可撤销) · 20 已出库(不可撤销) · 30 已撤销 |
| 修改 | sendStatus 发货单状态 | 0 待发货 · 1 配送中 · 2 已完成 · 3 已取消 · 4 合并新场次发货 | 0 待发货 · 1 配送中 · 2 已完成 · 3 已取消 |