diff --git a/README.md b/README.md index d52905e..b7b2b92 100644 --- a/README.md +++ b/README.md @@ -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 yqn --> whcore xc --> common xc --> whcore + hj --> common + hj --> whcore ``` **一次商品查询的调用链**(订单、售后、出库等能力走同一条骨架): @@ -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 ┘ 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 │ 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 # 单模块 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 # 恒健目录 / 渠道 / 商品保存 / 出库下单 ``` --- diff --git a/docs-warehouse/README.md b/docs-warehouse/README.md index e75ff01..c6bb39c 100644 --- a/docs-warehouse/README.md +++ b/docs-warehouse/README.md @@ -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) | 通用注意事项:写操作、幂等、时区、单位、字段口径 | ## 快速定位 diff --git a/docs-warehouse/hengjian/README.md b/docs-warehouse/hengjian/README.md new file mode 100644 index 0000000..3bae611 --- /dev/null +++ b/docs-warehouse/hengjian/README.md @@ -0,0 +1,335 @@ +# 恒健(HengJian / Efulfill)接入 + +语雀接口文档:(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 `」 | 与《基础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")`。 diff --git a/pom.xml b/pom.xml index ceef4af..d79eb93 100644 --- a/pom.xml +++ b/pom.xml @@ -35,6 +35,7 @@ warehouse-sdk-yqn warehouse-sdk-xincang warehouse-sdk-edayun + warehouse-sdk-hengjian @@ -74,6 +75,11 @@ warehouse-sdk-xincang ${project.version} + + ecommerce + warehouse-sdk-hengjian + ${project.version} + com.squareup.okhttp3 diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseProvider.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseProvider.java index 51d9314..89733d4 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseProvider.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseProvider.java @@ -18,6 +18,8 @@ public enum WarehouseProvider { EDAYUN(30, "易达云"), /** 领星 WMS:预留,本期不实现 */ LINGXING(40, "领星WMS"), + /** 恒健(Efulfill) */ + HENGJIAN(50, "恒健"), /** 其他自建/直连仓 */ CUSTOM(90, "自建仓"); diff --git a/warehouse-sdk-hengjian/pom.xml b/warehouse-sdk-hengjian/pom.xml new file mode 100644 index 0000000..9c89624 --- /dev/null +++ b/warehouse-sdk-hengjian/pom.xml @@ -0,0 +1,49 @@ + + + 4.0.0 + + + ecommerce + channel-sdk-parent + 1.0.0-SNAPSHOT + + + warehouse-sdk-hengjian + 恒健(HengJian / Efulfill)三方仓适配器(3PL 仓储履约) + + + + ecommerce + sdk-common + + + ecommerce + warehouse-sdk-core + + + com.fasterxml.jackson.core + jackson-databind + + + com.squareup.okhttp3 + okhttp + + + org.slf4j + slf4j-api + + + + ecommerce + warehouse-sdk-testkit + test + + + org.junit.jupiter + junit-jupiter + test + + + diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java new file mode 100644 index 0000000..c76af70 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java @@ -0,0 +1,96 @@ +package common.ecommerce.hengjian; + +/** + * 恒健(HengJian / Efulfill)协议常量。 + * + *

端点与路径是协议的一部分,写在代码里,不做成配置表。 + * 运行时不使用 {@link #TEST_BASE_URL}:端点由调用方每次经 + * {@code WarehouseConnection} 传入。

+ * + *

依据恒健语雀《OpenAPI接口文档》(book tvzvkk,2026-11 核对)。 + * 该文档单篇接口页里没有写鉴权细节,鉴权只在《基础API调用》一页, + * 且写了两个都叫「授权Token」的请求头。

+ */ +public final class HengjianConstants { + + /** 适配器标识。 */ + public static final String ADAPTER_ID = "hengjian"; + + /** + * 测试 / 联调环境基址。 + * + *

文档写的是 {@code https://pr-open-api.ehengjian.com},末尾不带斜杠, + * 与 {@code WarehouseConnection} 的归一化一致,路径直接以 {@code /} 开头拼接。

+ */ + 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}。 + * + *

文档把 {@code Authorization} 与 {@code x-api-key} 两个头都标成「授权Token」, + * 且都标「必须」,所以两个都带、取值相同(复用 {@code ChannelSecret.appSecret()})。

+ * + *

真机尚不能确认是否可以只带一个:用一个无效 token 试过, + * 只带一个和两个都带都返回 500「未知的账户!」,区分不出是哪个头在起作用。 + * 拿到有效 token 后应补一次对照实验,再决定能否精简。

+ */ + 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"; + + /** + * 创建 / 编辑产品。 + * + *

接口是保存语义(同一 SKU 再调即更新),响应只有 {@code code/message},没有 data。

+ */ + public static final String PATH_PRODUCT_SAVE = "/v1/product/save"; + + /** + * 创建销售发货单。 + * + *

响应回 {@code data.orderId}(仓内部数字 id);取消时 {@code orderId} 与 + * {@code orderNo} 都要,所以调用方必须落库这个 id。

+ */ + public static final String PATH_ORDER_CREATE = "/v1/saleOrder/create"; + + /** 业务成功码;文档各接口一致写 {@code 200}。 */ + public static final int SUCCESS_CODE = 200; + + /** + * 未授权 / 未知账户的业务码。 + * + *

真机观察(2026-11-12,测试环境):不带任何授权头请求 + * {@code /v2/warehouse/getWarehouse},HTTP 仍是 200,body 是 + * {@code {"statusCode":500,"status":1,"code":999999,"message":"查询失败Unauthorized"}}。 + * 带上任意一个头(值无效)时则返回 Spring 的 500 错误页 + * {@code {"status":500,...,"message":"未知的账户!"}}。

+ * + *

因此这个码必须按认证失败处理,不能当普通业务失败——否则宿主只会看到 + * 一条「业务码非 200」,不会去刷新凭据。

+ */ + public static final int UNAUTHORIZED_CODE = 999999; + + /** + * 限流:每秒许可数。 + * + *

恒健文档未公开限流值,先按三家仓的保守默认 2 req/s/仓;联调确认后只改这一处。

+ */ + public static final int PERMITS_PER_SECOND = 2; + + private HengjianConstants() { + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java new file mode 100644 index 0000000..9cebeae --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java @@ -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; + +/** + * 恒健适配器。 + * + *

已接入:仓库目录、承运商 / 物流产品、按仓的物流渠道(只读), + * 以及商品创建 / 编辑({@code /v1/product/save},保存语义)。

+ * + *

出库 / 库存 / 入库 / 退货等接口尚未接入,能力位不声明: + * 门面调用会显式抛 {@code WarehouseUnsupportedCapabilityException},不返回空集合。

+ * + *

适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经 + * {@code WarehouseConnection} 传入。

+ */ +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 capabilities() { + return EnumSet.of( + WarehouseCapability.PRODUCT, + WarehouseCapability.OUTBOUND, + WarehouseCapability.PLATFORM_LABEL_DELIVERY, + WarehouseCapability.DIRECTORY, + WarehouseCapability.LOGISTICS_PRODUCT); + } + + // ------------------------------------------------------------------ 出库 + + /** + * 创建销售发货单({@code POST /v1/saleOrder/create})。 + * + *

承接 {@code WarehouseOutbounds.create} 的幂等守卫:同一 + * {@code outboundRequestNo} 重复下发由门面拦住,这里只负责拼报文与解析。

+ * + *

响应只回 {@code data.orderId}(仓内部数字 id,不是字符串单号)。 + * 恒健的取消接口同时要 {@code orderId} 与 {@code orderNo},所以这个 id + * 必须随 {@link OutboundReceipt#providerOrderId()} 落库;缺了它后续取消做不了, + * 因此拿不到就报错,不静默当成创建成功。

+ */ + @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 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 packages(WarehouseContext ctx, OutboundRef ref) { + throw unsupportedOutbound("warehouse.outbound.packages", ctx); + } + + /** + * 平台面单必须真的带文件。 + * + *

恒健的面单就是 {@code attachInfoItems} 里的一条附件;声明了 + * {@code PLATFORM_LABEL_DELIVERY} 却不给文件,仓没有面单可打,等于静默失败。

+ */ + 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})。 + * + *

接口是保存语义:同一 SKU 再调即更新,所以不区分 create 与 update, + * 也不像信仓那样先查一次再决定调哪个接口。

+ * + *

响应只有 {@code code / message},没有 data,因此结果里的 + * {@code status} 固定为 {@code SAVED}、{@code rawStatus} 取仓方的 message—— + * 仓方并不告诉我们这次是新建还是更新,不能替它编。

+ * + * @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},无参数)。 + * + *

返回的 {@code warehouseCode} 可直接用于下单、库存查询等接口。

+ */ + @Override + public List warehouses(WarehouseContext ctx) { + String raw = execute(ctx, HengjianConstants.PATH_WAREHOUSE_LIST, null, OP_WAREHOUSE_LIST); + List rows = + json.listAt(raw, "data", HengjianWarehouseDtos.WarehouseRow.class); + return HengjianDirectoryMapper.toWarehouses(rows); + } + + /** + * 承运商 / 物流方式代码({@code POST /v2/carrierGroup/getCarrierGroup},无参数)。 + * + *

返回物流产品代码(如 {@code UPS2DAM_HL}),可直接作为下单的 {@code carrierCode}。 + * 按出现顺序去重。

+ */ + @Override + public List carriers(WarehouseContext ctx) { + return codesOf(fetchAllServices(ctx)); + } + + /** + * 物流产品清单({@code POST /v2/carrierGroup/getCarrierGroup})。 + * + *

恒健这个接口没有仓维度,拿到的是组织级清单;{@code warehouseCode} + * 仅用于写进结果字段,便于调用方区分来源。需要「某仓支持哪些渠道」用 + * {@link #productsOfWarehouse}。

+ */ + @Override + public List products(WarehouseContext ctx, String warehouseCode) { + return HengjianDirectoryMapper.toProducts(fetchAllServices(ctx), resolveWarehouseCode(ctx, warehouseCode)); + } + + /** + * 查询「某仓支持哪些物流渠道」({@code POST + * /v2/carrierGroup/getWarehouseCarrierGroupServices})。 + * + *

返回形状与 {@link #products} 不同:{@code data} 是以仓代码为键的对象, + * 不是数组;只取请求的那个仓,混进别的仓的渠道会让「仓不支持该渠道」 + * 变成仓方报错。

+ */ + public List 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 codes = new ArrayList(); + codes.add(code); + Map body = new LinkedHashMap(); + 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 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 servicesOfWarehouse(String raw, String warehouseCode) { + List rows = + new ArrayList(); + 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 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 codesOf(List rows) { + List out = new ArrayList(); + 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; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapterFactory.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapterFactory.java new file mode 100644 index 0000000..be5a197 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapterFactory.java @@ -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; + +/** + * 恒健适配器工厂。 + * + *

端点与凭据由调用方在每次请求时传入,工厂只装配协议与基础设施。 + * 恒健是组织级固定 token(两个请求头),没有换取 / 续约流程,所以不需要 + * {@code TokenStore} / {@code LockProvider}——与运去哪同构,与信仓不同。

+ */ +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()); + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianDirectoryMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianDirectoryMapper.java new file mode 100644 index 0000000..d4d47bc --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianDirectoryMapper.java @@ -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; + +/** + * 恒健仓库档案与物流渠道映射。 + * + *

只做字段搬运,不发请求、不读配置。

+ */ +public final class HengjianDirectoryMapper { + + private HengjianDirectoryMapper() { + } + + /** + * 仓库行 → 统一仓库档案。 + * + *

恒健文档的仓对象没有联系人、电话、邮箱字段(运去哪 / 信仓有), + * 所以 {@code contactName / mobilePhone / email} 恒为 null——这是平台限制, + * 不是漏接。

+ */ + public static List toWarehouses(List rows) { + List out = new ArrayList(); + 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; + } + + /** + * 承运商服务行 → 统一物流产品。 + * + *

{@code logisticsProductCode} 取恒健的 {@code code}(下单的 {@code carrierCode}), + * 名称拼成「承运商 + 服务名」——恒健把承运商和服务分在两列,统一模型只有一个名称字段。

+ * + *

{@code crossCountry} 恒为 false:恒健文档没有这个维度,不是「不支持跨国」。

+ * + * @param warehouseCode 仓代码;全量渠道接口没有这个维度时传 null + */ + public static List toProducts( + List rows, String warehouseCode) { + List out = new ArrayList(); + 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(); + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOutboundMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOutboundMapper.java new file mode 100644 index 0000000..f8de14d --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOutboundMapper.java @@ -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})。 + * + *

平台字段名只出现在本类与 {@link HengjianCreateOrderDtos}。

+ * + *

时间

+ *

恒健的时间字段是 UTC 的 {@code yyyy-MM-dd HH:mm:ss}(文档明确写了 utc 时间), + * 所以格式化固定按 {@link ZoneOffset#UTC},不用 {@code WarehouseContext.zone()}—— + * 那个时区是给「仓方回传的无时区本地时间」用的,方向相反。

+ * + *

必填项

+ *

{@code createdAt} 在统一模型里没有对应字段,用调用方注入的 {@link Clock} 生成 + * 「下单时刻」。这是请求侧的时间戳,不是把仓方没给的数据编出来; + * 幂等重放时它会变,但恒健不拿它做去重。

+ * + *

统一模型里恒健没有对应概念的字段

+ * + * + * + * + * + * + * + * + * + * + *
字段处理
{@code salesPlatform}恒健没有平台维度,店铺路由走 {@code channelAccount}。不发, + * 也不拿它去推断 {@code isDFOrder}——VC 订单里只有一部分是 DF。
{@code splitOrder} / {@code packages}恒健没有拆单入参与包裹入参,忽略。
{@code estimatedDeliveryTime}恒健只有 {@code expectedShipDate}(要求发货时间),没有送达时间。
{@code declaredTotal}恒健按行收金额,没有整单申报额。
+ */ +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 toProductItems( + List lines, Boolean signatureRequired, String orderNo) { + boolean signature = Boolean.TRUE.equals(signatureRequired); + List items = + new ArrayList(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; + } + + /** + * 行总金额。 + * + *

恒健 {@code skuAmount} 是「当前 SKU 总金额」,不是单价: + * 有 {@code totalAmount} 直接用;没有就用申报单价 × 数量, + * 否则整单金额会少算 quantity 倍(运去哪踩过同样的坑)。

+ */ + 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(); + } + + /** + * 附件:平台面单随单下发。 + * + *

恒健把 {@code attachInfoItems} 标为必填,所以没有附件时返回空数组, + * 不省略该字段——省略会被当成缺必填项。

+ * + *

仓自有面单({@link LabelMode#WAREHOUSE_LABEL})时不给附件; + * 给了面单内容却不是平台面单模式,直接拒绝,不静默丢弃。

+ */ + private static List 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(); + } + 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 out = + new ArrayList(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; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductMapper.java new file mode 100644 index 0000000..005d837 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianProductMapper.java @@ -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})。 + * + *

平台字段名只出现在本类与 {@link HengjianProductSaveDtos}。 + * 单位与统一模型一致(cm / g),不做换算。

+ * + *

必填项在本地拒绝

+ *

恒健把 产品尺寸 / 外箱尺寸 / 装箱数量 / 英文名 / 描述 / 发货包装 都标为必填。 + * 统一模型不强制这些(运去哪、信仓的要求各不相同),所以由本映射器按恒健的协议校验: + * 缺了直接抛 {@link IllegalArgumentException},不拿其它字段顶替—— + * 发出去被仓方拒,排查成本比本地报错高得多。

+ * + *

不发送的字段

+ * + * + * + * + * + * + *
恒健字段为什么不发
{@code imageUrls}文档写明是「产品测量图片」,用于复核长宽高,不是商品主图。 + * 统一模型的 {@code imageUrl} 是商品图片,语义不同,不能拿来顶替。
{@code isSpecialOuterPackaging}「特殊外包装」与统一模型的 {@code packageStyle}(裸包装 / 销售包装 / 物流包装) + * 不是同一套码,映射需要业务确认,暂时不发。
+ * + *

统一模型里的 SN、批次、HS Code、原产国、商品链接、客退处理方式、产品品类, + * 恒健文档都没有对应字段,一律不发。

+ */ +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; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCarrierGroupDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCarrierGroupDtos.java new file mode 100644 index 0000000..6172245 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCarrierGroupDtos.java @@ -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})。 + * + *

两个接口返回的行结构完全一样,只有外层形状不同:

+ *
    + *
  • 全量渠道:{@code data} 是数组;
  • + *
  • 按仓过滤:{@code data} 是以仓代码为键的对象, + * {@code {"EFCA":[{...}]}}。
  • + *
+ *

所以行模型共用,外层各自声明。

+ */ +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} 形状:仓代码 → 该仓可用的服务清单。 + * + *

键是动态的仓代码,不能声明成固定字段;解析时按 JSON 顶层对象逐键读取。

+ */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class WarehouseCarrierGroupRow { + + /** 仓代码(由解析时注入)。 */ + public String warehouseCode; + /** 该仓可用服务。 */ + public List services; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCreateOrderDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCreateOrderDtos.java new file mode 100644 index 0000000..ebfdb49 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianCreateOrderDtos.java @@ -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})。 + * + *

中英文两页文档描述的是同一个接口,中文页叫「创建销售发货单(带附件的)」, + * 英文页叫「Create Sale Order With Label」;两页字段表基本一致,差异见各字段注释。

+ * + *

两页的必填口径不完全一致:中文页把 {@code createdAt} 标为必填、英文页也标 Y; + * 但中文页没有 {@code isPrime}(只有英文页有),英文页没有 {@code customerRemark} / + * {@code warehouseRemark}(只有中文页有)。按两页并集实现,必填取两页都要求的字段。

+ */ +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};不填由仓方取当前时间。 + * + *

统一模型没有「支付时间」字段,这里通常不传。

+ */ + public String paidAt; + + /** Amazon VC Direct Fulfillment 订单:0 否 / 1 是;不填默认为否。 */ + public Integer isDFOrder; + + /** + * 是否 SFP 订单:0 否 / 1 是;不填默认为否。 + * + *

文档类型写的是 String,但请求示例给的是数字 {@code "isPrime": 0}。 + * 这里按示例用 Integer——两页示例一致,且 Spring 后端按数字绑定的可能性更高。 + * 真机若报类型错,改成 String 即可。

+ */ + public Integer isPrime; + + /** + * 平台要求发货时间,UTC,{@code yyyy-MM-dd HH:mm:ss}。 + * + *

文档:{@code isDFOrder=1} 时必填。

+ */ + 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 productItems; + + /** + * 附件信息;两页文档都标必填。 + * + *

没有附件时发空数组而不是省略该字段——省略会被仓方当成缺必填项。

+ */ + public List 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);必填。 + * + *

统一模型只有布尔型的 {@code signatureRequired},表达不了 2 / 3。

+ */ + 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; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianProductSaveDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianProductSaveDtos.java new file mode 100644 index 0000000..fe0856c --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianProductSaveDtos.java @@ -0,0 +1,123 @@ +package common.ecommerce.hengjian.dto; + +import com.fasterxml.jackson.annotation.JsonInclude; + +import java.util.List; + +/** + * 恒健报文结构:创建 / 编辑产品({@code POST /v1/product/save})。 + * + *

字段名照抄文档。注意尺寸与重量分三组,含义不同:

+ *
    + *
  • {@code length / width / height / weight}:产品(发货单元)尺寸与重量;
  • + *
  • {@code itemLength / itemWidth / itemHeight}:单品尺寸,选填;
  • + *
  • {@code packedLength / packedWidth / packedHeight / packedWeight / packedQty}: + * 外箱尺寸、外箱重量与装箱数量,文档标必填。
  • + *
+ *

三组不能互相顶替:把单品尺寸填进 {@code length} 会让仓方的计费重与货架位算错。

+ */ +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; + + /** + * 产品测量图片地址列表。 + * + *

文档说明「有变更产品长/宽/高重量时传入」——它不是商品主图, + * 而是仓方复核尺寸用的测量照片。

+ */ + public List imageUrls; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianWarehouseDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianWarehouseDtos.java new file mode 100644 index 0000000..d4e88c4 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianWarehouseDtos.java @@ -0,0 +1,42 @@ +package common.ecommerce.hengjian.dto; + +import com.fasterxml.jackson.annotation.JsonInclude; + +/** + * 恒健报文结构:获取当前组织仓库({@code POST /v2/warehouse/getWarehouse},无请求参数)。 + * + *

一个文件对应一个接口,只放该接口的请求 / 响应与内嵌子结构; + * 与其它接口共用的结构各自复制一份,避免跨接口耦合。

+ */ +public final class HengjianWarehouseDtos { + + private HengjianWarehouseDtos() { + } + + /** + * 仓库行。 + * + *

字段名照抄文档。恒健没有给仓方内部 id,{@code warehouseCode} 就是下单时 + * 要传的仓代码,也是唯一标识。

+ */ + @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; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/package-info.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/package-info.java new file mode 100644 index 0000000..cc04d60 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/package-info.java @@ -0,0 +1,10 @@ +/** + * 恒健报文结构(DTO)。 + * + *

约定:一个接口一个文件,不建大而全的 Dtos;字段名照抄文档, + * 连拼写错误也照抄并加注释说明;保留 {@code @JsonInclude(NON_NULL)}。

+ * + *

恒健文档里接口路径统一前缀 {@code /v1} 或 {@code /v2};字段多为 camelCase, + * 目前只出现一处文档笔误(见 {@code docs-warehouse/hengjian/README.md} 的「文档与实际不符」)。

+ */ +package common.ecommerce.hengjian.dto; diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/package-info.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/package-info.java new file mode 100644 index 0000000..8c11ebe --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/enums/package-info.java @@ -0,0 +1,18 @@ +/** + * 恒健平台枚举(本期尚未建立)。 + * + *

只读基础资料阶段没有状态码。接入出库 / 库存 / 退货时按 + * {@code docs-warehouse/onboarding-checklist.md} 阶段 2.6 建:

+ * + *
    + *
  • 带仓方原始码 + {@code toCore()} 映射到底层枚举;
  • + *
  • 精确匹配不用 {@code contains};未知值归 {@code UNKNOWN} 不猜;
  • + *
  • 提供反向 {@code codeOf()} 供下发;
  • + *
  • 用完的原值同时写进模型的 {@code rawStatus}。
  • + *
+ * + *

恒健已知的状态字段:{@code /v1/saleOrder/findByPage} 的 {@code orderStatusEnum} + * 取值为 {@code pending / unshipped / approved / assigned / picked / shipped / + * canceled / refunded}——注意与运去哪同名,但那是巧合,两套码表各建各的。

+ */ +package common.ecommerce.hengjian.enums; diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianEnvelope.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianEnvelope.java new file mode 100644 index 0000000..56c4ada --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianEnvelope.java @@ -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; + +/** + * 恒健响应信封校验。 + * + *

恒健统一信封(《基础API调用》与绝大多数接口页一致):

+ *
+ * { "statusCode": 200, "status": 0, "code": 200, "message": "查询成功" }
+ * 
+ * + *

HTTP 通常恒为 200,成败看 body 里的 {@code code}:200 成功。 + * 少数接口页只列 {@code code + message}(如查询库存),也有的把 {@code code} + * 标成 STRING;这里统一按文本读再转数字,两种形态都能识别。

+ * + *

真机观察(2026-11-12,测试环境):

+ *
    + *
  • 不带授权头:HTTP 200 + {@code {"statusCode":500,"status":1,"code":999999, + * "message":"查询失败Unauthorized"}};
  • + *
  • 只带一个授权头(值无效):HTTP 500 + Spring 错误页 + * {@code {"status":500,"error":"Internal Server Error","message":"未知的账户!"}}。
  • + *
+ *

前者按认证失败处理({@link AuthException});后者没有业务码,按 HTTP 5xx + * 归 {@link TransientException},但「未知的账户」实际是凭据问题,所以单独识别成 + * {@link AuthException},避免宿主无意义重试。

+ */ +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}。 + * + *

恒健有的接口页只写 {@code code},有的只写 {@code status},还有的把 + * {@code code} 标成 STRING。统一按文本读,缺失返回 {@link Integer#MIN_VALUE}。

+ */ + 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) + "..."; + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianRateLimiter.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianRateLimiter.java new file mode 100644 index 0000000..1dfd93f --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianRateLimiter.java @@ -0,0 +1,65 @@ +package common.ecommerce.hengjian.http; + +import java.util.HashMap; +import java.util.Map; +import java.util.function.LongSupplier; + +/** + * 按接口路径的令牌桶(间隔式)。 + * + *

恒健文档未公开限流值,先按保守默认 {@link common.ecommerce.hengjian.HengjianConstants#PERMITS_PER_SECOND} + * 节流;429 的 {@code Retry-After} 由宿主处理,这里只做本地限速。

+ * + *

进程内实现,多实例部署会叠加;需要跨实例限流时由宿主替换。 + * 可注入 {@link Sleeper} 与纳秒时钟,测试不真的 sleep。

+ */ +public final class HengjianRateLimiter { + + /** 便于测试注入,生产用 {@link Thread#sleep}。 */ + public interface Sleeper { + void sleep(long millis, int nanos); + } + + private final Map nextAllowed = new HashMap(); + 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); + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianRequestFactory.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianRequestFactory.java new file mode 100644 index 0000000..ce8f791 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/HengjianRequestFactory.java @@ -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; + +/** + * 构造恒健请求。 + * + *

鉴权是组织级固定 token 放请求头(《基础API调用》),没有换取 / 续约流程, + * 因此不经过 {@code TokenManager}。token 复用 {@link ChannelSecret#appSecret()} 承载。

+ * + *

文档要求 {@code Authorization} 与 {@code x-api-key} 两个头都带,取值相同; + * 真机用无效 token 试过,只带一个也返回「未知的账户!」,无法区分, + * 所以按文档两个都带。见 {@code HengjianConstants} 的说明。

+ */ +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 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}。 + * + *

恒健的「批量查询库存」文档把 {@code warehouseCodes} 写成 LIST 却用 GET, + * 这是唯一能表达数组的方式;联调时若仓方只认逗号分隔,改这里一处。

+ */ + public HttpRequest getMulti(String baseUrl, String path, Map> params, + ChannelSecret secret, CallScope ctx, String operation) { + StringBuilder query = new StringBuilder(); + if (params != null) { + for (Map.Entry> e : params.entrySet()) { + List 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 headers(ChannelSecret secret, CallScope ctx) { + String token = requireToken(secret); + Map out = new LinkedHashMap(); + 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 params) { + if (params == null) { + return ""; + } + StringBuilder sb = new StringBuilder(); + for (Map.Entry 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); + } + } +} diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/package-info.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/package-info.java new file mode 100644 index 0000000..27416dc --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/http/package-info.java @@ -0,0 +1,12 @@ +/** + * 恒健出入网层:请求构造、限流、响应信封校验。 + * + *

鉴权与其它仓不同:两个请求头都要带({@code Authorization} 与 + * {@code x-api-key},取值相同)。真机实测只带一个会返回「未知的账户!」, + * 详见 {@code HengjianConstants}。

+ * + *

信封校验区分三种形态:正常业务信封({@code code=200} 成功)、 + * 未授权(HTTP 200 + {@code code=999999})、凭据被拒(HTTP 500 + 「未知的账户」)。 + * 后两种都映射成 {@code AuthException},见 {@code HengjianEnvelope}。

+ */ +package common.ecommerce.hengjian.http; diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/webhook/package-info.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/webhook/package-info.java new file mode 100644 index 0000000..769e303 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/webhook/package-info.java @@ -0,0 +1,12 @@ +/** + * 恒健回调验签与解析(待接入)。 + * + *

恒健语雀文档目前没有回调(Webhook)相关页面:book 目录里只有 OpenAPI + * 接口,没有推送地址、验签算法或响应体约定。因此本期不声明 {@code WEBHOOK} 能力位, + * 也不实现 {@code WarehouseWebhookCapable}——声明了却解析不了,宿主会当能力可用。

+ * + *

拿到回调文档后按 {@code docs-warehouse/callback.md} 接入:用 + * {@code WebhookSignatures}(HMAC + 恒定时间比较 + 时间窗);多个回调共用一个地址时 + * 按报文特征分派;回调也要走 {@code CallSupport.observe}。

+ */ +package common.ecommerce.hengjian.webhook; diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java new file mode 100644 index 0000000..a0921e6 --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java @@ -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()); + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java new file mode 100644 index 0000000..c5becfc --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java @@ -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)); + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java new file mode 100644 index 0000000..dde4c2d --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java @@ -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; + +/** + * 恒健基础资料契约测试:请求形状、鉴权头、响应映射。 + * + *

全部基于录制夹具,无网络。

+ */ +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」且都标必须,所以两个都要带、取值相同。 + * + *

真机用无效 token 试过,只带一个也返回「未知的账户!」,暂时无法用实验 + * 证明「必须两个」;拿到有效 token 后补一次对照实验再决定能否精简。

+ */ + @Test + void sendsBothAuthorizationHeaders() { + RecordingTransport transport = RecordingTransport.create() + .route(HengjianConstants.PATH_WAREHOUSE_LIST, req -> Responses.ok(WAREHOUSE_BODY)); + adapter(transport).warehouses(ctx()); + + Map 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 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 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 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); + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductSaveTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductSaveTest.java new file mode 100644 index 0000000..d744936 --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianProductSaveTest.java @@ -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})契约测试。 + * + *

重点在三件容易出错的事:必填项本地拒绝、三组尺寸不互相顶替、 + * 不在报文里编造恒健没有的字段。

+ */ +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)); + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/http/HengjianEnvelopeTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/http/HengjianEnvelopeTest.java new file mode 100644 index 0000000..5e8af25 --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/http/HengjianEnvelopeTest.java @@ -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; + +/** + * 恒健响应信封校验。 + * + *

把真机观察到的三种形态都固化成用例:正常业务信封、 + * HTTP 200 + {@code code=999999}(未授权)、HTTP 500 + 「未知的账户」。 + * 后续有人把信封改成严格数字解析、或把 999999 当普通业务失败,这些用例会挂。

+ */ +class HengjianEnvelopeTest { + + private static final JacksonJsonCodec JSON = new JacksonJsonCodec(); + + private static HttpResponse ok(String body) { + return HttpResponse.of(200, Collections.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.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.emptyMap(), "bad gateway", 0L))); + assertTrue(ex.retryable()); + } + + @Test + void http401IsAuthFailure() { + assertThrows(AuthException.class, () -> parse( + HttpResponse.of(401, Collections.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("proxy error"))); + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianReadOnlyProbeTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianReadOnlyProbeTest.java new file mode 100644 index 0000000..9c95189 --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianReadOnlyProbeTest.java @@ -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; + +/** + * 恒健只读探针:核对已对接接口的真实出入参。 + * + *

默认跳过,用 {@code -Dhengjian.probe=true} 显式开启;凭据走系统属性, + * 真实 token 不入库:

+ * + *
+ * mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
+ *     -Dhengjian.probe=true \
+ *     -Dhengjian.probe.token=你的组织token \
+ *     -Dhengjian.probe.warehouseCode=EFCA \
+ *     -Dtest=HengjianReadOnlyProbeTest test
+ * 
+ * + *

只跑查询类接口:建单 / 取消 / 销毁会真实创建单据,没有测试环境 + * 明确许可前一律不碰。

+ * + *

输出只打印字段名与取值摘要,不打印 token 与完整报文(可能含 PII)。

+ */ +@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 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 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 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 codes = adapter().carriers(ctx()); + System.out.println(" 去重后 " + codes.size() + " 个 code:" + codes); + } + }); + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java new file mode 100644 index 0000000..7feaae8 --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java @@ -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; + +/** + * 恒健写接口探针:真实创建商品,用于核对 {@code /v1/product/save} 的报文。 + * + *

需要两个开关同时打开,避免误跑在正式环境:

+ *
+ * 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
+ * 
+ * + *

会在仓方测试环境留下真实商品数据:恒健文档里没有删除产品的接口, + * 跑完需要人工在 Efulfill 后台清理。SKU 默认带时间戳,重跑不会撞唯一约束。

+ * + *

输出只打印结果与关键字段,不打印 token。

+ */ +@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(); + } + + /** + * 建商品:验证必填项组合与保存语义。 + * + *

同 SKU 连跑两次可确认 {@code save} 是幂等保存(第二次应为更新而非报重复)。

+ */ + @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} 是否真回。 + * + *

需要 {@code -Dhengjian.probe.postcode};SKU 用 {@link #SKU}, + * 所以要先把商品建出来({@link #probeProductSave})。

+ * + *

会在仓方测试环境留一张真实订单。探针不自动取消——取消接口尚未接入。

+ */ + @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(); + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java index b016b7d..2edf1d1 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java @@ -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 @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 *

{@code api.productlist} 的 {@code key} 是 SKU 过滤条件,但文档没说是否精确匹配, * 这里再按 {@code product_no} 精确比对一次。

*/ - private XincangDtos.ProductListItem findTemporaryProduct(WarehouseContext ctx, AccessToken token, + private XincangProductListDtos.ProductListItem findTemporaryProduct(WarehouseContext ctx, AccessToken token, String sku) { Map params = new LinkedHashMap<>(); params.put("state", 0); @@ -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 items = - json.listAt(raw, "rst.data", XincangDtos.ProductListItem.class); - for (XincangDtos.ProductListItem item : items) { + List 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 Map 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 } 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 @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 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 public List warehouses(WarehouseContext ctx) { String raw = executeGet(ctx, XincangConstants.PATH_CUSTOMER_WAREHOUSES, new LinkedHashMap(), 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 out = new ArrayList(); 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 public List carriers(WarehouseContext ctx) { String raw = executeGet(ctx, XincangConstants.PATH_CUSTOMER_LOGISTICS, new LinkedHashMap(), 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 out = new ArrayList(); 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 */ @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 @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 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 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 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 */ @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"); diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangChannelRecommendMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangChannelRecommendMapper.java index 5cf1cea..01bee5b 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangChannelRecommendMapper.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangChannelRecommendMapper.java @@ -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 { } /** 统一询价条件 → 信仓请求体。 */ - public static XincangDtos.CalculateV3Request toRequest(ChannelRecommendQuery query) { - XincangDtos.CalculateV3Request req = new XincangDtos.CalculateV3Request(); - List products = - new ArrayList(query.products().size()); + public static XincangChannelRecommendDtos.CalculateV3Request toRequest(ChannelRecommendQuery query) { + XincangChannelRecommendDtos.CalculateV3Request req = new XincangChannelRecommendDtos.CalculateV3Request(); + List products = + new ArrayList(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 { } /** 信仓响应 → 统一结果。 */ - 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 { .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 { } 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 { } 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; } diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangForecastMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangForecastMapper.java index ff5f0d7..81841f7 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangForecastMapper.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangForecastMapper.java @@ -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 { *

信仓必填:目的仓、出运类型、柜型、柜号、参考发货 / 到港时间、发货需求、 * 参考 SKU 种类数。缺一项在下发前就拒绝,避免仓返回难懂的 err。

*/ - 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 { * @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 { * 按「一箱一件」兜底({@code box_count = sku_count});装箱率不同的场景 * 需要调用方在 {@code InboundCarton} 里显式给出,本轮不做更细的拆分。

*/ - public static List products(InboundCommand cmd) { - List products = - new ArrayList(cmd.lines().size()); + public static List products(InboundCommand cmd) { + List products = + new ArrayList(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 { *

双号:{@code forecast_no} 既作仓侧单号也作业务单号兜底—— * 信仓的 {@code ref_no} 可能为空。

*/ - 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 lines = new ArrayList(); if (detail.products != null) { - for (XincangDtos.ForecastDetailProduct product : detail.products) { + for (XincangForecastDetailDtos.ForecastDetailProduct product : detail.products) { if (product == null || blank(product.productNo)) { continue; } diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java index d6c54d7..b3fed89 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java @@ -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; *
  • 库龄列表 {@code GET api.stockagelist}
  • * * - *

    平台字段名只出现在本类与 {@link XincangDtos};时间按北京时间解析成 UTC。

    + *

    平台字段名只出现在本类与 {@code dto} 包下的各 {@code Xincang*Dtos};时间按北京时间解析成 UTC。

    */ public final class XincangInventoryMapper { @@ -79,14 +80,14 @@ public final class XincangInventoryMapper { } /** 库存响应 → 快照分页。 */ - public static Page toSnapshots(XincangDtos.StockListResult rst, + public static Page toSnapshots(XincangStockListDtos.StockListResult rst, String fallbackWarehouseCode, Instant asOf, int currentPage, int pageSize) { List out = new ArrayList(); 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 { } /** 库龄响应 → 记录分页。 */ - public static Page toAgeRecords(XincangDtos.StockAgeListResult rst, + public static Page toAgeRecords(XincangStockAgeListDtos.StockAgeListResult rst, String fallbackWarehouseCode, int currentPage, int pageSize) { List out = new ArrayList(); 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; } diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java index a48dd37..791f4d4 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java @@ -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; /** * 信仓订单详情报文 → 统一模型({@code GET api.get_order})。 * - *

    平台字段名只出现在本类与 {@link XincangDtos}。 + *

    平台字段名只出现在本类与 {@code XincangOrderDetailDtos}。 * 时间字段是北京时间 {@code yyyy-MM-dd HH:mm:ss},统一折算成 UTC。

    */ 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 { * 单值字段;前者非空时以它为准,为空才退回单值字段。数量缺失或非正的行直接跳过—— * {@link OutboundLine} 要求数量为正,保留会在构造期抛异常。

    */ - static List toLines(XincangDtos.OrderDetail detail) { + static List toLines(XincangOrderDetailDtos.OrderDetail detail) { List lines = new ArrayList(); 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 { 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; } diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java index fabc8b3..4d78cad 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java @@ -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; * 信仓出库下单报文映射({@code POST api.add_order_multiple})。 * *

    该接口是 {@code multipart/form-data},{@code products} 字段本身是一段 JSON 字符串。 - * 平台字段名只出现在本类与 {@link XincangDtos}。

    + * 平台字段名只出现在本类与 {@code XincangOrderCreateDtos}。

    * *

    文档没有对应字段的就不发:申报信息(HS / 原产国 / 申报价值)、包裹尺寸等 * 统一模型里有,但信仓这版接口不收,硬塞只会被忽略或报错。

    @@ -120,9 +120,10 @@ public final class XincangOrderMapper { /** 商品明细:{@code [{"product_sku":"...","sku_count":"1"}, ...]}。 */ static String productsJson(List lines, JsonCodec json) { - List products = new ArrayList(lines.size()); + List products = + new ArrayList(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); diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java index 326ec70..751fa9d 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java @@ -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; /** * 信仓商品报文映射({@code POST api.add_product} / {@code api.update_product})。 * - *

    平台字段名只出现在本类与 {@link XincangDtos}。单位换算也在这里: + *

    平台字段名只出现在本类与 {@code XincangProductSaveDtos}。单位换算也在这里: * 统一模型用 cm / g,信仓用 inch / lbs,按 {@link XincangConstants} 里的常量换算并保留 4 位小数 * (文档「最长四位小数」)。

    * @@ -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(); diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java index bc67f3e..7245586 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java @@ -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 { * * @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 { } /** 转运明细行 → 统一模型。 */ - static java.util.List toLines(XincangDtos.TransferDetail detail) { + static java.util.List toLines(XincangTransferDetailDtos.TransferDetail detail) { if (detail.products == null || detail.products.isEmpty()) { return java.util.Collections.emptyList(); } java.util.List out = new java.util.ArrayList(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 { } /** 明细件数合计;明细缺失时返回 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); } diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java index 18beb8f..3e1fa58 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java @@ -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 { } /** 统一命令 → 信仓新增转运请求。 */ - 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 { } /** 统一附件 → 信仓附件报文;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 { } /** 附件列表;空列表返回 null(不发空数组)。 */ - private static List attachments(List sources) { + private static List attachments(List sources) { if (sources == null || sources.isEmpty()) { return null; } - List out = new ArrayList(sources.size()); + List out = new ArrayList(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 { } /** 产品明细:{@code [{"product_no":"SKU","sku_count":"1"}]}。 */ - public static List products(TransferCommand cmd) { - List products = - new ArrayList(cmd.lines().size()); + public static List products(TransferCommand cmd) { + List products = + new ArrayList(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()); diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/auth/XincangTokenClient.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/auth/XincangTokenClient.java index 675d0a2..ec8effe 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/auth/XincangTokenClient.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/auth/XincangTokenClient.java @@ -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 { 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()) { diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangChannelRecommendDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangChannelRecommendDtos.java new file mode 100644 index 0000000..e24a593 --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangChannelRecommendDtos.java @@ -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)。 + * + *

    文档写的是 GET + {@code application/json} body;信仓其它 GET 都是 query, + * 这里按文档原样用 JSON body。

    + */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CalculateV3Request { + + /** 产品信息;必填。 */ + @JsonProperty("products") + public List 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 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; + } + + /** 单个物流渠道的报价。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class LogisticsService { + + @JsonProperty("service_code") + public String serviceCode; + + /** 总费用。 */ + @JsonProperty("sum") + public String sum; + + /** 费用明细。 */ + @JsonProperty("fees") + public List 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; + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java deleted file mode 100644 index 36850fc..0000000 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java +++ /dev/null @@ -1,1601 +0,0 @@ -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.math.BigDecimal; -import java.util.List; - -/** - * 信仓报文结构。 - * - *

    字段名以 Apifox「OMS接口文档V2」为准。信仓全局响应外层统一为 - * {@code {"rst": ..., "errno": 0, "err": "", "trace_id": "..."}},这里只放登录接口用到的部分。 - * 字段差异只改本类,不动适配器与领域模型。

    - */ -public final class XincangDtos { - - private XincangDtos() { - } - - /** - * 登录响应({@code GET /api.login})。 - * - *

    注意与业务接口不同:登录的 {@code rst} 没有 {@code code/msg/data} 包裹, - * 而是直接给出客户与 token 字段。

    - */ - @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; - } - - /** - * 新增 / 更新产品请求({@code POST api.add_product} / {@code api.update_product})。 - * - *

    信仓这两个接口的 {@code token} 放在 请求体里(文档 required 列表含 {@code token}); - * 新增接口的 query 里同时也收一份,见 {@code XincangRequestFactory}。

    - * - *

    单位:金额美元、尺寸英寸、重量磅;与统一模型(cm / g)的换算在 - * {@code XincangProductMapper}。

    - */ - @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 计费重量。 - * - *

    文档标注已废弃:具体值由各服务商参数自动计算。SDK 不填, - * 保留占位只为与文档字段表对齐。

    - */ - @JsonProperty("ahs_weight") - @Deprecated - public String ahsWeight; - - /** - * AHS 计费尺寸。 - * - *

    文档标注已废弃:具体值由各服务商参数自动计算。SDK 不填。

    - */ - @JsonProperty("ahs_dimensions") - @Deprecated - public String ahsDimensions; - - /** - * 是否超尺寸。 - * - *

    文档标注已废弃:具体值由各服务商参数自动计算。SDK 不填。

    - */ - @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; - } - - /** - * 产品列表响应({@code GET api.productlist})中 {@code rst.data[]} 的元素。 - * - *

    只声明判断「是否已存在、处于什么状态」需要的字段。

    - */ - @JsonIgnoreProperties(ignoreUnknown = true) - public static final class ProductListItem { - - /** 产品 SKU。 */ - @JsonProperty("product_no") - public String productNo; - - /** 产品状态:0 临时产品 / 1 正式产品。 */ - @JsonProperty("state") - public String state; - } - - /** - * 新增订单(一单多件)请求中的一条商品。 - * - *

    信仓把整组商品 JSON 序列化后放进 multipart 的 {@code products} 字段。

    - */ - @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 POST fba.do_fba})。 - * - *

    附件字段(产品贴 / 外箱贴 / 托盘贴 / BOL)要求先用 {@code upload.files} 上传, - * 再把返回的 {@code data.data} 对象原样放进来;SDK 只做字段搬运。

    - */ - @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 Attachment productLabelAtt; - - /** 外箱贴附件;{@code label_requirement} 含「外箱标签」时必传。 */ - @JsonProperty("ctn_label_att") - public Attachment ctnLabelAtt; - - /** 快递面单附件;{@code delivery_way} 为快递发货类型时必传。 */ - @JsonProperty("express_label_att") - public Attachment expressLabelAtt; - - /** 托盘贴附件;卡车 + 打托 + 含「托盘标签」三条件同时满足时必传。 */ - @JsonProperty("pallet_label_att") - public Attachment palletLabelAtt; - - /** 其他附件(数组)。 */ - @JsonProperty("other_att") - public List otherAtt; - - /** BOL 附件(数组)。 */ - @JsonProperty("bol_att") - public List 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 upload.files} 返回的 {@code data.data} 原样回传)。 - * - *

    字段名与上传接口返回保持一致,包括 {@code file_url} 与 {@code fileType} 的 - * 大小写差异——信仓文档里就是这么写的。

    - */ - @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; - } - - /** - * 转运单详情({@code GET fba.fba_detail})的 {@code rst}。 - * - *

    只声明统一模型用得上的字段与排查必需的字段;附件同时给了对象和 - * {@code *_url}(签名后可直接下载),这里两者都保留。

    - */ - @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 Attachment productLabelAtt; - @JsonProperty("ctn_label_att") - public Attachment ctnLabelAtt; - @JsonProperty("pallet_label_att") - public Attachment palletLabelAtt; - @JsonProperty("bol_att") - public List bolAtt; - @JsonProperty("signature_bol_att") - public List signatureBolAtt; - @JsonProperty("express_label_att") - public Attachment expressLabelAtt; - @JsonProperty("other_att") - public List 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 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; - } - - /** 转运单创建结果 {@code rst}。 */ - @JsonIgnoreProperties(ignoreUnknown = true) - public static final class TransferResult { - - /** 信仓转运单号(LTL...),审核时传它。 */ - @JsonProperty("order_no") - public String orderNo; - } - - /** - * 订单详情({@code GET api.get_order})的 {@code rst}。 - * - *

    字段名以文档为准;时间均为北京时间 {@code yyyy-MM-dd HH:mm:ss}(日期字段为 - * {@code yyyy-MM-dd})。空值可能是空串,适配器里统一转 null。

    - */ - @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 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; - } - - /** - * 最优渠道请求({@code GET api.calculate_order_v3} 的 JSON body)。 - * - *

    文档写的是 GET + {@code application/json} body;信仓其它 GET 都是 query, - * 这里按文档原样用 JSON body。

    - */ - @JsonInclude(JsonInclude.Include.NON_NULL) - public static final class CalculateV3Request { - - /** 产品信息;必填。 */ - @JsonProperty("products") - public List 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 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; - } - - /** 单个物流渠道的报价。 */ - @JsonIgnoreProperties(ignoreUnknown = true) - public static final class LogisticsService { - - @JsonProperty("service_code") - public String serviceCode; - - /** 总费用。 */ - @JsonProperty("sum") - public String sum; - - /** 费用明细。 */ - @JsonProperty("fees") - public List 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; - } - - /** 实时库存响应 {@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 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; - } - - /** 库龄列表响应 {@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 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; - } - - /** - * 新增预报请求({@code POST forecast.do_forecast})。 - * - *

    只建单,不带商品明细;明细走「完善资料」。

    - */ - @JsonInclude(JsonInclude.Include.NON_NULL) - public static final class ForecastCreateRequest { - - /** - * 客户 id。 - * - *

    文档标注已舍弃,SDK 不填;保留占位以与文档字段表对齐。

    - */ - @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 POST forecast.do_improve_forecast})。 - * - *

    {@code products} 是一段 JSON 字符串,新数据直接覆盖旧数据。

    - */ - @JsonInclude(JsonInclude.Include.NON_NULL) - public static final class ForecastImproveRequest { - - /** - * 预报单 id。 - * - *

    文档标注已舍弃,SDK 不填;保留占位以与文档字段表对齐。

    - */ - @JsonProperty("id") - @Deprecated - public String id; - - /** - * 客户 id。 - * - *

    文档标注已舍弃,SDK 不填。

    - */ - @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; - - /** - * 新增预报柜号。 - * - *

    文档标注已舍弃,SDK 不填。

    - */ - @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; - - /** - * 最晚免费时间(提柜)。 - * - *

    文档标注已舍弃,SDK 不填。

    - */ - @JsonProperty("lfd") - @Deprecated - public String lfd; - - @JsonProperty("delivery_requirements") - public String deliveryRequirements; - - @JsonProperty("remark") - public String remark; - - /** 其他需求,如 内箱贴,外箱贴。 */ - @JsonProperty("other_need") - public String otherNeed; - - /** - * 总件数。 - * - *

    文档标注已舍弃(由 {@code products} 汇总),SDK 不填。

    - */ - @JsonProperty("sku_count_sum") - @Deprecated - public String skuCountSum; - - /** - * 总箱数。 - * - *

    文档标注已舍弃(由 {@code products} 汇总),SDK 不填。

    - */ - @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; - } - - /** - * 预报详情({@code GET forecast.forecast_detail})的 {@code rst}。 - * - *

    时间字段是北京时间。

    - */ - @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 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; - } - - /** 新增预报响应 {@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; - } - - /** 客户仓库列表响应 {@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 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; - } - - /** 客户承运商列表响应 {@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 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; - } - - /** 新增订单响应外层,用于取 {@code rst}。 */ - @JsonIgnoreProperties(ignoreUnknown = true) - public static final class OrderResponse { - - /** 下单结果;业务失败时为 null。 */ - @JsonProperty("rst") - public OrderResult rst; - } - - /** 新增转运响应外层,用于取 {@code rst}。 */ - @JsonIgnoreProperties(ignoreUnknown = true) - public static final class TransferResponse { - - /** 转运结果;业务失败时为 null。 */ - @JsonProperty("rst") - public TransferResult rst; - } -} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangForecastCreateDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangForecastCreateDtos.java new file mode 100644 index 0000000..67272f8 --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangForecastCreateDtos.java @@ -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})。 + * + *

    只建单,不带商品明细;明细走「完善资料」。

    + */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ForecastCreateRequest { + + /** + * 客户 id。 + * + *

    文档标注已舍弃,SDK 不填;保留占位以与文档字段表对齐。

    + */ + @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; + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangForecastDetailDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangForecastDetailDtos.java new file mode 100644 index 0000000..292b11f --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangForecastDetailDtos.java @@ -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}。 + * + *

    时间字段是北京时间。

    + */ + @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 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; + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangForecastImproveDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangForecastImproveDtos.java new file mode 100644 index 0000000..36d6c80 --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangForecastImproveDtos.java @@ -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})。 + * + *

    {@code products} 是一段 JSON 字符串,新数据直接覆盖旧数据。

    + */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ForecastImproveRequest { + + /** + * 预报单 id。 + * + *

    文档标注已舍弃,SDK 不填;保留占位以与文档字段表对齐。

    + */ + @JsonProperty("id") + @Deprecated + public String id; + + /** + * 客户 id。 + * + *

    文档标注已舍弃,SDK 不填。

    + */ + @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; + + /** + * 新增预报柜号。 + * + *

    文档标注已舍弃,SDK 不填。

    + */ + @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; + + /** + * 最晚免费时间(提柜)。 + * + *

    文档标注已舍弃,SDK 不填。

    + */ + @JsonProperty("lfd") + @Deprecated + public String lfd; + + @JsonProperty("delivery_requirements") + public String deliveryRequirements; + + @JsonProperty("remark") + public String remark; + + /** 其他需求,如 内箱贴,外箱贴。 */ + @JsonProperty("other_need") + public String otherNeed; + + /** + * 总件数。 + * + *

    文档标注已舍弃(由 {@code products} 汇总),SDK 不填。

    + */ + @JsonProperty("sku_count_sum") + @Deprecated + public String skuCountSum; + + /** + * 总箱数。 + * + *

    文档标注已舍弃(由 {@code products} 汇总),SDK 不填。

    + */ + @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; + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangLoginDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangLoginDtos.java new file mode 100644 index 0000000..34c56e6 --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangLoginDtos.java @@ -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})。 + * + *

    注意与业务接口不同:登录的 {@code rst} 没有 {@code code/msg/data} 包裹, + * 而是直接给出客户与 token 字段。

    + */ + @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; + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangLogisticsDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangLogisticsDtos.java new file mode 100644 index 0000000..9990961 --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangLogisticsDtos.java @@ -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 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; + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangOrderCreateDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangOrderCreateDtos.java new file mode 100644 index 0000000..cb9600a --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangOrderCreateDtos.java @@ -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() { + } + + /** + * 新增订单(一单多件)请求中的一条商品。 + * + *

    信仓把整组商品 JSON 序列化后放进 multipart 的 {@code products} 字段。

    + */ + @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; + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangOrderDetailDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangOrderDetailDtos.java new file mode 100644 index 0000000..ea42ac5 --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangOrderDetailDtos.java @@ -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}。 + * + *

    字段名以文档为准;时间均为北京时间 {@code yyyy-MM-dd HH:mm:ss}(日期字段为 + * {@code yyyy-MM-dd})。空值可能是空串,适配器里统一转 null。

    + */ + @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 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; + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangProductListDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangProductListDtos.java new file mode 100644 index 0000000..6ab4a35 --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangProductListDtos.java @@ -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[]} 的元素。 + * + *

    只声明判断「是否已存在、处于什么状态」需要的字段。

    + */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class ProductListItem { + + /** 产品 SKU。 */ + @JsonProperty("product_no") + public String productNo; + + /** 产品状态:0 临时产品 / 1 正式产品。 */ + @JsonProperty("state") + public String state; + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangProductSaveDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangProductSaveDtos.java new file mode 100644 index 0000000..939eb02 --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangProductSaveDtos.java @@ -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})。 + * + *

    两个接口共用同一套请求 schema,所以放在同一个文件。

    + */ +public final class XincangProductSaveDtos { + + private XincangProductSaveDtos() { + } + + /** + * 新增 / 更新产品请求({@code POST api.add_product} / {@code api.update_product})。 + * + *

    信仓这两个接口的 {@code token} 放在 请求体里(文档 required 列表含 {@code token}); + * 新增接口的 query 里同时也收一份,见 {@code XincangRequestFactory}。

    + * + *

    单位:金额美元、尺寸英寸、重量磅;与统一模型(cm / g)的换算在 + * {@code XincangProductMapper}。

    + */ + @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 计费重量。 + * + *

    文档标注已废弃:具体值由各服务商参数自动计算。SDK 不填, + * 保留占位只为与文档字段表对齐。

    + */ + @JsonProperty("ahs_weight") + @Deprecated + public String ahsWeight; + + /** + * AHS 计费尺寸。 + * + *

    文档标注已废弃:具体值由各服务商参数自动计算。SDK 不填。

    + */ + @JsonProperty("ahs_dimensions") + @Deprecated + public String ahsDimensions; + + /** + * 是否超尺寸。 + * + *

    文档标注已废弃:具体值由各服务商参数自动计算。SDK 不填。

    + */ + @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; + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangStockAgeListDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangStockAgeListDtos.java new file mode 100644 index 0000000..3c8e4e1 --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangStockAgeListDtos.java @@ -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 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; + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangStockListDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangStockListDtos.java new file mode 100644 index 0000000..58c6832 --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangStockListDtos.java @@ -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 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; + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangTransferCreateDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangTransferCreateDtos.java new file mode 100644 index 0000000..3b9c5b2 --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangTransferCreateDtos.java @@ -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})。 + * + *

    附件字段(产品贴 / 外箱贴 / 托盘贴 / BOL)要求先用 {@code upload.files} 上传, + * 再把返回的 {@code data.data} 对象原样放进来;SDK 只做字段搬运。

    + */ + @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 otherAtt; + + /** BOL 附件(数组)。 */ + @JsonProperty("bol_att") + public List 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; + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangTransferDetailDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangTransferDetailDtos.java new file mode 100644 index 0000000..30fd4e8 --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangTransferDetailDtos.java @@ -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}。 + * + *

    只声明统一模型用得上的字段与排查必需的字段;附件同时给了对象和 + * {@code *_url}(签名后可直接下载),这里两者都保留。

    + */ + @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 bolAtt; + @JsonProperty("signature_bol_att") + public List signatureBolAtt; + @JsonProperty("express_label_att") + public XincangUploadDtos.Attachment expressLabelAtt; + @JsonProperty("other_att") + public List 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 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; + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangUploadDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangUploadDtos.java new file mode 100644 index 0000000..83c2126 --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangUploadDtos.java @@ -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})。 + * + *

    {@code Attachment} 是上传返回的 {@code data.data},原样回传给转运的 + * {@code *_att} 字段,所以由本文件持有。

    + */ +public final class XincangUploadDtos { + + private XincangUploadDtos() { + } + + /** + * 附件元数据({@code upload.files} 返回的 {@code data.data} 原样回传)。 + * + *

    字段名与上传接口返回保持一致,包括 {@code file_url} 与 {@code fileType} 的 + * 大小写差异——信仓文档里就是这么写的。

    + */ + @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; + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangWarehouseDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangWarehouseDtos.java new file mode 100644 index 0000000..c97f8d5 --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangWarehouseDtos.java @@ -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 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; + } +}