领星新品测量接口联调说明

范围

墨家上传的 boxCode 不包含 # 时，Firstleg 将它作为 SKU 测量收件记录保存；带 # 的箱唛继续使用原箱唛测量流程。SKU 记录默认只保存，不自动修改领星，是否自动推送由 Nacos 配置控制。

领星账号使用独立浏览器容器和独立 profile，不复用其他 Node.js 账号或浏览器会话。

领星查询

请求：

POST https://wms.xlwms.com/gateway/wms/newProduct/page
Content-Type: application/json

请求体：

{
  "barcode": "A120133-A-TK",
  "current": 1,
  "customerCode": "",
  "keyword": "A120133-A-TK",
  "multiKeyword": "",
  "searchType": "barcode",
  "size": 20,
  "whCode": "US01"
}

系统按 US01、US02 分别查询，并只接受 productSku 或 barcode 精确等于请求 SKU 的记录。查询结果中的 maintained=1 表示该仓库已经维护过，不能再次提交。

领星测量

请求：

POST https://wms.xlwms.com/gateway/wms/newProduct/measure
Content-Type: application/json

Java 会以查询返回的整条商品记录为基础，仅替换墨家测量值。请求中的单位字段必须区分：

字段	值	含义
`sizeUnit`	`in`	领星原商品尺寸展示单位
`length`/`width`/`height`	查询原值	原商品申报尺寸
`lengthBs`/`widthBs`/`heightBs`	查询原值	原商品英寸换算值
`wmsSizeUnit`	`cm`	本次维护尺寸单位
`wmsLength`/`wmsWidth`/`wmsHeight`	墨家厘米值	本次维护尺寸
`wmsLengthBs`/`wmsWidthBs`/`wmsHeightBs`	厘米 ÷ 2.54	本次维护英寸换算值
`weightUnit`	`lb`	领星原商品重量展示单位
`wmsWeightUnit`	`kg`	本次维护重量单位
`wmsWeight`	墨家千克值	本次维护重量
`wmsWeightBs`	千克 × 2.2046226218	本次维护磅换算值

示例中的维护字段如下：

{
  "wmsLength": "24.5",
  "wmsLengthBs": "9.646",
  "wmsWidth": "18.5",
  "wmsWidthBs": "7.283",
  "wmsHeight": "5",
  "wmsHeightBs": "1.969",
  "wmsSizeUnit": "cm",
  "wmsWeight": "0.15",
  "wmsWeightBs": "0.331",
  "wmsWeightUnit": "kg"
}

接口返回 code=200 才视为提交成功。HTTP 401 或领星业务码表示登录失效时，Java 清理缓存并自动重新登录后重试一次；其他失败记录为同步失败，不自动无限重试。

登录和二次验证

浏览器页地址为 https://wms.xlwms.com/login。Java 通过 CDP 操作独立浏览器页面：

账号：input[name="username"]
密码：input[name="password"]
登录：.login-btn
腾讯安全验证容器：#captchaId（仅在可见挑战出现时转人工处理）
短信/邮箱验证码：input[placeholder="输入验证码"]
TOTP 验证码：input.verification-code-native
短信/邮箱获取验证码：.verify-code-login .code-btn
验证登录：.verify-code-login .login-btn

检测到二次验证页面后，Java 立即为短信/邮箱渠道点击获取验证码；用户在后台输入收到的验证码后，Java 只提交验证码，不会再次发送。TOTP 由领星页面自动初始化。腾讯安全滑块属于人工安全验证，必须通过 noVNC 完成，Java 不绕过该验证。

账号、密码和主登录按钮选择器已根据 https://wms.xlwms.com/login 页面源码及登录脚本核对；短信/邮箱和 TOTP 二次验证输入选择器也已确认。验证码错误或过期等业务结果仍需以真实运行时返回为准。

Nacos 配置

开发环境默认关闭自动推送：

firstleg:
  lingxing:
    auto-sync-enabled: false
    base-url: https://wms.xlwms.com
    login-origin: https://wms.xlwms.com
    browser-cdp-endpoint: http://lingxing-browser:9222
    username: ${LINGXING_USERNAME}
    password: ${LINGXING_PASSWORD}
    track-key-v2-secret-base64: ${LINGXING_TRACK_KEY_V2_SECRET_BASE64}
    warehouses: [US01, US02]

lingxing-browser 和 Java Firstleg 必须加入同一个 Docker 网络（开发部署脚本默认是 firstleg-development-network）。noVNC 只绑定服务器回环地址，远程人工处理安全滑块时使用 SSH 本地端口转发。账号、密码、Cookie、Token 和 Track-Key 密钥不得写入仓库或提交到 Git。

Track-Key 密钥按参考实现只做一次 Base64 解码，Java 不限制解码后的固定字节长度；只要密钥非空且与 Node 实际使用的 keyBytes 相同即可。

验收步骤

启动独立浏览器容器并确认 http://lingxing-browser:9222/json/version 可从 Java 容器访问。
保持 auto-sync-enabled=false，进入后台“SKU同步”页面，输入 SKU，点击“测试连接”。
首次触发二次验证时，在后台输入验证码，确认原查询自动继续，并返回 US01、US02 结果。
对 maintained=0 的记录点击“人工推送”，确认领星返回 code=200。
再次查询同一 SKU，确认已维护记录不会重复提交。
将 auto-sync-enabled 改为 true 后重新上传不带 # 的 SKU，确认入库后自动推送；失败记录可在页面人工重新推送。

5.1 KiB Raw Blame History Unescape Escape