配置代理仓系统
更新时间：2026-07-31
1. 操作场景
代理仓模块用于维护 GWMS 与外部代理仓系统之间的对接关系。系统配置完成后，GWMS 才能把入库、出库和库存同步这几类动作交给代理仓处理，并把结果回写到本地任务页和日志页。
本文适用于仓库实施、系统管理员和负责第三方仓配对接的运营人员。常见使用场景包括：
- 新接入一个代理仓系统；
- 为代理仓系统补齐仓库映射、渠道映射或查看 SKU 配对；
- 手工触发某个仓库映射的库存同步；
- 排查为什么某张单据没有继续同步、为什么库存没有对齐。
1.1 代理仓整体运转方式
运营日常操作流程说明
整个代理仓使用可以按 3 个阶段理解：
第一步：配置代理仓系统（仅首次需要）
在 GWMS-代理仓-代理仓系统 页面完成：
- 新增代理仓系统，填写接入信息
- 配对仓库映射（重点：必须配置虚拟上架库位和残品库位）
- 配对渠道映射
- 配置完成后，日常业务就能自动推送到代理仓了
- SKU 在第一次创建代理仓入库单会自动推送
第二步：业务触发代理仓动作
运营人员仍然在 GWMS 正常做入库、出库和库存同步。 系统会在后台自动生成任务并继续跟踪，不需要人工重复查询。
入库业务：
- GWMS 推送入库单到代理仓。
- 系统生成任务记录。
- 系统按自动节奏继续查询代理仓处理结果。
- 代理仓返回可完成状态后，GWMS 自动执行收货、上架或取消回写。
- 如果代理仓结果无法识别、本地动作条件不满足，任务会进入人工处理。
入库序列号：
- 如果当前代理仓路由支持入库序列号同步，入库单创建成功后，系统会把这张入库单当前已经绑定的本地序列号自动补推到代理仓。
- 后续如果本地又发生序列号新增、变更或删除，系统会在本地事务提交后异步同步到代理仓。
- 当代理仓返回入库终态结果时，系统也会从代理仓回包中解析序列号并回写到 GWMS 本地入库序列号记录。
- 这部分不是单独的新任务类型，排查时应优先看日志，再结合入库任务状态判断主链路是否已经完成。
出库业务：
- GWMS 推送出库单到代理仓。
- 系统生成任务记录。
- 系统按自动节奏继续查询代理仓处理结果。
- 代理仓返回可完成状态后，GWMS 自动推进本地出库状态。
- 如果这次代理仓出库结果回包里带了序列号，系统会在推进本地出库状态时尝试把序列号回写到 GWMS 本地出库序列号记录。
- 如果代理仓已取消但本地当前不能自动取消，或本地正式出库条件不满足，任务会进入人工处理或等待重试。
出库序列号：
- 当前代码里，出库序列号主要体现在“代理仓结果回写到 GWMS”这条链路。
- 也就是说，系统会在代理仓返回出库完成结果时，尝试从返回报文里解析商品对应的序列号列表，并回写本地出库序列号记录。
- 这部分不是独立任务类型，而是附着在出库主流程状态回写阶段执行。
- 如果出库序列号回写失败，当前代码不会直接把出库主流程判失败，而是先保留主流程结果，并在日志里留下失败信息供排查。
库存同步（与入库/出库不同，不靠轮询推进）：
- 手工触发或系统定时启动库存同步。
- 系统会先尽量处理同仓待处理业务任务，但这一步有数量和时长预算，不是必须等所有任务都完成。
- 系统抓取代理仓库存快照。
- 对比 GWMS 本地代理仓托管库位的库存。
- 自动修正差异并保存快照。
- 任务根据执行结果直接写成成功、等待重试或人工处理。
第三步：查看结果和处理异常
运营主要关注两个页面：
- 同步任务页面：看这次业务当前走到哪一步，是否等待自动重试、已经成功，还是需要人工处理。
- 日志页面：看这一步到底发了什么请求、代理仓回了什么响应。
常见处理场景：
- 任务显示等待中：说明这条任务还没有结束，可能是代理仓未到终态，也可能是系统已安排下一次自动查询。
- 任务显示人工处理：说明自动链路已经停下，需要先按错误提示修正资料、配置或业务状态。
- 任务显示成功：说明这条任务已经完成，不需要继续处理。
- 看不懂原因：先看同步任务的执行摘要，再决定要不要去日志页看原始报文。
入库/出库 vs 库存同步的区别：
| 对比项 | 入库/出库任务 | 库存同步任务 |
|---|---|---|
| 任务类型 | 创建确认、取消确认、查询任务 | 库存同步任务 |
| 执行方式 | 推送后再按节奏查询代理仓处理结果 | 抓取库存快照后直接修正本地托管库存 |
| 是否依赖轮询 | 是 | 否 |
| 执行时长 | 取决于代理仓处理进度和本地回写情况 | 取决于预处理任务数量、快照大小和库存修正量 |
| 典型结果 | 成功、继续等待、人工处理 | 成功、继续重试、人工处理 |
| 典型场景 | 把单据交给代理仓执行并持续跟踪处理结果 | 把代理仓当前库存重新校正到 GWMS 代理仓托管库位 |
关键理解点：
- 配置页解决的是“能不能接入”和“按哪条映射执行”。
- 同步任务页解决的是“这次业务当前走到哪一步”。
- 日志页解决的是“请求和响应的原始细节是什么”。
- 入库/出库不是推送后立刻结束，而是继续由任务自动跟踪。
- 库存同步不是严格等所有业务任务处理完才开始，而是预算内先处理一部分再继续。
- 取消是否真的会同步到代理仓，取决于业务类型和当前对接系统支持范围。
- 序列号相关链路目前不会在同步任务页里单独生成一种“序列号任务”，它附着在入库或出库主流程上执行。
1.2 序列号专题总览
如果后面要排查“序列号为什么不对”，建议先把方向分清楚。当前代码里，代理仓序列号至少分成下面 4 类场景：
| 链路方向 | 发生时机 | 当前代码范围 | 是否单独生成任务 | 失败后是否直接打断主流程 | 优先看哪里 |
|---|---|---|---|---|---|
| GWMS -> 代理仓 | 入库单创建成功后，补推当前本地入库序列号 | 入库序列号推送 | 否 | 这一步失败通常会体现在对应推送/同步结果里，需要结合当次链路判断 | 日志 |
| GWMS -> 代理仓 | 本地后来又新增、变更、删除入库序列号时 | 入库序列号增量同步 | 否 | 不属于单独任务，按事件异步发起 | 日志 |
| 代理仓 -> GWMS | 代理仓返回入库终态结果时 | 入库序列号回写 | 否 | 不会直接把入库主流程判失败，后续可继续补录 | 先日志，再同步任务 |
| 代理仓 -> GWMS | 代理仓返回出库完成结果时 | 出库序列号回写 | 否 | 不会直接把出库主流程判失败，主流程先保留成功/已推进结果 | 先日志，再同步任务 |
排查时的 3 个关键判断：
- 先判断你查的是“推过去没”还是“拉回来没”。
- 再判断你查的是入库链路还是出库链路。
- 最后再判断这次问题会不会影响主流程状态，不要看到序列号缺失就直接等同于任务失败。
2. 操作指引
前提条件
请提前确认以下条件：
- 当前账号可以进入
GWMS-代理仓-代理仓系统。 - 已经拿到代理仓提供的系统接入信息，例如系统类型、地址、账号或密码。
- 如需配对仓库，请先在 GWMS 内完成仓库、库区（存储区和残品区）、库区对应库位基础资料维护。
- 如需配对渠道，请先在 GWMS 内完成物流渠道资料维护。
- 如需查看 SKU 配对状态，请先保证对应 GSKU 已在 GWMS 中存在，并且已经发生过代理仓入库。
2.1 新增代理仓系统
菜单路径：GWMS-代理仓-代理仓系统
- 进入代理仓系统页面。
- 页面上方可以按【系统名称】【系统代码】【配置 json】搜索。
- 点击【新增】。
- 在弹窗中填写【系统名称】和【系统类型】：
- 【系统名称】：当前这套代理仓系统的识别名称，用于后续运营区分
- 【系统类型】：当前可选
hipackingWMS等
- 根据选择的系统类型，页面会展示不同的配置方式，自行配置。
- 点击【确定】后，系统提示【新增成功】。
2.2 维护仓库配对并触发库存同步
- 在目标系统所在行点击【仓库】。
- 系统打开”已配对仓库信息”弹窗。
- 弹窗表格展示列：
- 【代理仓代码】
- 【GWMS 仓库代码】
- 【虚拟上架库位】
- 【残品库位】
- 【操作】：包含【绑定 gwms 仓库】【同步库存】【删除】三个图标按钮
- 点击右上角【添加仓库】。
- 在新增仓库映射弹窗中填写以下内容：
- 【代理仓代码】：必填，输入代理仓系统中的仓库编码
- 【GWMS 仓库代码】：必填，从 GWMS 仓库列表选择
- 【虚拟上架库位】：必填，从已选 GWMS 仓库的库位列表选择
- 【残品库位】：必填，从已选 GWMS 仓库的残品库区库位列表选择
- 点击【确定】。系统提示【新增仓库映射成功】。
执行库存同步
- 点击【同步库存】。
- 系统弹出确认框【确认立即触发该仓库映射的库存同步任务？】。
- 确认后，系统提示【已触发库存同步】。
- 后续执行结果请到《同步任务》查看，任务类型为"库存同步任务"。
2.3 配对代理仓渠道
- 在目标系统所在行点击【渠道】。
- 系统打开”已配对渠道信息”弹窗。
- 点击右上角【添加渠道】。
- 系统从代理仓获取可选渠道列表。
- 列表展示以下字段：
- 【代理仓渠道代码】
- 【代理仓渠道名称】
- 【承运商】
- 【服务类型】
- 【可用仓库】
- 【是否自提】
- 勾选要接入的渠道。
- 点击【确定】。系统提示【新增渠道成功】。
绑定 GWMS 渠道
如果需要把代理仓渠道和 GWMS 物流渠道对应起来：
- 在已配对渠道列表中点击编辑按钮。
- 在弹窗中选择【GWMS 渠道代码】。
- 点击【确定】。系统提示【绑定 GWMS 渠道成功】。
删除渠道映射
删除不再使用的渠道映射时：
- 点击删除按钮。
- 确认删除操作。
- 系统提示【删除成功】。
2.4 查看 SKU 配对状态
- 在目标系统所在行点击【sku】。
- 系统打开 SKU 信息弹窗。
- 页面表格展示以下信息：
- 【sku 代码】
- 【同步状态】
- 【异常信息】
- 【操作】：包含重新同步、标记等操作
- 页面支持按【sku 代码】【同步状态】【异常信息】筛选。
- 如需刷新当前结果，可点击【拉取】按钮查看最新状态。
SKU 配对的理解方式
需要注意的是：
- SKU 不是先在这个页面里手工首次推送
- 系统会在第一次代理仓入库推送时，自动推送这次入库涉及到的 SKU
- 只有某个 GSKU 已经通过入库推送过，它才会出现在这个 SKU 配对列表里
- SKU 推送成功后，代理仓系统会记录这条 SKU 的同步状态
3. 补充说明
3.1 系统、仓库、渠道、SKU 的关系
代理仓配置是分层维护的：
- 代理仓系统：定义这次对接接入的是哪个外部系统；
- 仓库配对：定义这个系统下的代理仓代码对应哪个 GWMS 仓库；
- 渠道配对：定义代理仓渠道代码对应哪个 GWMS 渠道；
- SKU 配对：用于查看某个 GSKU 是否已经通过代理仓入库推送过，并查看当前同步状态。
只有系统记录存在，后续三类配对入口才可用。
3.2 为什么库存同步入口放在仓库配对里
库存同步是按“仓库映射”执行的，不是按系统整体执行的。也就是说：
- 同一个代理仓系统下可以有多条仓库映射；
- 每条仓库映射的库存同步任务独立生成。
- 任务执行时只会修正这条映射对应的 GWMS 仓库、代理仓代码、虚拟上架库位和残品库位。
如果某条映射缺少虚拟上架库位或残品库位，系统不会允许直接触发库存同步。
3.3 同步库存为什么不是点完马上看到结果
点击【同步库存】只是提交任务，不等于页面立刻完成同步。 后续还要经历任务创建、业务预处理、库存抓取、库存修正和结果写回。
如果你点完后没有立刻看到结果，优先看《同步任务》：
- 任务是否已经生成；
- 当前是等待中、成功还是人工处理；
- 执行摘要里有没有明确提示原因。
3.4 SKU 配对状态怎么理解
SKU 页面里的记录，不是所有 GSKU 的完整清单。 只有已经通过代理仓入库推送过的 SKU，才会显示在这个列表里。
如果页面中出现异常信息，请优先排查：
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：为什么本地点了取消，但代理仓不一定同步取消？
A6：是否会同步到代理仓，取决于这张单据的业务类型和当前对接系统支持范围。如果代理仓取消没有通过，本次取消不会按成功结束；如果当前业务本来就不走代理仓取消链路，也不能把本地取消理解成代理仓已经取消。
Q7：当前对接的是 HPK，这页看完后还要看哪一页？
A7：建议继续看《HPK 使用说明》。那一页会把 HPK 的当前支持范围、库存理解方式和常见问题集中说明。