配置代理仓系统

更新时间：2026-06-04

1. 操作场景

代理仓模块用于维护 GWMS 与外部代理仓系统之间的对接关系。仓库完成系统配置后，才能继续处理代理仓入库推送、出库推送、状态回写、库存同步和异常排查。

本文适用于仓库实施、系统管理员和负责第三方仓配对接的运营人员。常见使用场景包括：

• 新接入一个代理仓系统；
• 为代理仓系统补齐仓库映射、渠道映射或 查看 SKU 配对；
• 手工触发某个仓库映射的库存同步；
• 检查某个 SKU 是否已经出现在配对列表里。

1.1 代理仓整体运转方式

运营日常操作流程说明

整个代理仓使用分为三大步骤：

第一步：配置代理仓系统（仅首次需要）

在 GWMS-代理仓-代理仓系统 页面完成：

• 新增代理仓系统，填写接入信息
• 配对仓库映射（重点：必须配置虚拟上架库位和残品库位）
• 配对渠道映射
• 配置完成后，日常业务就能自动推送到代理仓了
• SKU 在第一次创建代理仓入库单会自动推送

第二步：日常业务操作（自动进行）

运营人员在 GWMS 中正常操作，系统会自动处理代理仓交互：

入库业务：

1. GWMS 推送入库单到代理仓
2. 系统自动创建"创建任务"
3. 任务进入队列，系统自动轮询代理仓处理结果
4. 代理仓处理完成后，GWMS 自动完成收货和上架
5. 如果失败，任务会进入"人工处理"状态
6. 如果需要取消入库，会创建新的"取消任务"

出库业务：

1. GWMS 推送出库单到代理仓
2. 系统自动创建"创建任务"
3. 任务进入队列，系统自动轮询代理仓处理结果
4. 代理仓完成后，GWMS 自动更新出库状态
5. 如果失败，任务会进入"人工处理"状态
6. 如果需要取消出库，会创建新的"取消任务"

库存同步（与入库/出库不同，一次性完成）：

1. 手工触发或系统定时（每 12 小时）启动库存同步
2. 关键：先执行同仓未完成的入库/出库任务，确保业务动作先处理完
3. GWMS 查询代理仓库存快照
4. 系统自动创建"库存同步任务"
5. 对比 GWMS 本地库存，找出差异
6. 立即自动修正库存差异：
   • 远端有、本地有：直接改数量
   • 远端有、本地无：补一条库存记录
   • 远端无、本地有：归零（需检查锁定库存）
7. 保存库存快照到任务记录
8. 任务直接标记为"成功"或"人工处理"（不需要等待轮询）

第三步：查看结果和处理异常

运营主要关注两个页面：

• 同步任务页面（GWMS-代理仓-同步任务）

  • 查看任务状态：等待中、成功、人工处理
  • 查看执行结果和错误信息
  • 对失败任务点击【立即同步】重试

• 日志页面（GWMS-代理仓-日志）

  • 查看 GWMS 发送给代理仓的请求内容
  • 查看代理仓返回的响应内容
  • 定位具体失败原因

常见处理场景：

• 任务显示"等待中"：代理仓还在处理，继续等待或点【立即同步】
• 任务显示"人工处理"：查看错误信息，修正配置后重试
• 任务显示"成功"：无需操作，业务正常完成
• 配置有问题：回到【代理仓系统】页面修正仓库映射或渠道映射

入库/出库 vs 库存同步的区别：

对比项	入库/出库任务	库存同步任务
任务类型	创建任务 / 取消任务	库存同步任务
执行方式	推送给代理仓 → 等待代理仓处理	查询代理仓库存 → 直接修正本地
是否需要轮询	✅ 需要反复查询代理仓状态	❌ 查询一次立即完成
执行时长	取决于代理仓处理速度（几分钟到几小时）	几秒钟内完成
任务状态变化	等待中 → 成功/人工处理	直接成功/人工处理
典型场景	把业务单据推送到代理仓执行	把代理仓库存同步到 GWMS

关键理解点：

1. ✅ 每个业务动作都会产生一条同步任务记录
2. ✅ 推送后不是立即完成，入库/出库需要等待代理仓处理
3. ✅ 系统会自动轮询代理仓，不需要人工反复查询
4. ✅ 库存同步是一次性完成的，不需要轮询等待
5. ✅ 库存同步前会先把未完成的业务任务处理完
6. ✅ 大部分情况下任务会自动完成，只有异常时才需要人工介入
7. ✅ 【同步任务】页面是运营的核心操作页面
8. ✅ 【日志】页面用于排查问题时查看详细报文

2. 操作指引

前提条件

请提前确认以下条件：

1. 当前账号可以进入 GWMS-代理仓-代理仓系统。
2. 已经拿到代理仓提供的系统接入信息，例如系统类型、地址、账号或密码。
3. 如需配对仓库，请先在 GWMS 内完成仓库、库区（存储区和残品区）、库区对应库位基础资料维护。
4. 如需配对渠道，请先在 GWMS 内完成物流渠道资料维护。
5. 如需查看 SKU 配对状态，请先保证对应 GSKU 已在 GWMS 中存在，并且已经发生过代理仓入库。

2.1 新增代理仓系统

菜单路径：GWMS-代理仓-代理仓系统

1. 进入代理仓系统页面。
2. 页面上方可以按【系统名称】【系统代码】【配置 json】搜索。
3. 点击【新增】。
4. 在弹窗中填写【系统名称】和【系统类型】：
   • 【系统名称】：当前这套代理仓系统的识别名称，用于后续运营区分
   • 【系统类型】：当前可选 hipackingWMS 等
5. 根据选择的系统类型，页面会展示不同的配置方式，自行配置。
6. 点击【确定】后，系统提示【新增成功】。

2.2 维护仓库配对并触发库存同步

1. 在目标系统所在行点击【仓库】。
2. 系统打开”已配对仓库信息”弹窗。
3. 弹窗表格展示列：
   • 【代理仓代码】
   • 【GWMS 仓库代码】
   • 【虚拟上架库位】
   • 【残品库位】
   • 【操作】：包含【绑定 gwms 仓库】【同步库存】【删除】三个图标按钮
4. 点击右上角【添加仓库】。
5. 在新增仓库映射弹窗中填写以下内容：
   • 【代理仓代码】：必填，输入代理仓系统中的仓库编码
   • 【GWMS 仓库代码】：必填，从 GWMS 仓库列表选择
   • 【虚拟上架库位】：必填，从已选 GWMS 仓库的库位列表选择
   • 【残品库位】：必填，从已选 GWMS 仓库的残品库区库位列表选择
6. 点击【确定】。系统提示【新增仓库映射成功】。

执行库存同步

1. 点击【同步库存】。
2. 系统弹出确认框【确认立即触发该仓库映射的库存同步任务？】。
3. 确认后，系统提示【已触发库存同步】。
4. 后续执行结果请到《同步任务》查看，任务类型为"库存同步任务"。

2.3 配对代理仓渠道

1. 在目标系统所在行点击【渠道】。
2. 系统打开”已配对渠道信息”弹窗。
3. 点击右上角【添加渠道】。
4. 系统从代理仓获取可选渠道列表。
5. 列表展示以下字段：
   • 【代理仓渠道代码】
   • 【代理仓渠道名称】
   • 【承运商】
   • 【服务类型】
   • 【可用仓库】
   • 【是否自提】
6. 勾选要接入的渠道。
7. 点击【确定】。系统提示【新增渠道成功】。

绑定 GWMS 渠道

如果需要把代理仓渠道和 GWMS 物流渠道对应起来：

1. 在已配对渠道列表中点击编辑按钮。
2. 在弹窗中选择【GWMS 渠道代码】。
3. 点击【确定】。系统提示【绑定 GWMS 渠道成功】。

删除渠道映射

删除不再使用的渠道映射时：

1. 点击删除按钮。
2. 确认删除操作。
3. 系统提示【删除成功】。

2.4 查看 SKU 配对状态

1. 在目标系统所在行点击【sku】。
2. 系统打开 SKU 信息弹窗。
3. 页面表格展示以下信息：
   • 【sku 代码】
   • 【同步状态】
   • 【异常信息】
   • 【操作】：包含重新同步、标记等操作
4. 页面支持按【sku 代码】【同步状态】【异常信息】筛选。
5. 如需刷新当前结果，可点击【拉取】按钮查看最新状态。

SKU 配对的理解方式

需要注意的是：

• SKU 不是先在这个页面里手工首次推送
• 系统会在第一次代理仓入库推送时，自动推送这次入库涉及到的 SKU
• 只有某个 GSKU 已经通过入库推送过，它才会出现在这个 SKU 配对列表里
• SKU 推送成功后，代理仓系统会记录这条 SKU 的同步状态

3. 补充说明

3.1 系统、仓库、渠道、SKU 的关系

代理仓配置是分层维护的：

• 代理仓系统：定义这次对接接入的是哪个外部系统；
• 仓库配对：定义这个系统下的代理仓代码对应哪个 GWMS 仓库；
• 渠道配对：定义代理仓渠道代码对应哪个 GWMS 渠道；
• SKU 配对：用于查看某个 GSKU 是否已经通过代理仓入库推送过，并查看当前同步状态。

只有系统记录存在，后续三类配对入口才可用。

3.2 为什么库存同步入口放在仓库配对里

库存同步是按“仓库映射”执行的，不是按系统整体执行的。也就是说：

• 同一个代理仓系统下可以有多条仓库映射；
• 每条仓库映射的库存同步任务独立生成；
• 任务执行时会根据这条映射上的 GWMS 仓库、代理仓代码、虚拟上架库位和残品库位做库存校正。

如果某条映射缺少虚拟上架库位或残品库位，系统不会允许直接触发库存同步。

3.3 SKU 配对状态怎么理解

SKU 页面里的记录，不是所有 GSKU 的完整清单。
只有已经通过代理仓入库推送过的 SKU，才会显示在这个列表里。

页面里的【同步状态】用于表示这条 SKU 记录当前是否同步正常。

• 【已同步】：说明系统认为该 SKU 已完成同步。
• 【未同步】：说明该 SKU 还没有同步成功，或同步后又被手工改回未同步状态。

如果页面中出现异常信息，请优先排查：

1. GSKU 基础资料是否完整；
2. 是否已经发生过这条 SKU 的代理仓入库；
3. 代理仓系统配置是否正确；
4. 对应请求是否已经进入《日志》或《同步任务》。

4. 常见问题

Q1：为什么【同步库存】按钮是灰色的？

A1：这条仓库映射通常还没有补齐【GWMS 仓库代码】【代理仓代码】【虚拟上架库位】【残品库位】。请先进入仓库配对弹窗补齐这 4 项配置。

Q2：新增仓库映射时为什么选不到库位？

A2：库位列表会跟随已选择的 GWMS 仓库变化。如果还没有先选择【GWMS 仓库代码】，或该仓库下没有对应库位，库位下拉会为空。

Q3：为什么渠道已经添加了，但还需要再绑定 GWMS 渠道？

A3：把代理仓渠道拉到 GWMS 只是建立“可选渠道”记录。只有继续绑定【GWMS 渠道代码】，出库业务才能把 GWMS 内的渠道选择映射到代理仓渠道。

Q4：SKU 已经存在，为什么还是显示【未同步】？

A4：SKU 存在只说明 GWMS 内有这条产品资料，不代表它已经推送到代理仓。当前只有在第一次代理仓入库时，系统才会自动推送对应 SKU；只要还没有发生过代理仓入库，这条 SKU 就可能还不会出现在配对列表里。

Q5：库存同步触发成功后，在哪里看结果？

A5：库存同步只负责发起任务，不会直接在仓库映射弹窗展示执行明细。请进入 GWMS-代理仓-同步任务，按任务类型"库存同步任务"或仓库筛选后查看执行结果。

Q6：当前对接的是 HPK，这页看完后还要看哪一页？

A6：建议继续看《HPK 使用说明》。那一页会把 HPK 的完整测试顺序、库存理解方式和常见问题集中说明。