HPK 代理仓使用说明
更新时间：2026-07-31
1. 先看这页解决什么问题
这篇文档只讲 HPK 这个代理仓系统的特殊规则，不重复介绍通用的代理仓配置和任务页操作。
如果你要处理的是下面这些问题，优先看这篇：
- HPK 当前支持哪些代理仓能力；
- HPK 库存数量应该怎么理解；
- HPK 场景下哪些出库链路会走代理仓，哪些不会；
- HPK 任务长时间等待、取消失败或库存不同步时，应该先查哪里。
如果你还没完成系统、仓库、渠道配置，请先看《代理仓系统》。 如果你已经有任务异常，需要看状态和重试，请看《同步任务》。
2. 配置要点
2.1 新增 HPK 系统
菜单路径：GWMS-代理仓-代理仓系统
- 点击【新增】
- 填写【系统名称】
- 【系统类型】选择 HPK（Hipacking）
- 填写 HPK 提供的接入配置：
- 接口地址
- 登录账号
- 登录密码
- 版本号（填写 5）
- 点击【确定】
测试环境地址： http://test.hipacking.cn
2.2 配置仓库映射（重要）
菜单路径：GWMS-代理仓-代理仓系统-仓库
必须配置 4 项：
- 代理仓代码
- GWMS 仓库代码
- 虚拟上架库位（存放 HPK 合格品）
- 残品库位（存放 HPK 残品）
❗ 如果缺少专用库位配置：
- 入库只能收货，无法上架
- 无法触发库存同步
2.3 HPK 库存数量说明
HPK 返回的库存包含两部分：
- 可用库存：可以分配出库的数量
- 锁定库存：已分配但未出库的数量
重要：总库存 = 可用库存 + 锁定库存
❌ 错误理解：只看可用库存 ✅ 正确理解：可用 + 锁定 = 总库存
举例：
- HPK 显示：可用 80，锁定 20
- 实际总库存：100（不是 80）
3. 当前链路范围
3.1 入库业务
- GWMS 创建入库单
- 系统自动推送到 HPK
- 到《同步任务》查看任务状态
- HPK 处理完成后，GWMS 自动收货和上架
注意：
- 推送后需要等待 HPK 处理完成
- 等待中不只表示 HPK 正在处理，也可能表示任务已进入下一次自动查询等待
- 只有缺少专用库位时，才会无法上架
3.2 序列号相关链路
当前 HPK 已支持序列号相关链路，但它不是单独的新任务类型，而是挂在入库或出库主链路下面执行。
当前支持范围：
- 入库单创建成功后，系统会把这张单据当前已经绑定的本地序列号自动补推到 HPK。
- 如果本地后来又新增、变更或删除了入库序列号，系统会在事务提交后异步把变化同步到 HPK。
- 当 HPK 返回入库终态结果时，系统会从返回报文里解析序列号并回写到 GWMS 本地入库序列号记录。
- 当 HPK 返回出库完成结果时，系统会从返回报文里解析序列号并回写到 GWMS 本地出库序列号记录。
- 同步时会按 SKU 映射找到 HPK 对应商品，再执行序列号录入、查询、更新或本地回写。
重要边界：
- “推给 HPK”和“从 HPK 拉回 GWMS”是两条不同方向的链路，排查时不要混在一起看。
- 当前代码里，入库序列号回写失败不会直接把入库主流程判失败，系统会保留主流程结果并等待后续轮询补录。
- 当前代码里，出库序列号回写失败也不会直接把出库主流程判失败，系统会先保留出库主流程结果。
排查方式：
- 先确认这张单据本身是否已经走到 HPK 代理仓链路。
- 如果排查的是“本地往 HPK 推”，到《日志》看序列号录入、查询、更新请求和响应。
- 如果排查的是“HPK 往 GWMS 回写”，到《日志》看入库或出库状态查询回包里有没有带序列号。
- 如果日志里已经显示成功，但业务仍有异常，再回到《同步任务》结合入库或出库任务状态判断是否还有主链路问题。
HPK 序列号边界速查表：
| 你想确认的问题 | 真实链路 | 先看哪里 | 当前代码边界 |
|---|---|---|---|
| 本地入库序列号有没有推到 HPK | GWMS -> HPK | 日志 | 只看到入库序列号推送，没有独立任务页 |
| HPK 入库结果有没有把序列号带回 GWMS | HPK -> GWMS 入库回写 | 先日志，再同步任务 | 回写失败不直接打断入库主流程 |
| HPK 出库结果有没有把序列号带回 GWMS | HPK -> GWMS 出库回写 | 先日志，再同步任务 | 回写失败不直接打断出库主流程 |
3.3 出库业务
当前代码里，HPK 出库要先区分业务类型：
- 一件代发：当前代理仓主链路支持推送、状态查询和取消确认。
- 备货中转：当前不走这套代理仓推送链路，取消时也不会向 HPK 发起取消请求。
如果你看到的是一件代发出库：
- GWMS 创建出库单。
- 系统自动推送到 HPK。
- 系统创建任务并按自动节奏查询 HPK 处理状态。
- HPK 已完成后，GWMS 再推进本地出库状态。
- 如果 HPK 这次出库结果回包里带了序列号，系统会同时尝试把序列号回写到 GWMS 本地出库序列号记录。
如果你看到的是备货中转出库：
- 不要默认它会通过当前代理仓任务页完成 HPK 推送；
- 取消时也不要默认会向 HPK 发取消请求；
- 这类单据需要先确认当前业务场景是否已经接入代理仓链路。
补充理解：
- 出库序列号目前主要不是“GWMS 主动往 HPK 推”，而是“HPK 在出库结果里带回后，GWMS 再落本地”。
- 如果出库序列号回写失败，当前代码不会直接把本次出库主流程改判为失败，还是要结合任务状态和日志一起看。
3.4 库存同步
触发方式：
- 在仓库映射页面点击【同步库存】
- 系统每 12 小时自动执行一次
执行内容：
- 先尽量处理同仓待处理业务任务
- 从 HPK 拉取库存快照
- 自动修正本地库存差异
- 保存库存快照
查看结果： 到《同步任务》查看库存同步任务详情。
注意：
- 只修正虚拟上架库位和残品库位
- 库存同步任务本身不靠轮询推进，但执行前的业务预处理有数量和时长预算，不是必须等所有业务任务都跑完才开始
4. 常见问题
4.1 "未配置虚拟上架库位"
**原因：**仓库映射配置不完整
处理：
- 到《代理仓系统》查看仓库映射
- 检查是否配置了虚拟上架库位和残品库位
- 补齐缺失配置
4.2 "客户未开户，无法收货"
**原因：**本地客户资料不满足收货条件
处理：
- 到《同步任务》查看错误详情
- 确认客户的开户状态
- 检查客户是否绑定了对应仓库
- 修正后点击【立即同步】
4.3 "系统配置异常"
**原因：**系统类型或配置错误
处理：
- 确认【系统类型】是否选择了 HPK
- 确认仓库映射是否已建立
- 确认接口地址、账号、密码是否正确
- 到《日志》查看错误详情
4.4 "SKU 同步失败"
**原因：**GSKU 基础资料不完整
处理：
- 到代理仓系统的【sku】页面查看异常
- 检查 GSKU 的必填信息（名称、规格、重量等）
- 补齐后点击【重新同步】
4.5 序列号没有同步到 HPK
常见原因：
- 当前仓库路由没有开通入库序列号同步能力；
- 这张入库单还没有成功创建到 HPK；
- SKU 映射缺失，系统无法找到 HPK 对应商品；
- 本地当前序列号状态已经变化，导致本次事件被系统判定为过期变化并跳过；
- HPK 接口返回失败或异常。
处理：
- 先确认该仓库和系统当前确实走 HPK 代理仓链路。
- 确认入库单是否已经成功推送并拿到了 HPK 单号。
- 到《日志》检查序列号录入、查询、更新请求和响应。
- 检查 SKU 配对是否完整，必要时补齐映射后重新触发相关业务操作。
4.6 HPK 序列号没有回写到 GWMS
常见原因：
- HPK 的入库或出库状态回包里没有带序列号；
- 回包里带了序列号，但 SKU 映射后没有匹配到 GWMS 商品；
- 本地主流程已经完成，但这次序列号回写解析或落库失败；
- 当前这次回包还没轮询到，后续补查才会带回序列号。
处理：
- 到《日志》确认 HPK 入库或出库状态回包里是否真的带了序列号。
- 确认回包里的 SKU 和 GWMS 商品映射是否一致。
- 再看《同步任务》确认主流程是否已经完成，以及后续是否还有轮询机会。
- 如果主流程已完成但序列号仍缺失，优先按日志和映射关系继续排查，不要只盯着任务状态颜色。
4.7 任务一直在等待中
常见原因：
- HPK 仍未处理到终态；
- 任务已经进入下一次自动查询等待；
- 当前摘要里已经有错误，但还没被人工处理；
- 映射、系统配置或资料问题还没修正。
处理：
- 先看《同步任务》里的【执行摘要】和【下次执行时间】。
- 如果摘要明确提示配置或资料问题，先修正问题，不要只反复点【立即同步】。
- 如果没有明显错误，再到《日志》确认 HPK 的返回内容。
- 必要时联系 HPK 确认单据在对方系统中的实际处理状态。
4.8 取消失败后，本地会怎样
HPK 场景下，不要把“本地点击取消成功”和“HPK 端也一定取消成功”当成一件事。
- 对当前走代理仓取消链路的业务，如果 HPK 取消未通过，本次取消不会按成功结束，需要先排查原因后再重新取消。
- 对当前不走代理仓取消链路的业务，例如现阶段的备货中转，不要默认 HPK 会收到取消请求。