baiyue-firstleg/docs/领星新品测量接口说明.md

# 领星新品测量接口说明

> 依据开发环境实际成功请求整理。接口属于领星 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、账号、密码或验证码。