聚水潭库存偏差可因同步中断、映射错误等导致，需通过核查链路、盘点覆盖、修正映射、启用事件驱动及清理脏数据五步校准。
如果您发现聚水潭系统中显示的库存数量与实际仓库实物或下游系统（如商城、ERP）存在明显偏差，则可能是由于同步中断、字段映射错误、未启用实时更新机制或操作未触发同步事件所致。以下是校准聚水潭库存数据的多种方法：
一、核查并修复同步链路异常
该方法用于定位因网络、认证失效或接口调用失败导致的库存数据停滞或丢失。需确认聚水潭与目标系统（如金蝶云星空、MySQL 或自有商城）之间的双向通信是否持续有效。
1、登录聚水潭ERP后台，进入【设置】→【店铺设置】→【消息推送】，检查对应店铺的回调地址是否填写正确且状态为“已启用”。
2、在轻易云或自建集成平台中，查看最近30分钟内的同步任务日志，确认是否存在“401 Unauthorized”、“连接超时”或“空响应”等错误记录。
3、重新验证API密钥有效性：前往聚水潭开放平台开发者后台，核对当前应用的APP Key与APP Secret是否与集成平台配置一致；若近期重置过密钥，必须同步更新至所有对接系统中。
4、手动触发一次全量同步：在集成平台中执行“强制刷新库存”操作，或调用聚水潭库存查询接口（https://api.jushuitan.com/inventory/query）验证返回数据是否完整可读。
二、执行库存盘点与强制覆盖同步
该方法适用于已确认源端（聚水潭）库存准确但目标系统数据滞后或错乱的情形，通过人工盘点后以聚水潭为准强制刷新下游库存值。
1、在聚水潭ERP中执行【库存管理】→【库存盘点】，选择对应仓库，生成盘点单并完成实盘录入与审核，确保聚水潭内各SKU的可用库存和在途库存字段为最新状态。
2、导出盘点结果：点击盘点单右上角【导出Excel】，获取含sku、warehouse_code、quantity三列的标准格式文件。
3、在目标系统（如MySQL）中执行覆盖写入：使用脚本或数据库工具运行INSERT ... ON DUPLICATE KEY UPDATE语句，将导出数据逐条写入inventory_sync表，并强制更新stock_quantity与last_sync_time字段。
4、同步完成后，在商城后台手动点击【库存同步】按钮，触发一次即时拉取，验证前端展示是否与盘点结果一致。
三、修正字段映射与元数据配置
该方法解决因源系统与目标系统字段定义不一致引发的数量误写问题，例如将“锁定库存”误映射为“可用库存”，或未区分多仓场景下的仓库编码格式。
1、进入轻易云集成平台的方案配置页，在【元数据配置】模块中展开聚水潭库存查询API的响应结构，确认字段available_qty（可用库存）、locked_qty（锁定库存）、frozen_qty（冻结库存）是否被分别映射至目标系统的对应字段。
2、检查目标系统接收表结构：若MySQL中stock_quantity字段未做分区设计，而聚水潭返回的是按warehouse_code聚合后的总量，则需在映射逻辑中加入GROUP BY处理，避免多仓同SKU数据被覆盖。
3、修改映射规则：将原映射quantity → stock_quantity替换为available_qty → stock_quantity，并为locked_qty单独映射至locked_stock字段，确保业务逻辑可分离。
4、保存配置后，运行一次测试同步任务，比对日志中原始响应JSON与写入SQL语句，确认数值未发生截断、类型转换错误或单位换算偏差。
四、启用库存变更事件驱动同步
该方法替代定时轮询机制，利用聚水潭提供的消息推送能力，在库存发生入库、出库、调拨、盘点等操作后即时触发同步，从源头杜绝延迟偏差。
1、在聚水潭ERP中进入【设置】→【店铺设置】→【消息推送】，勾选“库存变更”事件类型，并确保回调地址指向具备接收POST请求能力的服务端接口。
2、服务端接口需支持解析聚水潭推送的JSON体，其中关键字段包括event_type（如INVENTORY_INCREASE）、sku、warehouse_code、change_amount及operator。
3、编写幂等处理逻辑：根据event_id去重，仅当change_amount不为零时更新目标系统对应SKU在指定仓库的库存值，避免重复消费导致数量翻倍或归零。
4、部署接口后，在聚水潭模拟一次手工调拨操作，观察目标系统库存是否在5秒内自动更新，且增减值与操作完全一致。
五、隔离并清理脏数据批次
该方法针对历史同步过程中因程序Bug或配置错误写入的异常库存记录，例如负数库存、超大数值或NULL值，需在不影响当前业务的前提下精准剔除。
1、在目标数据库（如MySQL）中执行诊断查询：SELECT sku, warehouse_code, stock_quantity FROM inventory_sync WHERE stock_quantity 9999999;
2、对命中记录进行标记：新增临时字段is_dirty，将上述查询结果批量更新为1，并保留原始值至backup_quantity字段。
3、暂停当前同步任务，在轻易云平台中禁用该集成方案的自动执行，防止新脏数据持续写入。
4、联系聚水潭技术支持获取对应时间段内的原始库存快照CSV，以其为基准，对is_dirty=1的记录执行UPDATE语句回填校准值。
