版本差异冷库暂存花材

冷库暂存花材接口

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

更新: 2026-07-15
接口数: 21

Markdown 原文（给 AI 用）：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.md

	旧版 · 首次部署	新版 · 当前线上
接口数	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 已取消

运营端（删 4 · 改 9）

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

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

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

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

POST/cold/demand/register仓库登记

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

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

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

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

接口级变化

返回字段变化

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

接口级变化

入参变化

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

入参变化

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

接口级变化

入参变化

返回字段变化

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

接口级变化

POST/cold/out/direct直接出库

接口级变化

入参变化

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

接口级变化

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

入参变化

返回字段变化

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

接口级变化

返回字段变化

PDA端（增 1 · 改 2）

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

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

POST/cold/pda/scan扫码入库

入参变化

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

返回字段变化

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

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

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

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

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

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

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

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

接口级变化

入参变化

返回字段变化

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

入参变化

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

POST`/cold/demand/save`暂存需求提报

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

POST`/cold/demand/register`仓库登记

POST`/cold/stock/confirm`次日出库确认

POST`/cold/stock/page`冷库暂存库存列表

POST`/cold/stock/stat`冷库暂存库存统计

POST`/cold/contact/save`新增联系记录

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

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

POST`/cold/out/direct`直接出库

POST`/cold/out/cancel`撤销出库任务

POST`/cold/out/records`历史出库记录

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

POST`/cold/pda/out/scan`扫码出库

POST`/cold/pda/scan`扫码入库

POST`/cold/pda/stock/detail`库存详情

POST`/cold/mini/customer/search`客户搜索

POST`/cold/mini/out/finish`点击出库

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

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

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