这个接口解决什么问题

在供应商与小米之间的 VMI（供应商管理库存）协同场景里,供应商需要把自有 ERP/WMS 中的即时库存按物料、批次、库龄维度上报给小米供应链平台。本接口正是用于从 SQL Server 的库存视图（含库龄）中查询符合小米规范的明细数据,实现库存可视化管理与按库龄段的精细化协同。

接口能力总览

认证方式：源端 SQL Server 走标准数据库账号密码+JDBC 连接;目标端小米供应链走 OAuth/应用密钥的开放接口鉴权（具体以平台分配的 appId/appSecret 为准）。
请求结构：源端为只读 SQL 查询,作用于 dbo.inventoryXM 视图,SQL 由轻易云适配器按策略模板自动拼装。目标端为 POST 写入接口,request.body 为 JSON 数组。
响应结构：源端返回行集,每行包含 product_code、stock_num、in_stock_time、in_stock_qty 等;目标端返回写入结果码与明细。
分页/增量模式：源端按 in_stock_time + product_code 增量拉取,轻易云的增量游标会持久化最近一次水位;目标端按 group_level: STOCK 整组覆盖/追加写入,无传统分页。
执行频次：常见配置 crontab 50 23,5,11,17 * * *,即每天 4 次轮询。

典型字段映射

字段名	类型	含义	实战注意事项
factory_code	string	工厂/供应商编码	与小米侧工厂维度严格一致,配置时建议在轻易云做一次字典校验
product_code	string	客户物料编码（小米侧产品唯一标识）	作为业务主键,轻易云字段映射器会自动参与去重
vendor_product_code	string	供应商内部物料编码	用于 ERP/WMS 反查,建议单独建一列,不要混进 product_code
component_code	string	组件/物料类型编码	BOM 层级用,若为空可不上报但要保留字段位
product_desc	string	物料描述/名称	中文注意 UTF-8 编码,避免出现「?」乱码
product_class	string	产品分类	静态字典,轻易云里通常做常量映射
product_level	string	产品层级	字符串类型,即便值是 '1' 也不要转 int
common_status	string	通用状态(Y/N)	只上报有效物料(Y),无效数据会污染目标侧
stock_num	int	即时库存数量	负数表示预留/锁定,需与业务确认是否上报
stock_unit	string	计量单位(常见 PCS)	单位不一致时优先在源端统一,轻易云可做单位换算
stock_org	string	库存组织/仓库组织	与小米侧组织编码映射,轻易云建议配置映射表
asn_stock_type	string	ASN 库存类型	仅在 ASN 场景有意义,常规库存可置空
in_stock_time	string	入库时间(批次维度)	库龄计算的关键字段,格式必须 ISO8601
in_stock_qty	string	入库数量(批次明细)	与 in_stock_time 配对形成 stock_age 群组

metadata 中 id/number 由 {{product_code}}{{stock_num}}{{in_stock_time}}{{in_stock_qty}} 复合而成,确保同产品多批次不丢不重。

在轻易云上如何配置

在轻易云数据集成平台里,这套接口通常用「SQL Server 适配器 + 小米供应链写入适配器」的双适配器组合来落地。源端适配器负责按策略模板拼装 SQL 并增量拉取 dbo.inventoryXM;轻易云的字段映射器会自动把源端的 in_stock_time、in_stock_qty 聚合成目标侧 stock_age 数组,并固定写入 group_level: STOCK。调度上直接用平台的可视化 crontab 配置 50 23,5,11,17 * * *,无需手写调度脚本。增量水位、失败重试、断点续传都由轻易云运行时统一托管。

跨方案实战要点

复合主键要稳定:多批次同步一定不要只拿 product_code 做唯一键,否则会严重丢数;坚持用四元组 product_code+stock_num+in_stock_time+in_stock_qty。
stock_age 是聚合产物:源端没有这个列,它是目标侧由 in_stock_time/in_stock_qty 聚合而来,在轻易云字段映射器里用数组转换节点实现,不要试图在 SQL 里拼。
库龄口径要先对齐:「30 天/60 天/90 天」的分段规则必须与小米侧达成一致,否则上报的群组会被退回。
编码字典单边维护:factory_code、stock_org、product_class 强烈建议在轻易云里集中维护映射表,变更一次全链路生效,避免改 SQL。
空值与 0 要区分:库存为 0 但记录有效,应正常上报;只有记录不存在才不上报,否则会被误判为缺数据。
单位与精度的最后一道关:PCS/箱/托混用时,在源端视图统一换算,轻易云只负责搬运,不负责单位换算。

踩坑复盘

乱码:SQL Server 源端字段为 varchar 而非 nvarchar 时,中文 product_desc 同步到小米会出现「?」。稳妥的做法是在源端视图就定义为 nvarchar,或者在轻易云里强制按 UTF-8 解析。
时区漂移:in_stock_time 用了本地时间字符串而非 UTC,导致库龄每天漂移 8 小时。建议入库时一律落 UTC,轻易云映射时再按需转换。
批次合并丢明细:有人偷懒在 SQL 里用 GROUP BY 把同一 product_code 的多 in_stock_time 合并了,结果 stock_age 只剩一条。务必保留每批次行,聚合交给目标侧。
crontab 撞车:4 个时间点如果同步耗时超过 6 小时会出现并发跑批,轻易云里要打开「同策略互斥」开关。
无效物料污染:common_status='N' 的物料被一起上报,目标侧拒绝整批。稳妥的做法是在源端 SQL 加 WHERE 过滤,或在轻易云前置过滤节点里剔除。

何时选用

本接口适用于供应商→小米供应链的库存可视化、VMI 协同、批次级库龄上报等场景,源库为 SQL Server 且需要按库龄分组输出时优先选用。若只需粗粒度汇总,或源端不是 SQL Server,建议改用更轻的库存汇总接口,避免不必要的复杂度。

查询小米库存（含 stock_age_XM_VIEW）接口字段手册：从 SQL Server 到小米供应链的实战教程