docs: document lingxing new product measurement api

2026-09-22 10:16:31 +08:00
parent 16849c2d6e
commit 0c7ff73e2d
1 changed files with 210 additions and 0 deletions
@@ -0,0 +1,210 @@
+# 领星新品测量接口说明
+
+> 依据开发环境实际成功请求整理。接口属于领星 WMS 内部网关接口，需要携带已经登录领星 WMS 后取得的 Token 和 Cookie。账号、密码、Token、Cookie 不写入本文档。
+
+## 1. 业务流程
+
+墨家上传不带 `#` 的 SKU 后，按以下流程处理：
+
+```text
+墨家 SKU 测量数据
+        ↓
+查询领星新品 SKU（US01、US02 分别查询）
+        ↓
+精确匹配 productSku 或 barcode
+        ↓
+maintained = 1：禁止再次维护，记录失败原因
+maintained = 0：调用新品测量维护接口
+        ↓
+记录同步成功或失败
+```
+
+箱唛（`boxCode` 包含 `#`）继续走现有箱唛测量逻辑，不调用本文档接口。
+
+## 2. 查询 SKU
+
+### 请求
+
+```http
+POST https://wms.xlwms.com/gateway/wms/newProduct/page
+Content-Type: application/json
+Authorization: Bearer {token}
+Cookie: {领星登录Cookie}
+```
+
+请求体：
+
+```json
+{
+  "barcode": "A120133-A-TK",
+  "current": 1,
+  "customerCode": "",
+  "keyword": "A120133-A-TK",
+  "multiKeyword": "",
+  "searchType": "barcode",
+  "size": 20,
+  "whCode": "US01"
+}
+```
+
+`US02` 查询时只替换：
+
+```json
+"whCode": "US02"
+```
+
+### 成功响应示例
+
+```json
+{
+  "code": 200,
+  "data": {
+    "records": [
+      {
+        "tenantCode": "1189",
+        "whCode": "US01",
+        "customerCode": "1189060",
+        "customerName": "DF067",
+        "skuId": "",
+        "productSku": "A120133-A-TK",
+        "productName": "（压缩）2026新款30CM耶稣玩偶",
+        "productLname": "",
+        "barcode": "A120133-A-TK",
+        "length": 23.000,
+        "lengthBs": 9.055,
+        "width": 15.000,
+        "widthBs": 5.906,
+        "height": 3.500,
+        "heightBs": 1.378,
+        "sizeUnit": "cm",
+        "weight": 0.150,
+        "weightBs": 0.331,
+        "weightUnit": "kg",
+        "wmsLength": 0.000,
+        "wmsLengthBs": 0.000,
+        "wmsWidth": 0.000,
+        "wmsWidthBs": 0.000,
+        "wmsHeight": 0.000,
+        "wmsHeightBs": 0.000,
+        "wmsSizeUnit": "cm",
+        "wmsWeight": 0.000,
+        "wmsWeightBs": 0.000,
+        "wmsWeightUnit": "kg",
+        "wmsUnitMark": 0,
+        "maintainer": "",
+        "wmsMaintenanceTime": "",
+        "maintained": 0
+      }
+    ],
+    "total": 1,
+    "size": 20,
+    "current": 1,
+    "pages": 1
+  },
+  "msg": "操作成功"
+}
+```
+
+### 查询规则
+
+1. `code = 200` 且 `data.records` 有记录，才算查询成功。
+2. 查询结果必须精确匹配墨家 SKU：`productSku` 或 `barcode` 等于墨家传入的 SKU。
+3. `US01`、`US02` 分别查询，不能把一个仓库的匹配结果当作另一个仓库的结果。
+4. 没有匹配记录时，记录失败原因“未匹配到领星 SKU”，不调用维护接口。
+5. 保存 `tenantCode`、`whCode`、`customerCode`、`customerName`、`productSku`、`barcode`、`maintained` 和当前领星尺寸重量，供页面追踪。
+
+## 3. 新品测量维护
+
+### 请求
+
+```http
+POST https://wms.xlwms.com/gateway/wms/newProduct/measure
+Content-Type: application/json
+Authorization: Bearer {token}
+Cookie: {领星登录Cookie}
+```
+
+维护请求以查询返回的 SKU 记录为基础，只把 `wmsLength`、`wmsWidth`、`wmsHeight`、`wmsWeight` 替换为墨家测量值，并保留领星返回的业务标识字段。
+
+成功样例：
+
+```json
+{
+  "barcode": "A120133-A-TK",
+  "customerCode": "1189060",
+  "customerName": "DF067",
+  "height": 3.5,
+  "heightBs": 1.378,
+  "length": 23,
+  "lengthBs": 9.055,
+  "maintained": 0,
+  "maintainer": "",
+  "productLname": "",
+  "productName": "（压缩）2026新款30CM耶稣玩偶",
+  "productSku": "A120133-A-TK",
+  "sizeUnit": "in",
+  "skuId": "",
+  "tenantCode": "1189",
+  "weight": 0.15,
+  "weightBs": 0.331,
+  "weightUnit": "lb",
+  "whCode": "US01",
+  "width": 15,
+  "widthBs": 5.906,
+  "wmsHeight": "5",
+  "wmsHeightBs": 1.969,
+  "wmsLength": "24.5",
+  "wmsLengthBs": 9.646,
+  "wmsMaintenanceTime": "",
+  "wmsSizeUnit": "cm",
+  "wmsUnitMark": 0,
+  "wmsWeight": "0.15",
+  "wmsWeightBs": 0.331,
+  "wmsWeightUnit": "kg",
+  "wmsWidth": "18.5",
+  "wmsWidthBs": 7.283
+}
+```
+
+### 成功响应
+
+```json
+{
+  "code": 200,
+  "data": {},
+  "msg": "操作成功"
+}
+```
+
+`data` 为空对象时，只要 `code = 200`，即视为维护成功。
+
+## 4. 单次维护限制
+
+领星新品测量只能维护一次，不能重复覆盖：
+
+- 查询结果 `maintained = 0`：允许调用 `/measure`。
+- 查询结果 `maintained = 1`：禁止调用 `/measure`，记录失败原因“领星 SKU 已维护，不能重复维护”。
+- 已经提交过维护但本地没有收到明确成功响应时，不应盲目重试；应重新查询确认 `maintained` 和 `wmsMaintenanceTime`。
+- 本地页面保留墨家测量原始数据和同步失败原因，但不允许通过编辑或重推绕过领星的单次维护限制。
+
+## 5. 单位处理
+
+当前成功样例中，查询返回的基础字段和维护请求中的单位字段存在差异：
+
+- 查询结果：`sizeUnit = cm`、`weightUnit = kg`；
+- 成功维护请求样例：`sizeUnit = in`、`weightUnit = lb`；
+- WMS 维护字段：`wmsSizeUnit = cm`、`wmsWeightUnit = kg`；
+- `wmsLength`、`wmsWidth`、`wmsHeight`、`wmsWeight` 在样例中以字符串传递。
+
+因此 Java 实现不能根据字段名自行换算或把所有字段统一成同一单位。应以查询返回的原始记录作为模板，仅按领星接口约定替换 WMS 维护字段；具体换算规则以领星成功请求和后续验证结果为准。
+
+## 6. 本地同步状态建议
+
+| 状态 | 含义 |
+| --- | --- |
+| 待同步 | 墨家已接收，尚未完成查询和维护 |
+| 同步成功 | `/measure` 返回 `code = 200` |
+| 同步失败 | 未匹配 SKU、已维护、查询失败、维护失败或登录态失效 |
+
+失败记录必须保存脱敏后的失败原因；不保存完整 Token、Cookie、账号、密码或验证码。
+