chenchuchuan 1 week ago
parent
commit
12718ec376
  1. 26
      README.md
  2. 1
      docs-warehouse/README.md
  3. 335
      docs-warehouse/hengjian/README.md
  4. 6
      pom.xml
  5. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseProvider.java
  6. 49
      warehouse-sdk-hengjian/pom.xml
  7. 96
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java
  8. 358
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java
  9. 35
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapterFactory.java
  10. 106
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianDirectoryMapper.java
  11. 243
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOutboundMapper.java
  12. 165
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductMapper.java
  13. 50
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCarrierGroupDtos.java
  14. 200
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCreateOrderDtos.java
  15. 123
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianProductSaveDtos.java
  16. 42
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianWarehouseDtos.java
  17. 10
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/package-info.java
  18. 18
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/package-info.java
  19. 197
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianEnvelope.java
  20. 65
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianRateLimiter.java
  21. 137
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianRequestFactory.java
  22. 12
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/package-info.java
  23. 12
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/webhook/package-info.java
  24. 100
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java
  25. 440
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java
  26. 252
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java
  27. 338
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductSaveTest.java
  28. 126
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/http/HengjianEnvelopeTest.java
  29. 148
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianReadOnlyProbeTest.java
  30. 191
      warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java
  31. 75
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
  32. 25
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangChannelRecommendMapper.java
  33. 24
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangForecastMapper.java
  34. 13
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java
  35. 12
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java
  36. 9
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java
  37. 8
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java
  38. 12
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java
  39. 25
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java
  40. 6
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/auth/XincangTokenClient.java
  41. 144
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangChannelRecommendDtos.java
  42. 1601
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java
  43. 104
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangForecastCreateDtos.java
  44. 222
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangForecastDetailDtos.java
  45. 150
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangForecastImproveDtos.java
  46. 64
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangLoginDtos.java
  47. 49
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangLogisticsDtos.java
  48. 55
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangOrderCreateDtos.java
  49. 173
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangOrderDetailDtos.java
  50. 30
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangProductListDtos.java
  51. 138
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangProductSaveDtos.java
  52. 88
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangStockAgeListDtos.java
  53. 84
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangStockListDtos.java
  54. 160
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangTransferCreateDtos.java
  55. 198
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangTransferDetailDtos.java
  56. 85
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangUploadDtos.java
  57. 64
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangWarehouseDtos.java

26
README.md

@ -81,6 +81,7 @@ graph BT @@ -81,6 +81,7 @@ graph BT
lingxing["lingxing"]
yqn["warehouse-sdk-yqn"]
xc["warehouse-sdk-xincang"]
hj["warehouse-sdk-hengjian"]
chcore --> common
whcore --> common
@ -95,6 +96,8 @@ graph BT @@ -95,6 +96,8 @@ graph BT
yqn --> whcore
xc --> common
xc --> whcore
hj --> common
hj --> whcore
```
**一次商品查询的调用链**(订单、售后、出库等能力走同一条骨架):
@ -138,6 +141,7 @@ sequenceDiagram @@ -138,6 +141,7 @@ sequenceDiagram
| `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 |
| `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) |
| `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄、头程预报、仓库 / 承运商资料) |
| `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单) |
依赖方向:
```
@ -147,6 +151,7 @@ warehouse-sdk-core ┘ @@ -147,6 +151,7 @@ warehouse-sdk-core ┘
lingxing ───────────→ channel-sdk-core, sdk-common
warehouse-sdk-yqn ──→ warehouse-sdk-core, sdk-common
warehouse-sdk-xincang ──→ warehouse-sdk-core, sdk-common
warehouse-sdk-hengjian ──→ warehouse-sdk-core, sdk-common
```
**渠道域与仓库域平级、互不依赖**,只在 `sdk-common` 上共享 SPI 契约与管道基础设施。
出库回传运单后由 OMS 调渠道域标发,仓库域不调用渠道域。
@ -357,10 +362,28 @@ common.ecommerce @@ -357,10 +362,28 @@ common.ecommerce
│ XincangTransferMapper / XincangTransferDetailMapper /
│ XincangChannelRecommendMapper / XincangInventoryMapper /
│ XincangForecastMapper
├── dto XincangDtos(登录 / 商品)
├── dto 一个接口一个文件:XincangLoginDtos / XincangProductSaveDtos /
│ XincangProductListDtos / XincangOrderCreateDtos /
│ XincangOrderDetailDtos / XincangUploadDtos /
│ XincangTransferCreateDtos / XincangTransferDetailDtos /
│ XincangChannelRecommendDtos / XincangStockListDtos /
│ XincangStockAgeListDtos / XincangForecastCreateDtos /
│ XincangForecastImproveDtos / XincangForecastDetailDtos /
│ XincangWarehouseDtos / XincangLogisticsDtos
├── enums XincangOrderStatus / XincangTransferState /
│ XincangForecastStatus / XincangOrderType
└── http XincangRequestFactory / XincangMultipart / XincangEnvelope / XincangRateLimiter
│
└── hengjian 恒健三方仓(warehouse-sdk-hengjian)
├── HengjianConstants 测试基址、当前接入路径、双授权头名、成功码 / 未授权码、限流
├── adapter HengjianAdapter(目录 + 渠道 + 商品保存 + 出库下单)/
│ HengjianAdapterFactory / HengjianDirectoryMapper /
│ HengjianProductMapper / HengjianOutboundMapper
├── dto HengjianWarehouseDtos / HengjianCarrierGroupDtos /
│ HengjianProductSaveDtos / HengjianCreateOrderDtos
├── enums (package-info:调拨 / 出库状态枚举约定,待建)
├── http HengjianRequestFactory / HengjianEnvelope / HengjianRateLimiter
└── webhook (package-info:文档无回调页,未实现)
```
包名统一前缀 `common.ecommerce.`,下表省略前缀。
@ -1053,6 +1076,7 @@ mvn -pl lingxing test # 单模块 @@ -1053,6 +1076,7 @@ mvn -pl lingxing test # 单模块
mvn -pl lingxing -Dtest=LingxingSdkListingCallTest test
mvn -pl warehouse-sdk-yqn test # 运去哪 P1 契约测试
mvn -pl warehouse-sdk-xincang -am test # 信仓登录 / 商品 / 下单 / 转运
mvn -pl warehouse-sdk-hengjian -am test # 恒健目录 / 渠道 / 商品保存 / 出库下单
```
---

1
docs-warehouse/README.md

@ -8,6 +8,7 @@ @@ -8,6 +8,7 @@
| [callback.md](callback.md) | 回调(Webhook)链路:验签、分派、出参模型、宿主怎么接 |
| [yqn/README.md](yqn/README.md) | 运去哪:接口汇总、联调结论、平台限制 |
| [xincang/README.md](xincang/README.md) | 信仓:接口汇总、枚举码表、协议待核对、联调探针 |
| [hengjian/README.md](hengjian/README.md) | 恒健:接口清单、鉴权真机结论、文档与实际不符、只读探针 |
| [notes.md](notes.md) | 通用注意事项:写操作、幂等、时区、单位、字段口径 |
## 快速定位

335
docs-warehouse/hengjian/README.md

@ -0,0 +1,335 @@ @@ -0,0 +1,335 @@
# 恒健(HengJian / Efulfill)接入
语雀接口文档:<https://ehengjian.yuque.com/org-wiki-ehengjian-ocq8pc/tvzvkk>(book `tvzvkk`)
核对时间:2026-11-12(文档 `toc_updated_at` = 2026-11-10)
## 1. 基本信息
| 项 | 值 |
|---|---|
| 适配器 ID / provider | `hengjian` / `WarehouseProvider.HENGJIAN`(code 50) |
| 测试环境 | `https://pr-open-api.ehengjian.com` |
| 生产环境 | `https://open-api.ehengjian.com` |
| 鉴权 | 组织级固定 token,放请求头**两个**:`Authorization` + `x-api-key`,取值相同 |
| token 获取 | 文档未写自助方式:测试参数需联系 `bianyuqi@henglin.com` |
| token 续期 | 文档未提 refresh;先按固定 token 处理(不经过 `TokenManager`) |
| 限流 | 未公开,保守默认 2 req/s/仓 |
| 成功判定 | body 里 `code = 200`;HTTP 通常恒为 200 |
| 时间口径 | 文档多处注明 **UTC**(`paidAt`、`expectedShipDate`、订单列表的时间参数) |
| 单位 | 商品尺寸 cm、重量 g;费用单位为 USD(试算接口另有单位入参) |
| 文档结构 | 67 个目录项,其中 64 个可见接口页(3 个 `visible=0`,1 个抓取 403);另有 `CloudShip接口文档` / `加拿大邮政` 两个不相关目录,其下文档均不可见 |
### 鉴权真机结论(2026-11-12,未拿到有效 token)
| 请求 | 结果 |
|---|---|
| 不带任何授权头 | **HTTP 200** + `{"statusCode":500,"status":1,"code":999999,"message":"查询失败Unauthorized"}` |
| 只带 `Authorization`(无效值) | HTTP 500 + `{"status":500,"error":"Internal Server Error","message":"未知的账户!"}` |
| 只带 `x-api-key`(无效值) | 同上 |
| 两个都带(无效值) | 同上 |
**结论**:
- 未授权有两种表现(HTTP 200 + `code=999999`;HTTP 500 + 「未知的账户」),
适配器把两者都映射成 `AuthException`,**不能**当普通业务失败或瞬时故障——
否则宿主不会去刷新凭据,还会无意义重试。
- 用无效 token 区分不出「两个头是否都必须」,所以按文档两个都带。拿到有效 token 后
应补一次对照实验(各只带一个),再决定能否精简。
### 文档与实际不一致(待真机逐条确认)
| # | 文档写的 | 问题 |
|---|---|---|
| 1 | 《基础API调用》:`Authorization` 与 `x-api-key` 都必填、都叫「授权Token」 | 没说两者是否同值;两个头是否都必须未验证(见上) |
| 2 | 《库存变动明细查询》(2026-10-20 新增):「沿用现有 OpenAPI 凭证,请求头使用 `Authorization: Bearer <token>`」 | 与《基础API调用》的双头要求**冲突**;该页是后来单独写的,可能代表新约定 |
| 3 | 《获取仓库支持的物流渠道》:`warehouseCodes` 类型写 `STRING` | 请求示例是数组 `["..."]`;按数组下发 |
| 4 | 《批量查询库存》:GET,参数是 `warehouseCodes` LIST | HTTP GET 不能可靠表达数组;先按重复 query 参数下发 |
| 5 | 《查询库存》《查询 sku》等页:`code` 类型写 `STRING` | 其它页写 INTEGER;信封按文本读再转数字,两种都认 |
| 6 | 多个接口页**不写路径 / 请求方式**(调拨取消、销毁计划、退货 v2、计费类) | 只能从标题和相邻页推断;这几类未接入前不需要 |
| 7 | 《创建/编辑 产品》`length` vs 《查询 sku》`itemLength` | 同一概念两个字段名;接入商品前要真机确认哪个是「产品长」 |
| 8 | 试算 / 地址属性文档的路径写的是 `open-api.ehenglin.com`、`thebizark.com` | 与 `ehengjian.com` 不同域,疑似旧域名或从别家文档复制;接入前必须真机核对 |
| 9 | 几乎所有接口页**没有验签 / 请求头说明** | 真机返回早于业务码的 Spring 错误页,说明鉴权在网关层,文档没覆盖 |
| 10 | 《创建销售发货单》与 "Create Sale Order With Label" 是同一路径的两页 | 中文页把 `createdAt` 标必填、也没有 `isPrime`;英文页有 `isPrime`、没有 `customerRemark` / `warehouseRemark`。字段表按两页并集实现 |
| 11 | 建单页 `isPrime` 类型写 STRING | 请求示例给的是数字 `0`;按示例发 Integer |
| 12 | 建单页行级 `isSignature` 是 0~3 | 统一模型只有布尔,2 / 3(成人 / 间接签收)暂不可表达 |
> 运去哪的教训:只按文档写代码,有 4 处接口一个都跑不通。恒健的文档完整度更差
> (路径缺失、类型不一致、域名不一致),**接入任何写接口前必须先跑只读探针**。
## 2. 已接入(本期)
| # | 接口 | 路径 | 能力位 | 状态 |
|---|---|---|---|---|
| 1 | 获取当前组织仓库 | `POST /v2/warehouse/getWarehouse` | `DIRECTORY` | ✅ |
| 2 | 获取物流渠道(全量) | `POST /v2/carrierGroup/getCarrierGroup` | `DIRECTORY` / `LOGISTICS_PRODUCT` | ✅ |
| 3 | 获取仓库支持的物流渠道 | `POST /v2/carrierGroup/getWarehouseCarrierGroupServices` | 同上(适配器方法,非 capability) | ✅ |
| 4 | 创建 / 编辑产品 | `POST /v1/product/save` | `PRODUCT` | ✅ |
| 5 | 创建销售发货单 | `POST /v1/saleOrder/create` | `OUTBOUND` / `PLATFORM_LABEL_DELIVERY` | ✅ |
| 6 | 回调 | — | — | ❌ 文档无回调页 |
前三个接口是无副作用查询、不依赖单号,用来先验证鉴权与信封;商品保存是写接口,
但只写主数据、不产生履约单据,所以放在第二阶段。出库下单是真正的履约写操作,
门面强制经幂等守卫(`warehouseCode + outboundRequestNo + create`)。
### 返回形状差异
| 接口 | `data` |
|---|---|
| `getWarehouse` | 数组 |
| `getCarrierGroup` | 数组 |
| `getWarehouseCarrierGroupServices` | **对象**:`{"EFCA":[{...}], "EFGA":[...]}` |
第三个接口只取请求的那个仓的键——别的仓的渠道混进来,会把「仓不支持该渠道」
推到仓方去报错。
### 字段口径
| 统一模型字段 | 恒健字段 | 说明 |
|---|---|---|
| `WarehouseFacility.warehouseCode` | `warehouseCode` | 唯一标识,下单也用它 |
| `WarehouseFacility.providerWarehouseId` | — | 恒健没有独立内部 id,恒为 null |
| `WarehouseFacility.contactName/mobilePhone/email` | — | 文档仓对象没有这三个字段,**恒为 null**(平台限制) |
| `WarehouseFacility.postcode` | `postal` | 字段名不同 |
| `LogisticsProduct.logisticsProductCode` | `code` | 下单的 `carrierCode` 用它 |
| `LogisticsProduct.logisticsProductName` | `carrier` + `carrierServiceName` | 统一模型只有一个名称字段,拼成「UPS - Ground」 |
| `LogisticsProduct.crossCountry` | — | 恒健无此维度,恒 false(**不是**「不支持跨国」) |
### 商品保存(`/v1/product/save`)
**保存语义**:同一 SKU 再调即更新,没有单独的 create / update 接口,也不像信仓那样
要先查一次再决定调哪个。响应只有 `code / message`,**没有 data**,所以:
- `ProductResult.status` 固定为 `SAVED`;
- `ProductResult.rawStatus` 取仓方的 `message`(如「产品创建成功」);
- 仓方不告诉这次是新建还是更新,**不替它编** `ADDED` / `UPDATED`。
**三组尺寸不能互相顶替**:
| 恒健字段 | 含义 | 必填 | 统一模型 |
|---|---|---|---|
| `length / width / height / weight` | 产品(发货单元)尺寸与重量 | 是 | `lengthCm / widthCm / heightCm / weightGrams` |
| `itemLength / itemWidth / itemHeight` | 单品尺寸 | 否 | `itemLengthCm / …`(未给不发) |
| `packedLength / packedWidth / packedHeight / packedWeight / packedQty` | 外箱尺寸、外箱重量、装箱数量 | 是 | `packedLengthCm / … / packedQuantity` |
把单品尺寸填进 `length` 会让仓方的计费重与货架位算错,所以适配器不做任何回退填充。
**本地拒绝的必填项**(恒健要求、统一模型不强制):
`nameEn`、`description`、`packingType`(0 原包装 / 1 重新打包)、外箱四项尺寸重量、
`packedQty`。缺任何一项直接抛 `IllegalArgumentException`,**一个请求都不发**。
**不在报文里编造字段**:
| 统一模型字段 | 为什么不发 |
|---|---|
| `imageUrl` | 恒健的 `imageUrls` 是「产品测量图片」(复核长宽高用),不是商品主图;语义不同 |
| `packageStyle` | 恒健的 `isSpecialOuterPackaging` 是「是否特殊外包装」,不是同一套码 |
| `requireSn` / `snManagementMode` / `lotControl*` | 文档无对应字段 |
| `hsCode` / `countryOfOrigin` / `declaredValue` | 恒健只收报关名称(`customName` / `customNameEn`),没有 HS 与原产国 |
| `link` / `returnDealMethod` / `productCategory` | 文档无对应字段 |
**其它口径**:
- `isInsuranceFlag` 是 `Y` / `N`(不是 0 / 1);未指定则整组不发。
- `expirationDate` 只在 `expirationControl = 1` 时发送,避免仓方存「有天数但未启用」的脏数据。
- `cost` 与 `currency` 成对发送;`cost` 缺失则两个都不发。
- 单位与统一模型一致(cm / g),**不做换算**。
### 创建销售发货单(`/v1/saleOrder/create`)
中英文两页文档是**同一个接口**(中文页「创建销售发货单(带附件的)」、英文页
「Create Sale Order With Label」),按两页并集实现。
**必填字段**:`orderNo`、`shipToCountry`、`shipToState`、`shipToCity`、`shipToPostal`、
`shipToAddress1`、`shipToContact`、`shipToTelephone`、`createdAt`、`productItems`、
`attachInfoItems`。适配器在本地逐项校验,缺任何一项直接抛 `IllegalArgumentException`,
**一个请求都不发**。
**几个关键口径**:
| 项 | 处理 |
|---|---|
| `createdAt` | 统一模型没有该字段,用调用方注入的 `Clock` 生成下单时刻(请求侧时间戳,不是编造数据)。恒健不拿它去重 |
| 时间格式 | 恒健是 **UTC** 的 `yyyy-MM-dd HH:mm:ss`,固定按 UTC 格式化,**不用** `WarehouseContext.zone()`——那个时区是给「仓方回传的无时区本地时间」用的,方向相反 |
| `skuAmount` | 是「当前 SKU **总**金额」,不是单价:有 `totalAmount` 直接用,没有就用申报单价 × 数量 |
| `isSign` / `isSignature` | 恒健挂在**行**上且必填;统一模型挂在**命令**上(布尔)。取命令值套到每一行 |
| 签收类型 | 统一模型只有布尔,表达不了成人签收(2) / 间接签收(3),统一映射成**直接签收(1)**——比静默降成「不签收(0)」安全 |
| `isInsure` / `insureAmount` | 由「行是否有保价金额」推导;有金额即视为保价并带上金额 |
| `attachInfoItems` | **必填**。没有附件时发**空数组**而不是省略字段;平台面单(base64)会剥掉 `data:` 前缀后放进 `file`,`type=0`,名称优先用跟踪号 |
| `salesPlatform` | 恒健没有平台维度(店铺路由走 `channelAccount`),**不发**,也**不**拿它推 `isDFOrder`——VC 订单里只有一部分是 DF |
| `splitOrder` / `packages` | 恒健没有拆单与包裹入参,忽略 |
| `estimatedDeliveryTime` | 恒健只有 `expectedShipDate`(要求发货时间),没有送达时间 |
**响应**:只回 `data.orderId`(仓内部**数字** id,不是字符串单号)。取消接口要
`orderId` + `orderNo` 两个都传,所以这个 id 必须随 `OutboundReceipt.providerOrderId()`
落库;拿不到就报错,**不当创建成功**。
**未接入**:查询 / 取消 / 包裹。调用这些方法会显式抛 `WarehouseException`,不返回 null——
静默返回空会让调用方以为「仓说没有这单」。
## 3. 未接入(文档已有,按需排期)
按能力位分组,路径取自文档(**标注 ⚠ 的表示文档没写路径或路径可疑,需真机核对**):
### 出库(`OUTBOUND`)
| 接口 | 路径 | 状态 |
|---|---|---|
| 创建销售发货单(中文页「带附件」/ 英文页 "With Label",同路径) | `POST /v1/saleOrder/create` → `data.orderId` | ✅ 已接入 |
| 订单详情 | `POST /v1/saleOrder/findOne` | ⬜ |
| 订单列表 | `GET /v1/saleOrder/findByPage` | ⬜ |
| 订单取消 | `POST /v1/saleOrder/cancel`(`orderId` + `orderNo` 都必填) | ⬜ |
| 订单上传附件 | `POST /v1/saleOrder/createAttachment` | ⬜ |
| 物流异动单 创建 / 查询 / 取消 | `POST /v1/trackingChange/create`、`POST /v1/saleOrder/findOrder`、`POST /v1/trackingChange/cancel` | ⬜ |
接查询 / 取消时要注意:
- `orderStatusEnum` 取值:`pending / unshipped / approved / assigned / picked / shipped / canceled / refunded`
——与运去哪**同名但不同源**,必须各建一套平台枚举,精确匹配、未知归 UNKNOWN。
- 取消接口需要**创建时由仓方返回的 `orderId`**(`findByPage` 也回 `orderId`),
只给单号不行。
- `attachInfoItems.type`:`0` ShippingLabel / `1` PackingList / `2` BOL / `3` Other / `4` CartonLabel /
`5` PalletLabel / `6` itemlabel。`url` 与 `file`(base64) 二选一。
### 库存(`INVENTORY_QUERY`)
| 接口 | 路径 |
|---|---|
| 查询库存(按 SKU) | `POST /v1/inventory/getInventory`(`skus` 必填) |
| 批量查询库存(分页) | `GET /v2/inventory/get_inventory_by_page` |
| 批次库存查询 | `POST v1/inventory/batch/getInventoryBatchByWarehouseCode`(⚠ 文档少了前导 `/`) |
| 库存批次快照 | `POST /v1/inventory/batch/getInventoryBatchSnapshotByPage` |
| 库存变动明细(流水) | `POST /v1/inventory/task/query`(该页要求 `Authorization: Bearer`,见冲突 #2) |
库存字段:`inventoryType`(0 可售 / 1 不可售)、`inventoryAvailable`、`inventoryReserved`、
`inventoryTransport`、`inventoryCurrent`、`updatedAt`。注意 `inventoryTransport` 与
`inventoryCurrent` 文档标成 STRING,数量类最终要转 int。
### 商品(`PRODUCT`)
| 接口 | 路径 | 状态 |
|---|---|---|
| 创建 / 编辑产品 | `POST /v1/product/save` | ✅ 已接入 |
| 查询 sku | `POST /v1/product/getBySku` | ⬜ |
| 分页查询 SKU / 产品打托信息 | `POST /v2/product/queryPage` | ⬜ |
| 渠道产品关系查询 | `GET /v1/productChannel/findByPage` | ⬜ |
| 创建产品识别码 | `POST /v1/product/createProductAlias` | ⬜ |
尺寸 cm / 重量 g,与统一模型一致(不需要换算)。
保存接口的字段口径见上一节。注意《查询 sku》页把「产品长」写作 `itemLength`,
而《创建/编辑产品》页写作 `length`——**两页对同一概念用了不同字段名**,
接查询接口时必须真机确认哪个才是产品长(见风险表 #7)。
### 入库(`INBOUND`)
入库计划创建 / 列表 / 查询 / 取消 / 加附件 / 上传附件 / 发运 / 更新到仓日期 / 生成箱标,
预约单创建 / 修改 / 取消 / 信息查询 / 日期查询。路径以 `/v1/inbound/...`、`/v3/booking_order/...` 为主。
### 调拨 / 退货 / 销毁 / 计费 / 测算
| 领域 | 规模 |
|---|---|
| 调拨 | 创建 / 查询 / 取消 / 上传附件(`/v1/transferPlan/...`) |
| 退货 | 旧版 3 个(标「废弃」)+ v2 10 个(`/v1/saleReturn/...`、`/v3/hj_wms/receiptReturn`) |
| 销毁 | 创建 / 取消 / 批量查询(`/v2/destroyPlanOrder/...`) |
| 计费 | 尾程配送费 / 仓储费明细 / 作业费账单明细 |
| 测算 | 测算费用 `/v2/api/shipping/calculate`、地址属性 `/v2/api/shipping/addressClassification`(⚠ 域名可疑) |
## 4. 代码结构
```
warehouse-sdk-hengjian/
├── pom.xml
└── src/
├── main/java/common/ecommerce/hengjian/
│ ├── HengjianConstants.java 端点 / 路径 / 两个授权头 / 成功码 / 未授权码 / 限流
│ ├── adapter/
│ │ ├── HengjianAdapter.java 目录 + 渠道 + 商品保存 + 出库下单
│ │ ├── HengjianAdapterFactory.java
│ │ ├── HengjianDirectoryMapper.java 仓库 / 渠道字段搬运
│ │ ├── HengjianProductMapper.java 商品报文 + 恒健必填项本地校验
│ │ └── HengjianOutboundMapper.java 出库下单报文(UTC 时间 / 行总额 / 面单附件)
│ ├── dto/
│ │ ├── HengjianWarehouseDtos.java
│ │ ├── HengjianCarrierGroupDtos.java 两个渠道接口共用行模型
│ │ ├── HengjianProductSaveDtos.java /v1/product/save
│ │ └── HengjianCreateOrderDtos.java /v1/saleOrder/create
│ ├── enums/package-info.java 状态枚举约定(待建)
│ ├── http/
│ │ ├── HengjianRequestFactory.java 双授权头 + 链路 ID
│ │ ├── HengjianEnvelope.java 三种形态信封校验
│ │ └── HengjianRateLimiter.java
│ └── webhook/package-info.java 文档无回调,未实现
└── test/java/common/ecommerce/hengjian/
├── adapter/HengjianDirectoryTest.java 13 个:请求形状 / 鉴权头 / 映射 / 能力位
├── adapter/HengjianProductSaveTest.java 20 个:必填拒绝 / 三组尺寸 / 不编造字段
├── adapter/HengjianCreateOrderTest.java 23 个:必填拒绝 / UTC 时间 / 行总额 / 面单 / 未接入拒绝
├── adapter/HengjianAdapterTest.java 5 个:注册 / 能力拒绝 / 枚举
├── http/HengjianEnvelopeTest.java 11 个:三种信封形态 + 错误路径
├── probe/HengjianReadOnlyProbeTest.java 默认跳过,凭据走系统属性
└── probe/HengjianWriteProbeTest.java 默认跳过,另需 -Dhengjian.probe.write=true
```
已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(74 个 + 2 个跳过)。
## 5. 探针用法
只读探针:
```bash
mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
-Dhengjian.probe=true \
-Dhengjian.probe.token=<组织token> \
-Dhengjian.probe.providerWarehouseId=EFCA \
-Dtest=HengjianReadOnlyProbeTest test
```
- 默认跳过;token 不入库、只走系统属性。
- 4 个用例:仓库目录 / 全量渠道 / 按仓渠道 / 承运商代码去重。异常只打印不中断。
- 只读,不建单。
写探针(会留下真实数据):
```bash
mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
-Dhengjian.probe=true -Dhengjian.probe.write=true \
-Dhengjian.probe.token=<组织token> \
-Dhengjian.probe.sku=PROBE-SKU-001 \
-Dhengjian.probe.postcode=90001 \
-Dtest=HengjianWriteProbeTest test
```
- 两个开关同时打开才跑;SKU 默认带时间戳,重跑不撞唯一约束。
- 3 个用例:建商品、同 SKU 再存一次(验证保存语义是否幂等)、建销售发货单
(需额外给 `-Dhengjian.probe.postcode`;可选 `carrierCode` / `shopName` / `state` / `city`)。
- **恒健没有删除产品的接口**,跑完需要人工在 Efulfill 后台清理;
建单探针也不自动取消——取消接口尚未接入。
## 6. 待确认(交给业务方 / 恒健)
| # | 要确认 | 影响 |
|---|---|---|
| 1 | **有效 token 与测试仓代码** | 没有就无法跑探针,后续接口一律「未验证」 |
| 2 | 两个授权头是否必须同时带、是否同值 | 决定 `HengjianRequestFactory` 能否精简 |
| 3 | 新约定(`Authorization: Bearer`)与旧双头是否二选一 | 冲突 #2,决定后续接口按哪套实现 |
| 4 | **是否有回调(Webhook)文档** | 没有回调就只能轮询订单状态 |
| 5 | 限流值、单日配额 | 现在是保守默认 2 req/s |
| 6 | 能否在 PR 环境走写操作(建单 / 取消) | 决定全链路探针怎么设计 |
| 7 | 计费 / 测算接口的真实域名 | 文档写的是 `ehenglin.com` / `thebizark.com` |
| 8 | 商品「产品长」到底是 `length` 还是 `itemLength` | 《创建/编辑产品》写 `length`、《查询 sku》写 `itemLength`;接查询接口前必须确认,否则尺寸错位 |
| 9 | 是否有沙箱测试 SKU | 建单需要仓方系统里真实存在的 SKU(运去哪的 `lineCode` 就踩过这个坑) |
| 10 | 时区口径 | 文档多处写 UTC,但仓在美国;需真机确认返回的时间到底是不是 UTC |
| 11 | 建单的 `channelAccount` 是否必填 | 两页文档都标「否」,但写的是「必须在 Efulfill 店铺管理中维护」;未给时仓方按什么路由需真机确认 |
| 12 | `isPrime` 的真实类型 | 文档类型列写 STRING,请求示例却是数字 `0`;适配器按示例发 Integer,真机报类型错就问仓方 |
| 13 | 签收类型能否区分成人 / 间接签收 | 统一模型只有布尔,目前全部映射成「直接签收(1)」;业务若需要 2 / 3,要在 `OutboundCommand` 上加行级签收类型 |
## 7. 下一步
1. 拿到 token 后跑 `HengjianReadOnlyProbeTest` 与 `HengjianWriteProbeTest`,把结论补进本文档
「文档与实际不一致」表;重点验商品保存的必填组合、保存语义、建单的必填组合与 `orderId` 回传。
2. 按 [onboarding-checklist.md](../onboarding-checklist.md) 阶段 2 逐接口接入,建议顺序:
**出库详情 / 列表 / 取消 → 库存(按 SKU + 分页)→ 商品查询 → 入库 → 退货 v2**。
3. 每个写接口接入前先确认第 6 节的 1 / 6 / 9 三项,否则写接口只能停在「有代码、未验证」。
4. 出库状态枚举按 `orderStatusEnum` 全量建(8 个值),未知归 `UNKNOWN`,原值进 `rawStatus`;
注意 `unshipped` / `shipped` 必须精确匹配,不能用 `contains("SHIP")`。

6
pom.xml

@ -35,6 +35,7 @@ @@ -35,6 +35,7 @@
<module>warehouse-sdk-yqn</module>
<module>warehouse-sdk-xincang</module>
<module>warehouse-sdk-edayun</module>
<module>warehouse-sdk-hengjian</module>
</modules>
<dependencyManagement>
@ -74,6 +75,11 @@ @@ -74,6 +75,11 @@
<artifactId>warehouse-sdk-xincang</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>ecommerce</groupId>
<artifactId>warehouse-sdk-hengjian</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>com.squareup.okhttp3</groupId>

2
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseProvider.java

@ -18,6 +18,8 @@ public enum WarehouseProvider { @@ -18,6 +18,8 @@ public enum WarehouseProvider {
EDAYUN(30, "易达云"),
/** 领星 WMS:预留,本期不实现 */
LINGXING(40, "领星WMS"),
/** 恒健(Efulfill) */
HENGJIAN(50, "恒健"),
/** 其他自建/直连仓 */
CUSTOM(90, "自建仓");

49
warehouse-sdk-hengjian/pom.xml

@ -0,0 +1,49 @@ @@ -0,0 +1,49 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>ecommerce</groupId>
<artifactId>channel-sdk-parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
</parent>
<artifactId>warehouse-sdk-hengjian</artifactId>
<description>恒健(HengJian / Efulfill)三方仓适配器(3PL 仓储履约)</description>
<dependencies>
<dependency>
<groupId>ecommerce</groupId>
<artifactId>sdk-common</artifactId>
</dependency>
<dependency>
<groupId>ecommerce</groupId>
<artifactId>warehouse-sdk-core</artifactId>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
</dependency>
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp</artifactId>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
</dependency>
<dependency>
<groupId>ecommerce</groupId>
<artifactId>warehouse-sdk-testkit</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
</project>

96
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java

@ -0,0 +1,96 @@ @@ -0,0 +1,96 @@
package common.ecommerce.hengjian;
/**
* 恒健(HengJian / Efulfill)协议常量。
*
* <p>端点与路径是<b>协议的一部分</b>,写在代码里,不做成配置表。
* 运行时不使用 {@link #TEST_BASE_URL}:端点由调用方每次经
* {@code WarehouseConnection} 传入。</p>
*
* <p>依据恒健语雀《OpenAPI接口文档》(book tvzvkk,2026-11 核对)。
* 该文档单篇接口页里<b>没有</b>写鉴权细节,鉴权只在《基础API调用》一页,
* 且写了两个都叫「授权Token」的请求头。</p>
*/
public final class HengjianConstants {
/** 适配器标识。 */
public static final String ADAPTER_ID = "hengjian";
/**
* 测试 / 联调环境基址。
*
* <p>文档写的是 {@code https://pr-open-api.ehengjian.com},末尾不带斜杠,
* 与 {@code WarehouseConnection} 的归一化一致,路径直接以 {@code /} 开头拼接。</p>
*/
public static final String TEST_BASE_URL = "https://pr-open-api.ehengjian.com";
/** 生产环境基址;运行时不使用,调用方需要时自己传。 */
public static final String PRODUCTION_BASE_URL = "https://open-api.ehengjian.com";
/**
* 授权请求头 1:{@code Authorization}。
*
* <p>文档把 {@code Authorization} 与 {@code x-api-key} 两个头都标成「授权Token」,
* 且都标「必须」,所以两个都带、取值相同(复用 {@code ChannelSecret.appSecret()})。</p>
*
* <p><b>真机尚不能确认是否可以只带一个</b>:用一个无效 token 试过,
* 只带一个和两个都带都返回 500「未知的账户!」,区分不出是哪个头在起作用。
* 拿到有效 token 后应补一次对照实验,再决定能否精简。</p>
*/
public static final String AUTHORIZATION_HEADER = "Authorization";
/** 授权请求头 2:{@code x-api-key};取值同 {@link #AUTHORIZATION_HEADER}。 */
public static final String API_KEY_HEADER = "x-api-key";
/** 获取当前组织仓库(无参数)。 */
public static final String PATH_WAREHOUSE_LIST = "/v2/warehouse/getWarehouse";
/** 获取物流渠道(无参数):全部承运商服务的扁平清单。 */
public static final String PATH_CARRIER_GROUP = "/v2/carrierGroup/getCarrierGroup";
/** 获取仓库支持的物流渠道:按仓代码过滤。 */
public static final String PATH_WAREHOUSE_CARRIER_GROUP =
"/v2/carrierGroup/getWarehouseCarrierGroupServices";
/**
* 创建 / 编辑产品。
*
* <p>接口是保存语义(同一 SKU 再调即更新),响应只有 {@code code/message},没有 data。</p>
*/
public static final String PATH_PRODUCT_SAVE = "/v1/product/save";
/**
* 创建销售发货单。
*
* <p>响应回 {@code data.orderId}(仓内部数字 id);取消时 {@code orderId} 与
* {@code orderNo} 都要,所以调用方必须落库这个 id。</p>
*/
public static final String PATH_ORDER_CREATE = "/v1/saleOrder/create";
/** 业务成功码;文档各接口一致写 {@code 200}。 */
public static final int SUCCESS_CODE = 200;
/**
* 未授权 / 未知账户的业务码。
*
* <p><b>真机观察</b>(2026-11-12,测试环境):不带任何授权头请求
* {@code /v2/warehouse/getWarehouse},HTTP 仍是 <b>200</b>,body 是
* {@code {"statusCode":500,"status":1,"code":999999,"message":"查询失败Unauthorized"}}。
* 带上任意一个头(值无效)时则返回 Spring 的 500 错误页
* {@code {"status":500,...,"message":"未知的账户!"}}。</p>
*
* <p>因此这个码必须按<b>认证失败</b>处理,不能当普通业务失败——否则宿主只会看到
* 一条「业务码非 200」,不会去刷新凭据。</p>
*/
public static final int UNAUTHORIZED_CODE = 999999;
/**
* 限流:每秒许可数。
*
* <p>恒健文档未公开限流值,先按三家仓的保守默认 2 req/s/仓;联调确认后只改这一处。</p>
*/
public static final int PERMITS_PER_SECOND = 2;
private HengjianConstants() {
}
}

358
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java

@ -0,0 +1,358 @@ @@ -0,0 +1,358 @@
package common.ecommerce.hengjian.adapter;
import com.fasterxml.jackson.databind.JsonNode;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.hengjian.dto.HengjianCarrierGroupDtos;
import common.ecommerce.hengjian.dto.HengjianCreateOrderDtos;
import common.ecommerce.hengjian.dto.HengjianProductSaveDtos;
import common.ecommerce.hengjian.dto.HengjianWarehouseDtos;
import common.ecommerce.hengjian.http.HengjianEnvelope;
import common.ecommerce.hengjian.http.HengjianRateLimiter;
import common.ecommerce.hengjian.http.HengjianRequestFactory;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.HttpTransport;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.capability.LogisticsProductCapable;
import common.ecommerce.warehouse.capability.OutboundCapable;
import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.enums.CancelEligibility;
import common.ecommerce.warehouse.enums.LabelMode;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.error.WarehouseException;
import common.ecommerce.warehouse.model.CancelCommand;
import common.ecommerce.warehouse.model.CancelResult;
import common.ecommerce.warehouse.model.LogisticsProduct;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundOrder;
import common.ecommerce.warehouse.model.OutboundQuery;
import common.ecommerce.warehouse.model.OutboundReceipt;
import common.ecommerce.warehouse.model.OutboundRef;
import common.ecommerce.warehouse.model.PackageResult;
import common.ecommerce.warehouse.model.WarehouseFacility;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import java.util.ArrayList;
import java.util.EnumSet;
import java.util.Iterator;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* 恒健适配器。
*
* <p><b>已接入</b>:仓库目录、承运商 / 物流产品、按仓的物流渠道(只读),
* 以及商品创建 / 编辑({@code /v1/product/save},保存语义)。</p>
*
* <p>出库 / 库存 / 入库 / 退货等接口<b>尚未接入</b>,能力位不声明:
* 门面调用会显式抛 {@code WarehouseUnsupportedCapabilityException},不返回空集合。</p>
*
* <p>适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经
* {@code WarehouseConnection} 传入。</p>
*/
public final class HengjianAdapter implements WarehouseDirectoryCapable, LogisticsProductCapable,
WarehouseProductCapable, OutboundCapable {
private static final String OP_WAREHOUSE_LIST = "warehouse.directory.warehouses";
private static final String OP_CARRIERS = "warehouse.directory.carriers";
private static final String OP_LOGISTICS_PRODUCTS = "warehouse.logistics.products";
private static final String OP_PRODUCT_SAVE = "warehouse.product.create";
private static final String OP_ORDER_CREATE = "warehouse.outbound.create";
/** 保存语义没有 create / update 之分,仓方也不回是哪种。 */
private static final String SAVED = "SAVED";
private final HttpTransport transport;
private final JacksonJsonCodec json;
private final HengjianRequestFactory requestFactory;
private final HengjianRateLimiter rateLimiter;
public HengjianAdapter(HttpTransport transport, JacksonJsonCodec json) {
this.transport = transport;
this.json = json;
this.requestFactory = new HengjianRequestFactory(json);
this.rateLimiter = new HengjianRateLimiter();
}
@Override
public String adapterId() {
return HengjianConstants.ADAPTER_ID;
}
@Override
public WarehouseProvider provider() {
return WarehouseProvider.HENGJIAN;
}
@Override
public EnumSet<WarehouseCapability> capabilities() {
return EnumSet.of(
WarehouseCapability.PRODUCT,
WarehouseCapability.OUTBOUND,
WarehouseCapability.PLATFORM_LABEL_DELIVERY,
WarehouseCapability.DIRECTORY,
WarehouseCapability.LOGISTICS_PRODUCT);
}
// ------------------------------------------------------------------ 出库
/**
* 创建销售发货单({@code POST /v1/saleOrder/create})。
*
* <p>承接 {@code WarehouseOutbounds.create} 的幂等守卫:同一
* {@code outboundRequestNo} 重复下发由门面拦住,这里只负责拼报文与解析。</p>
*
* <p>响应只回 {@code data.orderId}(<b>仓内部数字 id</b>,不是字符串单号)。
* 恒健的取消接口同时要 {@code orderId} 与 {@code orderNo},所以这个 id
* 必须随 {@link OutboundReceipt#providerOrderId()} 落库;缺了它后续取消做不了,
* 因此拿不到就报错,<b>不静默当成创建成功</b>。</p>
*/
@Override
public OutboundReceipt create(WarehouseContext ctx, OutboundCommand cmd) {
requirePlatformLabelSupported(cmd);
String warehouseCode = HengjianOutboundMapper.resolveWarehouseCode(
cmd.warehouseId(), ctx.providerWarehouseId());
HengjianCreateOrderDtos.CreateOrderRequest body =
HengjianOutboundMapper.toRequest(cmd, warehouseCode, ctx.clock());
String raw = execute(ctx, HengjianConstants.PATH_ORDER_CREATE, body, OP_ORDER_CREATE);
HengjianCreateOrderDtos.CreateOrderResponse resp =
json.fromJson(raw, HengjianCreateOrderDtos.CreateOrderResponse.class);
if (resp == null || resp.data == null || resp.data.orderId == null) {
throw WarehouseException.builder()
.message("hengjian create order returned no data.orderId: " + safeRelay(raw))
.operation(OP_ORDER_CREATE)
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.retryable(false)
.rawResponse(safeRelay(raw))
.build();
}
return OutboundReceipt.of(cmd.outboundRequestNo(), String.valueOf(resp.data.orderId),
resp.message);
}
/** 恒健出库查询尚未接入:显式拒绝,不返回 null 让调用方以为「仓说没有这单」。 */
@Override
public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) {
throw unsupportedOutbound("warehouse.outbound.get", ctx);
}
@Override
public Page<OutboundOrder> query(WarehouseContext ctx, OutboundQuery query) {
throw unsupportedOutbound("warehouse.outbound.query", ctx);
}
@Override
public CancelEligibility checkCancel(WarehouseContext ctx, OutboundRef ref) {
throw unsupportedOutbound("warehouse.outbound.checkCancel", ctx);
}
@Override
public CancelResult cancel(WarehouseContext ctx, CancelCommand cmd) {
throw unsupportedOutbound("warehouse.outbound.cancel", ctx);
}
@Override
public List<PackageResult> packages(WarehouseContext ctx, OutboundRef ref) {
throw unsupportedOutbound("warehouse.outbound.packages", ctx);
}
/**
* 平台面单必须真的带文件。
*
* <p>恒健的面单就是 {@code attachInfoItems} 里的一条附件;声明了
* {@code PLATFORM_LABEL_DELIVERY} 却不给文件,仓没有面单可打,等于静默失败。</p>
*/
private static void requirePlatformLabelSupported(OutboundCommand cmd) {
if (cmd.labelMode() == LabelMode.PLATFORM_LABEL
&& (cmd.labelContentBase64() == null || cmd.labelContentBase64().trim().isEmpty())) {
throw new IllegalArgumentException(
"labelContentBase64 is required when labelMode=PLATFORM_LABEL for "
+ cmd.outboundRequestNo());
}
}
private WarehouseException unsupportedOutbound(String operation, WarehouseContext ctx) {
return WarehouseException.builder()
.message("hengjian does not implement " + operation + " yet")
.operation(operation)
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.retryable(false)
.build();
}
/** 原始响应可能含 PII,异常里只留短片段。 */
private static String safeRelay(String raw) {
if (raw == null) {
return null;
}
return raw.length() <= 300 ? raw : raw.substring(0, 300) + "...";
}
// ------------------------------------------------------------------ 商品
/**
* 创建 / 编辑商品({@code POST /v1/product/save})。
*
* <p>接口是<b>保存语义</b>:同一 SKU 再调即更新,所以不区分 create 与 update,
* 也不像信仓那样先查一次再决定调哪个接口。</p>
*
* <p>响应只有 {@code code / message},<b>没有 data</b>,因此结果里的
* {@code status} 固定为 {@code SAVED}、{@code rawStatus} 取仓方的 message——
* 仓方并不告诉我们这次是新建还是更新,不能替它编。</p>
*
* @throws IllegalArgumentException 恒健要求但统一模型未给的非空字段缺失(本地拒绝)
*/
@Override
public ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product) {
HengjianProductSaveDtos.SaveProductRequest body = HengjianProductMapper.toRequest(product);
String raw = execute(ctx, HengjianConstants.PATH_PRODUCT_SAVE, body, OP_PRODUCT_SAVE);
return ProductResult.of(body.sku, SAVED, json.stringAt(raw, "message"));
}
// ------------------------------------------------------------------ 仓库目录
/**
* 当前组织下的全部仓库({@code POST /v2/warehouse/getWarehouse},无参数)。
*
* <p>返回的 {@code warehouseCode} 可直接用于下单、库存查询等接口。</p>
*/
@Override
public List<WarehouseFacility> warehouses(WarehouseContext ctx) {
String raw = execute(ctx, HengjianConstants.PATH_WAREHOUSE_LIST, null, OP_WAREHOUSE_LIST);
List<HengjianWarehouseDtos.WarehouseRow> rows =
json.listAt(raw, "data", HengjianWarehouseDtos.WarehouseRow.class);
return HengjianDirectoryMapper.toWarehouses(rows);
}
/**
* 承运商 / 物流方式代码({@code POST /v2/carrierGroup/getCarrierGroup},无参数)。
*
* <p>返回物流产品代码(如 {@code UPS2DAM_HL}),可直接作为下单的 {@code carrierCode}。
* 按出现顺序去重。</p>
*/
@Override
public List<String> carriers(WarehouseContext ctx) {
return codesOf(fetchAllServices(ctx));
}
/**
* 物流产品清单({@code POST /v2/carrierGroup/getCarrierGroup})。
*
* <p>恒健这个接口<b>没有仓维度</b>,拿到的是组织级清单;{@code warehouseCode}
* 仅用于写进结果字段,便于调用方区分来源。需要「某仓支持哪些渠道」用
* {@link #productsOfWarehouse}。</p>
*/
@Override
public List<LogisticsProduct> products(WarehouseContext ctx, String warehouseCode) {
return HengjianDirectoryMapper.toProducts(fetchAllServices(ctx), resolveWarehouseCode(ctx, warehouseCode));
}
/**
* 查询「某仓支持哪些物流渠道」({@code POST
* /v2/carrierGroup/getWarehouseCarrierGroupServices})。
*
* <p>返回形状与 {@link #products} 不同:{@code data} 是以仓代码为键的对象,
* 不是数组;只取请求的那个仓,混进别的仓的渠道会让「仓不支持该渠道」
* 变成仓方报错。</p>
*/
public List<LogisticsProduct> productsOfWarehouse(WarehouseContext ctx, String warehouseCode) {
String code = resolveWarehouseCode(ctx, warehouseCode);
if (code == null) {
throw new IllegalArgumentException(
"hengjian warehouse carrier services need a warehouseCode; none given and account has none");
}
List<String> codes = new ArrayList<String>();
codes.add(code);
Map<String, Object> body = new LinkedHashMap<String, Object>();
body.put("warehouseCodes", codes);
String raw = execute(ctx, HengjianConstants.PATH_WAREHOUSE_CARRIER_GROUP, body,
OP_LOGISTICS_PRODUCTS);
return HengjianDirectoryMapper.toProducts(servicesOfWarehouse(raw, code), code);
}
// ------------------------------------------------------------------ 内部
private List<HengjianCarrierGroupDtos.CarrierServiceRow> fetchAllServices(WarehouseContext ctx) {
String raw = execute(ctx, HengjianConstants.PATH_CARRIER_GROUP, null, OP_CARRIERS);
return json.listAt(raw, "data", HengjianCarrierGroupDtos.CarrierServiceRow.class);
}
/** {@code data} 是 {@code 仓代码 → 服务数组} 的对象;只取指定仓。 */
private List<HengjianCarrierGroupDtos.CarrierServiceRow> servicesOfWarehouse(String raw, String warehouseCode) {
List<HengjianCarrierGroupDtos.CarrierServiceRow> rows =
new ArrayList<HengjianCarrierGroupDtos.CarrierServiceRow>();
JsonNode data = json.nodeAt(raw, "data");
if (data == null || !data.isObject()) {
return rows;
}
JsonNode node = data.get(warehouseCode);
if (node == null || !node.isArray()) {
return rows;
}
Iterator<JsonNode> it = node.elements();
while (it.hasNext()) {
rows.add(json.mapper().convertValue(it.next(),
HengjianCarrierGroupDtos.CarrierServiceRow.class));
}
return rows;
}
/** 显式仓代码优先,否则用账户配置的;都没有返回 null,由调用方决定是否拒绝。 */
private static String resolveWarehouseCode(WarehouseContext ctx, String warehouseCode) {
if (warehouseCode != null && !warehouseCode.trim().isEmpty()) {
return warehouseCode.trim();
}
String configured = ctx.providerWarehouseId();
return configured == null || configured.trim().isEmpty() ? null : configured.trim();
}
private static List<String> codesOf(List<HengjianCarrierGroupDtos.CarrierServiceRow> rows) {
List<String> out = new ArrayList<String>();
if (rows == null) {
return out;
}
for (HengjianCarrierGroupDtos.CarrierServiceRow row : rows) {
if (row == null || row.code == null || row.code.trim().isEmpty()) {
continue;
}
String code = row.code.trim();
if (!out.contains(code)) {
out.add(code);
}
}
return out;
}
/**
* 发请求并校验信封。
*
* @param body null 表示无参数接口,发送空 JSON 对象
*/
private String execute(WarehouseContext ctx, String path, Object body, String operation) {
rateLimiter.acquire(path, HengjianConstants.PERMITS_PER_SECOND);
HttpRequest req = requestFactory.post(ctx.endpointBaseUrl(), path, body, ctx.secret(), ctx, operation);
HttpResponse resp = transport.execute(req);
String raw = HengjianEnvelope.of(resp, json, operation, ctx.warehouseCode(), ctx.requestId()).body();
if (raw == null || raw.trim().isEmpty()) {
throw WarehouseException.builder()
.message("hengjian " + operation + " returned an empty body")
.operation(operation)
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.retryable(true)
.build();
}
return raw;
}
}

35
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapterFactory.java

@ -0,0 +1,35 @@ @@ -0,0 +1,35 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.http.OkHttpTransport;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.sdk.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseAdapterFactory;
/**
* 恒健适配器工厂。
*
* <p>端点与凭据由调用方在每次请求时传入,工厂只装配协议与基础设施。
* 恒健是组织级固定 token(两个请求头),没有换取 / 续约流程,所以不需要
* {@code TokenStore} / {@code LockProvider}——与运去哪同构,与信仓不同。</p>
*/
public final class HengjianAdapterFactory implements WarehouseAdapterFactory {
@Override
public String adapterId() {
return HengjianConstants.ADAPTER_ID;
}
@Override
public WarehouseProvider provider() {
return WarehouseProvider.HENGJIAN;
}
@Override
public WarehouseAdapter create(AdapterConfig config) {
return new HengjianAdapter(
new OkHttpTransport("common-ecommerce/1.0.0 (hengjian)"),
new JacksonJsonCodec());
}
}

106
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianDirectoryMapper.java

@ -0,0 +1,106 @@ @@ -0,0 +1,106 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.dto.HengjianCarrierGroupDtos;
import common.ecommerce.hengjian.dto.HengjianWarehouseDtos;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.LogisticsProduct;
import common.ecommerce.warehouse.model.WarehouseFacility;
import java.util.ArrayList;
import java.util.List;
/**
* 恒健仓库档案与物流渠道映射。
*
* <p>只做字段搬运,不发请求、不读配置。</p>
*/
public final class HengjianDirectoryMapper {
private HengjianDirectoryMapper() {
}
/**
* 仓库行 → 统一仓库档案。
*
* <p>恒健文档的仓对象<b>没有联系人、电话、邮箱字段</b>(运去哪 / 信仓有),
* 所以 {@code contactName / mobilePhone / email} 恒为 null——这是平台限制,
* 不是漏接。</p>
*/
public static List<WarehouseFacility> toWarehouses(List<HengjianWarehouseDtos.WarehouseRow> rows) {
List<WarehouseFacility> out = new ArrayList<WarehouseFacility>();
if (rows == null) {
return out;
}
for (HengjianWarehouseDtos.WarehouseRow row : rows) {
if (row == null || blank(row.warehouseCode)) {
// 没有仓代码的行没法下单,跳过而不是造一条空档案
continue;
}
out.add(WarehouseFacility.builder()
.sourceProvider(WarehouseProvider.HENGJIAN)
.warehouseCode(row.warehouseCode.trim())
.name(trimToNull(row.name))
.country(trimToNull(row.country))
.state(trimToNull(row.state))
.province(trimToNull(row.state))
.city(trimToNull(row.city))
.address1(trimToNull(row.address1))
.address2(trimToNull(row.address2))
.postcode(trimToNull(row.postal))
.build());
}
return out;
}
/**
* 承运商服务行 → 统一物流产品。
*
* <p>{@code logisticsProductCode} 取恒健的 {@code code}(下单的 {@code carrierCode}),
* 名称拼成「承运商 + 服务名」——恒健把承运商和服务分在两列,统一模型只有一个名称字段。</p>
*
* <p>{@code crossCountry} 恒为 false:恒健文档没有这个维度,<b>不是</b>「不支持跨国」。</p>
*
* @param warehouseCode 仓代码;全量渠道接口没有这个维度时传 null
*/
public static List<LogisticsProduct> toProducts(
List<HengjianCarrierGroupDtos.CarrierServiceRow> rows, String warehouseCode) {
List<LogisticsProduct> out = new ArrayList<LogisticsProduct>();
if (rows == null) {
return out;
}
for (HengjianCarrierGroupDtos.CarrierServiceRow row : rows) {
if (row == null || blank(row.code)) {
continue;
}
out.add(LogisticsProduct.builder()
.sourceProvider(WarehouseProvider.HENGJIAN)
.warehouseCode(trimToNull(warehouseCode))
.logisticsProductCode(row.code.trim())
.logisticsProductName(displayName(row))
.crossCountry(false)
.build());
}
return out;
}
/** 「承运商 - 服务名」;缺哪个就只用另一个,都没有给 null。 */
public static String displayName(HengjianCarrierGroupDtos.CarrierServiceRow row) {
String carrier = trimToNull(row.carrier);
String service = trimToNull(row.carrierServiceName);
if (carrier == null) {
return service;
}
if (service == null) {
return carrier;
}
return carrier + " - " + service;
}
static boolean blank(String v) {
return v == null || v.trim().isEmpty();
}
private static String trimToNull(String v) {
return blank(v) ? null : v.trim();
}
}

243
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOutboundMapper.java

@ -0,0 +1,243 @@ @@ -0,0 +1,243 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.dto.HengjianCreateOrderDtos;
import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.enums.LabelMode;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundLine;
import common.ecommerce.warehouse.model.ShipTo;
import java.math.BigDecimal;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 恒健出库报文映射({@code POST /v1/saleOrder/create})。
*
* <p>平台字段名只出现在本类与 {@link HengjianCreateOrderDtos}。</p>
*
* <h2>时间</h2>
* <p>恒健的时间字段是 <b>UTC</b> 的 {@code yyyy-MM-dd HH:mm:ss}(文档明确写了 utc 时间),
* 所以格式化固定按 {@link ZoneOffset#UTC},<b>不用</b> {@code WarehouseContext.zone()}——
* 那个时区是给「仓方回传的无时区本地时间」用的,方向相反。</p>
*
* <h2>必填项</h2>
* <p>{@code createdAt} 在统一模型里没有对应字段,用调用方注入的 {@link Clock} 生成
* 「下单时刻」。这是请求侧的时间戳,不是把仓方没给的数据编出来;
* 幂等重放时它会变,但恒健不拿它做去重。</p>
*
* <h2>统一模型里恒健没有对应概念的字段</h2>
* <table border="1">
* <tr><th>字段</th><th>处理</th></tr>
* <tr><td>{@code salesPlatform}</td>
* <td>恒健没有平台维度,店铺路由走 {@code channelAccount}。<b>不发</b>,
* 也不拿它去推断 {@code isDFOrder}——VC 订单里只有一部分是 DF。</td></tr>
* <tr><td>{@code splitOrder} / {@code packages}</td>
* <td>恒健没有拆单入参与包裹入参,忽略。</td></tr>
* <tr><td>{@code estimatedDeliveryTime}</td>
* <td>恒健只有 {@code expectedShipDate}(要求发货时间),没有送达时间。</td></tr>
* <tr><td>{@code declaredTotal}</td>
* <td>恒健按行收金额,没有整单申报额。</td></tr>
* </table>
*/
public final class HengjianOutboundMapper {
/** 恒健只接受 UTC 的 {@code yyyy-MM-dd HH:mm:ss}。 */
private static final DateTimeFormatter TIME_FORMAT =
DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
/** 附件类型:面单。 */
private static final String ATTACH_TYPE_SHIPPING_LABEL = "0";
/** 保价 / 签收开关的取值。 */
private static final int FLAG_NO = 0;
private static final int FLAG_YES = 1;
/** 唯一支持的签收类型:直接签收(成人 / 间接签收统一模型表达不了)。 */
private static final int SIGNATURE_DIRECT = 1;
private HengjianOutboundMapper() {
}
/**
* 统一命令 → 恒健创建订单请求。
*
* @param warehouseCode 仓代码(命令显式指定优先,其次账户配置);null 时由仓方按默认仓处理
* @param clock 用于生成必填的 {@code createdAt}
* @throws IllegalArgumentException 缺少恒健必填但统一模型可空的字段
*/
public static HengjianCreateOrderDtos.CreateOrderRequest toRequest(OutboundCommand cmd,
String warehouseCode,
Clock clock) {
HengjianCreateOrderDtos.CreateOrderRequest req = new HengjianCreateOrderDtos.CreateOrderRequest();
String orderNo = cmd.outboundRequestNo();
req.orderNo = orderNo;
req.warehouseCode = trimToNull(warehouseCode);
req.carrier = trimToNull(cmd.carrier());
req.carrierCode = trimToNull(cmd.carrierCode());
// 店铺:仓方按店铺做路由 / 计费;标准模型对应 shopName
req.channelAccount = trimToNull(cmd.shopName());
req.currency = trimToNull(cmd.currency());
req.shipServiceLevel = trimToNull(cmd.shipServiceLevel());
// 平台要求发货时间;恒健只在 isDFOrder=1 时强制,但有值就带上
req.expectedShipDate = formatTime(cmd.latestShipDate());
req.isPrime = flagOf(cmd.sfp());
req.createdAt = formatTime(Instant.now(clock));
req.customerRemark = trimToNull(cmd.remark());
ShipTo shipTo = cmd.shipTo();
req.shipToCountry = require(shipTo.countryCode(), "shipTo.countryCode", orderNo);
req.shipToState = require(shipTo.stateOrProvince(), "shipTo.stateOrProvince", orderNo);
req.shipToPostal = require(shipTo.postalCode(), "shipTo.postalCode", orderNo);
req.shipToAddress1 = require(shipTo.addressLine1(), "shipTo.addressLine1", orderNo);
req.shipToContact = require(shipTo.name(), "shipTo.name", orderNo);
req.shipToTelephone = require(shipTo.phone(), "shipTo.phone", orderNo);
// 城市:中文页标必填、英文页未标,按必填处理
req.shipToCity = require(shipTo.city(), "shipTo.city", orderNo);
req.shipToAddress2 = trimToNull(shipTo.addressLine2());
req.customerEmail = trimToNull(shipTo.email());
req.productItems = toProductItems(cmd.lines(), cmd.signatureRequired(), orderNo);
req.attachInfoItems = toAttachInfoItems(cmd, orderNo);
return req;
}
/** 仓方仓编码:命令显式指定优先,否则用账户配置。 */
public static String resolveWarehouseCode(String fromCommand, String fromAccount) {
return trimToNull(fromCommand) != null ? trimToNull(fromCommand) : trimToNull(fromAccount);
}
private static List<HengjianCreateOrderDtos.CreateOrderRequest.ProductItem> toProductItems(
List<OutboundLine> lines, Boolean signatureRequired, String orderNo) {
boolean signature = Boolean.TRUE.equals(signatureRequired);
List<HengjianCreateOrderDtos.CreateOrderRequest.ProductItem> items =
new ArrayList<HengjianCreateOrderDtos.CreateOrderRequest.ProductItem>(lines.size());
for (OutboundLine line : lines) {
HengjianCreateOrderDtos.CreateOrderRequest.ProductItem item =
new HengjianCreateOrderDtos.CreateOrderRequest.ProductItem();
item.sku = line.providerSku() != null && !line.providerSku().trim().isEmpty()
? line.providerSku().trim() : line.omsSku();
item.quantity = line.quantity();
// 保价:统一模型只有「保价金额」,有金额即视为保价
boolean insured = line.insuredAmount() != null;
item.isInsure = insured ? FLAG_YES : FLAG_NO;
if (insured) {
item.insureAmount = line.insuredAmount().amount().doubleValue();
}
// 签收:恒健的 isSignature 挂在行上,统一模型挂在命令上。
// 语义是整单都要 / 都不要,所以取命令上的值套到每一行。
// 统一模型只有布尔值,表达不了成人签收(2) / 间接签收(3),
// 统一映射成「直接签收(1)」——比静默降成「不签收(0)」安全
item.isSignature = signature ? SIGNATURE_DIRECT : FLAG_NO;
item.skuAmount = skuTotalAmount(line);
items.add(item);
}
return items;
}
/**
* 行总金额。
*
* <p>恒健 {@code skuAmount} 是「当前 SKU 总金额」,<b>不是单价</b>:
* 有 {@code totalAmount} 直接用;没有就用申报单价 × 数量,
* 否则整单金额会少算 quantity 倍(运去哪踩过同样的坑)。</p>
*/
static Double skuTotalAmount(OutboundLine line) {
Money total = line.totalAmount();
if (total != null) {
return total.amount().doubleValue();
}
Money unit = line.declareValue();
if (unit == null) {
return null;
}
return unit.amount().multiply(BigDecimal.valueOf(line.quantity())).doubleValue();
}
/**
* 附件:平台面单随单下发。
*
* <p>恒健把 {@code attachInfoItems} 标为<b>必填</b>,所以没有附件时返回空数组,
* 不省略该字段——省略会被当成缺必填项。</p>
*
* <p>仓自有面单({@link LabelMode#WAREHOUSE_LABEL})时不给附件;
* 给了面单内容却不是平台面单模式,直接拒绝,不静默丢弃。</p>
*/
private static List<HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem> toAttachInfoItems(
OutboundCommand cmd, String orderNo) {
String content = cmd.labelContentBase64();
if (content == null || content.trim().isEmpty()) {
if (cmd.labelMode() == LabelMode.PLATFORM_LABEL) {
throw new IllegalArgumentException(
"hengjian order " + orderNo
+ ": labelContentBase64 is required when labelMode=PLATFORM_LABEL");
}
return new ArrayList<HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem>();
}
if (cmd.labelMode() != LabelMode.PLATFORM_LABEL) {
throw new IllegalArgumentException(
"hengjian order " + orderNo
+ ": labelContentBase64 requires labelMode=PLATFORM_LABEL");
}
HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem item =
new HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem();
// 文档建议附件名填跟踪号且不带后缀;没有运单号时退回出库单号
String tracking = trimToNull(cmd.trackingNumber());
item.name = tracking != null ? tracking : orderNo;
// 恒健同一个字段 url / file 二选一,file 优先;文档没说 file 支持 data URI 头,
// 这里统一剥掉,避免把 "data:application/pdf;base64," 当成文件内容解出来
item.file = stripDataUri(content);
item.type = ATTACH_TYPE_SHIPPING_LABEL;
List<HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem> out =
new ArrayList<HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem>(1);
out.add(item);
return Collections.unmodifiableList(out);
}
/** 去掉 {@code data:xxx/base64,} 头;没有头时原样返回。 */
static String stripDataUri(String content) {
if (content == null) {
return null;
}
int comma = content.indexOf(',');
if (content.startsWith("data:") && comma > 0) {
return content.substring(comma + 1);
}
return content;
}
/** 时间 → 恒健的 UTC {@code yyyy-MM-dd HH:mm:ss};null 透传。 */
static String formatTime(Instant instant) {
return instant == null ? null : TIME_FORMAT.format(instant.atZone(ZoneOffset.UTC));
}
/** 布尔开关 → 0 / 1;null 不发(由仓方按默认否处理)。 */
private static Integer flagOf(Boolean flag) {
return flag == null ? null : (flag ? FLAG_YES : FLAG_NO);
}
private static String require(String value, String field, String orderNo) {
String v = trimToNull(value);
if (v == null) {
throw new IllegalArgumentException(
"hengjian order " + orderNo + " requires " + field + " (恒健下单必填)");
}
return v;
}
private static String trimToNull(String v) {
if (v == null) {
return null;
}
String trimmed = v.trim();
return trimmed.isEmpty() ? null : trimmed;
}
}

165
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductMapper.java

@ -0,0 +1,165 @@ @@ -0,0 +1,165 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.dto.HengjianProductSaveDtos;
import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.capability.WarehouseProduct;
/**
* 恒健商品报文映射({@code POST /v1/product/save})。
*
* <p>平台字段名只出现在本类与 {@link HengjianProductSaveDtos}。
* 单位与统一模型一致(cm / g),不做换算。</p>
*
* <h2>必填项在本地拒绝</h2>
* <p>恒健把 <b>产品尺寸 / 外箱尺寸 / 装箱数量 / 英文名 / 描述 / 发货包装</b> 都标为必填。
* 统一模型不强制这些(运去哪、信仓的要求各不相同),所以由本映射器按恒健的协议校验:
* 缺了直接抛 {@link IllegalArgumentException},<b>不拿其它字段顶替</b>——
* 发出去被仓方拒,排查成本比本地报错高得多。</p>
*
* <h2>不发送的字段</h2>
* <table border="1">
* <tr><th>恒健字段</th><th>为什么不发</th></tr>
* <tr><td>{@code imageUrls}</td>
* <td>文档写明是「产品测量图片」,用于复核长宽高,<b>不是商品主图</b>。
* 统一模型的 {@code imageUrl} 是商品图片,语义不同,不能拿来顶替。</td></tr>
* <tr><td>{@code isSpecialOuterPackaging}</td>
* <td>「特殊外包装」与统一模型的 {@code packageStyle}(裸包装 / 销售包装 / 物流包装)
* 不是同一套码,映射需要业务确认,暂时不发。</td></tr>
* </table>
*
* <p>统一模型里的 SN、批次、HS Code、原产国、商品链接、客退处理方式、产品品类,
* 恒健文档都没有对应字段,一律不发。</p>
*/
public final class HengjianProductMapper {
/** 保价开关的开 / 关取值(恒健用 Y / N,不是 0 / 1)。 */
private static final String INSURED_YES = "Y";
private static final String INSURED_NO = "N";
private HengjianProductMapper() {
}
/**
* 统一商品 → 恒健保存请求。
*
* @param product 已通过 {@link WarehouseProduct} 构造期校验的商品
* @throws IllegalArgumentException 恒健要求但统一模型未给的非空字段缺失
*/
public static HengjianProductSaveDtos.SaveProductRequest toRequest(WarehouseProduct product) {
String sku = skuOf(product);
HengjianProductSaveDtos.SaveProductRequest req = new HengjianProductSaveDtos.SaveProductRequest();
req.sku = sku;
req.upc = trimToNull(product.barcode());
req.productType = product.productType() > 0 ? product.productType() : null;
req.name = require(product.name(), "name", sku);
req.nameEn = require(product.nameEn(), "nameEn", sku);
req.description = require(product.description(), "description", sku);
req.packingType = requirePackingType(product, sku);
// 产品尺寸与重量:WarehouseProduct 构造期已保证为正
req.length = product.lengthCm();
req.width = product.widthCm();
req.height = product.heightCm();
req.weight = product.weightGrams();
// 外箱五项同为必填,缺一不可
req.packedLength = requirePacked(product.packedLengthCm(), "packedLengthCm", sku);
req.packedWidth = requirePacked(product.packedWidthCm(), "packedWidthCm", sku);
req.packedHeight = requirePacked(product.packedHeightCm(), "packedHeightCm", sku);
req.packedWeight = requirePacked(product.packedWeightGrams(), "packedWeightGrams", sku);
req.packedQty = requirePackedQty(product, sku);
// 单品尺寸选填;未给(0)不发
req.itemLength = positiveOrNull(product.itemLengthCm());
req.itemWidth = positiveOrNull(product.itemWidthCm());
req.itemHeight = positiveOrNull(product.itemHeightCm());
req.expirationControl = flagOf(product.expirationControl());
// 没开保质期管理就不该带天数,避免仓方按「已设保质期但未启用」存脏数据
req.expirationDate = Boolean.TRUE.equals(product.expirationControl())
? product.expirationDays() : null;
Money cost = product.cost();
if (cost != null) {
req.cost = cost.amount().doubleValue();
req.currency = cost.currency().getCurrencyCode();
}
req.isInsuranceFlag = insuranceFlag(product.insured());
if (product.insuranceFee() != null) {
req.isInsuranceRate = product.insuranceFee().amount().doubleValue();
}
req.remark = trimToNull(product.remark());
req.customName = trimToNull(product.declaredName());
req.customNameEn = trimToNull(product.declaredNameEn());
return req;
}
/** 仓侧 SKU 优先;没有映射时用 OMS 主 SKU。 */
public static String skuOf(WarehouseProduct product) {
String providerSku = product.providerSku();
if (providerSku != null && !providerSku.trim().isEmpty()) {
return providerSku.trim();
}
return product.omsSku();
}
/** 0 原包装发货 / 1 重新打包;未给(-1)在恒健是必填,直接拒绝。 */
private static Integer requirePackingType(WarehouseProduct product, String sku) {
int packingType = product.packingType();
if (packingType < 0) {
throw new IllegalArgumentException(
"hengjian product " + sku + " requires packingType (0 原包装发货 / 1 重新打包)");
}
return packingType;
}
private static Double requirePacked(Double value, String field, String sku) {
if (value == null || value <= 0) {
throw new IllegalArgumentException("hengjian product " + sku + " requires " + field
+ " (外箱尺寸与重量是必填项)");
}
return value;
}
private static Integer requirePackedQty(WarehouseProduct product, String sku) {
Integer qty = product.packedQuantity();
if (qty == null || qty <= 0) {
throw new IllegalArgumentException("hengjian product " + sku
+ " requires packedQuantity (装箱数量是必填项)");
}
return qty;
}
/** 0/1 开关 → Integer;null 不发(由仓方按默认处理)。 */
private static Integer flagOf(Boolean flag) {
return flag == null ? null : (flag ? 1 : 0);
}
/** 保价开关 → 恒健的 {@code Y / N};null 不发。 */
private static String insuranceFlag(Boolean insured) {
return insured == null ? null : (insured ? INSURED_YES : INSURED_NO);
}
private static Double positiveOrNull(double v) {
return v > 0 ? v : null;
}
private static String require(String value, String field, String sku) {
if (value == null || value.trim().isEmpty()) {
throw new IllegalArgumentException("hengjian product " + sku + " requires " + field);
}
return value.trim();
}
private static String trimToNull(String v) {
if (v == null) {
return null;
}
String trimmed = v.trim();
return trimmed.isEmpty() ? null : trimmed;
}
}

50
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCarrierGroupDtos.java

@ -0,0 +1,50 @@ @@ -0,0 +1,50 @@
package common.ecommerce.hengjian.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 恒健报文结构:《获取物流渠道》({@code POST /v2/carrierGroup/getCarrierGroup},无请求参数)
* 与《获取仓库支持的物流渠道》({@code POST
* /v2/carrierGroup/getWarehouseCarrierGroupServices})。
*
* <p>两个接口返回的行结构完全一样,只有外层形状不同:</p>
* <ul>
* <li>全量渠道:{@code data} 是数组;</li>
* <li>按仓过滤:{@code data} 是以仓代码为键的对象,
* {@code {"EFCA":[{...}]}}。</li>
* </ul>
* <p>所以行模型共用,外层各自声明。</p>
*/
public final class HengjianCarrierGroupDtos {
private HengjianCarrierGroupDtos() {
}
/** 一个承运商服务。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class CarrierServiceRow {
/** 物流产品代码;下单的 {@code carrierCode} 用它。 */
public String code;
/** 承运商代码,如 {@code UPS};下单的 {@code carrier} 用它。 */
public String carrier;
/** 物流产品服务名称,给人看。 */
public String carrierServiceName;
}
/**
* 按仓过滤的响应 {@code data} 形状:仓代码 → 该仓可用的服务清单。
*
* <p>键是动态的仓代码,不能声明成固定字段;解析时按 JSON 顶层对象逐键读取。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class WarehouseCarrierGroupRow {
/** 仓代码(由解析时注入)。 */
public String warehouseCode;
/** 该仓可用服务。 */
public List<CarrierServiceRow> services;
}
}

200
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCreateOrderDtos.java

@ -0,0 +1,200 @@ @@ -0,0 +1,200 @@
package common.ecommerce.hengjian.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* 恒健报文结构:创建销售发货单({@code POST /v1/saleOrder/create})。
*
* <p>中英文两页文档描述的是同一个接口,中文页叫「创建销售发货单(带附件的)」,
* 英文页叫「Create Sale Order With Label」;两页字段表基本一致,差异见各字段注释。</p>
*
* <p><b>两页的必填口径不完全一致</b>:中文页把 {@code createdAt} 标为必填、英文页也标 Y;
* 但中文页没有 {@code isPrime}(只有英文页有),英文页没有 {@code customerRemark} /
* {@code warehouseRemark}(只有中文页有)。按两页并集实现,必填取两页都要求的字段。</p>
*/
public final class HengjianCreateOrderDtos {
private HengjianCreateOrderDtos() {
}
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class CreateOrderRequest {
/** 来源单号;必填。用 OMS 的出库单号,也是后续按单号查询 / 取消的锚点。 */
public String orderNo;
/** 承运商名称,如 {@code FedEx} / {@code UPS}。 */
public String carrier;
/** 承运商服务代码,如 {@code FEDEX_GROUND} / {@code UPS_2DAY}。 */
public String carrierCode;
/** 仓库 code;必须已在 Efulfill 系统维护。 */
public String warehouseCode;
/** 店铺标识;必须已在 Efulfill 店铺管理中维护。 */
public String channelAccount;
/** 币种;不填默认 USD。 */
public String currency;
/**
* 支付时间,UTC,{@code yyyy-MM-dd HH:mm:ss};不填由仓方取当前时间。
*
* <p>统一模型没有「支付时间」字段,这里通常不传。</p>
*/
public String paidAt;
/** Amazon VC Direct Fulfillment 订单:0 否 / 1 是;不填默认为否。 */
public Integer isDFOrder;
/**
* 是否 SFP 订单:0 否 / 1 是;不填默认为否。
*
* <p><b>文档类型写的是 String,但请求示例给的是数字 {@code "isPrime": 0}</b>。
* 这里按示例用 Integer——两页示例一致,且 Spring 后端按数字绑定的可能性更高。
* 真机若报类型错,改成 String 即可。</p>
*/
public Integer isPrime;
/**
* 平台要求发货时间,UTC,{@code yyyy-MM-dd HH:mm:ss}。
*
* <p>文档:{@code isDFOrder=1} 时必填。</p>
*/
public String expectedShipDate;
/** 目的国家,2 位字符;必填。 */
public String shipToCountry;
/** 目的州(美国:2 位编码);必填。 */
public String shipToState;
/** 目的城市;中文页标必填,英文页未标。 */
public String shipToCity;
/** 发运邮编;必填。 */
public String shipToPostal;
/** 发运地址 1;必填。 */
public String shipToAddress1;
/** 发运地址 2。 */
public String shipToAddress2;
/** 发运联系人;必填。 */
public String shipToContact;
/** 客户邮箱。 */
public String customerEmail;
/** 发运联系电话;必填。 */
public String shipToTelephone;
/** third party 账号。 */
public String thirdPartyAccount;
/** 发货时效:{@code Standard-48Hours}(标准)/ {@code SameDay ShipOut}(加急);不填为标准。 */
public String shipServiceLevel;
/** 创建时间,UTC,{@code yyyy-MM-dd HH:mm:ss};必填。 */
public String createdAt;
/** 买家备注。 */
public String customerRemark;
/** 仓库备注;传了仓方会参考此信息发货。 */
public String warehouseRemark;
/** 产品行;必填。 */
public List<ProductItem> productItems;
/**
* 附件信息;<b>两页文档都标必填</b>。
*
* <p>没有附件时发空数组而不是省略该字段——省略会被仓方当成缺必填项。</p>
*/
public List<AttachInfoItem> attachInfoItems;
/** 产品行。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ProductItem {
/** 发货产品 SKU;必填。 */
public String sku;
/** 发货数量;必填。 */
public Integer quantity;
/** 是否保价:0 否 / 1 是;必填。 */
public Integer isInsure;
/**
* 签收类型:0 否 / 1 直接签收 / 2 成人签收 / 3 间接签收(仅 FedEx);必填。
*
* <p>统一模型只有布尔型的 {@code signatureRequired},表达不了 2 / 3。</p>
*/
public Integer isSignature;
/** 当前 SKU 总金额(不是单价)。 */
public Double skuAmount;
/** 投保金额;{@code isInsure=1} 时必填。 */
public Double insureAmount;
}
/** 附件。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class AttachInfoItem {
/** 附件名称;必填。文档建议填跟踪号且不带后缀。 */
public String name;
/** 附件 URL;与 {@link #file} 至少给一个。 */
public String url;
/** base64 内容;给了就忽略 {@link #url}。 */
public String file;
/**
* 附件类型;必填。文档类型写 STRING:
* 0 Shippinglabel / 1 Packinglist / 2 BOL / 3 Other /
* 4 CartonLabel / 5 PalletLabel / 6 itemlabel。
*/
public String type;
/** 备注。 */
public String remark;
}
}
/** 创建响应:{@code {statusCode, status, code, message, data:{orderId}}}。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class CreateOrderResponse {
@JsonProperty("statusCode")
public Integer statusCode;
@JsonProperty("code")
public Integer code;
@JsonProperty("message")
public String message;
@JsonProperty("data")
public CreateOrderData data;
}
/** 响应 {@code data}。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class CreateOrderData {
/** 仓方订单 id;列表查询的条件,取消时也要带上。 */
@JsonProperty("orderId")
public Long orderId;
}
}

123
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianProductSaveDtos.java

@ -0,0 +1,123 @@ @@ -0,0 +1,123 @@
package common.ecommerce.hengjian.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 恒健报文结构:创建 / 编辑产品({@code POST /v1/product/save})。
*
* <p>字段名照抄文档。注意<b>尺寸与重量分三组,含义不同</b>:</p>
* <ul>
* <li>{@code length / width / height / weight}:产品(发货单元)尺寸与重量;</li>
* <li>{@code itemLength / itemWidth / itemHeight}:单品尺寸,选填;</li>
* <li>{@code packedLength / packedWidth / packedHeight / packedWeight / packedQty}:
* 外箱尺寸、外箱重量与装箱数量,<b>文档标必填</b>。</li>
* </ul>
* <p>三组不能互相顶替:把单品尺寸填进 {@code length} 会让仓方的计费重与货架位算错。</p>
*/
public final class HengjianProductSaveDtos {
private HengjianProductSaveDtos() {
}
/** 保存请求;响应没有 data,只有一个 {@code message}。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class SaveProductRequest {
/** 产品 SKU;必填。 */
public String sku;
/** UPC 编码;选填。 */
public String upc;
/** 产品类型:1 成品 / 2 配件 / 3 耗材;不传由仓方按默认处理。 */
public Integer productType;
/** 中文名称;必填。 */
public String name;
/** 英文名称;必填。 */
public String nameEn;
/** 产品描述;必填。 */
public String description;
/** 产品发货包装:0 原包装发货 / 1 重新打包;必填。 */
public Integer packingType;
/** 产品长(cm);必填。 */
public Double length;
/** 产品宽(cm);必填。 */
public Double width;
/** 产品高(cm);必填。 */
public Double height;
/** 产品重量(g);必填。 */
public Double weight;
/** 外箱长(cm);必填。 */
public Double packedLength;
/** 外箱宽(cm);必填。 */
public Double packedWidth;
/** 外箱高(cm);必填。 */
public Double packedHeight;
/** 外箱重量(g);必填。 */
public Double packedWeight;
/** 装箱数量;必填。 */
public Integer packedQty;
/** 单品长(cm);选填。 */
public Double itemLength;
/** 单品宽(cm);选填。 */
public Double itemWidth;
/** 单品高(cm);选填。 */
public Double itemHeight;
/** 保质期管理:0 否 / 1 是;不填默认为否。 */
public Integer expirationControl;
/** 保质期天数;{@code expirationControl=1} 时才有意义。 */
public Integer expirationDate;
/** 成本。 */
public Double cost;
/** 币种,如 {@code USD}。 */
public String currency;
/** 是否保价:{@code Y} / {@code N};不填默认为否。 */
public String isInsuranceFlag;
/** 保价费用。 */
public Double isInsuranceRate;
/** 备注。 */
public String remark;
/** 报关中文名。 */
public String customName;
/** 报关英文名。 */
public String customNameEn;
/** 是否特殊外包装:0 否 / 1 是。 */
public Integer isSpecialOuterPackaging;
/**
* 产品测量图片地址列表。
*
* <p>文档说明「有变更产品长/宽/高重量时传入」——它不是商品主图,
* 而是仓方复核尺寸用的测量照片。</p>
*/
public List<String> imageUrls;
}
}

42
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianWarehouseDtos.java

@ -0,0 +1,42 @@ @@ -0,0 +1,42 @@
package common.ecommerce.hengjian.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
/**
* 恒健报文结构:获取当前组织仓库({@code POST /v2/warehouse/getWarehouse},无请求参数)。
*
* <p>一个文件对应一个接口,只放该接口的请求 / 响应与内嵌子结构;
* 与其它接口共用的结构各自复制一份,避免跨接口耦合。</p>
*/
public final class HengjianWarehouseDtos {
private HengjianWarehouseDtos() {
}
/**
* 仓库行。
*
* <p>字段名照抄文档。<b>恒健没有给仓方内部 id</b>,{@code warehouseCode} 就是下单时
* 要传的仓代码,也是唯一标识。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class WarehouseRow {
/** 仓库 code;下单的 {@code warehouseCode} 用它。 */
public String warehouseCode;
/** 仓库名称。 */
public String name;
/** 国家,2 位。 */
public String country;
/** 州;文档写作「州」。 */
public String state;
/** 城市。 */
public String city;
/** 地址 1。 */
public String address1;
/** 地址 2。 */
public String address2;
/** 邮编。 */
public String postal;
}
}

10
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/package-info.java

@ -0,0 +1,10 @@ @@ -0,0 +1,10 @@
/**
* 恒健报文结构(DTO)。
*
* <p><b>约定</b>:一个接口一个文件,不建大而全的 Dtos;字段名照抄文档,
* 连拼写错误也照抄并加注释说明;保留 {@code @JsonInclude(NON_NULL)}。</p>
*
* <p>恒健文档里接口路径统一前缀 {@code /v1} 或 {@code /v2};字段多为 camelCase,
* 目前只出现一处文档笔误(见 {@code docs-warehouse/hengjian/README.md} 的「文档与实际不符」)。</p>
*/
package common.ecommerce.hengjian.dto;

18
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/package-info.java

@ -0,0 +1,18 @@ @@ -0,0 +1,18 @@
/**
* 恒健平台枚举(<b>本期尚未建立</b>)。
*
* <p>只读基础资料阶段没有状态码。接入出库 / 库存 / 退货时按
* {@code docs-warehouse/onboarding-checklist.md} 阶段 2.6 建:</p>
*
* <ul>
* <li>带仓方原始码 + {@code toCore()} 映射到底层枚举;</li>
* <li><b>精确匹配</b>不用 {@code contains};未知值归 {@code UNKNOWN} 不猜;</li>
* <li>提供反向 {@code codeOf()} 供下发;</li>
* <li>用完的原值同时写进模型的 {@code rawStatus}。</li>
* </ul>
*
* <p>恒健已知的状态字段:{@code /v1/saleOrder/findByPage} 的 {@code orderStatusEnum}
* 取值为 {@code pending / unshipped / approved / assigned / picked / shipped /
* canceled / refunded}——注意与运去哪<b>同名</b>,但那是巧合,两套码表各建各的。</p>
*/
package common.ecommerce.hengjian.enums;

197
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianEnvelope.java

@ -0,0 +1,197 @@ @@ -0,0 +1,197 @@
package common.ecommerce.hengjian.http;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.shared.error.AuthException;
import common.ecommerce.shared.error.PlatformBusinessException;
import common.ecommerce.shared.error.RateLimitException;
import common.ecommerce.shared.error.TransientException;
import common.ecommerce.shared.error.ValidationException;
import common.ecommerce.warehouse.error.WarehouseException;
/**
* 恒健响应信封校验。
*
* <p>恒健统一信封(《基础API调用》与绝大多数接口页一致):</p>
* <pre>
* { "statusCode": 200, "status": 0, "code": 200, "message": "查询成功" }
* </pre>
*
* <p>HTTP 通常恒为 200,成败看 <b>body 里的 {@code code}:200 成功</b>。
* 少数接口页只列 {@code code + message}(如查询库存),也有的把 {@code code}
* 标成 STRING;这里统一按文本读再转数字,两种形态都能识别。</p>
*
* <p><b>真机观察(2026-11-12,测试环境):</b></p>
* <ul>
* <li>不带授权头:HTTP 200 + {@code {"statusCode":500,"status":1,"code":999999,
* "message":"查询失败Unauthorized"}};</li>
* <li>只带一个授权头(值无效):HTTP 500 + Spring 错误页
* {@code {"status":500,"error":"Internal Server Error","message":"未知的账户!"}}。</li>
* </ul>
* <p>前者按认证失败处理({@link AuthException});后者没有业务码,按 HTTP 5xx
* 归 {@link TransientException},但「未知的账户」实际是凭据问题,所以单独识别成
* {@link AuthException},避免宿主无意义重试。</p>
*/
public final class HengjianEnvelope {
/** 业务成功码。 */
public static final int SUCCESS_CODE = HengjianConstants.SUCCESS_CODE;
private final String rawBody;
private HengjianEnvelope(String rawBody) {
this.rawBody = rawBody;
}
/**
* 校验 HTTP 状态与业务码。
*
* @throws AuthException 401 / 403,或业务码 999999,或「未知的账户」
* @throws RateLimitException 429
* @throws TransientException 5xx(认证相关的 500 除外)
* @throws ValidationException 其它 4xx / 空 body / 没有业务码
* @throws PlatformBusinessException 业务码非成功
*/
public static HengjianEnvelope of(HttpResponse response, JacksonJsonCodec json,
String operation, String warehouseCode, String requestId) {
int status = response.statusCode();
if (status == 401 || status == 403) {
throw new AuthException(base(operation, warehouseCode, requestId)
.message("hengjian auth failed: http " + status)
.platformCode(String.valueOf(status))
.rawResponse(truncate(response.body()))
.retryable(false));
}
if (status == 429) {
throw new RateLimitException(base(operation, warehouseCode, requestId)
.message("hengjian rate limited")
.platformCode(String.valueOf(status))
.retryable(true), retryAfterMillis(response));
}
if (status >= 500) {
// 只有一个授权头时恒健抛 Spring 500「未知的账户!」,这是凭据问题不是瞬时故障
if (mentionsUnknownAccount(json, response.body())) {
throw new AuthException(base(operation, warehouseCode, requestId)
.message("hengjian rejected the credential: unknown account")
.platformCode(String.valueOf(status))
.rawResponse(truncate(response.body()))
.retryable(false));
}
throw new TransientException(base(operation, warehouseCode, requestId)
.message("hengjian server error: http " + status)
.platformCode(String.valueOf(status))
.retryable(true), null);
}
if (status < 200 || status >= 300) {
throw new ValidationException(base(operation, warehouseCode, requestId)
.message("hengjian request rejected: http " + status
+ ", body=" + truncate(response.body()))
.platformCode(String.valueOf(status))
.rawResponse(truncate(response.body()))
.retryable(false));
}
String body = response.body();
if (body == null || body.trim().isEmpty()) {
throw new ValidationException(base(operation, warehouseCode, requestId)
.message("hengjian returned an empty body; cannot verify business code")
.platformCode(String.valueOf(status))
.retryable(false));
}
int code = firstPresentCode(json, body);
if (code == Integer.MIN_VALUE) {
throw new ValidationException(base(operation, warehouseCode, requestId)
.message("hengjian response has no business code: " + truncate(body))
.rawResponse(truncate(body))
.retryable(false));
}
if (code == HengjianConstants.UNAUTHORIZED_CODE) {
throw new AuthException(base(operation, warehouseCode, requestId)
.message("hengjian unauthorized: code=" + code + ", message=" + messageOf(json, body))
.platformCode(String.valueOf(code))
.rawResponse(truncate(body))
.retryable(false));
}
if (code != SUCCESS_CODE) {
throw new PlatformBusinessException(base(operation, warehouseCode, requestId)
.message("hengjian business error: code=" + code + ", message=" + messageOf(json, body))
.platformCode(String.valueOf(code))
.rawResponse(truncate(body))
.retryable(false));
}
return new HengjianEnvelope(body);
}
/** 原始响应体(已确认业务成功)。 */
public String body() {
return rawBody;
}
/**
* 取业务码:先 {@code code},缺了再看 {@code status}。
*
* <p>恒健有的接口页只写 {@code code},有的只写 {@code status},还有的把
* {@code code} 标成 STRING。统一按文本读,缺失返回 {@link Integer#MIN_VALUE}。</p>
*/
private static int firstPresentCode(JacksonJsonCodec json, String body) {
Integer code = intOrNull(json.stringAt(body, "code"));
if (code != null) {
return code;
}
Integer status = intOrNull(json.stringAt(body, "status"));
return status != null ? status : Integer.MIN_VALUE;
}
private static boolean mentionsUnknownAccount(JacksonJsonCodec json, String body) {
String message = messageOf(json, body);
return message != null && message.contains("未知的账户");
}
/** 业务提示语;恒健用 {@code message}。 */
private static String messageOf(JacksonJsonCodec json, String body) {
String message = json.stringAt(body, "message");
return message != null ? message : json.stringAt(body, "msg");
}
private static Integer intOrNull(String value) {
if (value == null || value.trim().isEmpty()) {
return null;
}
try {
return Integer.valueOf(value.trim());
} catch (NumberFormatException e) {
return null;
}
}
/** {@code Retry-After} 秒折算毫秒;缺失按 1s。 */
private static long retryAfterMillis(HttpResponse response) {
String header = response.header("Retry-After");
if (header == null || header.trim().isEmpty()) {
return 1000L;
}
try {
return Long.parseLong(header.trim()) * 1000L;
} catch (NumberFormatException e) {
return 1000L;
}
}
private static WarehouseException.Builder base(String operation, String warehouseCode,
String requestId) {
return WarehouseException.builder()
.operation(operation)
.warehouseCode(warehouseCode)
.provider(HengjianConstants.ADAPTER_ID)
.requestId(requestId);
}
private static String truncate(String body) {
if (body == null) {
return null;
}
return body.length() <= 2000 ? body : body.substring(0, 2000) + "...";
}
}

65
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianRateLimiter.java

@ -0,0 +1,65 @@ @@ -0,0 +1,65 @@
package common.ecommerce.hengjian.http;
import java.util.HashMap;
import java.util.Map;
import java.util.function.LongSupplier;
/**
* 按接口路径的令牌桶(间隔式)。
*
* <p>恒健文档未公开限流值,先按保守默认 {@link common.ecommerce.hengjian.HengjianConstants#PERMITS_PER_SECOND}
* 节流;429 的 {@code Retry-After} 由宿主处理,这里只做本地限速。</p>
*
* <p>进程内实现,多实例部署会叠加;需要跨实例限流时由宿主替换。
* 可注入 {@link Sleeper} 与纳秒时钟,测试不真的 sleep。</p>
*/
public final class HengjianRateLimiter {
/** 便于测试注入,生产用 {@link Thread#sleep}。 */
public interface Sleeper {
void sleep(long millis, int nanos);
}
private final Map<String, Long> nextAllowed = new HashMap<String, Long>();
private final Sleeper sleeper;
private final LongSupplier nanoClock;
public HengjianRateLimiter() {
this(new Sleeper() {
@Override
public void sleep(long millis, int nanos) {
try {
Thread.sleep(millis, nanos);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
}
}, new LongSupplier() {
@Override
public long getAsLong() {
return System.nanoTime();
}
});
}
public HengjianRateLimiter(Sleeper sleeper, LongSupplier nanoClock) {
this.sleeper = sleeper;
this.nanoClock = nanoClock;
}
/** 同一路径两次调用之间至少间隔 {@code 1e9 / permitsPerSecond} 纳秒。 */
public synchronized void acquire(String path, int permitsPerSecond) {
if (permitsPerSecond <= 0) {
return;
}
long interval = 1_000_000_000L / permitsPerSecond;
long now = nanoClock.getAsLong();
Long next = nextAllowed.get(path);
if (next != null && now < next) {
long wait = next - now;
sleeper.sleep(wait / 1_000_000L, (int) (wait % 1_000_000L));
now = nanoClock.getAsLong();
}
nextAllowed.put(path, now + interval);
}
}

137
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianRequestFactory.java

@ -0,0 +1,137 @@ @@ -0,0 +1,137 @@
package common.ecommerce.hengjian.http;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.audit.CallScope;
import common.ecommerce.shared.spi.ChannelSecret;
import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
import java.util.Collection;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* 构造恒健请求。
*
* <p>鉴权是<b>组织级固定 token 放请求头</b>(《基础API调用》),没有换取 / 续约流程,
* 因此不经过 {@code TokenManager}。token 复用 {@link ChannelSecret#appSecret()} 承载。</p>
*
* <p>文档要求 {@code Authorization} 与 {@code x-api-key} <b>两个头都带</b>,取值相同;
* 真机用无效 token 试过,只带一个也返回「未知的账户!」,无法区分,
* 所以按文档两个都带。见 {@code HengjianConstants} 的说明。</p>
*/
public final class HengjianRequestFactory {
private final JacksonJsonCodec json;
public HengjianRequestFactory(JacksonJsonCodec json) {
this.json = json;
}
/** POST:业务参数放 JSON 请求体;无参数接口传 null 或空 body。 */
public HttpRequest post(String baseUrl, String path, Object body,
ChannelSecret secret, CallScope ctx, String operation) {
return HttpRequest.builder()
.method("POST")
.url(baseUrl + path)
.contentType("application/json")
.headers(headers(secret, ctx))
.body(body == null ? "{}" : json.toJson(body))
.operation(operation)
.build();
}
/** GET:业务参数放 query。 */
public HttpRequest get(String baseUrl, String path, Map<String, Object> params,
ChannelSecret secret, CallScope ctx, String operation) {
return HttpRequest.builder()
.method("GET")
.url(baseUrl + path + queryString(params))
.headers(headers(secret, ctx))
.operation(operation)
.build();
}
/**
* GET:支持同名参数重复出现,如 {@code warehouseCodes=A&warehouseCodes=B}。
*
* <p>恒健的「批量查询库存」文档把 {@code warehouseCodes} 写成 LIST 却用 GET,
* 这是唯一能表达数组的方式;联调时若仓方只认逗号分隔,改这里一处。</p>
*/
public HttpRequest getMulti(String baseUrl, String path, Map<String, List<String>> params,
ChannelSecret secret, CallScope ctx, String operation) {
StringBuilder query = new StringBuilder();
if (params != null) {
for (Map.Entry<String, List<String>> e : params.entrySet()) {
List<String> values = e.getValue();
if (values == null) {
continue;
}
for (String value : values) {
if (value == null) {
continue;
}
query.append(query.length() == 0 ? '?' : '&');
query.append(urlEncode(e.getKey())).append('=').append(urlEncode(value));
}
}
}
return HttpRequest.builder()
.method("GET")
.url(baseUrl + path + query)
.headers(headers(secret, ctx))
.operation(operation)
.build();
}
/** 本次调用统一携带的请求头:两个授权头 + 链路 ID。 */
private static Map<String, String> headers(ChannelSecret secret, CallScope ctx) {
String token = requireToken(secret);
Map<String, String> out = new LinkedHashMap<String, String>();
out.put(HengjianConstants.AUTHORIZATION_HEADER, token);
out.put(HengjianConstants.API_KEY_HEADER, token);
out.put("requestId", ctx.requestId());
return out;
}
/** 缺 token 直接失败:发一个没有鉴权的请求只会拿到看不懂的 Unauthorized。 */
private static String requireToken(ChannelSecret secret) {
String token = secret == null ? null : secret.appSecret();
if (token == null || token.trim().isEmpty()) {
throw new IllegalStateException("hengjian requires an organization token in ChannelSecret.appSecret()");
}
return token;
}
/** 拼 {@code ?k=v};null 值跳过,返回串自带前导 {@code ?}。 */
private static String queryString(Map<String, Object> params) {
if (params == null) {
return "";
}
StringBuilder sb = new StringBuilder();
for (Map.Entry<String, Object> e : params.entrySet()) {
if (e.getValue() == null) {
continue;
}
if (e.getValue() instanceof Collection || e.getValue() instanceof Map) {
// 数组参数必须走 getMulti,否则会被序列化成看不懂的 JSON 串
throw new IllegalStateException(
"hengjian GET does not support collection parameters; use getMulti: " + e.getKey());
}
sb.append(sb.length() == 0 ? '?' : '&');
sb.append(urlEncode(e.getKey())).append('=').append(urlEncode(String.valueOf(e.getValue())));
}
return sb.toString();
}
private static String urlEncode(String v) {
try {
return URLEncoder.encode(v == null ? "" : v, "UTF-8");
} catch (UnsupportedEncodingException e) {
throw new IllegalStateException(e);
}
}
}

12
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/package-info.java

@ -0,0 +1,12 @@ @@ -0,0 +1,12 @@
/**
* 恒健出入网层:请求构造、限流、响应信封校验。
*
* <p>鉴权与其它仓不同:<b>两个请求头都要带</b>({@code Authorization} 与
* {@code x-api-key},取值相同)。真机实测只带一个会返回「未知的账户!」,
* 详见 {@code HengjianConstants}。</p>
*
* <p>信封校验区分三种形态:正常业务信封({@code code=200} 成功)、
* 未授权(HTTP 200 + {@code code=999999})、凭据被拒(HTTP 500 + 「未知的账户」)。
* 后两种都映射成 {@code AuthException},见 {@code HengjianEnvelope}。</p>
*/
package common.ecommerce.hengjian.http;

12
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/webhook/package-info.java

@ -0,0 +1,12 @@ @@ -0,0 +1,12 @@
/**
* 恒健回调验签与解析(<b>待接入</b>)。
*
* <p>恒健语雀文档目前<b>没有回调(Webhook)相关页面</b>:book 目录里只有 OpenAPI
* 接口,没有推送地址、验签算法或响应体约定。因此本期不声明 {@code WEBHOOK} 能力位,
* 也不实现 {@code WarehouseWebhookCapable}——声明了却解析不了,宿主会当能力可用。</p>
*
* <p>拿到回调文档后按 {@code docs-warehouse/callback.md} 接入:用
* {@code WebhookSignatures}(HMAC + 恒定时间比较 + 时间窗);多个回调共用一个地址时
* 按报文特征分派;回调也要走 {@code CallSupport.observe}。</p>
*/
package common.ecommerce.hengjian.webhook;

100
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java

@ -0,0 +1,100 @@ @@ -0,0 +1,100 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.model.OutboundRef;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseSdk;
import common.ecommerce.warehouse.spi.WarehouseAccount;
import common.ecommerce.warehouse.testkit.InMemoryWarehouses;
import org.junit.jupiter.api.Test;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 恒健适配器门面契约:注册后能按 provider 解析,未实现的能力显式拒绝。
*/
class HengjianAdapterTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-12T00:00:00Z"), ZoneOffset.UTC);
private static final String WH = "HJ-EFCA";
private static WarehouseAccount account() {
return WarehouseAccount.builder()
.warehouseCode(WH)
.provider(WarehouseProvider.HENGJIAN.name())
.providerWarehouseId("EFCA")
.credentialRef("kms://test/hengjian")
.timeZone("America/Los_Angeles")
.build();
}
private static WarehouseSdk sdk() {
return WarehouseSdk.builder()
.warehouseRepository(new InMemoryWarehouses().put(account()))
.clock(CLOCK)
.register(new HengjianAdapterFactory())
.build();
}
private static WarehouseConnection conn() {
return WarehouseConnection.of(HengjianConstants.TEST_BASE_URL,
ChannelSecret.builder().appSecret("token-1").build());
}
@Test
void registersAndResolves() {
WarehouseSdk sdk = sdk();
assertTrue(sdk.capabilities(WH).supports(
common.ecommerce.warehouse.enums.WarehouseCapability.DIRECTORY));
assertTrue(sdk.capabilities(WH).supports(
common.ecommerce.warehouse.enums.WarehouseCapability.LOGISTICS_PRODUCT));
}
/**
* 下单已接、查询未接:门面能力检查放行 {@code OUTBOUND},
* 适配器对未实现的 {@code get} 显式抛异常,不返回 null。
*/
@Test
void unimplementedOutboundQueryIsRejected() {
WarehouseSdk sdk = sdk();
assertThrows(common.ecommerce.warehouse.error.WarehouseException.class,
() -> sdk.warehouses(WH, conn()).outbound().get(OutboundRef.ofRequestNo("OB-1")));
}
/** 库存 / 入库 / 退货仍未接入:门面按能力位直接拒绝。 */
@Test
void undeclaredCapabilityIsRejected() {
WarehouseSdk sdk = sdk();
assertThrows(WarehouseUnsupportedCapabilityException.class,
() -> sdk.warehouses(WH, conn()).inventory().query(null));
}
/** 能力矩阵查询本身可用(不触发真实 API)。 */
@Test
void capabilityQueryIsOffline() {
HengjianAdapter adapter = new HengjianAdapter(RecordingTransport.create(), new JacksonJsonCodec());
assertTrue(!adapter.capabilities().contains(
common.ecommerce.warehouse.enums.WarehouseCapability.INVENTORY_QUERY));
}
@Test
void providerEnumIsRegistered() {
assertEquals("恒健", WarehouseProvider.HENGJIAN.label());
assertEquals(50, WarehouseProvider.HENGJIAN.code());
}
}

440
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java

@ -0,0 +1,440 @@ @@ -0,0 +1,440 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.model.Platform;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Money;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.LabelMode;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundLine;
import common.ecommerce.warehouse.model.OutboundReceipt;
import common.ecommerce.warehouse.model.OutboundRef;
import common.ecommerce.warehouse.model.ShipTo;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.warehouse.sdk.WarehouseSdk;
import common.ecommerce.warehouse.spi.WarehouseAccount;
import common.ecommerce.warehouse.testkit.InMemoryWarehouses;
import org.junit.jupiter.api.Test;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneId;
import java.time.ZoneOffset;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 创建销售发货单({@code POST /v1/saleOrder/create})契约测试。
*/
class HengjianCreateOrderTest {
private static final Instant NOW = Instant.parse("2026-11-12T03:04:05Z");
private static final Clock CLOCK = Clock.fixed(NOW, ZoneOffset.UTC);
private static final String CREATE_BODY =
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"创建订单成功\","
+ "\"data\":{\"orderId\":193252852}}";
private static WarehouseContext ctx() {
return ctx(ZoneOffset.UTC);
}
private static WarehouseContext ctx(ZoneId zone) {
return WarehouseContext.of("HJ-EFCA", WarehouseProvider.HENGJIAN, "EFCA",
WarehouseConnection.of(HengjianConstants.TEST_BASE_URL,
ChannelSecret.builder().appSecret("token-1").build(), zone),
"req-1", CLOCK);
}
private static HengjianAdapter adapter(RecordingTransport transport) {
return new HengjianAdapter(transport, new JacksonJsonCodec());
}
private static RecordingTransport creating() {
return RecordingTransport.create()
.route(HengjianConstants.PATH_ORDER_CREATE, req -> Responses.ok(CREATE_BODY));
}
private static ShipTo shipTo() {
return ShipTo.builder()
.name("Test Receiver")
.phone("555-0100")
.email("buyer@example.com")
.countryCode("US")
.stateOrProvince("CA")
.city("Los Angeles")
.addressLine1("1 Test St")
.addressLine2("Suite 2")
.postalCode("90001")
.build();
}
private static OutboundCommand.Builder order() {
return OutboundCommand.builder()
.outboundRequestNo("OB-2026-0001")
.orderRef("SO-1")
.salesPlatform(Platform.AMAZON_SC)
.carrier("UPS")
.carrierCode("UPSG_HL")
.shopName("EFCA-STORE")
.shipTo(shipTo())
.line(OutboundLine.builder()
.lineNo("1")
.omsSku("DM00001")
.quantity(2)
.declareValue(Money.of("9.99", "USD"))
.build());
}
// ---------------------------------------------------------------- 请求形状
@Test
void sendsPostToSaleOrderCreate() {
RecordingTransport transport = creating();
adapter(transport).create(ctx(), order().build());
assertEquals("POST", transport.lastDataRequest().method());
assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/saleOrder/create",
transport.lastDataRequest().url());
}
/** 文档必填的字段必须全部出现。 */
@Test
void sendsAllMandatoryFields() {
RecordingTransport transport = creating();
adapter(transport).create(ctx(), order().build());
String body = transport.lastDataRequest().body();
String[] mandatory = {"orderNo", "shipToCountry", "shipToState", "shipToCity",
"shipToPostal", "shipToAddress1", "shipToContact", "shipToTelephone",
"createdAt", "productItems", "attachInfoItems"};
for (String field : mandatory) {
assertTrue(body.contains("\"" + field + "\""), "缺少必填字段 " + field + ",body=" + body);
}
}
/** 产品行里的四个必填子字段都要有。 */
@Test
void productItemCarriesMandatoryFlags() {
RecordingTransport transport = creating();
adapter(transport).create(ctx(), order().build());
String body = transport.lastDataRequest().body();
String[] mandatory = {"sku", "quantity", "isInsure", "isSignature"};
for (String field : mandatory) {
assertTrue(body.contains("\"" + field + "\""), "产品行缺少 " + field + ",body=" + body);
}
assertTrue(body.contains("\"sku\":\"DM00001\""), body);
assertTrue(body.contains("\"quantity\":2"), body);
}
/**
* 恒健把 {@code attachInfoItems} 标为必填:没有附件时发空数组,
* 不能省略字段。
*/
@Test
void sendsEmptyAttachmentArrayWhenNoLabel() {
RecordingTransport transport = creating();
adapter(transport).create(ctx(), order().build());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"attachInfoItems\":[]"),
"没有附件时应发空数组而不是省略,body=" + body);
}
/** 平台面单:base64 内容进 file,类型 0,名称优先用跟踪号。 */
@Test
void sendsPlatformLabelAsAttachment() {
RecordingTransport transport = creating();
adapter(transport).create(ctx(), order()
.labelMode(LabelMode.PLATFORM_LABEL)
.trackingNumber("1ZXH1234567890")
.labelContentBase64("data:application/pdf;base64,JVBERi0xLjQK")
.build());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"name\":\"1ZXH1234567890\""), body);
// data URI 头必须剥掉,否则仓方会把前缀当文件内容
assertTrue(body.contains("\"file\":\"JVBERi0xLjQK\""), body);
assertFalse(body.contains("data:application/pdf"), body);
assertTrue(body.contains("\"type\":\"0\""), body);
}
/** 声明平台面单却不给文件,本地就拒绝——仓没有面单可打等于静默失败。 */
@Test
void rejectsPlatformLabelWithoutContent() {
RecordingTransport transport = creating();
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> adapter(transport).create(ctx(),
order().labelMode(LabelMode.PLATFORM_LABEL).build()));
assertTrue(ex.getMessage().contains("labelContentBase64"), ex.getMessage());
assertTrue(transport.dataRequests().isEmpty(), "本地校验失败不应发出请求");
}
/** 给了面单内容却不是平台面单模式,拒绝而不是静默丢弃。 */
@Test
void rejectsLabelContentWithoutPlatformMode() {
RecordingTransport transport = creating();
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> adapter(transport).create(ctx(),
order().labelContentBase64("JVBERi0xLjQK").build()));
assertTrue(ex.getMessage().contains("PLATFORM_LABEL"), ex.getMessage());
assertTrue(transport.dataRequests().isEmpty());
}
/** 时间按 UTC 输出,不受调用方传的时区影响。 */
@Test
void formatsTimesInUtc() {
RecordingTransport transport = creating();
adapter(transport).create(ctx(ZoneId.of("America/Los_Angeles")),
order().latestShipDate(Instant.parse("2026-11-15T23:30:00Z")).build());
String body = transport.lastDataRequest().body();
// createdAt 用注入的固定时钟
assertTrue(body.contains("\"createdAt\":\"2026-11-12 03:04:05\""), body);
assertTrue(body.contains("\"expectedShipDate\":\"2026-11-15 23:30:00\""),
"恒健要求 UTC,不能按仓所在时区输出,body=" + body);
}
/** 行金额是「当前 SKU 总金额」,申报单价要乘数量。 */
@Test
void skuAmountIsLineTotalNotUnitPrice() {
RecordingTransport transport = creating();
adapter(transport).create(ctx(), order().build());
String body = transport.lastDataRequest().body();
// 9.99 × 2 = 19.98
assertTrue(body.contains("\"skuAmount\":19.98"), "skuAmount 必须是行总额,body=" + body);
}
@Test
void usesExplicitTotalAmountWhenGiven() {
RecordingTransport transport = creating();
adapter(transport).create(ctx(), OutboundCommand.builder()
.outboundRequestNo("OB-2")
.salesPlatform(Platform.AMAZON_SC)
.shipTo(shipTo())
.line(OutboundLine.builder()
.lineNo("1")
.omsSku("DM00001")
.quantity(3)
.declareValue(Money.of("10.00", "USD"))
.totalAmount(Money.of("28.00", "USD"))
.build())
.build());
assertTrue(transport.lastDataRequest().body().contains("\"skuAmount\":28.0"));
}
/** 保价由「是否有保价金额」推导;有金额就要带 insureAmount。 */
@Test
void insuredLineSendsFlagAndAmount() {
RecordingTransport transport = creating();
adapter(transport).create(ctx(), OutboundCommand.builder()
.outboundRequestNo("OB-3")
.salesPlatform(Platform.AMAZON_SC)
.shipTo(shipTo())
.line(OutboundLine.builder()
.lineNo("1")
.omsSku("DM00001")
.quantity(1)
.insuredAmount(Money.of("100.00", "USD"))
.build())
.build());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"isInsure\":1"), body);
assertTrue(body.contains("\"insureAmount\":100.0"), body);
}
@Test
void uninsuredLineSendsZero() {
RecordingTransport transport = creating();
adapter(transport).create(ctx(), order().build());
assertTrue(transport.lastDataRequest().body().contains("\"isInsure\":0"));
}
/** 签收:布尔值映射成 1 / 0;null 视为不签收(恒健必填,不能省略)。 */
@Test
void signatureFlagIsMandatoryAndMapped() {
RecordingTransport required = creating();
adapter(required).create(ctx(), order().signatureRequired(true).build());
assertTrue(required.lastDataRequest().body().contains("\"isSignature\":1"));
RecordingTransport notRequired = creating();
adapter(notRequired).create(ctx(), order().build());
assertTrue(notRequired.lastDataRequest().body().contains("\"isSignature\":0"));
}
@Test
void mapsShopCurrencyAndCarrier() {
RecordingTransport transport = creating();
adapter(transport).create(ctx(), order()
.currency("CAD")
.sfp(true)
.remark("买家备注")
.build());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"channelAccount\":\"EFCA-STORE\""), body);
assertTrue(body.contains("\"currency\":\"CAD\""), body);
assertTrue(body.contains("\"carrier\":\"UPS\""), body);
assertTrue(body.contains("\"carrierCode\":\"UPSG_HL\""), body);
assertTrue(body.contains("\"isPrime\":1"), body);
assertTrue(body.contains("\"customerRemark\":\"买家备注\""), body);
}
/** 恒健没有平台维度:salesPlatform 不发,也不拿它推 isDFOrder。 */
@Test
void doesNotSendSalesPlatformOrInferDfOrder() {
RecordingTransport transport = creating();
adapter(transport).create(ctx(), order().build());
String body = transport.lastDataRequest().body();
assertFalse(body.contains("salesPlatform"), body);
assertFalse(body.contains("isDFOrder"), body);
}
/** 仓代码:命令显式指定优先,否则用账户配置。 */
@Test
void warehouseCodeResolvesFromCommandThenAccount() {
RecordingTransport fromCommand = creating();
adapter(fromCommand).create(ctx(), order().warehouseId("EFNJ").build());
assertTrue(fromCommand.lastDataRequest().body().contains("\"warehouseCode\":\"EFNJ\""));
RecordingTransport fromAccount = creating();
adapter(fromAccount).create(ctx(), order().build());
assertTrue(fromAccount.lastDataRequest().body().contains("\"warehouseCode\":\"EFCA\""));
}
// ---------------------------------------------------------------- 本地必填校验
@Test
void rejectsMissingShipToFields() {
String[] fields = {"countryCode", "stateOrProvince", "postalCode", "addressLine1",
"name", "phone", "city"};
for (String field : fields) {
ShipTo.Builder b = ShipTo.builder()
.name("N").phone("P").countryCode("US").stateOrProvince("CA")
.city("C").addressLine1("A").postalCode("Z");
if ("countryCode".equals(field)) {
b.countryCode(null);
} else if ("stateOrProvince".equals(field)) {
b.stateOrProvince(null);
} else if ("postalCode".equals(field)) {
b.postalCode(null);
} else if ("addressLine1".equals(field)) {
b.addressLine1(null);
} else if ("name".equals(field)) {
b.name(null);
} else if ("phone".equals(field)) {
b.phone(null);
} else {
b.city(null);
}
OutboundCommand cmd = OutboundCommand.builder()
.outboundRequestNo("OB-X")
.salesPlatform(Platform.AMAZON_SC)
.shipTo(b.build())
.line(OutboundLine.builder().lineNo("1").omsSku("S").quantity(1).build())
.build();
assertThrows(IllegalArgumentException.class,
() -> adapter(creating()).create(ctx(), cmd), field);
}
}
// ---------------------------------------------------------------- 响应
@Test
void readsProviderOrderIdFromData() {
RecordingTransport transport = creating();
OutboundReceipt receipt = adapter(transport).create(ctx(), order().build());
assertEquals("OB-2026-0001", receipt.outboundRequestNo());
assertEquals("193252852", receipt.providerOrderId(), "仓内部数字 id 必须落库,取消时要用");
assertEquals("创建订单成功", receipt.rawStatus());
}
/** 没有 orderId 不能当成功:后续取消需要它。 */
@Test
void rejectsResponseWithoutOrderId() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_ORDER_CREATE, req -> Responses.ok(
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"ok\"}"));
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter(transport).create(ctx(), order().build()));
assertTrue(ex.getMessage().contains("data.orderId"), ex.getMessage());
}
@Test
void businessErrorIsPropagated() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_ORDER_CREATE, req -> Responses.ok(
"{\"code\":500,\"message\":\"仓库不存在\"}"));
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter(transport).create(ctx(), order().build()));
assertTrue(ex.getMessage().contains("仓库不存在"), ex.getMessage());
}
// ---------------------------------------------------------------- 能力位与未接入接口
@Test
void declaresOutboundAndLabelCapabilities() {
HengjianAdapter adapter = adapter(RecordingTransport.create());
assertTrue(adapter.capabilities().contains(WarehouseCapability.OUTBOUND));
assertTrue(adapter.capabilities().contains(WarehouseCapability.PLATFORM_LABEL_DELIVERY));
}
/** 查询 / 取消还没接:显式拒绝,不返回 null 或空集合。 */
@Test
void unimplementedOutboundMethodsThrow() {
HengjianAdapter adapter = adapter(RecordingTransport.create());
assertThrows(RuntimeException.class,
() -> adapter.get(ctx(), OutboundRef.ofRequestNo("OB-1")));
assertThrows(RuntimeException.class,
() -> adapter.packages(ctx(), OutboundRef.ofRequestNo("OB-1")));
assertThrows(RuntimeException.class,
() -> adapter.checkCancel(ctx(), OutboundRef.ofRequestNo("OB-1")));
assertThrows(RuntimeException.class,
() -> adapter.cancel(ctx(), common.ecommerce.warehouse.model.CancelCommand.builder()
.outboundRequestNo("OB-1").build()));
}
/** 未声明的能力位仍然被门面挡住(INVENTORY_QUERY 还没接)。 */
@Test
void undeclaredCapabilityIsRejectedByFacade() {
WarehouseSdk sdk = WarehouseSdk.builder()
.warehouseRepository(new InMemoryWarehouses().put(WarehouseAccount.builder()
.warehouseCode("HJ-EFCA")
.provider(WarehouseProvider.HENGJIAN.name())
.providerWarehouseId("EFCA")
.credentialRef("kms://test")
.timeZone("America/Los_Angeles")
.build()))
.clock(CLOCK)
.register(new HengjianAdapterFactory())
.build();
assertThrows(WarehouseUnsupportedCapabilityException.class,
() -> sdk.warehouses("HJ-EFCA", WarehouseConnection.of(
HengjianConstants.TEST_BASE_URL,
ChannelSecret.builder().appSecret("t").build(),
ZoneOffset.UTC))
.inventory().query(null));
}
}

252
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java

@ -0,0 +1,252 @@ @@ -0,0 +1,252 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.hengjian.http.HengjianEnvelope;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.LogisticsProduct;
import common.ecommerce.warehouse.model.WarehouseFacility;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import org.junit.jupiter.api.Test;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.List;
import java.util.Map;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 恒健基础资料契约测试:请求形状、鉴权头、响应映射。
*
* <p>全部基于录制夹具,无网络。</p>
*/
class HengjianDirectoryTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-12T00:00:00Z"), ZoneOffset.UTC);
private static WarehouseContext ctx() {
return WarehouseContext.of("HJ-EFCA", WarehouseProvider.HENGJIAN, "EFCA",
WarehouseConnection.of(HengjianConstants.TEST_BASE_URL,
ChannelSecret.builder().appSecret("token-1").build()),
"req-1", CLOCK);
}
private static HengjianAdapter adapter(RecordingTransport transport) {
return new HengjianAdapter(transport, new JacksonJsonCodec());
}
/** 文档示例的仓库结构。 */
private static final String WAREHOUSE_BODY =
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"查询成功\",\"data\":["
+ "{\"warehouseCode\":\"EFCA\",\"name\":\"恒健加州仓\",\"country\":\"US\","
+ "\"state\":\"CA\",\"city\":\"Los Angeles\",\"address1\":\"1 Main St\","
+ "\"address2\":\"\",\"postal\":\"90001\"},"
+ "{\"warehouseCode\":\"EFNJ\",\"name\":\"恒健新泽西仓\",\"country\":\"US\","
+ "\"state\":\"NJ\",\"city\":\"Wharton\",\"address1\":\"40 Harry Shupe Blvd\","
+ "\"address2\":\"\",\"postal\":\"07885\"}]}";
// ---------------------------------------------------------------- 鉴权
/**
* 文档把两个头都标成「授权Token」且都标必须,所以两个都要带、取值相同。
*
* <p>真机用无效 token 试过,只带一个也返回「未知的账户!」,暂时无法用实验
* 证明「必须两个」;拿到有效 token 后补一次对照实验再决定能否精简。</p>
*/
@Test
void sendsBothAuthorizationHeaders() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_WAREHOUSE_LIST, req -> Responses.ok(WAREHOUSE_BODY));
adapter(transport).warehouses(ctx());
Map<String, String> headers = transport.lastDataRequest().headers();
assertEquals("token-1", headers.get(HengjianConstants.AUTHORIZATION_HEADER));
assertEquals("token-1", headers.get(HengjianConstants.API_KEY_HEADER));
assertEquals("req-1", headers.get("requestId"));
}
/** 缺 token 直接失败,不发一个没有鉴权的请求。 */
@Test
void rejectsRequestWithoutToken() {
RecordingTransport transport = RecordingTransport.create();
WarehouseContext ctx = WarehouseContext.of("HJ-EFCA", WarehouseProvider.HENGJIAN, "EFCA",
WarehouseConnection.of(HengjianConstants.TEST_BASE_URL, ChannelSecret.builder().build()),
"req-1", CLOCK);
try {
adapter(transport).warehouses(ctx);
throw new AssertionError("expected IllegalStateException");
} catch (IllegalStateException ex) {
assertTrue(ex.getMessage().contains("appSecret"), ex.getMessage());
}
assertTrue(transport.dataRequests().isEmpty(), "不应发出无鉴权请求");
}
// ---------------------------------------------------------------- 仓库目录
@Test
void sendsPostWithoutParameters() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_WAREHOUSE_LIST, req -> Responses.ok(WAREHOUSE_BODY));
adapter(transport).warehouses(ctx());
assertEquals("POST", transport.lastDataRequest().method());
assertEquals(HengjianConstants.TEST_BASE_URL + "/v2/warehouse/getWarehouse",
transport.lastDataRequest().url());
assertEquals("{}", transport.lastDataRequest().body());
}
@Test
void mapsEveryWarehouseField() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_WAREHOUSE_LIST, req -> Responses.ok(WAREHOUSE_BODY));
WarehouseFacility wh = adapter(transport).warehouses(ctx()).get(0);
assertEquals(WarehouseProvider.HENGJIAN, wh.sourceProvider());
assertEquals("EFCA", wh.warehouseCode());
assertEquals("恒健加州仓", wh.name());
assertEquals("US", wh.country());
assertEquals("CA", wh.state());
assertEquals("CA", wh.province());
assertEquals("Los Angeles", wh.city());
assertEquals("1 Main St", wh.address1());
assertNull(wh.address2(), "空串归一成 null,避免宿主把 \"\" 当有效值");
assertEquals("90001", wh.postcode());
// 恒健文档的仓对象没有联系人 / 电话 / 邮箱——平台限制,不是漏接
assertNull(wh.contactName());
assertNull(wh.mobilePhone());
assertNull(wh.email());
assertNull(wh.providerWarehouseId(), "恒健没有独立的仓方内部 id");
}
@Test
void skipsRowsWithoutWarehouseCode() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_WAREHOUSE_LIST, req -> Responses.ok(
"{\"code\":200,\"message\":\"ok\",\"data\":["
+ "{\"name\":\"没有仓代码的行\"},"
+ "{\"warehouseCode\":\"EFCA\",\"name\":\"仓\"}]}"));
List<WarehouseFacility> list = adapter(transport).warehouses(ctx());
assertEquals(1, list.size());
assertEquals("EFCA", list.get(0).warehouseCode());
}
@Test
void emptyWarehouseListIsNotAnError() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_WAREHOUSE_LIST, req -> Responses.ok(
"{\"code\":200,\"message\":\"ok\",\"data\":[]}"));
assertTrue(adapter(transport).warehouses(ctx()).isEmpty());
}
// ---------------------------------------------------------------- 物流渠道
private static final String CARRIER_BODY =
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"查询成功\",\"data\":["
+ "{\"code\":\"UPS2DAM_HL\",\"carrier\":\"UPS\",\"carrierServiceName\":\"2nd Day Air AM\"},"
+ "{\"code\":\"UPSG_HL\",\"carrier\":\"UPS\",\"carrierServiceName\":\"Ground\"},"
+ "{\"code\":\"FEDHD\",\"carrier\":\"FedEx\",\"carrierServiceName\":\"Home Delivery\"}]}";
@Test
void carriersAreDeduplicatedAndOrdered() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_CARRIER_GROUP, req -> Responses.ok(CARRIER_BODY));
List<String> codes = adapter(transport).carriers(ctx());
assertEquals(3, codes.size());
assertEquals("UPS2DAM_HL", codes.get(0));
assertEquals("FEDHD", codes.get(2));
}
@Test
void carrierRequestHasNoBodyParameters() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_CARRIER_GROUP, req -> Responses.ok(CARRIER_BODY));
adapter(transport).carriers(ctx());
assertEquals("POST", transport.lastDataRequest().method());
assertEquals(HengjianConstants.TEST_BASE_URL + "/v2/carrierGroup/getCarrierGroup",
transport.lastDataRequest().url());
assertEquals("{}", transport.lastDataRequest().body());
}
@Test
void mapsLogisticsProduct() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_CARRIER_GROUP, req -> Responses.ok(CARRIER_BODY));
LogisticsProduct p = adapter(transport).products(ctx(), null).get(0);
assertEquals(WarehouseProvider.HENGJIAN, p.sourceProvider());
assertEquals("EFCA", p.warehouseCode(), "未指定仓时用账户配置的 providerWarehouseId");
assertEquals("UPS2DAM_HL", p.logisticsProductCode());
assertEquals("UPS - 2nd Day Air AM", p.logisticsProductName());
// 恒健文档没有跨国维度:false 表示「未提供」,不是「不支持」
assertTrue(!p.crossCountry());
}
/** 按仓过滤的接口外层是「仓代码 → 数组」的对象,不是数组。 */
@Test
void warehouseCarrierServicesParsesObjectShapedData() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_WAREHOUSE_CARRIER_GROUP, req -> Responses.ok(
"{\"code\":200,\"message\":\"查询成功\",\"data\":{"
+ "\"EFCA\":[{\"code\":\"UPSG_HL\",\"carrier\":\"UPS\","
+ "\"carrierServiceName\":\"Ground\"}],"
+ "\"EFGA\":[{\"code\":\"OTHER_HL\",\"carrier\":\"UPS\","
+ "\"carrierServiceName\":\"别的仓的渠道\"}]}}"));
List<LogisticsProduct> list = adapter(transport).productsOfWarehouse(ctx(), "EFCA");
assertEquals(1, list.size(), "只取请求的仓,别人的渠道不能混进来");
assertEquals("UPSG_HL", list.get(0).logisticsProductCode());
assertEquals("EFCA", list.get(0).warehouseCode());
}
@Test
void warehouseCarrierServicesSendsWarehouseCodes() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_WAREHOUSE_CARRIER_GROUP, req -> Responses.ok(
"{\"code\":200,\"message\":\"ok\",\"data\":{\"EFCA\":[]}}"));
adapter(transport).productsOfWarehouse(ctx(), null);
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"warehouseCodes\""), body);
assertTrue(body.contains("\"EFCA\""), body);
}
// ---------------------------------------------------------------- 能力位
@Test
void declaresExpectedCapabilities() {
HengjianAdapter adapter = adapter(RecordingTransport.create());
assertTrue(adapter.capabilities().contains(WarehouseCapability.DIRECTORY));
assertTrue(adapter.capabilities().contains(WarehouseCapability.LOGISTICS_PRODUCT));
assertTrue(adapter.capabilities().contains(WarehouseCapability.PRODUCT));
assertTrue(adapter.capabilities().contains(WarehouseCapability.OUTBOUND));
// 库存 / 入库 / 退货 / 回调都还没接:声明了就必须有实现
assertTrue(!adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY));
assertTrue(!adapter.capabilities().contains(WarehouseCapability.INBOUND));
assertTrue(!adapter.capabilities().contains(WarehouseCapability.RETURN));
assertTrue(!adapter.capabilities().contains(WarehouseCapability.WEBHOOK));
}
@Test
void adapterIdentity() {
HengjianAdapter adapter = adapter(RecordingTransport.create());
assertEquals(HengjianConstants.ADAPTER_ID, adapter.adapterId());
assertEquals(WarehouseProvider.HENGJIAN, adapter.provider());
assertEquals(HengjianEnvelope.SUCCESS_CODE, HengjianConstants.SUCCESS_CODE);
}
}

338
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductSaveTest.java

@ -0,0 +1,338 @@ @@ -0,0 +1,338 @@
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Money;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import org.junit.jupiter.api.Test;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 商品创建 / 编辑({@code POST /v1/product/save})契约测试。
*
* <p>重点在三件容易出错的事:必填项本地拒绝、三组尺寸不互相顶替、
* 不在报文里编造恒健没有的字段。</p>
*/
class HengjianProductSaveTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-12T00:00:00Z"), ZoneOffset.UTC);
private static final String SAVE_BODY =
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"产品创建成功\"}";
private static WarehouseContext ctx() {
return WarehouseContext.of("HJ-EFCA", WarehouseProvider.HENGJIAN, "EFCA",
WarehouseConnection.of(HengjianConstants.TEST_BASE_URL,
ChannelSecret.builder().appSecret("token-1").build()),
"req-1", CLOCK);
}
private static HengjianAdapter adapter(RecordingTransport transport) {
return new HengjianAdapter(transport, new JacksonJsonCodec());
}
private static RecordingTransport saving() {
return RecordingTransport.create()
.route(HengjianConstants.PATH_PRODUCT_SAVE, req -> Responses.ok(SAVE_BODY));
}
/** 一份满足恒健全部必填项的商品。 */
private static WarehouseProduct.Builder product() {
return WarehouseProduct.builder()
.omsSku("DM00001")
.name("测试商品")
.nameEn("Test Product")
.description("用于契约测试的商品")
.packingType(1)
.lengthCm(30)
.widthCm(20)
.heightCm(10)
.weightGrams(500)
.packedQuantity(6)
.packedLengthCm(60.0)
.packedWidthCm(40.0)
.packedHeightCm(30.0)
.packedWeightGrams(3200.0);
}
// ---------------------------------------------------------------- 请求形状
@Test
void sendsPostToProductSave() {
RecordingTransport transport = saving();
adapter(transport).createOrUpdate(ctx(), product().build());
assertEquals("POST", transport.lastDataRequest().method());
assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/product/save",
transport.lastDataRequest().url());
}
/** 文档必填的字段必须全部出现在报文里。 */
@Test
void sendsAllMandatoryFields() {
RecordingTransport transport = saving();
adapter(transport).createOrUpdate(ctx(), product().build());
String body = transport.lastDataRequest().body();
String[] mandatory = {"sku", "name", "nameEn", "description", "packingType",
"length", "width", "height", "weight",
"packedLength", "packedWidth", "packedHeight", "packedWeight", "packedQty"};
for (String field : mandatory) {
assertTrue(body.contains("\"" + field + "\""), "缺少必填字段 " + field + ",body=" + body);
}
}
/**
* 三组尺寸各归各位:产品尺寸、单品尺寸、外箱尺寸不能互相顶替。
* 顶替会让仓方的计费重与货架位算错。
*/
@Test
void keepsThreeDimensionGroupsSeparate() {
RecordingTransport transport = saving();
adapter(transport).createOrUpdate(ctx(), product()
.itemLengthCm(12.5)
.itemWidthCm(8)
.itemHeightCm(3.5)
.build());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"length\":30.0"), body);
assertTrue(body.contains("\"width\":20.0"), body);
assertTrue(body.contains("\"height\":10.0"), body);
assertTrue(body.contains("\"itemLength\":12.5"), body);
assertTrue(body.contains("\"itemWidth\":8.0"), body);
assertTrue(body.contains("\"itemHeight\":3.5"), body);
assertTrue(body.contains("\"packedLength\":60.0"), body);
assertTrue(body.contains("\"packedWidth\":40.0"), body);
assertTrue(body.contains("\"packedHeight\":30.0"), body);
assertTrue(body.contains("\"packedWeight\":3200.0"), body);
assertTrue(body.contains("\"packedQty\":6"), body);
}
/** 单品尺寸选填:没给就不出现在报文里,不能填 0 占位。 */
@Test
void omitsOptionalItemDimensionsWhenAbsent() {
RecordingTransport transport = saving();
adapter(transport).createOrUpdate(ctx(), product().build());
String body = transport.lastDataRequest().body();
assertFalse(body.contains("itemLength"), body);
assertFalse(body.contains("itemWidth"), body);
assertFalse(body.contains("itemHeight"), body);
}
/** 没开保质期管理就不带天数,避免仓方存「已设天数但未启用」的脏数据。 */
@Test
void expirationDaysOnlySentWhenControlOn() {
RecordingTransport transport = saving();
adapter(transport).createOrUpdate(ctx(), product().expirationDays(365).build());
assertFalse(transport.lastDataRequest().body().contains("expirationDate"),
"未启用保质期管理时不应发送天数");
RecordingTransport on = saving();
adapter(on).createOrUpdate(ctx(), product().expirationControl(true).expirationDays(365).build());
String body = on.lastDataRequest().body();
assertTrue(body.contains("\"expirationControl\":1"), body);
assertTrue(body.contains("\"expirationDate\":365"), body);
}
/** 保价开关用 Y / N,不是 0 / 1。 */
@Test
void insuranceFlagUsesYn() {
RecordingTransport transport = saving();
adapter(transport).createOrUpdate(ctx(), product()
.insured(true)
.insuranceFee(Money.of("2.50", "USD"))
.build());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"isInsuranceFlag\":\"Y\""), body);
assertTrue(body.contains("\"isInsuranceRate\":2.5"), body);
RecordingTransport no = saving();
adapter(no).createOrUpdate(ctx(), product().insured(false).build());
assertTrue(no.lastDataRequest().body().contains("\"isInsuranceFlag\":\"N\""));
}
/** 未指定保价时整组不发,由仓方按默认(否)处理。 */
@Test
void insuranceFieldsOmittedWhenUnspecified() {
RecordingTransport transport = saving();
adapter(transport).createOrUpdate(ctx(), product().build());
String body = transport.lastDataRequest().body();
assertFalse(body.contains("isInsuranceFlag"), body);
assertFalse(body.contains("isInsuranceRate"), body);
}
@Test
void mapsCostCurrencyAndCustomsNames() {
RecordingTransport transport = saving();
adapter(transport).createOrUpdate(ctx(), product()
.cost(Money.of("12.30", "USD"))
.declaredName("测试品")
.declaredNameEn("Test Item")
.build());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"cost\":12.3"), body);
assertTrue(body.contains("\"currency\":\"USD\""), body);
assertTrue(body.contains("\"customName\":\"测试品\""), body);
assertTrue(body.contains("\"customNameEn\":\"Test Item\""), body);
}
/** 仓侧 SKU 优先。 */
@Test
void providerSkuWins() {
RecordingTransport transport = saving();
adapter(transport).createOrUpdate(ctx(), product().providerSku("HJ-SKU-1").build());
assertTrue(transport.lastDataRequest().body().contains("\"sku\":\"HJ-SKU-1\""));
}
/**
* 恒健没有的字段不能编:SN、批次、HS Code、原产国、商品链接、客退处理、品类,
* 以及语义不同的 {@code imageUrls} / {@code isSpecialOuterPackaging}。
*/
@Test
void doesNotInventFieldsHengjianDoesNotHave() {
RecordingTransport transport = saving();
adapter(transport).createOrUpdate(ctx(), product()
.imageUrl("https://example.com/main.jpg")
.productCategory(5)
.packageStyle(1)
.requireSn(1)
.link("https://example.com/p/1")
.hsCode("9503.00")
.countryOfOrigin("CN")
.lotControlEnabled(true)
.lotAttributeCode("LOT")
.build());
String body = transport.lastDataRequest().body();
String[] absent = {"imageUrls", "productCategory", "packageStyle", "isRequireSn",
"snMgmtMode", "link", "hsCode", "countryOfOrigin", "customs",
"lotControl", "returnDealMethod", "isSpecialOuterPackaging"};
for (String field : absent) {
assertFalse(body.contains("\"" + field + "\""), "不应发送恒健没有的字段 " + field + ",body=" + body);
}
}
// ---------------------------------------------------------------- 本地必填校验
@Test
void rejectsMissingNameEn() {
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> adapter(saving()).createOrUpdate(ctx(), product().nameEn(null).build()));
assertTrue(ex.getMessage().contains("nameEn"), ex.getMessage());
}
@Test
void rejectsMissingDescription() {
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> adapter(saving()).createOrUpdate(ctx(), product().description(null).build()));
assertTrue(ex.getMessage().contains("description"), ex.getMessage());
}
@Test
void rejectsMissingPackingType() {
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> adapter(saving()).createOrUpdate(ctx(), product().packingType(-1).build()));
assertTrue(ex.getMessage().contains("packingType"), ex.getMessage());
}
/** 外箱五项缺任何一个都本地拒绝,不静默补值。 */
@Test
void rejectsMissingPackedDimensions() {
String[] fields = {"packedLengthCm", "packedWidthCm", "packedHeightCm", "packedWeightGrams"};
for (String field : fields) {
WarehouseProduct.Builder b = product();
if ("packedLengthCm".equals(field)) {
b.packedLengthCm(null);
} else if ("packedWidthCm".equals(field)) {
b.packedWidthCm(null);
} else if ("packedHeightCm".equals(field)) {
b.packedHeightCm(null);
} else {
b.packedWeightGrams(null);
}
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> adapter(saving()).createOrUpdate(ctx(), b.build()), field);
assertTrue(ex.getMessage().contains("packedLengthCm") || ex.getMessage().contains("外箱"),
ex.getMessage());
}
}
@Test
void rejectsMissingPackedQuantity() {
IllegalArgumentException ex = assertThrows(IllegalArgumentException.class,
() -> adapter(saving()).createOrUpdate(ctx(), product().packedQuantity(null).build()));
assertTrue(ex.getMessage().contains("packedQuantity"), ex.getMessage());
}
/** 校验失败时一个请求都不该发出去。 */
@Test
void noRequestSentWhenValidationFails() {
RecordingTransport transport = saving();
assertThrows(IllegalArgumentException.class,
() -> adapter(transport).createOrUpdate(ctx(), product().nameEn(null).build()));
assertTrue(transport.dataRequests().isEmpty(), "本地校验失败不应发出请求");
}
// ---------------------------------------------------------------- 响应
@Test
void resultCarriesSkuAndProviderMessage() {
WarehouseProductCapable.ProductResult result =
adapter(saving()).createOrUpdate(ctx(), product().build());
assertEquals("DM00001", result.providerSku());
assertEquals("SAVED", result.status());
assertEquals("产品创建成功", result.rawStatus(), "仓方没有 data,只回 message");
}
/** 空 body 不能被当成成功。 */
@Test
void emptyResponseBodyIsRejected() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_PRODUCT_SAVE, req -> Responses.ok(""));
assertThrows(RuntimeException.class,
() -> adapter(transport).createOrUpdate(ctx(), product().build()));
}
@Test
void businessErrorIsPropagated() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_PRODUCT_SAVE, req -> Responses.ok(
"{\"statusCode\":500,\"status\":1,\"code\":500,\"message\":\"sku 已存在\"}"));
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter(transport).createOrUpdate(ctx(), product().build()));
assertTrue(ex.getMessage().contains("sku 已存在"), ex.getMessage());
}
// ---------------------------------------------------------------- 能力位
@Test
void declaresProductCapability() {
assertTrue(adapter(RecordingTransport.create()).capabilities()
.contains(WarehouseCapability.PRODUCT));
}
}

126
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/http/HengjianEnvelopeTest.java

@ -0,0 +1,126 @@ @@ -0,0 +1,126 @@
package common.ecommerce.hengjian.http;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.error.AuthException;
import common.ecommerce.shared.error.PlatformBusinessException;
import common.ecommerce.shared.error.TransientException;
import common.ecommerce.shared.error.ValidationException;
import org.junit.jupiter.api.Test;
import java.util.Collections;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 恒健响应信封校验。
*
* <p>把真机观察到的三种形态都固化成用例:正常业务信封、
* HTTP 200 + {@code code=999999}(未授权)、HTTP 500 + 「未知的账户」。
* 后续有人把信封改成严格数字解析、或把 999999 当普通业务失败,这些用例会挂。</p>
*/
class HengjianEnvelopeTest {
private static final JacksonJsonCodec JSON = new JacksonJsonCodec();
private static HttpResponse ok(String body) {
return HttpResponse.of(200, Collections.<String, String>emptyMap(), body, 0L);
}
private static HengjianEnvelope parse(HttpResponse response) {
return HengjianEnvelope.of(response, JSON, "warehouse.test", "WH-1", "req-1");
}
// ---------------------------------------------------------------- 成功
@Test
void acceptsNumericCode() {
String body = "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"查询成功\"}";
assertEquals(body, parse(ok(body)).body());
}
/** 查询库存等接口页把 code 标成 STRING,必须同样按成功处理。 */
@Test
void acceptsStringCode() {
parse(ok("{\"code\":\"200\",\"message\":\"ok\"}"));
}
/** 个别接口页只列 status 不列 code。 */
@Test
void fallsBackToStatusWhenCodeMissing() {
parse(ok("{\"status\":200,\"message\":\"ok\"}"));
}
// ---------------------------------------------------------------- 失败
@Test
void businessErrorIsNotRetryable() {
PlatformBusinessException ex = assertThrows(PlatformBusinessException.class,
() -> parse(ok("{\"code\":500,\"message\":\"sku 不存在\"}")));
assertTrue(ex.getMessage().contains("500"), ex.getMessage());
assertTrue(ex.getMessage().contains("sku 不存在"), ex.getMessage());
assertTrue(!ex.retryable());
}
/**
* 真机:不带授权头时 HTTP 200 但 body 里 code=999999。
* 这必须归认证失败——当普通业务失败宿主不会刷新凭据。
*/
@Test
void unauthorizedCodeIsAuthFailure() {
AuthException ex = assertThrows(AuthException.class, () -> parse(ok(
"{\"statusCode\":500,\"status\":1,\"code\":999999,"
+ "\"message\":\"查询失败Unauthorized\"}")));
assertEquals("999999", ex.platformCode());
assertTrue(!ex.retryable());
}
/**
* 真机:只带一个授权头 / token 无效时 HTTP 500 + Spring 错误页。
* 消息虽是 500,根因是凭据,按认证失败处理,避免宿主无意义重试。
*/
@Test
void unknownAccountOn500IsAuthFailure() {
AuthException ex = assertThrows(AuthException.class, () -> parse(
HttpResponse.of(500, Collections.<String, String>emptyMap(),
"{\"timestamp\":\"2026-11-12T07:01:31.760+0000\",\"status\":500,"
+ "\"error\":\"Internal Server Error\","
+ "\"message\":\"未知的账户!\",\"path\":\"/v2/warehouse/getWarehouse\"}",
0L)));
assertTrue(ex.getMessage().contains("unknown account"), ex.getMessage());
assertTrue(!ex.retryable());
}
/** 普通 5xx(网关 / 后端故障)仍按瞬时错误处理。 */
@Test
void plainServerErrorIsRetryable() {
TransientException ex = assertThrows(TransientException.class, () -> parse(
HttpResponse.of(502, Collections.<String, String>emptyMap(), "bad gateway", 0L)));
assertTrue(ex.retryable());
}
@Test
void http401IsAuthFailure() {
assertThrows(AuthException.class, () -> parse(
HttpResponse.of(401, Collections.<String, String>emptyMap(), "", 0L)));
}
@Test
void emptyBodyIsValidationError() {
assertThrows(ValidationException.class, () -> parse(ok("")));
}
@Test
void missingCodeIsValidationError() {
ValidationException ex = assertThrows(ValidationException.class,
() -> parse(ok("{\"message\":\"no code here\"}")));
assertTrue(ex.getMessage().contains("no business code"), ex.getMessage());
}
@Test
void nonJsonErrorBodyIsValidationError() {
assertThrows(ValidationException.class, () -> parse(ok("<html>proxy error</html>")));
}
}

148
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianReadOnlyProbeTest.java

@ -0,0 +1,148 @@ @@ -0,0 +1,148 @@
package common.ecommerce.hengjian.probe;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.hengjian.adapter.HengjianAdapter;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.http.OkHttpTransport;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.LogisticsProduct;
import common.ecommerce.warehouse.model.WarehouseFacility;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import org.junit.jupiter.api.Assumptions;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.EnabledIfSystemProperty;
import java.time.Clock;
import java.util.List;
/**
* 恒健<b>只读</b>探针:核对已对接接口的真实出入参。
*
* <p>默认跳过,用 {@code -Dhengjian.probe=true} 显式开启;凭据走系统属性,
* <b>真实 token 不入库</b>:</p>
*
* <pre>
* mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
* -Dhengjian.probe=true \
* -Dhengjian.probe.token=你的组织token \
* -Dhengjian.probe.warehouseCode=EFCA \
* -Dtest=HengjianReadOnlyProbeTest test
* </pre>
*
* <p><b>只跑查询类接口</b>:建单 / 取消 / 销毁会真实创建单据,没有测试环境
* 明确许可前一律不碰。</p>
*
* <p>输出只打印字段名与取值摘要,不打印 token 与完整报文(可能含 PII)。</p>
*/
@EnabledIfSystemProperty(named = "hengjian.probe", matches = "true")
class HengjianReadOnlyProbeTest {
private static final String TOKEN = System.getProperty("hengjian.probe.token", "");
private static final String BASE_URL = opt("hengjian.probe.baseUrl", HengjianConstants.TEST_BASE_URL);
private static final String WAREHOUSE_CODE = opt("hengjian.probe.warehouseCode", "HJ-PROBE");
private static final String PROVIDER_WAREHOUSE = opt("hengjian.probe.providerWarehouseId", "EFCA");
private static String opt(String key, String fallback) {
String v = System.getProperty(key);
return v == null || v.trim().isEmpty() ? fallback : v.trim();
}
private static void assumeToken() {
Assumptions.assumeTrue(!TOKEN.trim().isEmpty(),
"未提供 -Dhengjian.probe.token,跳过恒健探针");
}
private static WarehouseContext ctx() {
return WarehouseContext.of(WAREHOUSE_CODE, WarehouseProvider.HENGJIAN, PROVIDER_WAREHOUSE,
WarehouseConnection.of(BASE_URL,
ChannelSecret.builder().appSecret(TOKEN.trim()).build()),
"probe-" + System.currentTimeMillis(), Clock.systemUTC());
}
private static HengjianAdapter adapter() {
return new HengjianAdapter(new OkHttpTransport("common-ecommerce-hengjian-probe"),
new JacksonJsonCodec());
}
/** 一次跑完,异常只打印不中断——探针要把所有问题一次暴露出来。 */
private static void run(String what, Runnable action) {
System.out.println("---- " + what);
try {
action.run();
} catch (RuntimeException e) {
System.out.println(" [FAIL] " + e.getClass().getSimpleName() + ": " + e.getMessage());
}
}
/** 仓库目录:不依赖任何单号,最容易验通,也顺带验证鉴权与信封。 */
@Test
void probeWarehouseDirectory() {
assumeToken();
run("POST /v2/warehouse/getWarehouse", new Runnable() {
@Override
public void run() {
List<WarehouseFacility> list = adapter().warehouses(ctx());
System.out.println(" 返回 " + list.size() + " 个仓");
for (int i = 0; i < Math.min(list.size(), 10); i++) {
WarehouseFacility w = list.get(i);
System.out.println(" [" + i + "] code=" + w.warehouseCode()
+ " name=" + w.name()
+ " country=" + w.country()
+ " state=" + w.state()
+ " city=" + w.city()
+ " postal=" + w.postcode());
}
}
});
}
/** 全量物流渠道:验证无参数 POST 与 data 是数组。 */
@Test
void probeAllCarrierServices() {
assumeToken();
run("POST /v2/carrierGroup/getCarrierGroup", new Runnable() {
@Override
public void run() {
List<LogisticsProduct> list = adapter().products(ctx(), PROVIDER_WAREHOUSE);
System.out.println(" 返回 " + list.size() + " 个物流产品");
for (int i = 0; i < Math.min(list.size(), 10); i++) {
LogisticsProduct p = list.get(i);
System.out.println(" [" + i + "] code=" + p.logisticsProductCode()
+ " name=" + p.logisticsProductName());
}
}
});
}
/** 按仓过滤的物流渠道:验证 data 是「仓代码 → 数组」的对象。 */
@Test
void probeWarehouseCarrierServices() {
assumeToken();
run("POST /v2/carrierGroup/getWarehouseCarrierGroupServices", new Runnable() {
@Override
public void run() {
List<LogisticsProduct> list = adapter().productsOfWarehouse(ctx(), PROVIDER_WAREHOUSE);
System.out.println(" 仓 " + PROVIDER_WAREHOUSE + " 返回 " + list.size() + " 个物流产品");
for (int i = 0; i < Math.min(list.size(), 10); i++) {
System.out.println(" [" + i + "] code=" + list.get(i).logisticsProductCode()
+ " name=" + list.get(i).logisticsProductName());
}
}
});
}
/** 承运商代码清单(走同一个全量接口,验证去重)。 */
@Test
void probeCarrierCodes() {
assumeToken();
run("POST /v2/carrierGroup/getCarrierGroup (carriers)", new Runnable() {
@Override
public void run() {
List<String> codes = adapter().carriers(ctx());
System.out.println(" 去重后 " + codes.size() + " 个 code:" + codes);
}
});
}
}

191
warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java

@ -0,0 +1,191 @@ @@ -0,0 +1,191 @@
package common.ecommerce.hengjian.probe;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.hengjian.adapter.HengjianAdapter;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.http.OkHttpTransport;
import common.ecommerce.shared.model.Platform;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundLine;
import common.ecommerce.warehouse.model.OutboundReceipt;
import common.ecommerce.warehouse.model.ShipTo;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import org.junit.jupiter.api.Assumptions;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.condition.EnabledIfSystemProperty;
import java.time.Clock;
/**
* 恒健<b>写接口</b>探针:真实创建商品,用于核对 {@code /v1/product/save} 的报文。
*
* <p>需要两个开关同时打开,避免误跑在正式环境:</p>
* <pre>
* mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
* -Dhengjian.probe=true -Dhengjian.probe.write=true \
* -Dhengjian.probe.token=你的组织token \
* -Dhengjian.probe.sku=PROBE-SKU-001 \
* -Dtest=HengjianWriteProbeTest test
* </pre>
*
* <p><b>会在仓方测试环境留下真实商品数据</b>:恒健文档里没有删除产品的接口,
* 跑完需要人工在 Efulfill 后台清理。SKU 默认带时间戳,重跑不会撞唯一约束。</p>
*
* <p>输出只打印结果与关键字段,不打印 token。</p>
*/
@EnabledIfSystemProperty(named = "hengjian.probe.write", matches = "true")
class HengjianWriteProbeTest {
private static final String TOKEN = System.getProperty("hengjian.probe.token", "");
private static final String BASE_URL = opt("hengjian.probe.baseUrl", HengjianConstants.TEST_BASE_URL);
private static final String WAREHOUSE_CODE = opt("hengjian.probe.warehouseCode", "HJ-PROBE");
private static final String PROVIDER_WAREHOUSE = opt("hengjian.probe.providerWarehouseId", "EFCA");
private static final String SKU =
opt("hengjian.probe.sku", "PROBE-" + System.currentTimeMillis());
private static String opt(String key, String fallback) {
String v = System.getProperty(key);
return v == null || v.trim().isEmpty() ? fallback : v.trim();
}
private static WarehouseContext ctx() {
return WarehouseContext.of(WAREHOUSE_CODE, WarehouseProvider.HENGJIAN, PROVIDER_WAREHOUSE,
WarehouseConnection.of(BASE_URL,
ChannelSecret.builder().appSecret(TOKEN.trim()).build()),
"probe-" + System.currentTimeMillis(), Clock.systemUTC());
}
private static HengjianAdapter adapter() {
return new HengjianAdapter(new OkHttpTransport("common-ecommerce-hengjian-probe"),
new JacksonJsonCodec());
}
private static void assumeToken() {
Assumptions.assumeTrue(!TOKEN.trim().isEmpty(),
"未提供 -Dhengjian.probe.token,跳过恒健写探针");
}
/** 一份满足恒健全部必填项的商品。 */
private static WarehouseProduct product(String sku) {
return WarehouseProduct.builder()
.omsSku(sku)
.name("探针商品")
.nameEn("Probe Product")
.description("SDK 探针创建,可删除")
.packingType(1)
.lengthCm(30)
.widthCm(20)
.heightCm(10)
.weightGrams(500)
.packedQuantity(6)
.packedLengthCm(60.0)
.packedWidthCm(40.0)
.packedHeightCm(30.0)
.packedWeightGrams(3200.0)
.cost(Money.of("1.00", "USD"))
.build();
}
/**
* 建商品:验证必填项组合与保存语义。
*
* <p>同 SKU 连跑两次可确认 {@code save} 是幂等保存(第二次应为更新而非报重复)。</p>
*/
@Test
void probeProductSave() {
assumeToken();
System.out.println("\n================ hengjian / v1/product/save ================");
System.out.println(" sku=" + SKU + " base=" + BASE_URL + " warehouse=" + PROVIDER_WAREHOUSE);
try {
WarehouseProductCapable.ProductResult result =
adapter().createOrUpdate(ctx(), product(SKU));
System.out.println(" [OK] status=" + result.status()
+ " providerSku=" + result.providerSku()
+ " rawStatus=" + result.rawStatus());
} catch (RuntimeException e) {
System.out.println(" [FAIL] " + e.getClass().getSimpleName() + ": " + e.getMessage());
}
}
/** 再存一次:确认保存语义(更新)不会因 SKU 重复而失败。 */
@Test
void probeProductSaveTwice() {
assumeToken();
System.out.println("\n================ hengjian / v1/product/save (second save) ================");
try {
WarehouseProductCapable.ProductResult result =
adapter().createOrUpdate(ctx(), product(SKU));
System.out.println(" [OK] 第二次保存 status=" + result.status()
+ " rawStatus=" + result.rawStatus());
} catch (RuntimeException e) {
System.out.println(" [FAIL] " + e.getClass().getSimpleName() + ": " + e.getMessage()
+ " ← 若非幂等保存,这里会报 SKU 已存在");
}
}
// ================================================================ 出库
/**
* 建销售发货单:验证必填组合、时间格式与 {@code data.orderId} 是否真回。
*
* <p>需要 {@code -Dhengjian.probe.postcode};SKU 用 {@link #SKU},
* 所以要先把商品建出来({@link #probeProductSave})。</p>
*
* <p><b>会在仓方测试环境留一张真实订单</b>。探针不自动取消——取消接口尚未接入。</p>
*/
@Test
void probeCreateSaleOrder() {
assumeToken();
String postcode = opt("hengjian.probe.postcode", "");
Assumptions.assumeTrue(!postcode.isEmpty(),
"未提供 -Dhengjian.probe.postcode,跳过建单探针");
System.out.println("\n================ hengjian / v1/saleOrder/create ================");
System.out.println(" orderNo=" + orderNo() + " warehouse=" + PROVIDER_WAREHOUSE
+ " sku=" + SKU + " postcode=" + postcode);
try {
OutboundReceipt receipt = adapter().create(ctx(), command(postcode));
System.out.println(" [OK] outboundRequestNo=" + receipt.outboundRequestNo()
+ " providerOrderId=" + receipt.providerOrderId()
+ " rawStatus=" + receipt.rawStatus());
System.out.println(" ← providerOrderId 是仓内部数字 id,取消接口要同时用它和单号");
} catch (RuntimeException e) {
System.out.println(" [FAIL] " + e.getClass().getSimpleName() + ": " + e.getMessage());
}
}
private static String orderNo() {
return "PROBE-OB-" + System.currentTimeMillis();
}
private static OutboundCommand command(String postcode) {
return OutboundCommand.builder()
.outboundRequestNo(orderNo())
.salesPlatform(Platform.AMAZON_SC)
.carrier("UPS")
.carrierCode(opt("hengjian.probe.carrierCode", "UPSG_HL"))
.shopName(opt("hengjian.probe.shopName", ""))
.currency("USD")
.shipTo(ShipTo.builder()
.name("Probe Receiver")
.phone("5550000000")
.countryCode("US")
.stateOrProvince(opt("hengjian.probe.state", "CA"))
.city(opt("hengjian.probe.city", "Los Angeles"))
.addressLine1("1 Probe St")
.postalCode(postcode)
.build())
.line(OutboundLine.builder()
.lineNo("1")
.omsSku(SKU)
.quantity(1)
.declareValue(Money.of("1.00", "USD"))
.build())
.build();
}
}

75
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java

@ -49,7 +49,20 @@ import common.ecommerce.warehouse.model.TransferOrder; @@ -49,7 +49,20 @@ import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.xincang.XincangConstants;
import common.ecommerce.xincang.auth.XincangTokenClient;
import common.ecommerce.xincang.dto.XincangDtos;
import common.ecommerce.xincang.dto.XincangChannelRecommendDtos;
import common.ecommerce.xincang.dto.XincangForecastCreateDtos;
import common.ecommerce.xincang.dto.XincangForecastDetailDtos;
import common.ecommerce.xincang.dto.XincangForecastImproveDtos;
import common.ecommerce.xincang.dto.XincangLogisticsDtos;
import common.ecommerce.xincang.dto.XincangOrderCreateDtos;
import common.ecommerce.xincang.dto.XincangOrderDetailDtos;
import common.ecommerce.xincang.dto.XincangProductListDtos;
import common.ecommerce.xincang.dto.XincangProductSaveDtos;
import common.ecommerce.xincang.dto.XincangStockAgeListDtos;
import common.ecommerce.xincang.dto.XincangStockListDtos;
import common.ecommerce.xincang.dto.XincangTransferCreateDtos;
import common.ecommerce.xincang.dto.XincangTransferDetailDtos;
import common.ecommerce.xincang.dto.XincangWarehouseDtos;
import common.ecommerce.xincang.http.XincangEnvelope;
import common.ecommerce.xincang.http.XincangMultipart;
import common.ecommerce.xincang.http.XincangRateLimiter;
@ -164,7 +177,7 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa @@ -164,7 +177,7 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
@Override
public ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product) {
AccessToken token = login(ctx);
XincangDtos.ProductRequest body = XincangProductMapper.toRequest(product, token.value());
XincangProductSaveDtos.ProductRequest body = XincangProductMapper.toRequest(product, token.value());
boolean existsAsTemporary = findTemporaryProduct(ctx, token, body.productNo) != null;
if (existsAsTemporary) {
@ -181,7 +194,7 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa @@ -181,7 +194,7 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
* <p>{@code api.productlist} 的 {@code key} 是 SKU 过滤条件,但文档没说是否精确匹配,
* 这里再按 {@code product_no} 精确比对一次。</p>
*/
private XincangDtos.ProductListItem findTemporaryProduct(WarehouseContext ctx, AccessToken token,
private XincangProductListDtos.ProductListItem findTemporaryProduct(WarehouseContext ctx, AccessToken token,
String sku) {
Map<String, Object> params = new LinkedHashMap<>();
params.put("state", 0);
@ -190,9 +203,9 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa @@ -190,9 +203,9 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
params.put("key", sku);
String raw = executeGet(ctx, XincangConstants.PATH_PRODUCT_LIST, params, token, OP_PRODUCT_QUERY);
List<XincangDtos.ProductListItem> items =
json.listAt(raw, "rst.data", XincangDtos.ProductListItem.class);
for (XincangDtos.ProductListItem item : items) {
List<XincangProductListDtos.ProductListItem> items =
json.listAt(raw, "rst.data", XincangProductListDtos.ProductListItem.class);
for (XincangProductListDtos.ProductListItem item : items) {
if (sku.equals(item.productNo)) {
return item;
}
@ -220,7 +233,7 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa @@ -220,7 +233,7 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
Map<String, String> form = XincangOrderMapper.toForm(ctx, cmd, json);
String raw = executeMultipart(ctx, XincangConstants.PATH_ORDER_ADD_MULTIPLE, form,
"warehouse.outbound.create");
XincangDtos.OrderResult result = json.fromJson(raw, XincangDtos.OrderResponse.class).rst;
XincangOrderCreateDtos.OrderResult result = json.fromJson(raw, XincangOrderCreateDtos.OrderResponse.class).rst;
if (result == null || blank(result.orderNo)) {
throw WarehouseException.builder()
.message("xincang create order returned no rst.order_no: " + safeRelay(raw))
@ -256,7 +269,8 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa @@ -256,7 +269,8 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
}
String raw = executeGet(ctx, XincangConstants.PATH_ORDER_DETAIL, params, login(ctx),
"warehouse.outbound.get");
XincangDtos.OrderDetail detail = json.fromJson(raw, XincangDtos.OrderDetailResponse.class).rst;
XincangOrderDetailDtos.OrderDetail detail =
json.fromJson(raw, XincangOrderDetailDtos.OrderDetailResponse.class).rst;
if (detail == null) {
throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.outbound.get",
"xincang get_order returned no rst");
@ -361,10 +375,11 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa @@ -361,10 +375,11 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
@Override
public TransferOrder create(WarehouseContext ctx, TransferCommand cmd) {
String productsJson = json.toJson(XincangTransferMapper.products(cmd));
XincangDtos.TransferRequest body = XincangTransferMapper.toRequest(cmd, ctx, productsJson);
XincangTransferCreateDtos.TransferRequest body = XincangTransferMapper.toRequest(cmd, ctx, productsJson);
String raw = execute(ctx, XincangConstants.PATH_TRANSFER_CREATE, body, login(ctx),
"warehouse.transfer.create");
XincangDtos.TransferResult result = json.fromJson(raw, XincangDtos.TransferResponse.class).rst;
XincangTransferCreateDtos.TransferResult result =
json.fromJson(raw, XincangTransferCreateDtos.TransferResponse.class).rst;
if (result == null || blank(result.orderNo)) {
throw WarehouseException.builder()
.message("xincang transfer returned no rst.order_no: " + safeRelay(raw))
@ -409,8 +424,8 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa @@ -409,8 +424,8 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
params.put("order_no", providerTransferNo);
String raw = executeGet(ctx, XincangConstants.PATH_TRANSFER_DETAIL, params, login(ctx),
"warehouse.transfer.get");
XincangDtos.TransferDetail detail =
json.fromJson(raw, XincangDtos.TransferDetailResponse.class).rst;
XincangTransferDetailDtos.TransferDetail detail =
json.fromJson(raw, XincangTransferDetailDtos.TransferDetailResponse.class).rst;
if (detail == null) {
throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.transfer.get",
"xincang fba_detail returned no rst");
@ -447,15 +462,15 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa @@ -447,15 +462,15 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
public List<WarehouseFacility> warehouses(WarehouseContext ctx) {
String raw = executeGet(ctx, XincangConstants.PATH_CUSTOMER_WAREHOUSES,
new LinkedHashMap<String, Object>(), login(ctx), "warehouse.directory.warehouses");
XincangDtos.WarehouseListResult rst =
json.fromJson(raw, XincangDtos.WarehouseListResponse.class).rst;
XincangWarehouseDtos.WarehouseListResult rst =
json.fromJson(raw, XincangWarehouseDtos.WarehouseListResponse.class).rst;
if (rst == null) {
throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.directory.warehouses",
"xincang get_customer_warehouses returned no rst");
}
List<WarehouseFacility> out = new ArrayList<WarehouseFacility>();
if (rst.data != null) {
for (XincangDtos.WarehouseListResult.WarehouseRow row : rst.data) {
for (XincangWarehouseDtos.WarehouseListResult.WarehouseRow row : rst.data) {
if (row == null || XincangForecastMapper.blank(row.warehouseCode)) {
continue;
}
@ -482,15 +497,15 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa @@ -482,15 +497,15 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
public List<String> carriers(WarehouseContext ctx) {
String raw = executeGet(ctx, XincangConstants.PATH_CUSTOMER_LOGISTICS,
new LinkedHashMap<String, Object>(), login(ctx), "warehouse.directory.carriers");
XincangDtos.LogisticsListResult rst =
json.fromJson(raw, XincangDtos.LogisticsListResponse.class).rst;
XincangLogisticsDtos.LogisticsListResult rst =
json.fromJson(raw, XincangLogisticsDtos.LogisticsListResponse.class).rst;
if (rst == null) {
throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.directory.carriers",
"xincang get_customer_logistics returned no rst");
}
List<String> out = new ArrayList<String>();
if (rst.data != null) {
for (XincangDtos.LogisticsListResult.LogisticsRow row : rst.data) {
for (XincangLogisticsDtos.LogisticsListResult.LogisticsRow row : rst.data) {
if (row != null && !XincangForecastMapper.blank(row.logisticsType)) {
out.add(row.logisticsType.trim());
}
@ -509,11 +524,11 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa @@ -509,11 +524,11 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
*/
@Override
public InboundReceipt create(WarehouseContext ctx, InboundCommand cmd) {
XincangDtos.ForecastCreateRequest body = XincangForecastMapper.toCreateRequest(cmd, ctx);
XincangForecastCreateDtos.ForecastCreateRequest body = XincangForecastMapper.toCreateRequest(cmd, ctx);
String raw = execute(ctx, XincangConstants.PATH_FORECAST_CREATE, body, login(ctx),
"warehouse.inbound.create");
XincangDtos.ForecastCreateResult result =
json.fromJson(raw, XincangDtos.ForecastCreateResponse.class).rst;
XincangForecastCreateDtos.ForecastCreateResult result =
json.fromJson(raw, XincangForecastCreateDtos.ForecastCreateResponse.class).rst;
if (result == null || blank(result.orderNo)) {
throw WarehouseException.builder()
.message("xincang forecast returned no rst.order_no: " + safeRelay(raw))
@ -536,7 +551,7 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa @@ -536,7 +551,7 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
@Override
public void improve(WarehouseContext ctx, String inboundRef, InboundCommand cmd) {
String productsJson = json.toJson(XincangForecastMapper.products(cmd));
XincangDtos.ForecastImproveRequest body =
XincangForecastImproveDtos.ForecastImproveRequest body =
XincangForecastMapper.toImproveRequest(cmd, inboundRef, productsJson, ctx);
execute(ctx, XincangConstants.PATH_FORECAST_IMPROVE, body, login(ctx),
"warehouse.inbound.improve");
@ -576,8 +591,8 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa @@ -576,8 +591,8 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
params.put("forecast_no", inboundRef);
String raw = executeGet(ctx, XincangConstants.PATH_FORECAST_DETAIL, params, login(ctx),
"warehouse.inbound.get");
XincangDtos.ForecastDetail detail =
json.fromJson(raw, XincangDtos.ForecastDetailResponse.class).rst;
XincangForecastDetailDtos.ForecastDetail detail =
json.fromJson(raw, XincangForecastDetailDtos.ForecastDetailResponse.class).rst;
if (detail == null) {
throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.inbound.get",
"xincang forecast_detail returned no rst");
@ -624,7 +639,7 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa @@ -624,7 +639,7 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
ctx.providerWarehouseId());
String raw = executeGet(ctx, XincangConstants.PATH_STOCK_LIST, params, login(ctx),
"warehouse.inventory.query");
XincangDtos.StockListResult rst = json.fromJson(raw, XincangDtos.StockListResponse.class).rst;
XincangStockListDtos.StockListResult rst = json.fromJson(raw, XincangStockListDtos.StockListResponse.class).rst;
if (rst == null) {
throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.inventory.query",
"xincang stocklist returned no rst");
@ -646,8 +661,8 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa @@ -646,8 +661,8 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
ctx.providerWarehouseId());
String raw = executeGet(ctx, XincangConstants.PATH_STOCK_AGE_LIST, params, login(ctx),
"warehouse.inventory.ages");
XincangDtos.StockAgeListResult rst =
json.fromJson(raw, XincangDtos.StockAgeListResponse.class).rst;
XincangStockAgeListDtos.StockAgeListResult rst =
json.fromJson(raw, XincangStockAgeListDtos.StockAgeListResponse.class).rst;
if (rst == null) {
throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.inventory.ages",
"xincang stockagelist returned no rst");
@ -669,11 +684,11 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa @@ -669,11 +684,11 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
*/
@Override
public ChannelRecommendResult recommend(WarehouseContext ctx, ChannelRecommendQuery query) {
XincangDtos.CalculateV3Request body = XincangChannelRecommendMapper.toRequest(query);
XincangChannelRecommendDtos.CalculateV3Request body = XincangChannelRecommendMapper.toRequest(query);
String raw = execute(ctx, XincangConstants.PATH_CHANNEL_RECOMMEND, body, login(ctx),
"warehouse.channel.recommend");
XincangDtos.CalculateV3Result rst =
json.fromJson(raw, XincangDtos.CalculateV3Response.class).rst;
XincangChannelRecommendDtos.CalculateV3Result rst =
json.fromJson(raw, XincangChannelRecommendDtos.CalculateV3Response.class).rst;
if (rst == null) {
throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.channel.recommend",
"xincang calculate_order_v3 returned no rst");

25
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangChannelRecommendMapper.java

@ -4,7 +4,7 @@ import common.ecommerce.shared.support.Money; @@ -4,7 +4,7 @@ import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.ChannelRecommendQuery;
import common.ecommerce.warehouse.model.ChannelRecommendResult;
import common.ecommerce.xincang.dto.XincangDtos;
import common.ecommerce.xincang.dto.XincangChannelRecommendDtos;
import java.math.BigDecimal;
import java.util.ArrayList;
@ -32,12 +32,13 @@ public final class XincangChannelRecommendMapper { @@ -32,12 +32,13 @@ public final class XincangChannelRecommendMapper {
}
/** 统一询价条件 → 信仓请求体。 */
public static XincangDtos.CalculateV3Request toRequest(ChannelRecommendQuery query) {
XincangDtos.CalculateV3Request req = new XincangDtos.CalculateV3Request();
List<XincangDtos.CalculateV3Request.Product> products =
new ArrayList<XincangDtos.CalculateV3Request.Product>(query.products().size());
public static XincangChannelRecommendDtos.CalculateV3Request toRequest(ChannelRecommendQuery query) {
XincangChannelRecommendDtos.CalculateV3Request req = new XincangChannelRecommendDtos.CalculateV3Request();
List<XincangChannelRecommendDtos.CalculateV3Request.Product> products =
new ArrayList<XincangChannelRecommendDtos.CalculateV3Request.Product>(query.products().size());
for (ChannelRecommendQuery.SkuQuantity item : query.products()) {
XincangDtos.CalculateV3Request.Product product = new XincangDtos.CalculateV3Request.Product();
XincangChannelRecommendDtos.CalculateV3Request.Product product =
new XincangChannelRecommendDtos.CalculateV3Request.Product();
product.sku = item.sku();
product.qty = String.valueOf(item.quantity());
products.add(product);
@ -52,7 +53,7 @@ public final class XincangChannelRecommendMapper { @@ -52,7 +53,7 @@ public final class XincangChannelRecommendMapper {
}
/** 信仓响应 → 统一结果。 */
public static ChannelRecommendResult toResult(XincangDtos.CalculateV3Result rst) {
public static ChannelRecommendResult toResult(XincangChannelRecommendDtos.CalculateV3Result rst) {
ChannelRecommendResult.Builder builder = ChannelRecommendResult.builder()
.sourceProvider(WarehouseProvider.XINCANG);
if (rst.optimalPlan != null) {
@ -65,7 +66,7 @@ public final class XincangChannelRecommendMapper { @@ -65,7 +66,7 @@ public final class XincangChannelRecommendMapper {
.build());
}
if (rst.warehouseFeeList != null) {
for (XincangDtos.CalculateV3Result.WarehouseFee warehouse : rst.warehouseFeeList) {
for (XincangChannelRecommendDtos.CalculateV3Result.WarehouseFee warehouse : rst.warehouseFeeList) {
// 仓代码是必填主键,缺了这条报价无法归属,直接跳过而不是编一个 "-"
if (warehouse == null || blankToNull(warehouse.warehouse) == null) {
continue;
@ -77,14 +78,14 @@ public final class XincangChannelRecommendMapper { @@ -77,14 +78,14 @@ public final class XincangChannelRecommendMapper {
}
private static ChannelRecommendResult.WarehouseQuote toQuote(
XincangDtos.CalculateV3Result.WarehouseFee warehouse) {
XincangChannelRecommendDtos.CalculateV3Result.WarehouseFee warehouse) {
ChannelRecommendResult.WarehouseQuote.Builder builder =
ChannelRecommendResult.WarehouseQuote.builder()
.warehouseCode(warehouse.warehouse.trim())
.inventoryEnough(parseFlag(warehouse.isInventoryEnough))
.insufficientStockError(blankToNull(warehouse.insufficientStockError));
if (warehouse.logisticsService != null) {
for (XincangDtos.CalculateV3Result.LogisticsService service : warehouse.logisticsService) {
for (XincangChannelRecommendDtos.CalculateV3Result.LogisticsService service : warehouse.logisticsService) {
if (service == null || blankToNull(service.serviceCode) == null) {
continue;
}
@ -95,13 +96,13 @@ public final class XincangChannelRecommendMapper { @@ -95,13 +96,13 @@ public final class XincangChannelRecommendMapper {
}
private static ChannelRecommendResult.ServiceQuote toService(
XincangDtos.CalculateV3Result.LogisticsService service) {
XincangChannelRecommendDtos.CalculateV3Result.LogisticsService service) {
ChannelRecommendResult.ServiceQuote.Builder builder =
ChannelRecommendResult.ServiceQuote.builder()
.serviceCode(service.serviceCode.trim())
.total(parseMoney(service.sum));
if (service.fees != null) {
for (XincangDtos.CalculateV3Result.Fee fee : service.fees) {
for (XincangChannelRecommendDtos.CalculateV3Result.Fee fee : service.fees) {
if (fee == null) {
continue;
}

24
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangForecastMapper.java

@ -11,7 +11,9 @@ import common.ecommerce.warehouse.model.InboundOrder; @@ -11,7 +11,9 @@ import common.ecommerce.warehouse.model.InboundOrder;
import common.ecommerce.warehouse.model.InboundOrderLine;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.xincang.XincangConstants;
import common.ecommerce.xincang.dto.XincangDtos;
import common.ecommerce.xincang.dto.XincangForecastCreateDtos;
import common.ecommerce.xincang.dto.XincangForecastDetailDtos;
import common.ecommerce.xincang.dto.XincangForecastImproveDtos;
import common.ecommerce.xincang.enums.XincangForecastStatus;
import java.time.Instant;
@ -40,9 +42,9 @@ public final class XincangForecastMapper { @@ -40,9 +42,9 @@ public final class XincangForecastMapper {
* <p>信仓必填:目的仓、出运类型、柜型、柜号、参考发货 / 到港时间、发货需求、
* 参考 SKU 种类数。缺一项在下发前就拒绝,避免仓返回难懂的 err。</p>
*/
public static XincangDtos.ForecastCreateRequest toCreateRequest(InboundCommand cmd,
public static XincangForecastCreateDtos.ForecastCreateRequest toCreateRequest(InboundCommand cmd,
WarehouseContext ctx) {
XincangDtos.ForecastCreateRequest req = new XincangDtos.ForecastCreateRequest();
XincangForecastCreateDtos.ForecastCreateRequest req = new XincangForecastCreateDtos.ForecastCreateRequest();
req.destWarehouse = require(cmd.warehouseId(), "warehouseId (dest_warehouse)", ctx);
req.shipmentType = require(cmd.shipmentType(), "shipmentType", ctx);
req.cabinetType = require(cmd.cabinetType(), "cabinetType", ctx);
@ -75,14 +77,14 @@ public final class XincangForecastMapper { @@ -75,14 +77,14 @@ public final class XincangForecastMapper {
* @param forecastNo 新增预报返回的 {@code order_no}
* @param productsJson 商品明细 JSON 字符串
*/
public static XincangDtos.ForecastImproveRequest toImproveRequest(InboundCommand cmd,
public static XincangForecastImproveDtos.ForecastImproveRequest toImproveRequest(InboundCommand cmd,
String forecastNo,
String productsJson,
WarehouseContext ctx) {
if (cmd.lines().isEmpty()) {
throw validation(ctx, "xincang improve_forecast requires at least one product line");
}
XincangDtos.ForecastImproveRequest req = new XincangDtos.ForecastImproveRequest();
XincangForecastImproveDtos.ForecastImproveRequest req = new XincangForecastImproveDtos.ForecastImproveRequest();
req.forecastNo = require(forecastNo, "forecastNo", ctx);
req.destWarehouse = require(cmd.warehouseId(), "warehouseId (dest_warehouse)", ctx);
req.shipmentType = require(cmd.shipmentType(), "shipmentType", ctx);
@ -111,11 +113,11 @@ public final class XincangForecastMapper { @@ -111,11 +113,11 @@ public final class XincangForecastMapper {
* 按「一箱一件」兜底({@code box_count = sku_count});装箱率不同的场景
* 需要调用方在 {@code InboundCarton} 里显式给出,本轮不做更细的拆分。</p>
*/
public static List<XincangDtos.ForecastProduct> products(InboundCommand cmd) {
List<XincangDtos.ForecastProduct> products =
new ArrayList<XincangDtos.ForecastProduct>(cmd.lines().size());
public static List<XincangForecastImproveDtos.ForecastProduct> products(InboundCommand cmd) {
List<XincangForecastImproveDtos.ForecastProduct> products =
new ArrayList<XincangForecastImproveDtos.ForecastProduct>(cmd.lines().size());
for (InboundLine line : cmd.lines()) {
XincangDtos.ForecastProduct product = new XincangDtos.ForecastProduct();
XincangForecastImproveDtos.ForecastProduct product = new XincangForecastImproveDtos.ForecastProduct();
product.productNo = line.providerSku() == null ? line.omsSku() : line.providerSku();
product.skuCount = String.valueOf(line.quantity());
product.boxCount = String.valueOf(line.quantity());
@ -130,11 +132,11 @@ public final class XincangForecastMapper { @@ -130,11 +132,11 @@ public final class XincangForecastMapper {
* <p>双号:{@code forecast_no} 既作仓侧单号也作业务单号兜底——
* 信仓的 {@code ref_no} 可能为空。</p>
*/
public static InboundOrder toOrder(XincangDtos.ForecastDetail detail, WarehouseContext ctx) {
public static InboundOrder toOrder(XincangForecastDetailDtos.ForecastDetail detail, WarehouseContext ctx) {
InboundStatus status = XincangForecastStatus.toCore(detail.state);
List<InboundOrderLine> lines = new ArrayList<InboundOrderLine>();
if (detail.products != null) {
for (XincangDtos.ForecastDetailProduct product : detail.products) {
for (XincangForecastDetailDtos.ForecastDetailProduct product : detail.products) {
if (product == null || blank(product.productNo)) {
continue;
}

13
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java

@ -7,7 +7,8 @@ import common.ecommerce.warehouse.model.InventoryAgeRecord; @@ -7,7 +7,8 @@ import common.ecommerce.warehouse.model.InventoryAgeRecord;
import common.ecommerce.warehouse.model.InventoryQuery;
import common.ecommerce.warehouse.model.InventorySnapshot;
import common.ecommerce.xincang.XincangConstants;
import common.ecommerce.xincang.dto.XincangDtos;
import common.ecommerce.xincang.dto.XincangStockAgeListDtos;
import common.ecommerce.xincang.dto.XincangStockListDtos;
import java.math.BigDecimal;
import java.time.Instant;
@ -28,7 +29,7 @@ import java.util.Map; @@ -28,7 +29,7 @@ import java.util.Map;
* <li>库龄列表 {@code GET api.stockagelist}</li>
* </ul>
*
* <p>平台字段名只出现在本类与 {@link XincangDtos};时间按北京时间解析成 UTC。</p>
* <p>平台字段名只出现在本类与 {@code dto} 包下的各 {@code Xincang*Dtos};时间按北京时间解析成 UTC。</p>
*/
public final class XincangInventoryMapper {
@ -79,14 +80,14 @@ public final class XincangInventoryMapper { @@ -79,14 +80,14 @@ public final class XincangInventoryMapper {
}
/** 库存响应 → 快照分页。 */
public static Page<InventorySnapshot> toSnapshots(XincangDtos.StockListResult rst,
public static Page<InventorySnapshot> toSnapshots(XincangStockListDtos.StockListResult rst,
String fallbackWarehouseCode,
Instant asOf,
int currentPage,
int pageSize) {
List<InventorySnapshot> out = new ArrayList<InventorySnapshot>();
if (rst != null && rst.data != null) {
for (XincangDtos.StockListResult.StockRow row : rst.data) {
for (XincangStockListDtos.StockListResult.StockRow row : rst.data) {
if (row == null || blank(row.productSku)) {
continue;
}
@ -128,13 +129,13 @@ public final class XincangInventoryMapper { @@ -128,13 +129,13 @@ public final class XincangInventoryMapper {
}
/** 库龄响应 → 记录分页。 */
public static Page<InventoryAgeRecord> toAgeRecords(XincangDtos.StockAgeListResult rst,
public static Page<InventoryAgeRecord> toAgeRecords(XincangStockAgeListDtos.StockAgeListResult rst,
String fallbackWarehouseCode,
int currentPage,
int pageSize) {
List<InventoryAgeRecord> out = new ArrayList<InventoryAgeRecord>();
if (rst != null && rst.data != null) {
for (XincangDtos.StockAgeListResult.AgeRow row : rst.data) {
for (XincangStockAgeListDtos.StockAgeListResult.AgeRow row : rst.data) {
if (row == null || blank(row.productSku)) {
continue;
}

12
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java

@ -9,7 +9,7 @@ import common.ecommerce.warehouse.model.OutboundOrder; @@ -9,7 +9,7 @@ import common.ecommerce.warehouse.model.OutboundOrder;
import common.ecommerce.warehouse.model.ShipTo;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.xincang.XincangConstants;
import common.ecommerce.xincang.dto.XincangDtos;
import common.ecommerce.xincang.dto.XincangOrderDetailDtos;
import common.ecommerce.xincang.enums.XincangOrderStatus;
import java.time.Instant;
@ -23,7 +23,7 @@ import java.util.List; @@ -23,7 +23,7 @@ import java.util.List;
/**
* 信仓订单详情报文 → 统一模型({@code GET api.get_order})。
*
* <p>平台字段名只出现在本类与 {@link XincangDtos}。
* <p>平台字段名只出现在本类与 {@code XincangOrderDetailDtos}。
* 时间字段是北京时间 {@code yyyy-MM-dd HH:mm:ss},统一折算成 UTC。</p>
*/
public final class XincangOrderDetailMapper {
@ -42,7 +42,7 @@ public final class XincangOrderDetailMapper { @@ -42,7 +42,7 @@ public final class XincangOrderDetailMapper {
* @param detail 详情;调用方保证非 null
* @param ctx 本次调用上下文(仓编码兜底)
*/
public static OutboundOrder toOrder(XincangDtos.OrderDetail detail, WarehouseContext ctx) {
public static OutboundOrder toOrder(XincangOrderDetailDtos.OrderDetail detail, WarehouseContext ctx) {
OutboundStatus status = XincangOrderStatus.toCore(detail.state);
return OutboundOrder.builder()
.warehouseCode(firstNonBlank(detail.warehouseCode, ctx.providerWarehouseId()))
@ -108,11 +108,11 @@ public final class XincangOrderDetailMapper { @@ -108,11 +108,11 @@ public final class XincangOrderDetailMapper {
* 单值字段;前者非空时以它为准,为空才退回单值字段。数量缺失或非正的行直接跳过——
* {@link OutboundLine} 要求数量为正,保留会在构造期抛异常。</p>
*/
static List<OutboundLine> toLines(XincangDtos.OrderDetail detail) {
static List<OutboundLine> toLines(XincangOrderDetailDtos.OrderDetail detail) {
List<OutboundLine> lines = new ArrayList<OutboundLine>();
if (detail.products != null && !detail.products.isEmpty()) {
int index = 0;
for (XincangDtos.OrderDetailProduct product : detail.products) {
for (XincangOrderDetailDtos.OrderDetailProduct product : detail.products) {
if (product == null || blank(product.sku)) {
continue;
}
@ -144,7 +144,7 @@ public final class XincangOrderDetailMapper { @@ -144,7 +144,7 @@ public final class XincangOrderDetailMapper {
return lines;
}
private static ShipTo toShipTo(XincangDtos.OrderDetail detail) {
private static ShipTo toShipTo(XincangOrderDetailDtos.OrderDetail detail) {
if (blank(detail.country) && blank(detail.address) && blank(detail.receiveUser)) {
return null;
}

9
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java

@ -10,7 +10,7 @@ import common.ecommerce.warehouse.model.OutboundLine; @@ -10,7 +10,7 @@ import common.ecommerce.warehouse.model.OutboundLine;
import common.ecommerce.warehouse.model.ShipTo;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.xincang.XincangConstants;
import common.ecommerce.xincang.dto.XincangDtos;
import common.ecommerce.xincang.dto.XincangOrderCreateDtos;
import common.ecommerce.xincang.enums.XincangOrderType;
import java.time.Instant;
@ -25,7 +25,7 @@ import java.util.Map; @@ -25,7 +25,7 @@ import java.util.Map;
* 信仓出库下单报文映射({@code POST api.add_order_multiple})。
*
* <p>该接口是 {@code multipart/form-data},{@code products} 字段本身是一段 JSON 字符串。
* 平台字段名只出现在本类与 {@link XincangDtos}。</p>
* 平台字段名只出现在本类与 {@code XincangOrderCreateDtos}。</p>
*
* <p>文档没有对应字段的就不发:申报信息(HS / 原产国 / 申报价值)、包裹尺寸等
* 统一模型里有,但信仓这版接口不收,硬塞只会被忽略或报错。</p>
@ -120,9 +120,10 @@ public final class XincangOrderMapper { @@ -120,9 +120,10 @@ public final class XincangOrderMapper {
/** 商品明细:{@code [{"product_sku":"...","sku_count":"1"}, ...]}。 */
static String productsJson(List<OutboundLine> lines, JsonCodec json) {
List<XincangDtos.OrderProduct> products = new ArrayList<XincangDtos.OrderProduct>(lines.size());
List<XincangOrderCreateDtos.OrderProduct> products =
new ArrayList<XincangOrderCreateDtos.OrderProduct>(lines.size());
for (OutboundLine line : lines) {
XincangDtos.OrderProduct product = new XincangDtos.OrderProduct();
XincangOrderCreateDtos.OrderProduct product = new XincangOrderCreateDtos.OrderProduct();
product.productSku = skuOf(line);
product.skuCount = String.valueOf(line.quantity());
products.add(product);

8
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java

@ -3,7 +3,7 @@ package common.ecommerce.xincang.adapter; @@ -3,7 +3,7 @@ package common.ecommerce.xincang.adapter;
import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.xincang.XincangConstants;
import common.ecommerce.xincang.dto.XincangDtos;
import common.ecommerce.xincang.dto.XincangProductSaveDtos;
import java.math.BigDecimal;
import java.math.RoundingMode;
@ -11,7 +11,7 @@ import java.math.RoundingMode; @@ -11,7 +11,7 @@ import java.math.RoundingMode;
/**
* 信仓商品报文映射({@code POST api.add_product} / {@code api.update_product})。
*
* <p>平台字段名只出现在本类与 {@link XincangDtos}。单位换算也在这里:
* <p>平台字段名只出现在本类与 {@code XincangProductSaveDtos}。单位换算也在这里:
* 统一模型用 cm / g,信仓用 inch / lbs,按 {@link XincangConstants} 里的常量换算并保留 4 位小数
* (文档「最长四位小数」)。</p>
*
@ -40,8 +40,8 @@ public final class XincangProductMapper { @@ -40,8 +40,8 @@ public final class XincangProductMapper {
* @param token 业务令牌;两个接口的请求体都要求
* @throws IllegalArgumentException 申报价值不是美元(信仓 amount 固定 USD)
*/
public static XincangDtos.ProductRequest toRequest(WarehouseProduct product, String token) {
XincangDtos.ProductRequest req = new XincangDtos.ProductRequest();
public static XincangProductSaveDtos.ProductRequest toRequest(WarehouseProduct product, String token) {
XincangProductSaveDtos.ProductRequest req = new XincangProductSaveDtos.ProductRequest();
req.token = token;
req.productNo = skuOf(product);
req.chnName = product.name();

12
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java

@ -4,7 +4,7 @@ import common.ecommerce.warehouse.enums.TransferStatus; @@ -4,7 +4,7 @@ import common.ecommerce.warehouse.enums.TransferStatus;
import common.ecommerce.warehouse.enums.TransferType;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.xincang.dto.XincangDtos;
import common.ecommerce.xincang.dto.XincangTransferDetailDtos;
import common.ecommerce.xincang.enums.XincangTransferState;
/**
@ -22,7 +22,7 @@ public final class XincangTransferDetailMapper { @@ -22,7 +22,7 @@ public final class XincangTransferDetailMapper {
*
* @param detail 详情;调用方保证非 null
*/
public static TransferOrder toOrder(XincangDtos.TransferDetail detail) {
public static TransferOrder toOrder(XincangTransferDetailDtos.TransferDetail detail) {
TransferStatus status = XincangTransferState.toCore(detail.state);
return TransferOrder.builder()
// 双号:fba_no 是业务侧单号,order_no 是仓侧单号
@ -69,13 +69,13 @@ public final class XincangTransferDetailMapper { @@ -69,13 +69,13 @@ public final class XincangTransferDetailMapper {
}
/** 转运明细行 → 统一模型。 */
static java.util.List<TransferOrder.TransferLine> toLines(XincangDtos.TransferDetail detail) {
static java.util.List<TransferOrder.TransferLine> toLines(XincangTransferDetailDtos.TransferDetail detail) {
if (detail.products == null || detail.products.isEmpty()) {
return java.util.Collections.emptyList();
}
java.util.List<TransferOrder.TransferLine> out =
new java.util.ArrayList<TransferOrder.TransferLine>(detail.products.size());
for (XincangDtos.TransferDetailProduct product : detail.products) {
for (XincangTransferDetailDtos.TransferDetailProduct product : detail.products) {
if (product == null || XincangOrderDetailMapper.blank(product.productNo)) {
continue;
}
@ -96,12 +96,12 @@ public final class XincangTransferDetailMapper { @@ -96,12 +96,12 @@ public final class XincangTransferDetailMapper {
}
/** 明细件数合计;明细缺失时返回 0(未知,不猜)。 */
static int totalQuantityOf(XincangDtos.TransferDetail detail) {
static int totalQuantityOf(XincangTransferDetailDtos.TransferDetail detail) {
if (detail.products == null || detail.products.isEmpty()) {
return 0;
}
int total = 0;
for (XincangDtos.TransferDetailProduct product : detail.products) {
for (XincangTransferDetailDtos.TransferDetailProduct product : detail.products) {
if (product != null) {
total += XincangOrderDetailMapper.parsePositiveInt(product.skuCount);
}

25
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java

@ -8,7 +8,8 @@ import common.ecommerce.warehouse.model.TransferCommand; @@ -8,7 +8,8 @@ import common.ecommerce.warehouse.model.TransferCommand;
import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.enums.TransferType;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.xincang.dto.XincangDtos;
import common.ecommerce.xincang.dto.XincangTransferCreateDtos;
import common.ecommerce.xincang.dto.XincangUploadDtos;
import common.ecommerce.xincang.enums.XincangTransferState;
import java.time.LocalDate;
@ -38,13 +39,13 @@ public final class XincangTransferMapper { @@ -38,13 +39,13 @@ public final class XincangTransferMapper {
}
/** 统一命令 → 信仓新增转运请求。 */
public static XincangDtos.TransferRequest toRequest(TransferCommand cmd, WarehouseContext ctx,
public static XincangTransferCreateDtos.TransferRequest toRequest(TransferCommand cmd, WarehouseContext ctx,
String productsJson) {
if (cmd.type() != TransferType.OUTBOUND) {
throw validation(ctx, "xincang transfer only supports OUTBOUND (warehouse -> platform), got "
+ cmd.type());
}
XincangDtos.TransferRequest req = new XincangDtos.TransferRequest();
XincangTransferCreateDtos.TransferRequest req = new XincangTransferCreateDtos.TransferRequest();
req.fbaNo = cmd.transferRequestNo();
req.po = firstNonBlank(cmd.po(), cmd.transferRequestNo());
req.fromWarehouseName = require(cmd.fromWarehouseCode(),
@ -80,11 +81,11 @@ public final class XincangTransferMapper { @@ -80,11 +81,11 @@ public final class XincangTransferMapper {
}
/** 统一附件 → 信仓附件报文;null 透传(不发)。 */
private static XincangDtos.Attachment attachment(TransferAttachment source) {
private static XincangUploadDtos.Attachment attachment(TransferAttachment source) {
if (source == null) {
return null;
}
XincangDtos.Attachment target = new XincangDtos.Attachment();
XincangUploadDtos.Attachment target = new XincangUploadDtos.Attachment();
target.type = source.type();
target.bucket = source.bucket();
target.fileName = source.fileName();
@ -95,13 +96,13 @@ public final class XincangTransferMapper { @@ -95,13 +96,13 @@ public final class XincangTransferMapper {
}
/** 附件列表;空列表返回 null(不发空数组)。 */
private static List<XincangDtos.Attachment> attachments(List<TransferAttachment> sources) {
private static List<XincangUploadDtos.Attachment> attachments(List<TransferAttachment> sources) {
if (sources == null || sources.isEmpty()) {
return null;
}
List<XincangDtos.Attachment> out = new ArrayList<XincangDtos.Attachment>(sources.size());
List<XincangUploadDtos.Attachment> out = new ArrayList<XincangUploadDtos.Attachment>(sources.size());
for (TransferAttachment source : sources) {
XincangDtos.Attachment target = attachment(source);
XincangUploadDtos.Attachment target = attachment(source);
if (target != null) {
out.add(target);
}
@ -126,11 +127,11 @@ public final class XincangTransferMapper { @@ -126,11 +127,11 @@ public final class XincangTransferMapper {
}
/** 产品明细:{@code [{"product_no":"SKU","sku_count":"1"}]}。 */
public static List<XincangDtos.TransferProduct> products(TransferCommand cmd) {
List<XincangDtos.TransferProduct> products =
new ArrayList<XincangDtos.TransferProduct>(cmd.lines().size());
public static List<XincangTransferCreateDtos.TransferProduct> products(TransferCommand cmd) {
List<XincangTransferCreateDtos.TransferProduct> products =
new ArrayList<XincangTransferCreateDtos.TransferProduct>(cmd.lines().size());
for (TransferCommand.TransferLine line : cmd.lines()) {
XincangDtos.TransferProduct product = new XincangDtos.TransferProduct();
XincangTransferCreateDtos.TransferProduct product = new XincangTransferCreateDtos.TransferProduct();
product.productNo = line.providerSku();
product.skuCount = String.valueOf(line.quantity());
product.fnSku = blankToNull(line.fulfillmentSku());

6
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/auth/XincangTokenClient.java

@ -8,7 +8,7 @@ import common.ecommerce.shared.error.ValidationException; @@ -8,7 +8,7 @@ import common.ecommerce.shared.error.ValidationException;
import common.ecommerce.shared.spi.AccessToken;
import common.ecommerce.warehouse.error.WarehouseException;
import common.ecommerce.xincang.XincangConstants;
import common.ecommerce.xincang.dto.XincangDtos;
import common.ecommerce.xincang.dto.XincangLoginDtos;
import common.ecommerce.xincang.http.XincangEnvelope;
import common.ecommerce.xincang.http.XincangRateLimiter;
import common.ecommerce.xincang.http.XincangRequestFactory;
@ -70,8 +70,8 @@ public final class XincangTokenClient { @@ -70,8 +70,8 @@ public final class XincangTokenClient {
HttpResponse resp = transport.execute(req);
XincangEnvelope envelope = XincangEnvelope.of(resp, json, OP_FETCH, null);
XincangDtos.LoginResponse login = json.fromJson(envelope.body(), XincangDtos.LoginResponse.class);
XincangDtos.LoginResult result = login == null ? null : login.rst;
XincangLoginDtos.LoginResponse login = json.fromJson(envelope.body(), XincangLoginDtos.LoginResponse.class);
XincangLoginDtos.LoginResult result = login == null ? null : login.rst;
String token = result == null ? null : result.token;
if (token == null || token.trim().isEmpty()) {

144
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangChannelRecommendDtos.java

@ -0,0 +1,144 @@ @@ -0,0 +1,144 @@
package common.ecommerce.xincang.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* 信仓报文结构:最优渠道({@code POST api.calculate_order_v3})。
*/
public final class XincangChannelRecommendDtos {
private XincangChannelRecommendDtos() {
}
/**
* 最优渠道请求({@code GET api.calculate_order_v3} 的 JSON body)。
*
* <p>文档写的是 GET + {@code application/json} body;信仓其它 GET 都是 query,
* 这里按文档原样用 JSON body。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class CalculateV3Request {
/** 产品信息;必填。 */
@JsonProperty("products")
public List<Product> products;
/** 邮编;必填。 */
@JsonProperty("postcode")
public String postcode;
/** 是否签名:是 / 否;必填。 */
@JsonProperty("is_sign")
public String isSign;
/** 仓库代码;不传由仓择优。 */
@JsonProperty("warehouse_code")
public String warehouseCode;
/** 一行商品。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class Product {
/** 产品 SKU。 */
@JsonProperty("sku")
public String sku;
/** 件数(字符串)。 */
@JsonProperty("qty")
public String qty;
}
}
/** 最优渠道响应 {@code rst}。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class CalculateV3Result {
/** 最优方案;无可用渠道时为 null。 */
@JsonProperty("optimalPlan")
public OptimalPlan optimalPlan;
/** 所有仓库的报价。 */
@JsonProperty("warehouseFeeList")
public List<WarehouseFee> warehouseFeeList;
/** 最优方案。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class OptimalPlan {
@JsonProperty("warehouse")
public String warehouse;
/** 物流方式(渠道码)。 */
@JsonProperty("service_code")
public String serviceCode;
/** 总费用。 */
@JsonProperty("sum")
public String sum;
}
/** 单个仓库的费用列表。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class WarehouseFee {
@JsonProperty("warehouse")
public String warehouse;
/** 库存是否足够:1 够 / 0 不够。 */
@JsonProperty("isInventoryEnough")
public String isInventoryEnough;
/** 库存不足原因。 */
@JsonProperty("insufficientStockError")
public String insufficientStockError;
/** 该仓下的渠道报价。 */
@JsonProperty("logisticsService")
public List<LogisticsService> logisticsService;
}
/** 单个物流渠道的报价。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class LogisticsService {
@JsonProperty("service_code")
public String serviceCode;
/** 总费用。 */
@JsonProperty("sum")
public String sum;
/** 费用明细。 */
@JsonProperty("fees")
public List<Fee> fees;
}
/** 一条费用明细。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class Fee {
/** 一级分类,如「快递费」。 */
@JsonProperty("big_fee_type")
public String bigFeeType;
/** 费用项,如「燃油附加费」。 */
@JsonProperty("fee_type")
public String feeType;
/** 费用。 */
@JsonProperty("customer_fee")
public String customerFee;
}
}
/** 最优渠道响应外层。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class CalculateV3Response {
@JsonProperty("rst")
public CalculateV3Result rst;
}
}

1601
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java

File diff suppressed because it is too large Load Diff

104
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangForecastCreateDtos.java

@ -0,0 +1,104 @@ @@ -0,0 +1,104 @@
package common.ecommerce.xincang.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* 信仓报文结构:新增预报({@code POST forecast.do_forecast}):只建单,不带商品明细。
*/
public final class XincangForecastCreateDtos {
private XincangForecastCreateDtos() {
}
/**
* 新增预报请求({@code POST forecast.do_forecast})。
*
* <p>只建单,不带商品明细;明细走「完善资料」。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ForecastCreateRequest {
/**
* 客户 id。
*
* <p>文档标注<b>已舍弃</b>,SDK 不填;保留占位以与文档字段表对齐。</p>
*/
@JsonProperty("customer_id")
@Deprecated
public String customerId;
/** 目的地仓。 */
@JsonProperty("dest_warehouse")
public String destWarehouse;
/** 出运类型:1 空运 / 2 海运。 */
@JsonProperty("shipment_type")
public String shipmentType;
/** 柜型:0 20GP / 1 40GP / 2 40HQ / 3 45HQ / 4 纸箱入库 / 5 托盘入库。 */
@JsonProperty("cabinet_type")
public String cabinetType;
/** 柜号。 */
@JsonProperty("cabinet_no")
public String cabinetNo;
/** 参考发货时间。 */
@JsonProperty("rfc_etd")
public String rfcEtd;
/** 参考到港时间。 */
@JsonProperty("rfc_eta")
public String rfcEta;
/** 发货需求:1 一件代发 / 2 FBA 中转。 */
@JsonProperty("delivery_requirements")
public String deliveryRequirements;
/** 参考 SKU 种类数量。 */
@JsonProperty("rfc_sku_count")
public String rfcSkuCount;
/** 中文名称。 */
@JsonProperty("chn_name")
public String chnName;
/** 是否超 120cm:1 是 / 0 否。 */
@JsonProperty("is_oversize")
public String isOversize;
/** 超尺寸备注。 */
@JsonProperty("oversize_val")
public String oversizeVal;
@JsonProperty("remark")
public String remark;
/** 船务公司 id。 */
@JsonProperty("shipping_company_id")
public String shippingCompanyId;
/** 预报托盘数;柜型为托盘入库时填。 */
@JsonProperty("forecast_pallet_qty")
public String forecastPalletQty;
}
/** 新增预报响应 {@code rst}。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ForecastCreateResult {
/** 预报单号;完善资料与提交都用它。 */
@JsonProperty("order_no")
public String orderNo;
}
/** 新增预报响应外层。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ForecastCreateResponse {
@JsonProperty("rst")
public ForecastCreateResult rst;
}
}

222
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangForecastDetailDtos.java

@ -0,0 +1,222 @@ @@ -0,0 +1,222 @@
package common.ecommerce.xincang.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* 信仓报文结构:预报详情({@code GET forecast.forecast_detail})。
*/
public final class XincangForecastDetailDtos {
private XincangForecastDetailDtos() {
}
/**
* 预报详情({@code GET forecast.forecast_detail})的 {@code rst}。
*
* <p>时间字段是北京时间。</p>
*/
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ForecastDetail {
/** 预报单 id。 */
@JsonProperty("id")
public String id;
@JsonProperty("forecast_no")
public String forecastNo;
/** 中文名称。 */
@JsonProperty("chn_name")
public String chnName;
/** 客户 id。 */
@JsonProperty("customer_id")
public String customerId;
/** 客户代码。 */
@JsonProperty("customer_name")
public String customerName;
/** 目的仓 id / 代码。 */
@JsonProperty("dest_warehouse")
public String destWarehouseId;
@JsonProperty("dest_warehouse_name")
public String destWarehouseName;
/** 出运类型。 */
@JsonProperty("shipment_type")
public String shipmentType;
/** 参考编号。 */
@JsonProperty("ref_no")
public String refNo;
/** 柜型 / 柜号。 */
@JsonProperty("cabinet_type")
public String cabinetType;
@JsonProperty("cabinet_no")
public String cabinetNo;
/** 预计发货 / 到港时间。 */
@JsonProperty("rfc_etd")
public String rfcEtd;
@JsonProperty("rfc_eta")
public String rfcEta;
/** 实际发货 / 到港时间。 */
@JsonProperty("etd")
public String etd;
@JsonProperty("eta")
public String eta;
/** 是否超 120cm。 */
@JsonProperty("is_oversize")
public String isOversize;
@JsonProperty("oversize_val")
public String oversizeVal;
/** 发货需求。 */
@JsonProperty("delivery_requirements")
public String deliveryRequirements;
/** 预报时间。 */
@JsonProperty("forecast_time")
public String forecastTime;
/** 参考 SKU 种类数。 */
@JsonProperty("rfc_sku_count")
public String rfcSkuCount;
@JsonProperty("remark")
public String remark;
/** 托盘数:预报 / 实收 / 上架 / 计费。 */
@JsonProperty("forecast_pallet_qty")
public String forecastPalletQty;
@JsonProperty("receive_pallet_qty")
public String receivePalletQty;
@JsonProperty("shelf_pallet_qty")
public String shelfPalletQty;
@JsonProperty("bill_pallet_qty")
public String billPalletQty;
/** 到仓 / 卸柜清点 / 清点完成 / 上架 / 还柜时间。 */
@JsonProperty("receive_time")
public String receiveTime;
@JsonProperty("unlade_time")
public String unladeTime;
@JsonProperty("check_time")
public String checkTime;
@JsonProperty("putaway_time")
public String putawayTime;
@JsonProperty("leave_time")
public String leaveTime;
/** 是否需要内箱贴 / 外箱贴:1 是 / 0 否。 */
@JsonProperty("is_inner_box_sticker")
public String isInnerBoxSticker;
@JsonProperty("is_outer_box_sticker")
public String isOuterBoxSticker;
@JsonProperty("other_need")
public String otherNeed;
@JsonProperty("gmt_create")
public String gmtCreate;
@JsonProperty("gmt_modify")
public String gmtModify;
/** 预报状态码,见 {@code XincangForecastStatus}。 */
@JsonProperty("state")
public String state;
@JsonProperty("state_name")
public String stateName;
@JsonProperty("products")
public List<ForecastDetailProduct> products;
}
/** 预报详情里的产品行。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ForecastDetailProduct {
@JsonProperty("product_no")
public String productNo;
@JsonProperty("product_name")
public String productName;
/** 件数。 */
@JsonProperty("sku_count")
public String skuCount;
/** 箱数。 */
@JsonProperty("box_count")
public String boxCount;
/** 清点箱数。 */
@JsonProperty("check_box_qty")
public String checkBoxQty;
/** 打托件数 / 上架件数。 */
@JsonProperty("pallet_sku_count")
public String palletSkuCount;
@JsonProperty("put_on_sku_count")
public String putOnSkuCount;
/** 装箱率。 */
@JsonProperty("packing_rate")
public String packingRate;
/** 体积(立方厘米)。 */
@JsonProperty("volume_cm")
public String volumeCm;
/** 中文名。 */
@JsonProperty("chn_name")
public String chnName;
/** 英文名。 */
@JsonProperty("en_name")
public String enName;
/** 体积(立方英寸)。 */
@JsonProperty("volume_ln")
public String volumeLn;
/** 长(厘米)。 */
@JsonProperty("size_l_cm")
public String sizeLCm;
/** 宽(厘米)。 */
@JsonProperty("size_w_cm")
public String sizeWCm;
/** 高(厘米)。 */
@JsonProperty("size_h_cm")
public String sizeHCm;
/** 长(英寸)。 */
@JsonProperty("size_l_ln")
public String sizeLLn;
/** 宽(英寸)。 */
@JsonProperty("size_w_ln")
public String sizeWLn;
/** 高(英寸)。 */
@JsonProperty("size_h_ln")
public String sizeHLn;
/** 预报产品创建时间。 */
@JsonProperty("gmt_create")
public String gmtCreate;
/** 预报产品最后修改时间。 */
@JsonProperty("gmt_modify")
public String gmtModify;
}
/** 预报详情响应外层。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ForecastDetailResponse {
@JsonProperty("rst")
public ForecastDetail rst;
}
}

150
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangForecastImproveDtos.java

@ -0,0 +1,150 @@ @@ -0,0 +1,150 @@
package common.ecommerce.xincang.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* 信仓报文结构:完善预报资料({@code POST forecast.do_improve_forecast}):商品明细整段覆盖。
*/
public final class XincangForecastImproveDtos {
private XincangForecastImproveDtos() {
}
/**
* 完善预报资料请求({@code POST forecast.do_improve_forecast})。
*
* <p>{@code products} 是一段 JSON 字符串,新数据直接覆盖旧数据。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ForecastImproveRequest {
/**
* 预报单 id。
*
* <p>文档标注<b>已舍弃</b>,SDK 不填;保留占位以与文档字段表对齐。</p>
*/
@JsonProperty("id")
@Deprecated
public String id;
/**
* 客户 id。
*
* <p>文档标注<b>已舍弃</b>,SDK 不填。</p>
*/
@JsonProperty("customer_id")
@Deprecated
public String customerId;
@JsonProperty("forecast_no")
public String forecastNo;
@JsonProperty("dest_warehouse")
public String destWarehouse;
@JsonProperty("shipment_type")
public String shipmentType;
/** 参考编号,长度上限 32。 */
@JsonProperty("ref_no")
public String refNo;
/**
* 新增预报柜号。
*
* <p>文档标注<b>已舍弃</b>,SDK 不填。</p>
*/
@JsonProperty("old_cabinet_no")
@Deprecated
public String oldCabinetNo;
/** 柜型:0 20GP / 1 40GP / 2 40HQ / 3 45HQ / 4 纸箱入库 / 5 托盘入库。 */
@JsonProperty("cabinet_type")
public String cabinetType;
/** 柜号。 */
@JsonProperty("cabinet_no")
public String cabinetNo;
/** 发货时间。 */
@JsonProperty("etd")
public String etd;
/** 到港时间。 */
@JsonProperty("eta")
public String eta;
/**
* 最晚免费时间(提柜)。
*
* <p>文档标注<b>已舍弃</b>,SDK 不填。</p>
*/
@JsonProperty("lfd")
@Deprecated
public String lfd;
@JsonProperty("delivery_requirements")
public String deliveryRequirements;
@JsonProperty("remark")
public String remark;
/** 其他需求,如 内箱贴,外箱贴。 */
@JsonProperty("other_need")
public String otherNeed;
/**
* 总件数。
*
* <p>文档标注<b>已舍弃</b>(由 {@code products} 汇总),SDK 不填。</p>
*/
@JsonProperty("sku_count_sum")
@Deprecated
public String skuCountSum;
/**
* 总箱数。
*
* <p>文档标注<b>已舍弃</b>(由 {@code products} 汇总),SDK 不填。</p>
*/
@JsonProperty("box_count_sum")
@Deprecated
public String boxCountSum;
/** 产品明细 JSON 字符串。 */
@JsonProperty("products")
public String products;
/** 船务公司 id;通过【获取船务公司】接口取得。 */
@JsonProperty("shipping_company_id")
public String shippingCompanyId;
/** 预报托盘数;柜型为托盘入库时填写。 */
@JsonProperty("forecast_pallet_qty")
public String forecastPalletQty;
}
/** 完善资料里的产品行(序列化进 {@code products} 字符串)。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ForecastProduct {
@JsonProperty("product_no")
public String productNo;
/** 件数。 */
@JsonProperty("sku_count")
public String skuCount;
/** 箱数。 */
@JsonProperty("box_count")
public String boxCount;
/** 批次号;可选。 */
@JsonProperty("batch_no")
public String batchNo;
@JsonProperty("remark")
public String remark;
}
}

64
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangLoginDtos.java

@ -0,0 +1,64 @@ @@ -0,0 +1,64 @@
package common.ecommerce.xincang.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* 信仓报文结构:登录({@code GET /api.login}):换取客户级 token。
*/
public final class XincangLoginDtos {
private XincangLoginDtos() {
}
/**
* 登录响应({@code GET /api.login})。
*
* <p>注意与业务接口不同:登录的 {@code rst} <b>没有</b> {@code code/msg/data} 包裹,
* 而是直接给出客户与 token 字段。</p>
*/
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class LoginResponse {
/** 登录结果;业务失败时可能为 null。 */
@JsonProperty("rst")
public LoginResult rst;
/** 0 表示成功。 */
@JsonProperty("errno")
public Integer errno;
/** 错误描述;成功时为空串。 */
@JsonProperty("err")
public String err;
/** 信仓侧链路号。 */
@JsonProperty("trace_id")
public String traceId;
}
/** 登录结果的 {@code rst} 部分。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class LoginResult {
/** 客户 id。 */
@JsonProperty("id")
public String customerId;
/** 回显的 APIKEY,正常等于登录用的 appkey。 */
@JsonProperty("api_client_id")
public String apiClientId;
/** 回显的 APISECRET;不需要也不应落盘,仅用于排障时核对身份。 */
@JsonProperty("api_client_secret")
public String apiClientSecret;
/** 过期时间,北京时间 {@code yyyy-MM-dd HH:mm:ss}。 */
@JsonProperty("token_expire_time")
public String tokenExpireTime;
/** 令牌本体(形如 {@code {D0A7A4FB-...}})。 */
@JsonProperty("token")
public String token;
}
}

49
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangLogisticsDtos.java

@ -0,0 +1,49 @@ @@ -0,0 +1,49 @@
package common.ecommerce.xincang.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* 信仓报文结构:客户承运商列表({@code GET api.get_customer_logistics})。
*/
public final class XincangLogisticsDtos {
private XincangLogisticsDtos() {
}
/** 客户承运商列表响应 {@code rst}({@code GET api.get_customer_logistics})。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class LogisticsListResult {
@JsonProperty("code")
public String code;
@JsonProperty("msg")
public String msg;
@JsonProperty("data")
public List<LogisticsRow> data;
/** 总条数(字符串)。 */
@JsonProperty("count")
public String count;
/** 一行承运商。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class LogisticsRow {
/** 物流方式代码,如 {@code FEDEX-G}。 */
@JsonProperty("logistics_type")
public String logisticsType;
}
}
/** 客户承运商列表响应外层。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class LogisticsListResponse {
@JsonProperty("rst")
public LogisticsListResult rst;
}
}

55
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangOrderCreateDtos.java

@ -0,0 +1,55 @@ @@ -0,0 +1,55 @@
package common.ecommerce.xincang.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* 信仓报文结构:新增订单 / 一单多件({@code POST api.add_order_multiple})。
*/
public final class XincangOrderCreateDtos {
private XincangOrderCreateDtos() {
}
/**
* 新增订单(一单多件)请求中的一条商品。
*
* <p>信仓把整组商品 JSON 序列化后放进 multipart 的 {@code products} 字段。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class OrderProduct {
/** 产品 SKU。 */
@JsonProperty("product_sku")
public String productSku;
/** 数量(字符串)。 */
@JsonProperty("sku_count")
public String skuCount;
}
/**
* 新增订单(一单多件)响应中的 {@code rst}。
*/
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class OrderResult {
/** 信仓系统单号(DS-...)。 */
@JsonProperty("order_no")
public String orderNo;
/** 信仓内部订单 id。 */
@JsonProperty("order_id")
public String orderId;
}
/** 新增订单响应外层,用于取 {@code rst}。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class OrderResponse {
/** 下单结果;业务失败时为 null。 */
@JsonProperty("rst")
public OrderResult rst;
}
}

173
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangOrderDetailDtos.java

@ -0,0 +1,173 @@ @@ -0,0 +1,173 @@
package common.ecommerce.xincang.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* 信仓报文结构:订单详情({@code GET api.get_order})。
*/
public final class XincangOrderDetailDtos {
private XincangOrderDetailDtos() {
}
/**
* 订单详情({@code GET api.get_order})的 {@code rst}。
*
* <p>字段名以文档为准;时间均为北京时间 {@code yyyy-MM-dd HH:mm:ss}(日期字段为
* {@code yyyy-MM-dd})。空值可能是空串,适配器里统一转 null。</p>
*/
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class OrderDetail {
/** 订单 id。 */
@JsonProperty("id")
public String id;
/** 信仓系统单号(DS-...)。 */
@JsonProperty("order_no")
public String orderNo;
/** 订单状态码,见 {@code XincangOrderStatus}。 */
@JsonProperty("state")
public String state;
/** 状态名。 */
@JsonProperty("state_name")
public String stateName;
/** 仓侧报错信息;正常为空。 */
@JsonProperty("api_error")
public String apiError;
/** 跟踪号。 */
@JsonProperty("gzh")
public String trackingNumber;
/** 面单 URL。 */
@JsonProperty("face_url")
public String faceUrl;
/** 参考号,即我们下发的 {@code ckh}。 */
@JsonProperty("ckh")
public String ckh;
/** 订单类型:common / wayfair。 */
@JsonProperty("order_type")
public String orderType;
/** 产品明细(一票多件)。 */
@JsonProperty("products")
public List<OrderDetailProduct> products;
/** 件数。 */
@JsonProperty("sku_count")
public String skuCount;
@JsonProperty("dim_length")
public String dimLength;
@JsonProperty("dim_width")
public String dimWidth;
@JsonProperty("dim_height")
public String dimHeight;
@JsonProperty("dim_divisor")
public String dimDivisor;
/** 实重(磅)。 */
@JsonProperty("weight_lbs")
public String weightLbs;
/** 计费重(磅)。 */
@JsonProperty("billing_weight_lbs")
public String billingWeightLbs;
/** 体积重(磅)。 */
@JsonProperty("volume_weight_lbs")
public String volumeWeightLbs;
@JsonProperty("product_sku")
public String productSku;
@JsonProperty("product_name")
public String productName;
@JsonProperty("source_sku")
public String sourceSku;
@JsonProperty("warehouse_id")
public String warehouseId;
@JsonProperty("warehouse_code")
public String warehouseCode;
@JsonProperty("country")
public String country;
@JsonProperty("province")
public String province;
@JsonProperty("city")
public String city;
@JsonProperty("address")
public String address;
@JsonProperty("address2")
public String address2;
@JsonProperty("postcode")
public String postcode;
@JsonProperty("receive_user")
public String receiveUser;
@JsonProperty("phone")
public String phone;
@JsonProperty("email")
public String email;
/** 物流方式字典值。 */
@JsonProperty("logistics_type")
public String logisticsType;
@JsonProperty("is_sign")
public String isSign;
@JsonProperty("zone")
public String zone;
/** 总费用。 */
@JsonProperty("total_amount")
public String totalAmount;
@JsonProperty("repair_amount")
public String repairAmount;
@JsonProperty("approve_time")
public String approveTime;
/** 发货时间。 */
@JsonProperty("delivered_time")
public String deliveredTime;
@JsonProperty("shop_name")
public String shopName;
@JsonProperty("gmt_create")
public String gmtCreate;
@JsonProperty("gmt_modify")
public String gmtModify;
@JsonProperty("gmt_cancel")
public String gmtCancel;
/** 截单时间。 */
@JsonProperty("intercept_time")
public String interceptTime;
}
/** 订单详情里的产品行。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class OrderDetailProduct {
@JsonProperty("product_id")
public String productId;
/** 产品 SKU。 */
@JsonProperty("sku")
public String sku;
/** 数量。 */
@JsonProperty("qty")
public String qty;
@JsonProperty("name_zh_cn")
public String nameZhCn;
}
/** 订单详情响应外层,用于取 {@code rst}。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class OrderDetailResponse {
@JsonProperty("rst")
public OrderDetail rst;
}
}

30
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangProductListDtos.java

@ -0,0 +1,30 @@ @@ -0,0 +1,30 @@
package common.ecommerce.xincang.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* 信仓报文结构:产品列表({@code GET api.productlist})。
*/
public final class XincangProductListDtos {
private XincangProductListDtos() {
}
/**
* 产品列表响应({@code GET api.productlist})中 {@code rst.data[]} 的元素。
*
* <p>只声明判断「是否已存在、处于什么状态」需要的字段。</p>
*/
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ProductListItem {
/** 产品 SKU。 */
@JsonProperty("product_no")
public String productNo;
/** 产品状态:0 临时产品 / 1 正式产品。 */
@JsonProperty("state")
public String state;
}
}

138
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangProductSaveDtos.java

@ -0,0 +1,138 @@ @@ -0,0 +1,138 @@
package common.ecommerce.xincang.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.math.BigDecimal;
/**
* 信仓报文结构:新增 / 更新产品({@code POST api.add_product} / {@code api.update_product})。
*
* <p>两个接口共用同一套请求 schema,所以放在同一个文件。</p>
*/
public final class XincangProductSaveDtos {
private XincangProductSaveDtos() {
}
/**
* 新增 / 更新产品请求({@code POST api.add_product} / {@code api.update_product})。
*
* <p>信仓这两个接口的 {@code token} 放在 <b>请求体</b>里(文档 required 列表含 {@code token});
* 新增接口的 query 里同时也收一份,见 {@code XincangRequestFactory}。</p>
*
* <p>单位:金额美元、尺寸英寸、重量磅;与统一模型(cm / g)的换算在
* {@code XincangProductMapper}。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ProductRequest {
/** 令牌。 */
@JsonProperty("token")
public String token;
/** 产品 SKU。 */
@JsonProperty("product_no")
public String productNo;
/** 中文名。 */
@JsonProperty("chn_name")
public String chnName;
/** 金额,美元,最长两位小数。 */
@JsonProperty("amount")
public BigDecimal amount;
/** 产品条码。 */
@JsonProperty("bar_code")
public String barCode;
/** 毛重,磅,最长四位小数。 */
@JsonProperty("weight_lbs")
public BigDecimal weightLbs;
/** 装箱率 / 箱率。 */
@JsonProperty("packing_rate")
public Integer packingRate;
/** 长,英寸,最长四位小数。 */
@JsonProperty("size_l_ln")
public BigDecimal sizeLLn;
/** 宽,英寸,最长四位小数。 */
@JsonProperty("size_w_ln")
public BigDecimal sizeWLn;
/** 高,英寸,最长四位小数。 */
@JsonProperty("size_h_ln")
public BigDecimal sizeHLn;
/** 备注。 */
@JsonProperty("remark")
public String remark;
/** 仓库码(信仓 {@code ckm})。 */
@JsonProperty("ckm")
public String ckm;
/** 产品类型:1 普货 / 2 配件 / 3 危险品;不传默认 1。 */
@JsonProperty("product_type")
public Integer productType;
/** 产品品类:0 其它 / 1 家具 / 2 食品 / 3 汽配 / 4 服饰 / 5 化妆品 / 6 鞋类 / 7 玩具 / 8 电子 / 9 数码。 */
@JsonProperty("product_category")
public Integer productCategory;
/** 产品图片;需先调 {@code upload.files}。统一模型暂不承载图片,通常为 null。 */
@JsonProperty("product_image")
public ProductImage productImage;
/**
* AHS 计费重量。
*
* <p>文档标注<b>已废弃</b>:具体值由各服务商参数自动计算。SDK 不填,
* 保留占位只为与文档字段表对齐。</p>
*/
@JsonProperty("ahs_weight")
@Deprecated
public String ahsWeight;
/**
* AHS 计费尺寸。
*
* <p>文档标注<b>已废弃</b>:具体值由各服务商参数自动计算。SDK 不填。</p>
*/
@JsonProperty("ahs_dimensions")
@Deprecated
public String ahsDimensions;
/**
* 是否超尺寸。
*
* <p>文档标注<b>已废弃</b>:具体值由各服务商参数自动计算。SDK 不填。</p>
*/
@JsonProperty("oversize")
@Deprecated
public String oversize;
}
/** 产品图片(OSS 元数据)。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ProductImage {
/** 存储类型,如 {@code aliyun_oss}。 */
@JsonProperty("type")
public String type;
/** bucket 名。 */
@JsonProperty("bucket")
public String bucket;
/** 对象键。 */
@JsonProperty("file_name")
public String fileName;
/** 可访问 URL。 */
@JsonProperty("file_url")
public String fileUrl;
}
}

88
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangStockAgeListDtos.java

@ -0,0 +1,88 @@ @@ -0,0 +1,88 @@
package common.ecommerce.xincang.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* 信仓报文结构:库龄列表({@code GET api.stockagelist})。
*/
public final class XincangStockAgeListDtos {
private XincangStockAgeListDtos() {
}
/** 库龄列表响应 {@code rst}({@code GET api.stockagelist})。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class StockAgeListResult {
@JsonProperty("code")
public String code;
@JsonProperty("msg")
public String msg;
@JsonProperty("data")
public List<AgeRow> data;
/** 总条数(字符串)。 */
@JsonProperty("count")
public String count;
/** 一行库龄。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class AgeRow {
/** 计费日期 {@code yyyy-MM-dd}。 */
@JsonProperty("dt")
public String dt;
@JsonProperty("warehouse_code")
public String warehouseCode;
/** 产品 SKU。 */
@JsonProperty("product_sku")
public String productSku;
/** 入库柜号。 */
@JsonProperty("cabinet_no")
public String cabinetNo;
/** 当日费用。 */
@JsonProperty("sum_fee")
public String sumFee;
/** 计费总体积(立方米)。 */
@JsonProperty("total_volume_cbm")
public String totalVolumeCbm;
/** 库存数量。 */
@JsonProperty("sku_count")
public String skuCount;
/** 入库时间 {@code yyyy-MM-dd HH:mm:ss}。 */
@JsonProperty("in_stock_time")
public String inStockTime;
/** 库龄天数。 */
@JsonProperty("fee_days")
public String feeDays;
/** 费率。 */
@JsonProperty("config_price")
public String configPrice;
/** 计费数量。 */
@JsonProperty("fee_count")
public String feeCount;
}
}
/** 库龄列表响应外层。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class StockAgeListResponse {
@JsonProperty("rst")
public StockAgeListResult rst;
}
}

84
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangStockListDtos.java

@ -0,0 +1,84 @@ @@ -0,0 +1,84 @@
package common.ecommerce.xincang.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* 信仓报文结构:实时库存({@code GET api.stocklist})。
*/
public final class XincangStockListDtos {
private XincangStockListDtos() {
}
/** 实时库存响应 {@code rst}({@code GET api.stocklist})。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class StockListResult {
@JsonProperty("code")
public String code;
@JsonProperty("msg")
public String msg;
@JsonProperty("data")
public List<StockRow> data;
/** 总条数(字符串)。 */
@JsonProperty("count")
public String count;
/** 一行库存。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class StockRow {
@JsonProperty("warehouse_code")
public String warehouseCode;
/** 产品 SKU。 */
@JsonProperty("product_sku")
public String productSku;
/** 实时库存。 */
@JsonProperty("real_stock")
public String realStock;
/** 可售数量。 */
@JsonProperty("cansale_sku_count")
public String canSaleSkuCount;
/** 占用数量。 */
@JsonProperty("use_sku_count")
public String useSkuCount;
/** 待出库数量。 */
@JsonProperty("wait_sku_count")
public String waitSkuCount;
/** 在海上数量。 */
@JsonProperty("ship_sku_count")
public String shipSkuCount;
/** 预警数量。 */
@JsonProperty("alerm_count")
public String alarmCount;
/** 商品名。 */
@JsonProperty("chn_name")
public String chnName;
/** 体积(立方厘米)。 */
@JsonProperty("volume_cm")
public String volumeCm;
}
}
/** 实时库存响应外层。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class StockListResponse {
@JsonProperty("rst")
public StockListResult rst;
}
}

160
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangTransferCreateDtos.java

@ -0,0 +1,160 @@ @@ -0,0 +1,160 @@
package common.ecommerce.xincang.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* 信仓报文结构:新增转运({@code POST fba.do_fba})。
*/
public final class XincangTransferCreateDtos {
private XincangTransferCreateDtos() {
}
/**
* 新增转运请求({@code POST fba.do_fba})。
*
* <p>附件字段(产品贴 / 外箱贴 / 托盘贴 / BOL)要求先用 {@code upload.files} 上传,
* 再把返回的 {@code data.data} 对象原样放进来;SDK 只做字段搬运。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class TransferRequest {
/** 转运单号(业务侧),必填。 */
@JsonProperty("fba_no")
public String fbaNo;
/** PO 号,必填。 */
@JsonProperty("po")
public String po;
/** 发货仓(仓方字典名称),必填。 */
@JsonProperty("from_warehouse_name")
public String fromWarehouseName;
/** 目的仓(仓方字典名称),必填。 */
@JsonProperty("dest_warehouse_name")
public String destWarehouseName;
/** 其它仓库名;目的仓选「其他仓库」时填。 */
@JsonProperty("other_warehouse")
public String otherWarehouse;
/** 转运类型(订单类型字典值),必填。 */
@JsonProperty("order_type")
public String orderType;
/** 转运类型(转运类型字典值),必填。 */
@JsonProperty("delivery_mode")
public String deliveryMode;
/** 转运方式 / 配送方式(字典值),必填。 */
@JsonProperty("delivery_way")
public String deliveryWay;
/** 预约发货时间 {@code yyyy-MM-dd}。 */
@JsonProperty("pre_send_time")
public String preSendTime;
/** 标签需求,多选用英文逗号分隔,如 {@code 产品贴,外箱标签}。 */
@JsonProperty("label_requirement")
public String labelRequirement;
/** 备注。 */
@JsonProperty("remark")
public String remark;
/** 是否需要打托:{@code 是} / {@code 否}。 */
@JsonProperty("is_pallet")
public String isPallet;
/** 产品明细 JSON 字符串。 */
@JsonProperty("products")
public String products;
/** 产品贴打印份数。 */
@JsonProperty("product_print_copies")
public String productPrintCopies;
/** 外箱贴打印份数。 */
@JsonProperty("ctn_print_copies")
public String ctnPrintCopies;
/** 快递面单打印份数。 */
@JsonProperty("express_print_copies")
public String expressPrintCopies;
/** 托盘贴打印份数。 */
@JsonProperty("pallet_print_copies")
public String palletPrintCopies;
/** 产品贴附件;{@code label_requirement} 含「产品贴」时必传。 */
@JsonProperty("product_label_att")
public XincangUploadDtos.Attachment productLabelAtt;
/** 外箱贴附件;{@code label_requirement} 含「外箱标签」时必传。 */
@JsonProperty("ctn_label_att")
public XincangUploadDtos.Attachment ctnLabelAtt;
/** 快递面单附件;{@code delivery_way} 为快递发货类型时必传。 */
@JsonProperty("express_label_att")
public XincangUploadDtos.Attachment expressLabelAtt;
/** 托盘贴附件;卡车 + 打托 + 含「托盘标签」三条件同时满足时必传。 */
@JsonProperty("pallet_label_att")
public XincangUploadDtos.Attachment palletLabelAtt;
/** 其他附件(数组)。 */
@JsonProperty("other_att")
public List<XincangUploadDtos.Attachment> otherAtt;
/** BOL 附件(数组)。 */
@JsonProperty("bol_att")
public List<XincangUploadDtos.Attachment> bolAtt;
}
/** 转运请求里的产品明细(序列化进 {@code products} 字符串)。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class TransferProduct {
/** 产品 SKU,必填。 */
@JsonProperty("product_no")
public String productNo;
/** 数量(字符串),必填。 */
@JsonProperty("sku_count")
public String skuCount;
/** 三方 SKU(可选)。 */
@JsonProperty("fn_sku")
public String fnSku;
/** 箱标 SKU(可选)。 */
@JsonProperty("ctn_sku")
public String ctnSku;
/** 备注。 */
@JsonProperty("remark")
public String remark;
}
/** 转运单创建结果 {@code rst}。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class TransferResult {
/** 信仓转运单号(LTL...),审核时传它。 */
@JsonProperty("order_no")
public String orderNo;
}
/** 新增转运响应外层,用于取 {@code rst}。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class TransferResponse {
/** 转运结果;业务失败时为 null。 */
@JsonProperty("rst")
public TransferResult rst;
}
}

198
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangTransferDetailDtos.java

@ -0,0 +1,198 @@ @@ -0,0 +1,198 @@
package common.ecommerce.xincang.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* 信仓报文结构:转运详情({@code GET fba.fba_detail})。
*/
public final class XincangTransferDetailDtos {
private XincangTransferDetailDtos() {
}
/**
* 转运单详情({@code GET fba.fba_detail})的 {@code rst}。
*
* <p>只声明统一模型用得上的字段与排查必需的字段;附件同时给了对象和
* {@code *_url}(签名后可直接下载),这里两者都保留。</p>
*/
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class TransferDetail {
@JsonProperty("id")
public String id;
/** 转运单号(LTL...);审核与后续查询都用它。 */
@JsonProperty("order_no")
public String orderNo;
/** 业务侧转运单号(我们下发的 {@code fba_no})。 */
@JsonProperty("fba_no")
public String fbaNo;
@JsonProperty("po")
public String po;
/** 客户 id。 */
@JsonProperty("customer_id")
public String customerId;
/** 客户代码。 */
@JsonProperty("customer_no")
public String customerNo;
/** 发货仓 id / 代码。 */
@JsonProperty("from_warehouse")
public String fromWarehouseId;
@JsonProperty("from_warehouse_name")
public String fromWarehouseName;
/** 目的仓 id / 代码。 */
@JsonProperty("dest_warehouse")
public String destWarehouseId;
@JsonProperty("dest_warehouse_name")
public String destWarehouseName;
/** 预约发货时间 {@code yyyy-MM-dd}。 */
@JsonProperty("pre_send_time")
public String preSendTime;
/** 状态码,见 {@code XincangTransferState}。 */
@JsonProperty("state")
public String state;
@JsonProperty("state_name")
public String stateName;
/** 是否需要产品贴 / 外箱贴 / 托盘贴:0 否 / 1 是。 */
@JsonProperty("is_product_label")
public String isProductLabel;
@JsonProperty("is_ctn_label")
public String isCtnLabel;
@JsonProperty("is_pallet_label")
public String isPalletLabel;
/** 是否打托:0 否 / 1 是。 */
@JsonProperty("is_pallet")
public String isPallet;
@JsonProperty("remark")
public String remark;
@JsonProperty("picking_time")
public String pickingTime;
@JsonProperty("picked_time")
public String pickedTime;
@JsonProperty("palleted_time")
public String palletedTime;
/** 发货时间。 */
@JsonProperty("send_time")
public String sendTime;
@JsonProperty("approve_time")
public String approveTime;
@JsonProperty("shipping_id")
public String shippingId;
/** 转运类型(字典值)。 */
@JsonProperty("delivery_mode")
public String deliveryMode;
/** 转运方式(字典值)。 */
@JsonProperty("delivery_way")
public String deliveryWay;
/** 订单类型(字典值)。 */
@JsonProperty("order_type")
public String orderType;
@JsonProperty("other_warehouse")
public String otherWarehouse;
/** 标签需求,逗号分隔。 */
@JsonProperty("label_requirement")
public String labelRequirement;
/** 附件对象。 */
@JsonProperty("product_label_att")
public XincangUploadDtos.Attachment productLabelAtt;
@JsonProperty("ctn_label_att")
public XincangUploadDtos.Attachment ctnLabelAtt;
@JsonProperty("pallet_label_att")
public XincangUploadDtos.Attachment palletLabelAtt;
@JsonProperty("bol_att")
public List<XincangUploadDtos.Attachment> bolAtt;
@JsonProperty("signature_bol_att")
public List<XincangUploadDtos.Attachment> signatureBolAtt;
@JsonProperty("express_label_att")
public XincangUploadDtos.Attachment expressLabelAtt;
@JsonProperty("other_att")
public List<XincangUploadDtos.Attachment> otherAtt;
/** 附件签名 URL(可直接下载)。 */
@JsonProperty("product_label_att_url")
public String productLabelAttUrl;
@JsonProperty("ctn_label_att_url")
public String ctnLabelAttUrl;
@JsonProperty("pallet_label_att_url")
public String palletLabelAttUrl;
@JsonProperty("bol_att_url")
public String bolAttUrl;
@JsonProperty("signature_bol_file")
public String signatureBolFile;
@JsonProperty("express_label_att_url")
public String expressLabelAttUrl;
@JsonProperty("other_att_url")
public String otherAttUrl;
/** 总费用。 */
@JsonProperty("total_amount")
public String totalAmount;
@JsonProperty("gmt_create")
public String gmtCreate;
@JsonProperty("gmt_modify")
public String gmtModify;
/** 产品明细。 */
@JsonProperty("products")
public List<TransferDetailProduct> products;
}
/** 转运详情里的产品行。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class TransferDetailProduct {
@JsonProperty("product_no")
public String productNo;
/** 件数。 */
@JsonProperty("sku_count")
public String skuCount;
/** 箱数。 */
@JsonProperty("box_count")
public String boxCount;
@JsonProperty("chn_name")
public String chnName;
@JsonProperty("packing_rate")
public String packingRate;
@JsonProperty("remark")
public String remark;
@JsonProperty("weight_lbs")
public String weightLbs;
@JsonProperty("weight_kg")
public String weightKg;
/** 产品中文名(文档字段 {@code chn_name} 的语义;与 {@link #chnName} 同值来源)。 */
@JsonProperty("product_name")
public String productName;
/** 清点箱数。 */
@JsonProperty("check_box_qty")
public String checkBoxQty;
/** 打托件数。 */
@JsonProperty("pallet_sku_count")
public String palletSkuCount;
/** 上架件数。 */
@JsonProperty("put_on_sku_count")
public String putOnSkuCount;
}
/** 转运详情响应外层。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class TransferDetailResponse {
@JsonProperty("rst")
public TransferDetail rst;
}
}

85
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangUploadDtos.java

@ -0,0 +1,85 @@ @@ -0,0 +1,85 @@
package common.ecommerce.xincang.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
/**
* 信仓报文结构:文件上传({@code POST upload.files})。
*
* <p>{@code Attachment} 是上传返回的 {@code data.data},原样回传给转运的
* {@code *_att} 字段,所以由本文件持有。</p>
*/
public final class XincangUploadDtos {
private XincangUploadDtos() {
}
/**
* 附件元数据({@code upload.files} 返回的 {@code data.data} 原样回传)。
*
* <p>字段名与上传接口返回保持一致,包括 {@code file_url} 与 {@code fileType} 的
* 大小写差异——信仓文档里就是这么写的。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class Attachment {
/** 存储类型,如 {@code aliyun_oss}。 */
@JsonProperty("type")
public String type;
/** bucket 名。 */
@JsonProperty("bucket")
public String bucket;
/** 对象键。 */
@JsonProperty("file_name")
public String fileName;
/** 可访问 URL。 */
@JsonProperty("file_url")
public String fileUrl;
/** 文件类型(信仓原文是 camelCase)。 */
@JsonProperty("fileType")
public String fileType;
/** 原始文件名。 */
@JsonProperty("name")
public String name;
/** 上传接口返回的 uid,通常为空串。 */
@JsonProperty("uid")
public String uid;
/** 上传接口返回的 url(与 file_url 同值)。 */
@JsonProperty("url")
public String url;
}
/** 文件上传响应({@code POST upload.files}):{@code {code,msg,data:{data:{...}}}}。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class UploadResponse {
/** 业务数据外层。 */
@JsonProperty("data")
public UploadData data;
/** 200 表示成功。 */
@JsonProperty("code")
public Integer code;
/** 描述。 */
@JsonProperty("msg")
public String msg;
}
/** 上传响应的 {@code data} 层。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class UploadData {
/** 附件元数据;直接作为 {@code *_att} 传参。 */
@JsonProperty("data")
public Attachment data;
}
}

64
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangWarehouseDtos.java

@ -0,0 +1,64 @@ @@ -0,0 +1,64 @@
package common.ecommerce.xincang.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import java.util.List;
/**
* 信仓报文结构:客户仓库列表({@code GET api.get_customer_warehouses})。
*/
public final class XincangWarehouseDtos {
private XincangWarehouseDtos() {
}
/** 客户仓库列表响应 {@code rst}({@code GET api.get_customer_warehouses})。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class WarehouseListResult {
@JsonProperty("code")
public String code;
@JsonProperty("msg")
public String msg;
@JsonProperty("data")
public List<WarehouseRow> data;
/** 总条数(字符串)。 */
@JsonProperty("count")
public String count;
/** 一行仓库。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class WarehouseRow {
/** 仓方内部 id。 */
@JsonProperty("id")
public String id;
/** 仓代码。 */
@JsonProperty("warehouse_code")
public String warehouseCode;
@JsonProperty("country")
public String country;
@JsonProperty("province")
public String province;
@JsonProperty("city")
public String city;
@JsonProperty("street")
public String street;
@JsonProperty("postcode")
public String postcode;
}
}
/** 客户仓库列表响应外层。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class WarehouseListResponse {
@JsonProperty("rst")
public WarehouseListResult rst;
}
}
Loading…
Cancel
Save