冷库暂存花材 · 接口文档新旧版本差异
旧版 · 首次部署
26 个接口（页面误标 28）依据提交 dc00890ece · https://47ec718e.xm-cold-doc.pages.dev→
新版 · 当前线上
24 个接口依据提交 b5f20cfd24 · https://xm-cold-doc.pages.dev
5删除接口
3新增接口
13接口有字段/描述变化
7枚举变化（删 3 组 · 改 4 组）
两版之间经历了一次方案重构：取消暂存需求提报和次日出库确认（改为线下沟通 + 联系记录留痕）、出库由“运营端操作即完成”改为两段式（客服建待出库任务 → 仓库 PDA 逐包扫码 / 小程序整单确认，期间可撤销）、冷库状态收敛到冷库明细表（包裹表仅新增 40 拆箱重打，不再有 15/30 中间态）、裸花登记改为全二维码识别。
一、运营端 删 4 · 改 9
− 删除
/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 | 选填 | 客服备注 |
− 删除
/cold/demand/page暂存需求提报列表运营端
同上，需求提报功能整体取消。
入参明细（2 个字段） · 返回 R<PageVO<ColdDemandDto>>
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| demandStatus | Integer | 选填 | 需求状态 10待仓库登记 20已登记 30已作废 |
| storeType | Integer | 选填 | 暂存类型 1包裹 2裸花 |
− 删除
/cold/demand/register仓库登记运营端
同上，需求登记转库存的环节随需求提报一起取消，入库统一走扫码。
入参明细（4 个字段） · 返回 R<Long>
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| demandId | Long | 必填 | 暂存需求id |
| locationNo | String | 选填 | 实际暂存货位号(空则沿用建议货位) |
| bunchNum | Integer | 选填 | 裸花实际扎数(裸花暂存必填) |
| remark | String | 选填 | 备注(空则沿用客服备注) |
− 删除
/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(逗号分隔) |
~ 变更 13 处
/cold/stock/page冷库暂存库存列表运营端
接口级变化
| 属性 | 旧版 | 新版 |
|---|---|---|
| 描述 | 客服查看仓库登记后的库存。分页。 | 客服查看仓库扫码入库后的库存。分页。 |
返回字段变化
| 字段 | 类型 | 说明 | |
|---|---|---|---|
| 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 | 说明变更 | 出库任务状态→出库任务状态(最新非撤销任务),见枚举 | |
~ 变更 6 处
/cold/stock/stat冷库暂存库存统计运营端
接口级变化
| 属性 | 旧版 | 新版 |
|---|---|---|
| 描述 | 顶部统计卡片。入参同 /cold/stock/page(同筛选条件统计)。 | 顶部统计卡片。全局口径,不随列表筛选条件联动(在库客户数/在库包裹数为当前全量,今日出库客户数与小程序首页同口径)。 |
入参变化 新增 删除 修改
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| keyword | String | 选填 | 同库存列表 |
| storeType | Integer | 选填 | 同库存列表 |
| stockStatus | Integer | 选填 | 同库存列表 |
| storeRoundNo | String | 选填 | 同库存列表 |
| planShipDate | String | 选填 | 同库存列表 |
~ 变更 1 处
/cold/contact/save新增联系记录运营端
入参变化 新增 删除 修改
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| shipConfirm | 说明变更 | 联系结果 1今日出库 2继续暂存 3联系不上 4取消暂存→联系结果 1今日出库 2继续暂存 3联系不上 | |
~ 变更 7 处
/cold/out/today-send-order查询当天发货单运营端
接口级变化
| 属性 | 旧版 | 新版 |
|---|---|---|
| 描述 | 按客户账号 + 当前场次查询。入参仅 coldStockId。 | 默认按冷库库存客户 + 当前场次查询发货单；可按客户注册手机号搜索其他客户的当天发货单。 |
| 返回类型 | R<ColdSendOrderDto> | R<List<ColdSendOrderDto>> |
入参变化 新增 删除 修改
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| mobile | String | 选填 | 客户注册手机号，不传时查暂存客户自己的发货单 |
返回字段变化
| 字段 | 类型 | 说明 | |
|---|---|---|---|
| shelfSn | Integer | — | 主货位号 |
| subShelfSn | String | — | 子货位号 |
| zoneShelf | String | — | 区-货位号 |
| purchaserMobile | 说明变更 | 客户手机号→客户注册手机号 | |
~ 变更 1 处
/cold/out/link关联当天发货单出库运营端
接口级变化
| 属性 | 旧版 | 新版 |
|---|---|---|
| 描述 | 含拆箱重打。操作即完成冷库出库:任务直接落「已出库(20)」,冷库明细置已出库;非拆箱重打时包裹 express_status 30→10(打包完成)并回填当天发货单信息,随当天发货单走正常物流出库扫码,重量/运费/面单由正常发货流程采集。整批出库后库存「已出库(50)」;部分出库剩余回「待发货(10)」并清空发货确认。 | 含拆箱重打。常规出库生成待出库任务并锁定所选包裹，实际出库由 PDA 逐包扫码或小程序点击出库完成。拆箱重打时操作即完成出库，不可撤销。 |
~ 变更 3 处
/cold/out/direct直接出库运营端
接口级变化
| 属性 | 旧版 | 新版 |
|---|---|---|
| 描述 | 不关联当天发货单。操作即终态:任务直接落「已出库(20)」,包裹 express_status 30→20(发货完成),实际重量/运费置0走线下对账。整批出库后库存「已出库(50)」;部分出库剩余回「待发货(10)」并清空发货确认。 | 不关联当天发货单。生成待出库任务并锁定所选包裹，实际出库由 PDA 逐包扫码或小程序点击出库完成。发货物流由服务端根据原发货单解析，前端不传。 |
入参变化 新增 删除 修改
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| expressId | Long | 必填 | 发货物流id(必须为启用中的物流) |
| expressName | String | 选填 | 发货物流名称,由服务端按物流id回填,前端可不传 |
~ 变更 1 处
/cold/out/cancel撤销出库任务运营端
接口级变化
| 属性 | 旧版 | 新版 |
|---|---|---|
| 描述 | 当天反出库:仅可撤销当天完成的出库任务;拆箱重打不可撤;关联出库的包裹一旦被正常物流扫码发货(express_status=20)不可撤。撤销后包裹退回冷库暂存(30)并还原原场次,冷库明细回暂存中,库存回「待发货(10)」并回滚出库计数。历史遗留的「待出库」任务仍支持旧撤销逻辑。 | 仅可撤销待出库(10)且尚无包裹完成出库的任务。撤销后任务置已撤销(30)，释放锁定包裹；无其他待出库任务时，库存回退为待发货(10)。 |
~ 变更 10 处
/cold/out/records历史出库记录运营端
入参变化 新增 删除 修改
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 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为旧流程遗留)→任务状态,见枚举 | |
~ 变更 2 处
/cold/stock/pending-packages未入库包裹清单运营端
接口级变化
| 属性 | 旧版 | 新版 |
|---|---|---|
| 描述 | 发货单下已打包(状态10)但尚未扫入冷库的包裹清单,供客服核对预计/已入/未入件数并催办物流入库。sendNo 与 coldStockId 二选一(传 coldStockId 时取其原发货单号)。 | 发货单下已打包(状态10)但尚未扫入冷库的包裹清单,供客服核对已入/未入件数并催办物流入库。sendNo 与 coldStockId 二选一(传 coldStockId 时取其原发货单号)。 |
返回字段变化
| 字段 | 类型 | 说明 | |
|---|---|---|---|
| expectPackageNum | Integer | — | 客服提报预计暂存件数(无提报单为空) |
二、PDA端 增 1 · 改 2
+ 新增
/cold/pda/out/scan扫码出库PDA端
出库改为「两段式」：运营端只生成待出库任务，仓库 PDA 逐包扫码执行实际出库（最后一包扫完任务自动完成）。
入参明细（4 个字段） · 返回 Response<ColdScanOutResultVo>
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| outTaskId | Long | 必填 | 出库任务id |
| codeContent | String | 必填 | 包裹码(包裹id) |
| userId | Long | 注入 | 后端注入,前端不传 |
| userName | String | 注入 | 后端根据登录人解析,前端不传 |
~ 变更 1 处
/cold/pda/scan扫码入库PDA端
入参变化 新增 删除 修改
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| userName | 说明变更 | 操作人姓名→后端根据登录人解析,前端不传 | |
| userName | 注入变更 | -→inject | |
~ 变更 3 处
/cold/pda/stock/detail库存详情PDA端
返回字段变化
| 字段 | 类型 | 说明 | |
|---|---|---|---|
| purchaserId | Long | — | 客户id |
| remark | String | — | 客户备注 |
| scanPackageCode | String | — | 本次扫码的包裹码 |
三、小程序端 删 1 · 增 2 · 改 2
− 删除
/cold/mini/customer/search客户搜索小程序端
早期「手动选客户登记裸花」交互的残留：最终方案裸花登记全部由花材二维码识别客户，无手动搜索场景，且该接口可模糊枚举客户手机号，属无消费方的风险面。
入参明细（1 个字段） · 返回 Response<List<ColdCustomerVo>>
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| keyword | String | 必填 | 关键词(手机号或昵称) |
+ 新增
/cold/mini/out/finish点击出库小程序端
两段式出库的小程序执行入口：裸花任务整单完成，包裹任务批量完成剩余待出库包裹。
入参明细（3 个字段） · 返回 Response<String>
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| outTaskId | Long | 必填 | 出库任务id |
| userId | Long | 注入 | 后端注入,前端不传 |
| userName | String | 注入 | 后端根据登录人解析,前端不传 |
+ 新增
/cold/mini/package/scan包裹扫码入库小程序端
仓管小程序也支持包裹扫码入库（质检员/区域负责人/仓库管理员，不受物流商配置限制），与 PDA 扫码入库互补。
入参明细（5 个字段） · 返回 Response<ColdScanResultVo>
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| codeContent | String | 必填 | 扫码内容(包裹id) |
| coldStockId | Long | 选填 | 累计入库的冷库库存id(连续扫同一客户时传) |
| locationNo | String | 选填 | 暂存货位号(新建库存时使用) |
| userName | String | 注入 | 后端根据登录人解析,前端不传 |
| userId | Long | 注入 | 后端注入,前端不传 |
~ 变更 4 处
/cold/mini/out/page暂存出库列表小程序端
接口级变化
| 属性 | 旧版 | 新版 |
|---|---|---|
| 描述 | 今日出库任务查询视图(运营端操作即完成,列表以已出库为主)。分页。 | 待出库/已出库任务列表(默认不含已撤销)，含包裹扫码进度。分页。 |
入参变化 新增 删除 修改
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| taskStatus | 说明变更 | 任务状态 20已出库(空=全部;10/15为旧流程遗留)→任务状态 10待出库 20已出库(空=全部) | |
返回字段变化
| 字段 | 类型 | 说明 | |
|---|---|---|---|
| scannedPackageNum | Integer | — | 已扫码出库包裹数(包裹暂存,展示扫码进度;拆箱重打任务恒0,前端按 boxRepackFlag 隐藏) |
| taskStatus | 说明变更 | 任务状态 20已出库 30已撤销(10/15为旧流程遗留)→任务状态,见枚举 | |
~ 变更 5 处
/cold/mini/bare/register裸花暂存登记小程序端
入参变化 新增 删除 修改
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| 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 已取消 |