You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

1253 lines
60 KiB

package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.EdayunConstants;
import common.ecommerce.edayun.auth.EdayunTokenClient;
import common.ecommerce.edayun.dto.EdayunAccountFlowDtos;
import common.ecommerce.edayun.dto.EdayunBolDtos;
import common.ecommerce.edayun.dto.EdayunCarrierDtos;
import common.ecommerce.edayun.dto.EdayunCancelDtos;
feat(edayun): 对接退货单创建 / 详情 / 取消 / 列表 四个接口: - 创建退货单 POST /webApi/rma/info/v1/saveAndPublish(只支持 returnType=2 自行退回, 另三种要退货人地址或亚马逊单号,标准模型没有) - 退货单详情 POST /webApi/rma/info/v1/getOrderDetail - 取消退货单 POST /webApi/rma/info/v1/cancel - 退货单列表 POST /webApi/rma/info/v1/selectRmaInfoList 统一模型侧: - WarehouseReturnCapable.cancel 从 void 改成 boolean(返回值要能表达「仓方拒绝」), 目前只有易达云实现,改动安全 - queryReturns 签名从 (ctx, cursor) 改成 (ctx, ReturnQuery), 新增 ReturnQuery + ReturnQueryNoType(退货单号 / 出库单号 / 平台订单号) - 门面 returns().query(ReturnQuery) / returns().cancel(providerReturnNo), cancel 走幂等守卫 关键口径: - 创建响应 data 就是仓侧 RMA 单号(运去哪只回 code/message) - 取消响应 data 是布尔;code=200 + data=false 是仓方拒绝,抛异常而不是静默返回 false - 列表时间是字符串 yyyy-MM-dd HH:mm:ss,按仓方时区解释,不是毫秒 - 列表只认单个 status,多状态本地拒绝并提示拆查询 - 详情明细优先 checkList(仓实际收到),没有才回落 skuList(买家预报) - 状态码表来自列表文档:-1/0/1/2/3/4/5/6/7,之前只能按中文名猜 真机(2026-11-16,仓 2):列表返回 10 条 RMA,状态分布 -1/0/1/3/4/5/6 全部对上码表; 详情实测三处与文档不符——skuList.skuNum 文档标 string 实际 number、 valueAddedServices 标 number 实际字符串、picUrls 标 string 实际 JSON 数组, DTO 已按真机类型调。创建 / 取消是写操作,未在真机执行。 Co-Authored-By: Claude <noreply@anthropic.com>
4 days ago
import common.ecommerce.edayun.dto.EdayunCancelReturnDtos;
import common.ecommerce.edayun.dto.EdayunCaseMarkDtos;
feat(edayun): 对接退货单创建 / 详情 / 取消 / 列表 四个接口: - 创建退货单 POST /webApi/rma/info/v1/saveAndPublish(只支持 returnType=2 自行退回, 另三种要退货人地址或亚马逊单号,标准模型没有) - 退货单详情 POST /webApi/rma/info/v1/getOrderDetail - 取消退货单 POST /webApi/rma/info/v1/cancel - 退货单列表 POST /webApi/rma/info/v1/selectRmaInfoList 统一模型侧: - WarehouseReturnCapable.cancel 从 void 改成 boolean(返回值要能表达「仓方拒绝」), 目前只有易达云实现,改动安全 - queryReturns 签名从 (ctx, cursor) 改成 (ctx, ReturnQuery), 新增 ReturnQuery + ReturnQueryNoType(退货单号 / 出库单号 / 平台订单号) - 门面 returns().query(ReturnQuery) / returns().cancel(providerReturnNo), cancel 走幂等守卫 关键口径: - 创建响应 data 就是仓侧 RMA 单号(运去哪只回 code/message) - 取消响应 data 是布尔;code=200 + data=false 是仓方拒绝,抛异常而不是静默返回 false - 列表时间是字符串 yyyy-MM-dd HH:mm:ss,按仓方时区解释,不是毫秒 - 列表只认单个 status,多状态本地拒绝并提示拆查询 - 详情明细优先 checkList(仓实际收到),没有才回落 skuList(买家预报) - 状态码表来自列表文档:-1/0/1/2/3/4/5/6/7,之前只能按中文名猜 真机(2026-11-16,仓 2):列表返回 10 条 RMA,状态分布 -1/0/1/3/4/5/6 全部对上码表; 详情实测三处与文档不符——skuList.skuNum 文档标 string 实际 number、 valueAddedServices 标 number 实际字符串、picUrls 标 string 实际 JSON 数组, DTO 已按真机类型调。创建 / 取消是写操作,未在真机执行。 Co-Authored-By: Claude <noreply@anthropic.com>
4 days ago
import common.ecommerce.edayun.dto.EdayunCreateOrderDtos;
import common.ecommerce.edayun.dto.EdayunCreateProductDtos;
import common.ecommerce.edayun.dto.EdayunFeeEstimateDtos;
import common.ecommerce.edayun.dto.EdayunGetOrderDtos;
import common.ecommerce.edayun.dto.EdayunGetOrderLabelDtos;
import common.ecommerce.edayun.dto.EdayunInboundDtos;
import common.ecommerce.edayun.dto.EdayunInboundQueryDtos;
import common.ecommerce.edayun.dto.EdayunInventoryDtos;
import common.ecommerce.edayun.dto.EdayunLogisticsProductDtos;
import common.ecommerce.edayun.dto.EdayunOrderCostDtos;
feat: 运去哪 / 易达云 商品查询接口 统一模型新增: - ProductQuery:providerSkus(仓侧 SKU)/ barcode / 创建时间窗 / 分页, 单次上限 100 个 SKU - ProductInfo:查询结果(仓侧 SKU、条码、尺寸重量、装箱、状态、创建时间) - WarehouseProductCapable.query(...) 默认抛不支持;门面 queryProducts(ProductQuery) 运去哪(API 113 /v1/product/findPage): - **页码从 0 开始**(文档原文),游标即页码、不做 ±1 换算 - 单页上限 100、skuList 上限 100 - 该接口没有条码 / 时间窗过滤,传了本地拒绝 - 翻页优先 last,其次 number+1 < totalPages,最后按满页兜底 - cost 没有 currency 时不成 Money(避免丢单位) 易达云(/webApi/skuInfo/v1/listProductPage): - skuCode 是逗号拼接的单个字符串,一次最多 50 个,超了本地拒绝 - 页码从 1 开始、单页上限 200 - 尺寸取**实际值**,缺失才回落 forecast*(真机 ybtest:实际 55 vs 预报 10,差 5 倍) - 「查询无数据」按空页处理,不抛异常(与轨迹接口同口径) - 查询条件全空时仓方默认查最近一个月,本地不补默认值 真机验证(2026-11-17): - 易达云:不带时间窗 total=52244;skuCode=ybtest 命中 1 行; 30 天窗口 + 2021 年建的 SKU → 「查询无数据」;10 年窗口正常命中 - 运去哪:未提供 x-api-key,只做了离线单测 SKU 口径已确认并写入文档:两边都传仓侧 SKU(建档下发的 providerSku, 为空时才是 omsSku),SDK 不做 OMS→仓侧转换。 Co-Authored-By: Claude <noreply@anthropic.com>
4 days ago
import common.ecommerce.edayun.dto.EdayunProductQueryDtos;
import common.ecommerce.edayun.dto.EdayunRentDetailDtos;
feat(edayun): 对接退货单创建 / 详情 / 取消 / 列表 四个接口: - 创建退货单 POST /webApi/rma/info/v1/saveAndPublish(只支持 returnType=2 自行退回, 另三种要退货人地址或亚马逊单号,标准模型没有) - 退货单详情 POST /webApi/rma/info/v1/getOrderDetail - 取消退货单 POST /webApi/rma/info/v1/cancel - 退货单列表 POST /webApi/rma/info/v1/selectRmaInfoList 统一模型侧: - WarehouseReturnCapable.cancel 从 void 改成 boolean(返回值要能表达「仓方拒绝」), 目前只有易达云实现,改动安全 - queryReturns 签名从 (ctx, cursor) 改成 (ctx, ReturnQuery), 新增 ReturnQuery + ReturnQueryNoType(退货单号 / 出库单号 / 平台订单号) - 门面 returns().query(ReturnQuery) / returns().cancel(providerReturnNo), cancel 走幂等守卫 关键口径: - 创建响应 data 就是仓侧 RMA 单号(运去哪只回 code/message) - 取消响应 data 是布尔;code=200 + data=false 是仓方拒绝,抛异常而不是静默返回 false - 列表时间是字符串 yyyy-MM-dd HH:mm:ss,按仓方时区解释,不是毫秒 - 列表只认单个 status,多状态本地拒绝并提示拆查询 - 详情明细优先 checkList(仓实际收到),没有才回落 skuList(买家预报) - 状态码表来自列表文档:-1/0/1/2/3/4/5/6/7,之前只能按中文名猜 真机(2026-11-16,仓 2):列表返回 10 条 RMA,状态分布 -1/0/1/3/4/5/6 全部对上码表; 详情实测三处与文档不符——skuList.skuNum 文档标 string 实际 number、 valueAddedServices 标 number 实际字符串、picUrls 标 string 实际 JSON 数组, DTO 已按真机类型调。创建 / 取消是写操作,未在真机执行。 Co-Authored-By: Claude <noreply@anthropic.com>
4 days ago
import common.ecommerce.edayun.dto.EdayunReturnDetailDtos;
import common.ecommerce.edayun.dto.EdayunReturnDtos;
import common.ecommerce.edayun.dto.EdayunRmaListDtos;
import common.ecommerce.edayun.dto.EdayunSkuLabelDtos;
import common.ecommerce.edayun.dto.EdayunTrackDtos;
import common.ecommerce.edayun.dto.EdayunWarehouseDtos;
import common.ecommerce.edayun.enums.EdayunCancelStatus;
import common.ecommerce.edayun.http.EdayunRequestFactory;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.HttpTransport;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.http.TokenManager;
import common.ecommerce.shared.spi.AccessToken;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.spi.LockProvider;
import common.ecommerce.shared.spi.TokenStore;
import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.capability.BolCapable;
import common.ecommerce.warehouse.capability.CaseMarkPrintCapable;
import common.ecommerce.warehouse.capability.InboundCapable;
import common.ecommerce.warehouse.capability.InventoryCapable;
import common.ecommerce.warehouse.capability.LogisticsProductCapable;
import common.ecommerce.warehouse.capability.OutboundCapable;
import common.ecommerce.warehouse.capability.TrackingCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
feat(edayun): 对接退货单创建 / 详情 / 取消 / 列表 四个接口: - 创建退货单 POST /webApi/rma/info/v1/saveAndPublish(只支持 returnType=2 自行退回, 另三种要退货人地址或亚马逊单号,标准模型没有) - 退货单详情 POST /webApi/rma/info/v1/getOrderDetail - 取消退货单 POST /webApi/rma/info/v1/cancel - 退货单列表 POST /webApi/rma/info/v1/selectRmaInfoList 统一模型侧: - WarehouseReturnCapable.cancel 从 void 改成 boolean(返回值要能表达「仓方拒绝」), 目前只有易达云实现,改动安全 - queryReturns 签名从 (ctx, cursor) 改成 (ctx, ReturnQuery), 新增 ReturnQuery + ReturnQueryNoType(退货单号 / 出库单号 / 平台订单号) - 门面 returns().query(ReturnQuery) / returns().cancel(providerReturnNo), cancel 走幂等守卫 关键口径: - 创建响应 data 就是仓侧 RMA 单号(运去哪只回 code/message) - 取消响应 data 是布尔;code=200 + data=false 是仓方拒绝,抛异常而不是静默返回 false - 列表时间是字符串 yyyy-MM-dd HH:mm:ss,按仓方时区解释,不是毫秒 - 列表只认单个 status,多状态本地拒绝并提示拆查询 - 详情明细优先 checkList(仓实际收到),没有才回落 skuList(买家预报) - 状态码表来自列表文档:-1/0/1/2/3/4/5/6/7,之前只能按中文名猜 真机(2026-11-16,仓 2):列表返回 10 条 RMA,状态分布 -1/0/1/3/4/5/6 全部对上码表; 详情实测三处与文档不符——skuList.skuNum 文档标 string 实际 number、 valueAddedServices 标 number 实际字符串、picUrls 标 string 实际 JSON 数组, DTO 已按真机类型调。创建 / 取消是写操作,未在真机执行。 Co-Authored-By: Claude <noreply@anthropic.com>
4 days ago
import common.ecommerce.warehouse.capability.WarehouseReturnCapable;
import common.ecommerce.warehouse.enums.CancelEligibility;
import common.ecommerce.warehouse.enums.InventorySyncStrategy;
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.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.model.BillingDocument;
import common.ecommerce.warehouse.model.BolDocument;
import common.ecommerce.warehouse.model.BoxLabelCommand;
feat(edayun): 对接退货单创建 / 详情 / 取消 / 列表 四个接口: - 创建退货单 POST /webApi/rma/info/v1/saveAndPublish(只支持 returnType=2 自行退回, 另三种要退货人地址或亚马逊单号,标准模型没有) - 退货单详情 POST /webApi/rma/info/v1/getOrderDetail - 取消退货单 POST /webApi/rma/info/v1/cancel - 退货单列表 POST /webApi/rma/info/v1/selectRmaInfoList 统一模型侧: - WarehouseReturnCapable.cancel 从 void 改成 boolean(返回值要能表达「仓方拒绝」), 目前只有易达云实现,改动安全 - queryReturns 签名从 (ctx, cursor) 改成 (ctx, ReturnQuery), 新增 ReturnQuery + ReturnQueryNoType(退货单号 / 出库单号 / 平台订单号) - 门面 returns().query(ReturnQuery) / returns().cancel(providerReturnNo), cancel 走幂等守卫 关键口径: - 创建响应 data 就是仓侧 RMA 单号(运去哪只回 code/message) - 取消响应 data 是布尔;code=200 + data=false 是仓方拒绝,抛异常而不是静默返回 false - 列表时间是字符串 yyyy-MM-dd HH:mm:ss,按仓方时区解释,不是毫秒 - 列表只认单个 status,多状态本地拒绝并提示拆查询 - 详情明细优先 checkList(仓实际收到),没有才回落 skuList(买家预报) - 状态码表来自列表文档:-1/0/1/2/3/4/5/6/7,之前只能按中文名猜 真机(2026-11-16,仓 2):列表返回 10 条 RMA,状态分布 -1/0/1/3/4/5/6 全部对上码表; 详情实测三处与文档不符——skuList.skuNum 文档标 string 实际 number、 valueAddedServices 标 number 实际字符串、picUrls 标 string 实际 JSON 数组, DTO 已按真机类型调。创建 / 取消是写操作,未在真机执行。 Co-Authored-By: Claude <noreply@anthropic.com>
4 days ago
import common.ecommerce.warehouse.model.CancelCommand;
import common.ecommerce.warehouse.model.CancelResult;
import common.ecommerce.warehouse.model.CaseMarkPrintCommand;
import common.ecommerce.warehouse.model.FeeEstimateQuery;
import common.ecommerce.warehouse.model.FeeEstimateResult;
import common.ecommerce.warehouse.model.FeeQuery;
import common.ecommerce.warehouse.model.InboundCommand;
import common.ecommerce.warehouse.model.InboundOrder;
import common.ecommerce.warehouse.model.InboundReceipt;
import common.ecommerce.warehouse.model.InventoryQuery;
import common.ecommerce.warehouse.model.InventorySnapshot;
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;
feat: 运去哪 / 易达云 商品查询接口 统一模型新增: - ProductQuery:providerSkus(仓侧 SKU)/ barcode / 创建时间窗 / 分页, 单次上限 100 个 SKU - ProductInfo:查询结果(仓侧 SKU、条码、尺寸重量、装箱、状态、创建时间) - WarehouseProductCapable.query(...) 默认抛不支持;门面 queryProducts(ProductQuery) 运去哪(API 113 /v1/product/findPage): - **页码从 0 开始**(文档原文),游标即页码、不做 ±1 换算 - 单页上限 100、skuList 上限 100 - 该接口没有条码 / 时间窗过滤,传了本地拒绝 - 翻页优先 last,其次 number+1 < totalPages,最后按满页兜底 - cost 没有 currency 时不成 Money(避免丢单位) 易达云(/webApi/skuInfo/v1/listProductPage): - skuCode 是逗号拼接的单个字符串,一次最多 50 个,超了本地拒绝 - 页码从 1 开始、单页上限 200 - 尺寸取**实际值**,缺失才回落 forecast*(真机 ybtest:实际 55 vs 预报 10,差 5 倍) - 「查询无数据」按空页处理,不抛异常(与轨迹接口同口径) - 查询条件全空时仓方默认查最近一个月,本地不补默认值 真机验证(2026-11-17): - 易达云:不带时间窗 total=52244;skuCode=ybtest 命中 1 行; 30 天窗口 + 2021 年建的 SKU → 「查询无数据」;10 年窗口正常命中 - 运去哪:未提供 x-api-key,只做了离线单测 SKU 口径已确认并写入文档:两边都传仓侧 SKU(建档下发的 providerSku, 为空时才是 omsSku),SDK 不做 OMS→仓侧转换。 Co-Authored-By: Claude <noreply@anthropic.com>
4 days ago
import common.ecommerce.warehouse.model.ProductQuery;
import common.ecommerce.warehouse.model.ProductInfo;
feat(edayun): 对接退货单创建 / 详情 / 取消 / 列表 四个接口: - 创建退货单 POST /webApi/rma/info/v1/saveAndPublish(只支持 returnType=2 自行退回, 另三种要退货人地址或亚马逊单号,标准模型没有) - 退货单详情 POST /webApi/rma/info/v1/getOrderDetail - 取消退货单 POST /webApi/rma/info/v1/cancel - 退货单列表 POST /webApi/rma/info/v1/selectRmaInfoList 统一模型侧: - WarehouseReturnCapable.cancel 从 void 改成 boolean(返回值要能表达「仓方拒绝」), 目前只有易达云实现,改动安全 - queryReturns 签名从 (ctx, cursor) 改成 (ctx, ReturnQuery), 新增 ReturnQuery + ReturnQueryNoType(退货单号 / 出库单号 / 平台订单号) - 门面 returns().query(ReturnQuery) / returns().cancel(providerReturnNo), cancel 走幂等守卫 关键口径: - 创建响应 data 就是仓侧 RMA 单号(运去哪只回 code/message) - 取消响应 data 是布尔;code=200 + data=false 是仓方拒绝,抛异常而不是静默返回 false - 列表时间是字符串 yyyy-MM-dd HH:mm:ss,按仓方时区解释,不是毫秒 - 列表只认单个 status,多状态本地拒绝并提示拆查询 - 详情明细优先 checkList(仓实际收到),没有才回落 skuList(买家预报) - 状态码表来自列表文档:-1/0/1/2/3/4/5/6/7,之前只能按中文名猜 真机(2026-11-16,仓 2):列表返回 10 条 RMA,状态分布 -1/0/1/3/4/5/6 全部对上码表; 详情实测三处与文档不符——skuList.skuNum 文档标 string 实际 number、 valueAddedServices 标 number 实际字符串、picUrls 标 string 实际 JSON 数组, DTO 已按真机类型调。创建 / 取消是写操作,未在真机执行。 Co-Authored-By: Claude <noreply@anthropic.com>
4 days ago
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.ReturnQuery;
import common.ecommerce.warehouse.model.TrackEvent;
import common.ecommerce.warehouse.model.TrackingInfo;
import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable;
import common.ecommerce.warehouse.model.WarehouseCarrier;
import common.ecommerce.warehouse.model.WarehouseFacility;
import common.ecommerce.warehouse.model.WarehouseLabel;
feat(edayun): 对接退货单创建 / 详情 / 取消 / 列表 四个接口: - 创建退货单 POST /webApi/rma/info/v1/saveAndPublish(只支持 returnType=2 自行退回, 另三种要退货人地址或亚马逊单号,标准模型没有) - 退货单详情 POST /webApi/rma/info/v1/getOrderDetail - 取消退货单 POST /webApi/rma/info/v1/cancel - 退货单列表 POST /webApi/rma/info/v1/selectRmaInfoList 统一模型侧: - WarehouseReturnCapable.cancel 从 void 改成 boolean(返回值要能表达「仓方拒绝」), 目前只有易达云实现,改动安全 - queryReturns 签名从 (ctx, cursor) 改成 (ctx, ReturnQuery), 新增 ReturnQuery + ReturnQueryNoType(退货单号 / 出库单号 / 平台订单号) - 门面 returns().query(ReturnQuery) / returns().cancel(providerReturnNo), cancel 走幂等守卫 关键口径: - 创建响应 data 就是仓侧 RMA 单号(运去哪只回 code/message) - 取消响应 data 是布尔;code=200 + data=false 是仓方拒绝,抛异常而不是静默返回 false - 列表时间是字符串 yyyy-MM-dd HH:mm:ss,按仓方时区解释,不是毫秒 - 列表只认单个 status,多状态本地拒绝并提示拆查询 - 详情明细优先 checkList(仓实际收到),没有才回落 skuList(买家预报) - 状态码表来自列表文档:-1/0/1/2/3/4/5/6/7,之前只能按中文名猜 真机(2026-11-16,仓 2):列表返回 10 条 RMA,状态分布 -1/0/1/3/4/5/6 全部对上码表; 详情实测三处与文档不符——skuList.skuNum 文档标 string 实际 number、 valueAddedServices 标 number 实际字符串、picUrls 标 string 实际 JSON 数组, DTO 已按真机类型调。创建 / 取消是写操作,未在真机执行。 Co-Authored-By: Claude <noreply@anthropic.com>
4 days ago
import common.ecommerce.warehouse.model.WarehouseReturn;
import common.ecommerce.warehouse.sdk.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import java.time.Clock;
import java.util.ArrayList;
import java.util.EnumSet;
import java.util.List;
/**
* 易达云适配器。
*
fix(edayun): 修 CR 发现的三个真 bug 与若干语义问题 Critical: 1. EdayunRmaListMapper 静默丢弃调用方的仓库过滤——账户绑了数字仓 id 时, 传入不同的 warehouseCode 会被忽略,结果反而变宽。改为冲突时本地拒绝。 2. EdayunTrackMapper 把 track.receiver(收件人)映射到 signedBy(签收人), 导致每个在途包裹都被判成已签收。易达云响应没有签收人字段,改为不填。 3. 退货详情 / 列表用 warehouseName(美西1仓)当 warehouseCode,宿主拿它 equals / 回传查询会全线失效。改为只用仓编码,缺失直接回退 OMS 仓编码。 Important: 4. EdayunReturnMapper 静默丢弃 returnReason / estimatedReceiveDate / lineName——三个字段易达云都不支持,改为本地拒绝并说明原因。 5. WarehouseDirectoryCapable.carrierDirectory 默认实现把 carriers() 的码 包装成假的两层结构(carrierId == nameEn == FEDEX-G),改成默认抛不支持。 6. EdayunAdapter.printSkuLabel 改包级可见:SKU_LABEL 未声明,门面够不到, 留 public 会让调用方误以为能用。 7. products(warehouseCode) 之前完全忽略入参;改为显式优先,且必须数字。 8. 删掉 EdayunCarrierTest.warehousesAreUnsupported——它断言的是相反行为, 能过只是因为没注册路由。 9. EdayunAdapter 类注释还写着「已实现:商品建档、创建出库单」。 Minor:EdayunAdapterFactory 重复 import、CaseMarkPrintCapable javadoc 写的 BARCODE_PRINT 不存在、TODO.md 表格分隔行丢失、EdayunInventoryTest 合并残留 换行错乱。 新增回归用例:仓库过滤冲突 / 一致、三个不支持字段被拒。 验证:全仓 mvn test 通过;易达云 304 个用例全绿。 Co-Authored-By: Claude <noreply@anthropic.com>
4 days ago
* <p>已实现的能力见 {@link #capabilities()};<b>没声明的能力门面会显式抛
* {@code WarehouseUnsupportedCapabilityException},不返回空集合</b>。</p>
*
* <p>适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经
* {@code WarehouseConnection} 传入。</p>
*/
public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCapable,
OutboundCapable, WarehouseFeeCapable, WarehouseFeeEstimateCapable, InventoryCapable,
InboundCapable, WarehouseReturnCapable, BolCapable, LogisticsProductCapable,
TrackingCapable, CaseMarkPrintCapable, WarehouseDirectoryCapable {
/** 物流产品查询的适用业务:1 店铺订单(默认口径)。 */
private static final int APPLICABLE_BUSINESS_STORE_ORDER = 1;
private final HttpTransport transport;
private final JacksonJsonCodec json;
private final EdayunRequestFactory requestFactory;
private final EdayunTokenClient tokenClient;
private final TokenManager tokenManager;
public EdayunAdapter(HttpTransport transport, JacksonJsonCodec json) {
this(transport, json, null, null, Clock.systemUTC());
}
/**
* @param tokenStore 令牌缓存;为 null 时 {@link #token(WarehouseContext)} 每次都重新登录
* @param lockProvider 防击穿锁;与 tokenStore 成对提供
*/
public EdayunAdapter(HttpTransport transport, JacksonJsonCodec json,
TokenStore tokenStore, LockProvider lockProvider, Clock clock) {
this.transport = transport;
this.json = json;
this.requestFactory = new EdayunRequestFactory(json);
this.tokenClient = new EdayunTokenClient(transport, json, clock);
this.tokenManager = tokenStore == null || lockProvider == null ? null
: new TokenManager(tokenStore, lockProvider, clock,
EdayunConstants.TOKEN_EARLY_REFRESH_SECONDS) {
@Override
protected AccessToken refresh(ChannelSecret secret, AccessToken previous) {
return tokenClient.fetch(secret.endpointBaseUrl(),
secret.clientId(), secret.clientSecret());
}
};
}
@Override
public String adapterId() {
return EdayunConstants.ADAPTER_ID;
}
@Override
public WarehouseProvider provider() {
return WarehouseProvider.EDAYUN;
}
/**
* 已实现的能力。
*
* <p><b>声明了就必须有实现</b>,否则调用方看能力位会以为能用。</p>
*/
@Override
public EnumSet<WarehouseCapability> capabilities() {
return EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND,
WarehouseCapability.FEE_SETTLEMENT, WarehouseCapability.FEE_ESTIMATE,
feat(edayun): 对接退货单创建 / 详情 / 取消 / 列表 四个接口: - 创建退货单 POST /webApi/rma/info/v1/saveAndPublish(只支持 returnType=2 自行退回, 另三种要退货人地址或亚马逊单号,标准模型没有) - 退货单详情 POST /webApi/rma/info/v1/getOrderDetail - 取消退货单 POST /webApi/rma/info/v1/cancel - 退货单列表 POST /webApi/rma/info/v1/selectRmaInfoList 统一模型侧: - WarehouseReturnCapable.cancel 从 void 改成 boolean(返回值要能表达「仓方拒绝」), 目前只有易达云实现,改动安全 - queryReturns 签名从 (ctx, cursor) 改成 (ctx, ReturnQuery), 新增 ReturnQuery + ReturnQueryNoType(退货单号 / 出库单号 / 平台订单号) - 门面 returns().query(ReturnQuery) / returns().cancel(providerReturnNo), cancel 走幂等守卫 关键口径: - 创建响应 data 就是仓侧 RMA 单号(运去哪只回 code/message) - 取消响应 data 是布尔;code=200 + data=false 是仓方拒绝,抛异常而不是静默返回 false - 列表时间是字符串 yyyy-MM-dd HH:mm:ss,按仓方时区解释,不是毫秒 - 列表只认单个 status,多状态本地拒绝并提示拆查询 - 详情明细优先 checkList(仓实际收到),没有才回落 skuList(买家预报) - 状态码表来自列表文档:-1/0/1/2/3/4/5/6/7,之前只能按中文名猜 真机(2026-11-16,仓 2):列表返回 10 条 RMA,状态分布 -1/0/1/3/4/5/6 全部对上码表; 详情实测三处与文档不符——skuList.skuNum 文档标 string 实际 number、 valueAddedServices 标 number 实际字符串、picUrls 标 string 实际 JSON 数组, DTO 已按真机类型调。创建 / 取消是写操作,未在真机执行。 Co-Authored-By: Claude <noreply@anthropic.com>
4 days ago
WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.INBOUND,
WarehouseCapability.RETURN, WarehouseCapability.BOL,
WarehouseCapability.LOGISTICS_PRODUCT, WarehouseCapability.TRACKING,
WarehouseCapability.CASE_MARK_PRINT, WarehouseCapability.DIRECTORY);
}
/**
* 取一个可用 token(缓存命中则不登录)。
*
* <p>token 按 {@code appKey + clientId} 维度缓存——同一 OMS 授权账号下多个仓共用一个。</p>
*/
public AccessToken token(WarehouseContext ctx) {
ChannelSecret secret = ctx.secret();
if (tokenManager == null) {
return tokenClient.fetch(ctx.endpointBaseUrl(), secret.clientId(), secret.clientSecret());
}
return tokenManager.getOrRefresh(tokenKey(secret), secret);
}
/** 令牌缓存维度。 */
static String tokenKey(ChannelSecret secret) {
return EdayunConstants.ADAPTER_ID + ":" + secret.appKey() + ":" + secret.clientId();
}
// ------------------------------------------------------------------ 商品
/**
* 创建产品({@code POST /webApi/skuInfo/v1/createProduct})。
*
* <p>易达云是「创建」语义,不是「保存」——同 SKU 重复调用大概率报错而不是更新。
* 结果里带仓侧 {@code skuId},宿主可据此判断是否需要后续更新。</p>
*/
@Override
public ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product) {
EdayunCreateProductDtos.CreateProductRequest body =
EdayunProductMapper.toCreateRequest(product);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_PRODUCT_CREATE, bodyJson,
"warehouse.product.create");
EdayunCreateProductDtos.CreateProductResponse parsed =
json.fromJson(resp.body(), EdayunCreateProductDtos.CreateProductResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.product.create");
String skuCode = parsed.data != null && parsed.data.skuCode != null
? parsed.data.skuCode : body.skuCode;
return ProductResult.of(skuCode, "CREATED",
parsed.data == null ? null : parsed.data.skuId);
}
feat: 运去哪 / 易达云 商品查询接口 统一模型新增: - ProductQuery:providerSkus(仓侧 SKU)/ barcode / 创建时间窗 / 分页, 单次上限 100 个 SKU - ProductInfo:查询结果(仓侧 SKU、条码、尺寸重量、装箱、状态、创建时间) - WarehouseProductCapable.query(...) 默认抛不支持;门面 queryProducts(ProductQuery) 运去哪(API 113 /v1/product/findPage): - **页码从 0 开始**(文档原文),游标即页码、不做 ±1 换算 - 单页上限 100、skuList 上限 100 - 该接口没有条码 / 时间窗过滤,传了本地拒绝 - 翻页优先 last,其次 number+1 < totalPages,最后按满页兜底 - cost 没有 currency 时不成 Money(避免丢单位) 易达云(/webApi/skuInfo/v1/listProductPage): - skuCode 是逗号拼接的单个字符串,一次最多 50 个,超了本地拒绝 - 页码从 1 开始、单页上限 200 - 尺寸取**实际值**,缺失才回落 forecast*(真机 ybtest:实际 55 vs 预报 10,差 5 倍) - 「查询无数据」按空页处理,不抛异常(与轨迹接口同口径) - 查询条件全空时仓方默认查最近一个月,本地不补默认值 真机验证(2026-11-17): - 易达云:不带时间窗 total=52244;skuCode=ybtest 命中 1 行; 30 天窗口 + 2021 年建的 SKU → 「查询无数据」;10 年窗口正常命中 - 运去哪:未提供 x-api-key,只做了离线单测 SKU 口径已确认并写入文档:两边都传仓侧 SKU(建档下发的 providerSku, 为空时才是 omsSku),SDK 不做 OMS→仓侧转换。 Co-Authored-By: Claude <noreply@anthropic.com>
4 days ago
/**
* 批量查询仓侧商品资料({@code POST /webApi/skuInfo/v1/listProductPage})。
*
* <p>入参 SKU 是<b>仓侧 SKU</b>,即建档时下发到 {@code skuCode} 字段的那串
* ({@link EdayunProductMapper} 的 {@code skuOf}),不一定等于 OMS SKU。
* 易达云的 {@code skuCode} 是逗号拼接的
feat: 运去哪 / 易达云 商品查询接口 统一模型新增: - ProductQuery:providerSkus(仓侧 SKU)/ barcode / 创建时间窗 / 分页, 单次上限 100 个 SKU - ProductInfo:查询结果(仓侧 SKU、条码、尺寸重量、装箱、状态、创建时间) - WarehouseProductCapable.query(...) 默认抛不支持;门面 queryProducts(ProductQuery) 运去哪(API 113 /v1/product/findPage): - **页码从 0 开始**(文档原文),游标即页码、不做 ±1 换算 - 单页上限 100、skuList 上限 100 - 该接口没有条码 / 时间窗过滤,传了本地拒绝 - 翻页优先 last,其次 number+1 < totalPages,最后按满页兜底 - cost 没有 currency 时不成 Money(避免丢单位) 易达云(/webApi/skuInfo/v1/listProductPage): - skuCode 是逗号拼接的单个字符串,一次最多 50 个,超了本地拒绝 - 页码从 1 开始、单页上限 200 - 尺寸取**实际值**,缺失才回落 forecast*(真机 ybtest:实际 55 vs 预报 10,差 5 倍) - 「查询无数据」按空页处理,不抛异常(与轨迹接口同口径) - 查询条件全空时仓方默认查最近一个月,本地不补默认值 真机验证(2026-11-17): - 易达云:不带时间窗 total=52244;skuCode=ybtest 命中 1 行; 30 天窗口 + 2021 年建的 SKU → 「查询无数据」;10 年窗口正常命中 - 运去哪:未提供 x-api-key,只做了离线单测 SKU 口径已确认并写入文档:两边都传仓侧 SKU(建档下发的 providerSku, 为空时才是 omsSku),SDK 不做 OMS→仓侧转换。 Co-Authored-By: Claude <noreply@anthropic.com>
4 days ago
* 单个字符串且一次最多 50 个,超了本地拒绝(不截断)。
* 审核时间窗统一模型没有对应字段,不传。</p>
*
* <p>查询条件全空时仓方默认按创建时间查<b>最近一个月</b>——这一点由仓方兜底,
* 本地不补默认值。</p>
*/
@Override
public Page<ProductInfo> query(WarehouseContext ctx, ProductQuery query) {
int pageNum = EdayunProductQueryMapper.pageNumber(query.cursor());
EdayunProductQueryDtos.ListProductRequest body =
EdayunProductQueryMapper.toRequest(query, ctx.zone(), pageNum);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_PRODUCT_LIST, bodyJson,
"warehouse.product.query");
EdayunProductQueryDtos.ListProductResponse parsed =
json.fromJson(resp.body(), EdayunProductQueryDtos.ListProductResponse.class);
// 「查询无数据」是空结果,不是失败——易达云对查不到的 SKU / 条码回 code=500,
// 但语义与「运单还没轨迹」同类。
if (parsed != null && isNoData(parsed.msg)) {
return Page.empty();
}
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.product.query");
return EdayunProductQueryMapper.toPage(parsed, pageNum, body.pageSize);
}
// ------------------------------------------------------------------ 出库
/**
* 创建出库单({@code POST /webApi/order/v1/createOrder})。
*
* <p>仓侧幂等键是 {@code poNumber}(我们映射自 {@code orderRef})——文档要求
* 「取消重推时平台单号保持不变」。</p>
*/
@Override
public OutboundReceipt create(WarehouseContext ctx, OutboundCommand cmd) {
requireLabelUrl(cmd);
EdayunCreateOrderDtos.CreateOrderRequest body =
EdayunOrderMapper.toCreateRequest(cmd, ctx.providerWarehouseId());
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_ORDER_CREATE, bodyJson,
"warehouse.outbound.create");
EdayunCreateOrderDtos.CreateOrderResponse parsed =
json.fromJson(resp.body(), EdayunCreateOrderDtos.CreateOrderResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.outbound.create");
String providerOrderNo = parsed.data == null ? null : parsed.data.orderNo;
if (providerOrderNo == null || providerOrderNo.trim().isEmpty()) {
throw WarehouseException.builder()
.message("edayun createOrder returned no data.orderNo")
.operation("warehouse.outbound.create")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.rawResponse(safeRelay(resp.body()))
.retryable(false)
.build();
}
return OutboundReceipt.of(cmd.outboundRequestNo(), providerOrderNo.trim(), null);
}
/**
* 平台面单:易达云要的是<b>文件 URL</b>,不是 base64。
*
* <p>在本地就拒绝 base64,避免发出去被仓方以「面单不可访问」拒绝后难以定位。</p>
*/
private static void requireLabelUrl(OutboundCommand cmd) {
if (cmd.labelMode() != LabelMode.PLATFORM_LABEL) {
return;
}
String content = cmd.labelContentBase64();
if (content == null || content.trim().isEmpty()) {
return;
}
if (!content.startsWith("http://") && !content.startsWith("https://")) {
throw new IllegalArgumentException(
"edayun requires a label FILE URL (not base64) for "
+ cmd.outboundRequestNo()
+ "; upload the file and pass its https URL");
}
}
/**
* 查询出库单信息({@code POST /webApi/order/v1/getOrderInfo})。
*
* <p>{@code orderNo} 与 {@code poNumber} 二选一。我们优先用来源单号当
* {@code poNumber} 查(那是创建时下发的),没有来源单号才用仓侧单号。</p>
*/
@Override
public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) {
EdayunGetOrderDtos.GetOrderRequest body = new EdayunGetOrderDtos.GetOrderRequest();
if (hasText(ref.outboundRequestNo())) {
body.poNumber = ref.outboundRequestNo().trim();
} else if (hasText(ref.providerOrderId())) {
body.orderNo = ref.providerOrderId().trim();
} else {
throw new IllegalArgumentException(
"edayun needs outboundRequestNo (as poNumber) or providerOrderId (as orderNo)");
}
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_ORDER_GET, bodyJson,
"warehouse.outbound.get");
EdayunGetOrderDtos.GetOrderResponse parsed =
json.fromJson(resp.body(), EdayunGetOrderDtos.GetOrderResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.outbound.get");
if (parsed.data == null) {
return null;
}
return EdayunOrderQueryMapper.toOrder(parsed.data, ctx.warehouseCode(),
ref.outboundRequestNo());
}
@Override
public Page<OutboundOrder> query(WarehouseContext ctx, OutboundQuery query) {
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.OUTBOUND);
}
/**
* 取消前校验({@code POST /webApi/order/v1/checkCancelStatus})。
*
* <p>返回能不能不收费取消:{@code Published} 免费 / {@code Shipment} 收费 /
* 其余(含无法识别)按不可取消。</p>
*/
@Override
public CancelEligibility checkCancel(WarehouseContext ctx, OutboundRef ref) {
EdayunCancelDtos.CancelRequest body = cancelRequestOf(
ref.outboundRequestNo(), ref.providerOrderId());
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_ORDER_CHECK_CANCEL, bodyJson,
"warehouse.outbound.checkCancel");
EdayunCancelDtos.CheckCancelResponse parsed =
json.fromJson(resp.body(), EdayunCancelDtos.CheckCancelResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.outbound.checkCancel");
return EdayunCancelStatus.toCore(parsed.data);
}
/**
* 取消订单({@code POST /webApi/order/v1/cancelOrder})。
*
* <p>文档说明仓库操作后会收取取消费,可以先用 {@link #checkCancel} 判定。
* 这里不做「收费必须 acceptCharge」的强制拦截——因为校验与实际取消是两次调用,
* 中间状态可能变化;是否调用由宿主决定。收费与否通过 {@link CancelResult#cancelFee()}
* 之外的 {@code rawStatus} 与后续账单体现。</p>
*/
@Override
public CancelResult cancel(WarehouseContext ctx, CancelCommand cmd) {
EdayunCancelDtos.CancelRequest body = cancelRequestOf(
cmd.outboundRequestNo(), cmd.providerOrderId());
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_ORDER_CANCEL, bodyJson,
"warehouse.outbound.cancel");
EdayunCancelDtos.CancelOrderResponse parsed =
json.fromJson(resp.body(), EdayunCancelDtos.CancelOrderResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.outbound.cancel");
boolean cancelled = parsed.data != null && parsed.data;
return CancelResult.builder()
.outboundRequestNo(cmd.outboundRequestNo())
.providerOrderId(cmd.providerOrderId())
// data=false 表示仓侧拒绝,具体原因在 msg 里
.cancelled(cancelled)
.eligibility(cancelled ? CancelEligibility.FREE : CancelEligibility.BLOCKED)
.rawStatus(parsed.msg)
.build();
}
/**
* 取消类请求体:{@code orderNo}(仓侧)优先级高于 {@code poNumber}(我们的单号)。
*
* <p>与文档一致:「ORD 单号优先级更高」。</p>
*/
private static EdayunCancelDtos.CancelRequest cancelRequestOf(String outboundRequestNo,
String providerOrderId) {
EdayunCancelDtos.CancelRequest body = new EdayunCancelDtos.CancelRequest();
if (hasText(providerOrderId)) {
body.orderNo = providerOrderId.trim();
}
if (hasText(outboundRequestNo)) {
body.poNumber = outboundRequestNo.trim();
}
if (body.orderNo == null && body.poNumber == null) {
throw new IllegalArgumentException(
"edayun cancel needs outboundRequestNo (poNumber) or providerOrderId (orderNo)");
}
return body;
}
/**
* 查面单({@code POST /webApi/order/v1/getOrderLabel})。
*
* <p>返回的 {@code labels} 与 {@code trackingNo} 都是逗号拼接、按位置对应;
* 一个包裹(trackingNo)对应一个面单 URL。</p>
*/
@Override
public List<PackageResult> packages(WarehouseContext ctx, OutboundRef ref) {
EdayunGetOrderLabelDtos.GetLabelRequest body = new EdayunGetOrderLabelDtos.GetLabelRequest();
if (hasText(ref.outboundRequestNo())) {
body.poNumber = ref.outboundRequestNo().trim();
} else if (hasText(ref.providerOrderId())) {
body.orderNo = ref.providerOrderId().trim();
} else {
throw new IllegalArgumentException(
"edayun needs outboundRequestNo (as poNumber) or providerOrderId (as orderNo)");
}
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_ORDER_LABEL, bodyJson,
"warehouse.outbound.packages");
EdayunGetOrderLabelDtos.GetLabelResponse parsed =
json.fromJson(resp.body(), EdayunGetOrderLabelDtos.GetLabelResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.outbound.packages");
return EdayunOrderQueryMapper.toPackages(parsed.data, ref.outboundRequestNo());
}
/** 原始响应是否为空串。 */
private static boolean hasText(String v) {
return v != null && !v.trim().isEmpty();
}
// ------------------------------------------------------------------ 入库
/**
* 创建自发入库单并发布
* ({@code POST /webApi/entryInfo/v1/saveEntrySpontaneousOrder},{@code saveType=2})。
*
* <p>一次调用直接发布,不走「先存草稿再发布」两步——文档里发布是保存的一部分。
* 快递类(海快 / 空运 / 快递)发布时仓方还要求 {@code shipCompany + waybill},
* 卡车类要求 {@code estimatedDepartureTime},标准模型没有这几个字段,
* 缺了由仓方报错,不在本地编造。</p>
*/
@Override
public InboundReceipt create(WarehouseContext ctx, InboundCommand cmd) {
EdayunInboundDtos.SaveEntryRequest body = EdayunInboundMapper.toRequest(
cmd, EdayunInboundMapper.SAVE_PUBLISH, null, ctx.providerWarehouseId());
return saveEntry(ctx, body, cmd.inboundRequestNo(), "warehouse.inbound.create");
}
/**
* 编辑自发入库单({@code saveType=1})。
*
* @param inboundRef 仓侧入库单号({@code entryCode}),不是我们的来源单号
*/
@Override
public void improve(WarehouseContext ctx, String inboundRef, InboundCommand cmd) {
EdayunInboundDtos.SaveEntryRequest body = EdayunInboundMapper.toRequest(
cmd, EdayunInboundMapper.SAVE_UPDATE, inboundRef, ctx.providerWarehouseId());
saveEntry(ctx, body, cmd.inboundRequestNo(), "warehouse.inbound.improve");
}
private InboundReceipt saveEntry(WarehouseContext ctx, EdayunInboundDtos.SaveEntryRequest body,
String inboundRequestNo, String operation) {
HttpResponse resp = send(ctx, EdayunConstants.PATH_INBOUND_SAVE, json.toJson(body), operation);
EdayunInboundDtos.SaveEntryResponse parsed =
json.fromJson(resp.body(), EdayunInboundDtos.SaveEntryResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, operation);
String entryCode = parsed.data == null ? null : parsed.data.entryCode;
return InboundReceipt.of(inboundRequestNo, entryCode);
}
/**
* 查入库单({@code POST /webApi/entryInfo/v1/selectEntrySkuGoodsDetail})。
*
* <p>接口按 SKU 逐行返回,这里翻完所有页合并成一张单。
* <b>只认仓侧 {@code entryCode}(REV 单号)</b>——接口不支持按客户单号查。</p>
*
* <p>接口只回 SKU 级数据:仓库编码取 OMS 配置的仓,单头状态由各 SKU 状态汇总
* (还有 SKU 没上架,整单就不算完成)。</p>
*/
@Override
public InboundOrder get(WarehouseContext ctx, String inboundRef) {
List<EdayunInboundQueryDtos.EntrySkuRow> rows = fetchSkuRows(ctx, inboundRef,
"warehouse.inbound.get");
if (rows.isEmpty()) {
return null;
}
return EdayunInboundQueryMapper.toOrder(inboundRef.trim(), rows, ctx.warehouseCode());
}
/**
* 单条查。接口没有列表 / 时间窗,{@code cursor} 按仓侧 {@code entryCode} 解释,
* 返回 0 或 1 条;不传就拒绝,别被当成增量同步入口。
*/
@Override
public Page<InboundOrder> query(WarehouseContext ctx, String cursor) {
if (!hasText(cursor)) {
throw WarehouseException.builder()
.message("edayun has no inbound list API; pass entryCode (REV no) as cursor")
.operation("warehouse.inbound.query")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.retryable(false)
.build();
}
InboundOrder order = get(ctx, cursor);
return order == null ? Page.<InboundOrder>empty()
: Page.last(java.util.Collections.singletonList(order));
}
/** 翻完所有页,合并 SKU 行。 */
private List<EdayunInboundQueryDtos.EntrySkuRow> fetchSkuRows(
WarehouseContext ctx, String entryCode, String operation) {
List<EdayunInboundQueryDtos.EntrySkuRow> all =
new ArrayList<EdayunInboundQueryDtos.EntrySkuRow>();
for (int page = 1; ; page++) {
if (page > MAX_INBOUND_PAGES) {
// 单页 200 条 × 20 页 = 4000 个 SKU,再大多半是单号传错了
throw WarehouseException.builder()
.message("edayun inbound " + entryCode + " exceeded " + MAX_INBOUND_PAGES
+ " pages of sku detail; check the entryCode")
.operation(operation)
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.retryable(false)
.build();
}
EdayunInboundQueryDtos.SelectEntrySkuRequest body =
EdayunInboundQueryMapper.toRequest(entryCode, page);
HttpResponse resp = send(ctx, EdayunConstants.PATH_INBOUND_SKU_DETAIL,
json.toJson(body), operation);
EdayunInboundQueryDtos.SelectEntrySkuResponse parsed =
json.fromJson(resp.body(), EdayunInboundQueryDtos.SelectEntrySkuResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, operation);
if (parsed.rows == null || parsed.rows.isEmpty()) {
return all;
}
all.addAll(parsed.rows);
if (parsed.rows.size() < body.pageSize) {
return all;
}
}
}
/** 入库明细翻页上限。 */
private static final int MAX_INBOUND_PAGES = 20;
// ------------------------------------------------------------------ 库存
/**
* 库存同步策略:接口没有时间维度,只能按页全量拉。
*
* <p>宿主按本值做全量 diff,不要指望 {@code updatedAfter} 生效。</p>
*/
@Override
public InventorySyncStrategy syncStrategy() {
return InventorySyncStrategy.FULL_PULL_DIFF;
}
/**
* 库存查询({@code POST /webApi/userSkuStock/v1/queryInventory})。
*
* <p>一行 = 一个 SKU 在一个仓的汇总。默认只返回总库存大于 0 的数据,
* 需要零库存时由调用方传 {@code includeZeroStock(true)}。</p>
*
* <p>分页按页码游标:单页最多 500 条,{@code total} 是总行数。</p>
*/
@Override
public Page<InventorySnapshot> query(WarehouseContext ctx, InventoryQuery query) {
int pageNum = EdayunInventoryMapper.pageNumber(query.cursor());
EdayunInventoryDtos.QueryInventoryRequest body =
EdayunInventoryMapper.toRequest(query, ctx.providerWarehouseId(), pageNum);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_INVENTORY, bodyJson,
"warehouse.inventory.query");
EdayunInventoryDtos.QueryInventoryResponse parsed =
json.fromJson(resp.body(), EdayunInventoryDtos.QueryInventoryResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.inventory.query");
return EdayunInventoryMapper.toPage(parsed, ctx.warehouseCode(),
java.time.Instant.now(ctx.clock()), pageNum, body.pageSize);
}
// ------------------------------------------------------------------ 费用
/**
* 查询交易明细({@code POST /webApi/accountFlow/list})。
*
* <p>文档说明「同一个单号的某个计费项有多条数据」,所以<b>不做去重</b>,
* 每条流水都映射成一条 {@link BillingDocument},靠 {@code serialNumber} 区分。</p>
*
* <p>分页:文档要求 {@code pageNum} / {@code pageSize} 必填,当前只取第一页
* (200 条);超过时截断——<b>待确认是否需要翻页</b>。</p>
*/
@Override
public List<BillingDocument> settlements(WarehouseContext ctx, FeeQuery query) {
EdayunAccountFlowDtos.ListFlowRequest body = EdayunFeeMapper.toRequest(query);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_ACCOUNT_FLOW, bodyJson,
"warehouse.fee.settlements");
EdayunAccountFlowDtos.ListFlowResponse parsed =
json.fromJson(resp.body(), EdayunAccountFlowDtos.ListFlowResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.fee.settlements");
if (parsed.rows == null || parsed.rows.isEmpty()) {
return java.util.Collections.emptyList();
}
List<BillingDocument> out = new ArrayList<BillingDocument>(parsed.rows.size());
for (EdayunAccountFlowDtos.FlowRow row : parsed.rows) {
out.add(EdayunFeeMapper.toDocument(row, ctx.warehouseCode()));
}
return out;
}
/**
* 查询订单费用明细
* ({@code POST /webApi/order/cost/v1/selectOrderCostInfoList})。
*
* <p>与 {@link #settlements}(账户流水)不同:这个按订单拆费用,
* 带应收 / 折扣 / 实付与计费重。落库金额取<b>实付</b>。
*
* <p>一个订单可能展开成多条 {@link BillingDocument}(逐计费项)。</p>
*/
@Override
public List<BillingDocument> orderCosts(WarehouseContext ctx, FeeQuery query) {
EdayunOrderCostDtos.SelectOrderCostRequest body = EdayunOrderCostMapper.toRequest(query);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_ORDER_COST, bodyJson,
"warehouse.fee.orderCosts");
EdayunOrderCostDtos.SelectOrderCostResponse parsed =
json.fromJson(resp.body(), EdayunOrderCostDtos.SelectOrderCostResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.fee.orderCosts");
if (parsed.rows == null || parsed.rows.isEmpty()) {
return java.util.Collections.emptyList();
}
List<BillingDocument> out = new ArrayList<BillingDocument>();
for (EdayunOrderCostDtos.OrderCostRow row : parsed.rows) {
out.addAll(EdayunOrderCostMapper.toDocuments(row, ctx.warehouseCode()));
}
return out;
}
/**
* 查询仓租费用明细
* ({@code POST /webApi/order/cost/v1/selectUserRentDetailList})。
*
* <p>与 {@link #settlements}(账户流水)、{@link #orderCosts}(按订单拆费用)都不同:
* 这个只出仓储费,按 SKU + 计费日逐条,带租期天数与计费体积。</p>
*
* <p>文档要求计费时间窗必填且不超过 3 个月,所以按<b>时间窗 + 翻页</b>拉:
* 一页 200 条,最多 {@link EdayunRentDetailMapper#MAX_PAGES} 页。仍有剩余时
* <b>显式失败</b>而不是截断——少算仓租会让对账金额偏小。</p>
*/
@Override
public List<BillingDocument> storageRents(WarehouseContext ctx, FeeQuery query) {
EdayunRentDetailDtos.SelectRentDetailRequest body =
EdayunRentDetailMapper.toRequest(query, ctx.providerWarehouseId());
List<BillingDocument> out = new ArrayList<BillingDocument>();
long rowsFetched = 0;
for (int page = 1; ; page++) {
body.pageNum = page;
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_RENT_DETAIL, bodyJson,
"warehouse.fee.storageRents");
EdayunRentDetailDtos.SelectRentDetailResponse parsed =
json.fromJson(resp.body(), EdayunRentDetailDtos.SelectRentDetailResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.fee.storageRents");
if (parsed.rows == null || parsed.rows.isEmpty()) {
return out;
}
out.addAll(EdayunRentDetailMapper.toDocuments(parsed.rows, ctx.warehouseCode()));
rowsFetched += parsed.rows.size();
if (rowsFetched > EdayunRentDetailMapper.MAX_ROWS) {
break;
}
// 不满一页说明到底了(总行数恰好是整页时,下一轮会拿到空页)
if (parsed.rows.size() < EdayunRentDetailMapper.MAX_PAGE_SIZE) {
return out;
}
}
throw WarehouseException.builder()
.message("edayun rent detail exceeded " + EdayunRentDetailMapper.MAX_ROWS
+ " rows (" + EdayunRentDetailMapper.MAX_PAGES + " pages);"
+ " narrow the billing time window and query again")
.operation("warehouse.fee.storageRents")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.retryable(false)
.build();
}
// ------------------------------------------------------------------ 试算
/**
* 费用试算({@code POST /webApi/estimate/v1/trial})。
*
* <p>只做「按包裹」这一种预估——标准模型只带包裹尺寸重量。
* 真机实测:按 SKU 预估要求 SKU 在仓侧已建档,虚拟包裹在 PR 环境直接
* 「内部服务器错误」,两者都不适合作为默认路径。</p>
*
* <p>响应分 {@code successItems} / {@code failItems},只映射前者;
* 全部失败时返回一个 {@code carriers()} 为空的结果(表示该仓无法承运)。
* 渠道的无报价原因(如「不支持派送」)只在原报文里,不同步到统一模型。</p>
*/
@Override
public List<FeeEstimateResult> estimate(WarehouseContext ctx, FeeEstimateQuery query) {
EdayunFeeEstimateDtos.TrialRequest body =
EdayunFeeEstimateMapper.toRequest(query, ctx.providerWarehouseId());
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_FEE_ESTIMATE, bodyJson,
"warehouse.fee.estimate");
EdayunFeeEstimateDtos.TrialResponse parsed =
json.fromJson(resp.body(), EdayunFeeEstimateDtos.TrialResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.fee.estimate");
return java.util.Collections.singletonList(
EdayunFeeEstimateMapper.toResult(parsed, ctx.warehouseCode()));
}
feat(edayun): 对接退货单创建 / 详情 / 取消 / 列表 四个接口: - 创建退货单 POST /webApi/rma/info/v1/saveAndPublish(只支持 returnType=2 自行退回, 另三种要退货人地址或亚马逊单号,标准模型没有) - 退货单详情 POST /webApi/rma/info/v1/getOrderDetail - 取消退货单 POST /webApi/rma/info/v1/cancel - 退货单列表 POST /webApi/rma/info/v1/selectRmaInfoList 统一模型侧: - WarehouseReturnCapable.cancel 从 void 改成 boolean(返回值要能表达「仓方拒绝」), 目前只有易达云实现,改动安全 - queryReturns 签名从 (ctx, cursor) 改成 (ctx, ReturnQuery), 新增 ReturnQuery + ReturnQueryNoType(退货单号 / 出库单号 / 平台订单号) - 门面 returns().query(ReturnQuery) / returns().cancel(providerReturnNo), cancel 走幂等守卫 关键口径: - 创建响应 data 就是仓侧 RMA 单号(运去哪只回 code/message) - 取消响应 data 是布尔;code=200 + data=false 是仓方拒绝,抛异常而不是静默返回 false - 列表时间是字符串 yyyy-MM-dd HH:mm:ss,按仓方时区解释,不是毫秒 - 列表只认单个 status,多状态本地拒绝并提示拆查询 - 详情明细优先 checkList(仓实际收到),没有才回落 skuList(买家预报) - 状态码表来自列表文档:-1/0/1/2/3/4/5/6/7,之前只能按中文名猜 真机(2026-11-16,仓 2):列表返回 10 条 RMA,状态分布 -1/0/1/3/4/5/6 全部对上码表; 详情实测三处与文档不符——skuList.skuNum 文档标 string 实际 number、 valueAddedServices 标 number 实际字符串、picUrls 标 string 实际 JSON 数组, DTO 已按真机类型调。创建 / 取消是写操作,未在真机执行。 Co-Authored-By: Claude <noreply@anthropic.com>
4 days ago
// ------------------------------------------------------------------ 退货
/**
* 创建退货单 / 退货预报({@code POST /webApi/rma/info/v1/saveAndPublish})。
*
* <p>统一模型只对应「自行退回」({@code returnType=2}):它要求退货运单号,
* 正好是买家自己寄回的场景。未妥投 / 返邮 / FBA 退回要退货人地址或亚马逊单号,
* 标准模型没有——见 TODO。</p>
*
* <p>与运去哪不同,<b>响应 {@code data} 就是仓侧退货单号</b>,可直接落
* {@code providerReturnId};状态不回,只能后续人工或回调补。</p>
*/
@Override
public WarehouseReturn create(WarehouseContext ctx, ReturnCommand cmd) {
EdayunReturnDtos.SaveReturnRequest body =
EdayunReturnMapper.toRequest(cmd, ctx.providerWarehouseId());
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_RETURN_CREATE, bodyJson,
"warehouse.return.create");
EdayunReturnDtos.SaveReturnResponse parsed =
json.fromJson(resp.body(), EdayunReturnDtos.SaveReturnResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.return.create");
if (parsed.data == null || parsed.data.trim().isEmpty()) {
throw WarehouseException.builder()
.message("edayun return create returned no return order no")
.operation("warehouse.return.create")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.rawResponse(safeRelay(resp.body()))
.retryable(false)
.build();
}
return EdayunReturnMapper.toCreated(cmd, parsed.data.trim(), ctx.warehouseCode());
}
/**
* 获取退货单详情({@code POST /webApi/rma/info/v1/getOrderDetail})。
*
* <p>{@code returnRequestNo} 可以是 OMS 退货单号,也可以是仓方 RMA 号——
* 仓方只认 {@code rmaCode},所以<b>非 RMA 号要先有创建时拿到的
* {@code providerReturnId}</b>。这里原样传,查不到由仓方报错。</p>
*
* <p>明细行优先取仓的检验结果({@code checkList}),没有才退回预报
* ({@code skuList})——对账以实际收到为准。</p>
*/
@Override
public WarehouseReturn getReturn(WarehouseContext ctx, String returnRequestNo) {
EdayunReturnDetailDtos.GetReturnRequest body =
EdayunReturnDetailMapper.toRequest(returnRequestNo);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_RETURN_DETAIL, bodyJson,
"warehouse.return.get");
EdayunReturnDetailDtos.GetReturnResponse parsed =
json.fromJson(resp.body(), EdayunReturnDetailDtos.GetReturnResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.return.get");
if (parsed.data == null) {
// 单号不存在时仓方可能回 code=200 + data=null,按「查不到」返回 null
return null;
}
return EdayunReturnDetailMapper.toReturn(parsed.data, ctx.warehouseCode(),
body.rmaCode);
}
/**
* 取消退货单({@code POST /webApi/rma/info/v1/cancel})。
*
* <p>只认仓方 {@code rmaCode},所以传的必须是创建时拿到的
* {@code providerReturnId}——用 OMS 单号会被仓方查不到。</p>
*
* <p>响应 {@code data=true} 才算成功。{@code code=200} + {@code data=false}
* 是仓方拒绝(如已收货),这里抛异常而不是静默返回 false——
* 取消退货是状态变更,调用方必须知道没成功。</p>
*/
@Override
public boolean cancel(WarehouseContext ctx, String providerReturnNo) {
if (!hasText(providerReturnNo)) {
throw new IllegalArgumentException(
"edayun return cancel needs the provider return no (rmaCode)");
}
EdayunCancelReturnDtos.CancelReturnRequest body =
new EdayunCancelReturnDtos.CancelReturnRequest();
body.rmaCode = providerReturnNo.trim();
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_RETURN_CANCEL, bodyJson,
"warehouse.return.cancel");
EdayunCancelReturnDtos.CancelReturnResponse parsed =
json.fromJson(resp.body(), EdayunCancelReturnDtos.CancelReturnResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.return.cancel");
if (parsed.data == null || !parsed.data) {
throw WarehouseException.builder()
.message("edayun return cancel rejected: " + parsed.msg)
.operation("warehouse.return.cancel")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.rawResponse(safeRelay(resp.body()))
.retryable(false)
.build();
}
return true;
}
/**
* 查询退货单列表({@code POST /webApi/rma/info/v1/selectRmaInfoList})。
*
* <p>只回单头,没有明细行与退货人地址;要明细请用 {@link #getReturn}。</p>
*
* <p>时间窗不传时仓方默认近一个月——这一点由仓方兜底,本地不补默认值,
* 免得「没给时间窗」和「显式要近一个月」两种情况被混掉。</p>
*/
@Override
public Page<WarehouseReturn> queryReturns(WarehouseContext ctx, ReturnQuery query) {
int pageNum = EdayunRmaListMapper.pageNumber(query.cursor());
EdayunRmaListDtos.SelectRmaListRequest body = EdayunRmaListMapper.toRequest(
query, ctx.providerWarehouseId(), ctx.zone(), pageNum);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_RETURN_LIST, bodyJson,
"warehouse.return.query");
EdayunRmaListDtos.SelectRmaListResponse parsed =
json.fromJson(resp.body(), EdayunRmaListDtos.SelectRmaListResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.return.query");
return EdayunRmaListMapper.toPage(parsed, ctx.warehouseCode(), pageNum, body.pageSize);
}
/**
* 按明细行设置检验后处理方式。
*
* <p>需要仓侧明细行 id,而查退货单的接口还没有——无法构造,显式拒绝。</p>
*/
@Override
public void process(WarehouseContext ctx, ReturnProcessCommand cmd) {
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN_DISPOSITION);
}
// ------------------------------------------------------------------ BOL / 物流产品
/**
* 查询 BOL(提单 / 提货凭证)
* ({@code POST /webApi/fbaOrder/v1/getOrderBolList})。
*
* <p>店铺订单与平台仓订单共用,{@code orderNo} 传 EDA 的平台仓订单号
* (如 {@code FBA473182144})。没有 BOL 时返回空列表,不是错误。</p>
*/
@Override
public List<BolDocument> orderBols(WarehouseContext ctx, String providerOrderNo) {
EdayunBolDtos.GetBolRequest body = EdayunBolMapper.toRequest(providerOrderNo);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_BOL_LIST, bodyJson,
"warehouse.bol.order");
EdayunBolDtos.GetBolResponse parsed =
json.fromJson(resp.body(), EdayunBolDtos.GetBolResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.bol.order");
return EdayunBolMapper.toDocuments(parsed);
}
/**
* 查物流产品清单
* ({@code POST /webApi/order/listByLogisticProductHasPerm})。
*
* <p>{@code productId = -998}(使用分物流规则)不是真实产品,映射时跳过。</p>
*/
@Override
public List<LogisticsProduct> products(WarehouseContext ctx, String warehouseCode) {
// 统一模型不区分业务类型,默认查「店铺订单」(1);
// 不传反而返回全账号的产品,量太大
EdayunLogisticsProductDtos.ListProductRequest body = EdayunLogisticsProductMapper.toRequest(
fix(edayun): 修 CR 发现的三个真 bug 与若干语义问题 Critical: 1. EdayunRmaListMapper 静默丢弃调用方的仓库过滤——账户绑了数字仓 id 时, 传入不同的 warehouseCode 会被忽略,结果反而变宽。改为冲突时本地拒绝。 2. EdayunTrackMapper 把 track.receiver(收件人)映射到 signedBy(签收人), 导致每个在途包裹都被判成已签收。易达云响应没有签收人字段,改为不填。 3. 退货详情 / 列表用 warehouseName(美西1仓)当 warehouseCode,宿主拿它 equals / 回传查询会全线失效。改为只用仓编码,缺失直接回退 OMS 仓编码。 Important: 4. EdayunReturnMapper 静默丢弃 returnReason / estimatedReceiveDate / lineName——三个字段易达云都不支持,改为本地拒绝并说明原因。 5. WarehouseDirectoryCapable.carrierDirectory 默认实现把 carriers() 的码 包装成假的两层结构(carrierId == nameEn == FEDEX-G),改成默认抛不支持。 6. EdayunAdapter.printSkuLabel 改包级可见:SKU_LABEL 未声明,门面够不到, 留 public 会让调用方误以为能用。 7. products(warehouseCode) 之前完全忽略入参;改为显式优先,且必须数字。 8. 删掉 EdayunCarrierTest.warehousesAreUnsupported——它断言的是相反行为, 能过只是因为没注册路由。 9. EdayunAdapter 类注释还写着「已实现:商品建档、创建出库单」。 Minor:EdayunAdapterFactory 重复 import、CaseMarkPrintCapable javadoc 写的 BARCODE_PRINT 不存在、TODO.md 表格分隔行丢失、EdayunInventoryTest 合并残留 换行错乱。 新增回归用例:仓库过滤冲突 / 一致、三个不支持字段被拒。 验证:全仓 mvn test 通过;易达云 304 个用例全绿。 Co-Authored-By: Claude <noreply@anthropic.com>
4 days ago
EdayunLogisticsProductMapper.resolveWarehouseId(
warehouseCode, ctx.providerWarehouseId()),
APPLICABLE_BUSINESS_STORE_ORDER);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_LOGISTICS_PRODUCTS, bodyJson,
"warehouse.logistics.products");
EdayunLogisticsProductDtos.ListProductResponse parsed =
json.fromJson(resp.body(), EdayunLogisticsProductDtos.ListProductResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.logistics.products");
return EdayunLogisticsProductMapper.toProducts(
parsed == null ? null : parsed.data, ctx.warehouseCode());
}
// ------------------------------------------------------------------ 物流轨迹
/**
* 按跟踪号查轨迹节点({@code POST /webApi/track/getTrackInfoList})。
*
* <p>请求体是<b>纯字符串数组</b>,文档示例的嵌套对象是错的。
* 仓方无轨迹时返回<b>空列表</b>——真机对查不到的跟踪号回
* {@code code=500, msg=未匹配到轨迹},那是「没轨迹」不是「调用失败」。</p>
*/
@Override
public List<TrackEvent> track(WarehouseContext ctx, String trackingNumber) {
EdayunTrackDtos.Track parsed = fetchTrack(ctx, trackingNumber, "warehouse.track");
return EdayunTrackMapper.toTrackEvents(parsed);
}
/**
* 按跟踪号查运单级轨迹;除节点外带上网时间与妥投时间。
*
* <p>文档说明「主要关注上网时间跟妥投时间」,这两个在
* {@link TrackingInfo#firstOnlineAt()} / {@link TrackingInfo#deliveredAt()}。</p>
*/
@Override
public TrackingInfo trackShipment(WarehouseContext ctx, String trackingNumber) {
EdayunTrackDtos.Track parsed = fetchTrack(ctx, trackingNumber, "warehouse.track.shipment");
return EdayunTrackMapper.toTrackingInfo(parsed);
}
/**
* 查一条轨迹;查不到返回 null。
*
* <p><b>「未匹配到轨迹」按空结果处理</b>:仓方把这个当业务失败(code=500),
* 但对调用方来说和「运单还没揽收」是同一件事——两者都不该抛异常,
* 否则宿主无法区分「真失败」和「还没轨迹」。</p>
*/
private EdayunTrackDtos.Track fetchTrack(WarehouseContext ctx, String trackingNumber,
String operation) {
List<String> body = EdayunTrackMapper.toRequest(
java.util.Collections.singletonList(trackingNumber));
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_TRACK, bodyJson, operation);
EdayunTrackDtos.GetTrackResponse parsed =
json.fromJson(resp.body(), EdayunTrackDtos.GetTrackResponse.class);
feat: 运去哪 / 易达云 商品查询接口 统一模型新增: - ProductQuery:providerSkus(仓侧 SKU)/ barcode / 创建时间窗 / 分页, 单次上限 100 个 SKU - ProductInfo:查询结果(仓侧 SKU、条码、尺寸重量、装箱、状态、创建时间) - WarehouseProductCapable.query(...) 默认抛不支持;门面 queryProducts(ProductQuery) 运去哪(API 113 /v1/product/findPage): - **页码从 0 开始**(文档原文),游标即页码、不做 ±1 换算 - 单页上限 100、skuList 上限 100 - 该接口没有条码 / 时间窗过滤,传了本地拒绝 - 翻页优先 last,其次 number+1 < totalPages,最后按满页兜底 - cost 没有 currency 时不成 Money(避免丢单位) 易达云(/webApi/skuInfo/v1/listProductPage): - skuCode 是逗号拼接的单个字符串,一次最多 50 个,超了本地拒绝 - 页码从 1 开始、单页上限 200 - 尺寸取**实际值**,缺失才回落 forecast*(真机 ybtest:实际 55 vs 预报 10,差 5 倍) - 「查询无数据」按空页处理,不抛异常(与轨迹接口同口径) - 查询条件全空时仓方默认查最近一个月,本地不补默认值 真机验证(2026-11-17): - 易达云:不带时间窗 total=52244;skuCode=ybtest 命中 1 行; 30 天窗口 + 2021 年建的 SKU → 「查询无数据」;10 年窗口正常命中 - 运去哪:未提供 x-api-key,只做了离线单测 SKU 口径已确认并写入文档:两边都传仓侧 SKU(建档下发的 providerSku, 为空时才是 omsSku),SDK 不做 OMS→仓侧转换。 Co-Authored-By: Claude <noreply@anthropic.com>
4 days ago
if (parsed != null && isNoData(parsed.msg)) {
return null;
}
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, operation);
return EdayunTrackMapper.find(parsed, trackingNumber);
}
feat: 运去哪 / 易达云 商品查询接口 统一模型新增: - ProductQuery:providerSkus(仓侧 SKU)/ barcode / 创建时间窗 / 分页, 单次上限 100 个 SKU - ProductInfo:查询结果(仓侧 SKU、条码、尺寸重量、装箱、状态、创建时间) - WarehouseProductCapable.query(...) 默认抛不支持;门面 queryProducts(ProductQuery) 运去哪(API 113 /v1/product/findPage): - **页码从 0 开始**(文档原文),游标即页码、不做 ±1 换算 - 单页上限 100、skuList 上限 100 - 该接口没有条码 / 时间窗过滤,传了本地拒绝 - 翻页优先 last,其次 number+1 < totalPages,最后按满页兜底 - cost 没有 currency 时不成 Money(避免丢单位) 易达云(/webApi/skuInfo/v1/listProductPage): - skuCode 是逗号拼接的单个字符串,一次最多 50 个,超了本地拒绝 - 页码从 1 开始、单页上限 200 - 尺寸取**实际值**,缺失才回落 forecast*(真机 ybtest:实际 55 vs 预报 10,差 5 倍) - 「查询无数据」按空页处理,不抛异常(与轨迹接口同口径) - 查询条件全空时仓方默认查最近一个月,本地不补默认值 真机验证(2026-11-17): - 易达云:不带时间窗 total=52244;skuCode=ybtest 命中 1 行; 30 天窗口 + 2021 年建的 SKU → 「查询无数据」;10 年窗口正常命中 - 运去哪:未提供 x-api-key,只做了离线单测 SKU 口径已确认并写入文档:两边都传仓侧 SKU(建档下发的 providerSku, 为空时才是 omsSku),SDK 不做 OMS→仓侧转换。 Co-Authored-By: Claude <noreply@anthropic.com>
4 days ago
/** 仓方「没有数据」的提示语:查不到不等于调用失败。 */
private static boolean isNoData(String msg) {
return msg != null && (msg.contains("查询无数据") || msg.contains("未匹配到轨迹")
|| msg.contains("跟踪号为空"));
}
// ------------------------------------------------------------------ 条码打印
// ------------------------------------------------------------------ 箱唛
/**
* 打印箱唛({@code POST /webApi/skuInfo/v2/printBarcode})。
*
* <p><b>端点名叫 printBarcode,但实际打的是箱唛(外箱标)</b>——已与仓方确认。
* 真正的 SKU 标走 {@code printSkuLabel}(端点 {@code newPrintCaseMark})。</p>
*
* <p>与入库箱标({@code inbound().printBoxLabel})不同:那个是运去哪风格的
* 异步任务(只回任务号),易达云这个<b>同步返回 PDF 地址</b>。</p>
*
* <p>真机实测的仓方校验:{@code productInfos} 为空报「产品信息不能为空」,
* 缺 {@code pageSize} 报「纸张尺寸不能为空」,{@code pageSize} 非 0~3 报
* 「内部服务器错误」,{@code num=0} 同样「内部服务器错误」,超过 50 个 SKU
* 报「最多打印50个SKU」。本地已提前挡住后两者。</p>
*/
@Override
public WarehouseLabel printCaseMarks(WarehouseContext ctx, CaseMarkPrintCommand cmd) {
EdayunCaseMarkDtos.PrintCaseMarkRequest body = EdayunCaseMarkMapper.toRequest(cmd);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_CASE_MARK_PRINT, bodyJson,
"warehouse.caseMark.print");
EdayunCaseMarkDtos.PrintCaseMarkResponse parsed =
json.fromJson(resp.body(), EdayunCaseMarkDtos.PrintCaseMarkResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.caseMark.print");
if (parsed.data == null || parsed.data.trim().isEmpty()) {
throw WarehouseException.builder()
.message("edayun printBarcode returned no file url")
.operation("warehouse.caseMark.print")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.rawResponse(safeRelay(resp.body()))
.retryable(false)
.build();
}
return EdayunCaseMarkMapper.toLabel(parsed.data.trim(), cmd);
}
// ------------------------------------------------------------------ SKU 标
/**
* 打印 SKU 标({@code POST /webApi/entryInfo/v1/newPrintCaseMark})。
*
* <p><b>端点名叫 newPrintCaseMark,但实际打的是 SKU 标</b>——已与仓方确认。
* 箱唛走 {@code printCaseMarks}(端点 {@code printBarcode})。</p>
*
* <p>统一模型的 {@code BoxLabelCommand} 没有「选哪些箱」的字段,
* 所以默认整单打印;要打部分箱用重载。</p>
*
fix(edayun): 修 CR 发现的三个真 bug 与若干语义问题 Critical: 1. EdayunRmaListMapper 静默丢弃调用方的仓库过滤——账户绑了数字仓 id 时, 传入不同的 warehouseCode 会被忽略,结果反而变宽。改为冲突时本地拒绝。 2. EdayunTrackMapper 把 track.receiver(收件人)映射到 signedBy(签收人), 导致每个在途包裹都被判成已签收。易达云响应没有签收人字段,改为不填。 3. 退货详情 / 列表用 warehouseName(美西1仓)当 warehouseCode,宿主拿它 equals / 回传查询会全线失效。改为只用仓编码,缺失直接回退 OMS 仓编码。 Important: 4. EdayunReturnMapper 静默丢弃 returnReason / estimatedReceiveDate / lineName——三个字段易达云都不支持,改为本地拒绝并说明原因。 5. WarehouseDirectoryCapable.carrierDirectory 默认实现把 carriers() 的码 包装成假的两层结构(carrierId == nameEn == FEDEX-G),改成默认抛不支持。 6. EdayunAdapter.printSkuLabel 改包级可见:SKU_LABEL 未声明,门面够不到, 留 public 会让调用方误以为能用。 7. products(warehouseCode) 之前完全忽略入参;改为显式优先,且必须数字。 8. 删掉 EdayunCarrierTest.warehousesAreUnsupported——它断言的是相反行为, 能过只是因为没注册路由。 9. EdayunAdapter 类注释还写着「已实现:商品建档、创建出库单」。 Minor:EdayunAdapterFactory 重复 import、CaseMarkPrintCapable javadoc 写的 BARCODE_PRINT 不存在、TODO.md 表格分隔行丢失、EdayunInventoryTest 合并残留 换行错乱。 新增回归用例:仓库过滤冲突 / 一致、三个不支持字段被拒。 验证:全仓 mvn test 通过;易达云 304 个用例全绿。 Co-Authored-By: Claude <noreply@anthropic.com>
4 days ago
* <p><b>刻意不是 public、也没声明 {@code SKU_LABEL} 能力位</b>:该接口在 PR 环境
* 参数齐全后一律「内部服务器错误」(路径已确认存在,缺参数有中文校验提示),
* 属于仓方服务端异常。放成 public 会让调用方以为门面够得到,实际门面按
* {@code SKU_LABEL} 门控、会直接抛不支持。等仓方修复后再提升可见性并声明能力位。
* 见 docs-warehouse/edayun/TODO.md #68。</p>
*/
fix(edayun): 修 CR 发现的三个真 bug 与若干语义问题 Critical: 1. EdayunRmaListMapper 静默丢弃调用方的仓库过滤——账户绑了数字仓 id 时, 传入不同的 warehouseCode 会被忽略,结果反而变宽。改为冲突时本地拒绝。 2. EdayunTrackMapper 把 track.receiver(收件人)映射到 signedBy(签收人), 导致每个在途包裹都被判成已签收。易达云响应没有签收人字段,改为不填。 3. 退货详情 / 列表用 warehouseName(美西1仓)当 warehouseCode,宿主拿它 equals / 回传查询会全线失效。改为只用仓编码,缺失直接回退 OMS 仓编码。 Important: 4. EdayunReturnMapper 静默丢弃 returnReason / estimatedReceiveDate / lineName——三个字段易达云都不支持,改为本地拒绝并说明原因。 5. WarehouseDirectoryCapable.carrierDirectory 默认实现把 carriers() 的码 包装成假的两层结构(carrierId == nameEn == FEDEX-G),改成默认抛不支持。 6. EdayunAdapter.printSkuLabel 改包级可见:SKU_LABEL 未声明,门面够不到, 留 public 会让调用方误以为能用。 7. products(warehouseCode) 之前完全忽略入参;改为显式优先,且必须数字。 8. 删掉 EdayunCarrierTest.warehousesAreUnsupported——它断言的是相反行为, 能过只是因为没注册路由。 9. EdayunAdapter 类注释还写着「已实现:商品建档、创建出库单」。 Minor:EdayunAdapterFactory 重复 import、CaseMarkPrintCapable javadoc 写的 BARCODE_PRINT 不存在、TODO.md 表格分隔行丢失、EdayunInventoryTest 合并残留 换行错乱。 新增回归用例:仓库过滤冲突 / 一致、三个不支持字段被拒。 验证:全仓 mvn test 通过;易达云 304 个用例全绿。 Co-Authored-By: Claude <noreply@anthropic.com>
4 days ago
WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd) {
EdayunSkuLabelDtos.PrintSkuLabelRequest body = EdayunSkuLabelMapper.toRequest(cmd);
return sendSkuLabel(ctx, body);
}
/**
* 打印 SKU 标(可选箱)。
*
* @param selection 选箱条件;四选一,全空时本地拒绝
*/
fix(edayun): 修 CR 发现的三个真 bug 与若干语义问题 Critical: 1. EdayunRmaListMapper 静默丢弃调用方的仓库过滤——账户绑了数字仓 id 时, 传入不同的 warehouseCode 会被忽略,结果反而变宽。改为冲突时本地拒绝。 2. EdayunTrackMapper 把 track.receiver(收件人)映射到 signedBy(签收人), 导致每个在途包裹都被判成已签收。易达云响应没有签收人字段,改为不填。 3. 退货详情 / 列表用 warehouseName(美西1仓)当 warehouseCode,宿主拿它 equals / 回传查询会全线失效。改为只用仓编码,缺失直接回退 OMS 仓编码。 Important: 4. EdayunReturnMapper 静默丢弃 returnReason / estimatedReceiveDate / lineName——三个字段易达云都不支持,改为本地拒绝并说明原因。 5. WarehouseDirectoryCapable.carrierDirectory 默认实现把 carriers() 的码 包装成假的两层结构(carrierId == nameEn == FEDEX-G),改成默认抛不支持。 6. EdayunAdapter.printSkuLabel 改包级可见:SKU_LABEL 未声明,门面够不到, 留 public 会让调用方误以为能用。 7. products(warehouseCode) 之前完全忽略入参;改为显式优先,且必须数字。 8. 删掉 EdayunCarrierTest.warehousesAreUnsupported——它断言的是相反行为, 能过只是因为没注册路由。 9. EdayunAdapter 类注释还写着「已实现:商品建档、创建出库单」。 Minor:EdayunAdapterFactory 重复 import、CaseMarkPrintCapable javadoc 写的 BARCODE_PRINT 不存在、TODO.md 表格分隔行丢失、EdayunInventoryTest 合并残留 换行错乱。 新增回归用例:仓库过滤冲突 / 一致、三个不支持字段被拒。 验证:全仓 mvn test 通过;易达云 304 个用例全绿。 Co-Authored-By: Claude <noreply@anthropic.com>
4 days ago
WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd,
EdayunSkuLabelMapper.CaseSelection selection) {
EdayunSkuLabelDtos.PrintSkuLabelRequest body =
EdayunSkuLabelMapper.toRequest(cmd, selection);
return sendSkuLabel(ctx, body);
}
private WarehouseLabel sendSkuLabel(WarehouseContext ctx,
EdayunSkuLabelDtos.PrintSkuLabelRequest body) {
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_SKU_LABEL_PRINT, bodyJson,
"warehouse.skuLabel.print");
EdayunSkuLabelDtos.PrintSkuLabelResponse parsed =
json.fromJson(resp.body(), EdayunSkuLabelDtos.PrintSkuLabelResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.skuLabel.print");
if (parsed.data == null || parsed.data.trim().isEmpty()) {
throw WarehouseException.builder()
.message("edayun newPrintCaseMark returned no file url")
.operation("warehouse.skuLabel.print")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.rawResponse(safeRelay(resp.body()))
.retryable(false)
.build();
}
return EdayunSkuLabelMapper.toLabel(parsed.data.trim());
}
// ------------------------------------------------------------------ 承运商
/**
* 客户名下有权限的仓库列表
* ({@code POST /webApi/warehouse/listWarehouseHasPerm})。
*
* <p><b>用这个,不要用 listActive</b>:listActive 是平台全量激活仓(118 条),
* 含当前客户没授权的;这个只返回有权限的(69 条)。</p>
*
* <p>{@code -999}(智能分仓)是哨兵值,映射时已跳过。</p>
*/
@Override
public List<WarehouseFacility> warehouses(WarehouseContext ctx) {
EdayunWarehouseDtos.ListPermittedRequest body =
EdayunWarehouseMapper.toListPermittedRequest();
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_WAREHOUSE_PERMITTED, bodyJson,
"warehouse.directory.warehouses");
EdayunWarehouseDtos.ListWarehouseResponse parsed =
json.fromJson(resp.body(), EdayunWarehouseDtos.ListWarehouseResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.directory.warehouses");
return EdayunWarehouseMapper.toFacilities(parsed == null ? null : parsed.data);
}
/**
* 平台侧全量激活仓({@code POST /webApi/warehouse/listActive})。
*
* <p>与 {@link #warehouses} 的区别:那个只返回<b>有权限</b>的仓;这个是平台
* 全量(实测 118 条 vs 69 条),<b>含当前客户没授权的</b>——不要用它给客户选仓。</p>
*
* <p>实测:{@code warehouseOperationType=0} 尾程仓 111 条、{@code =1} 头程仓 7 条、
* 不传则两者之和 118 条(文档说必填,实际不传也通)。</p>
*/
public List<WarehouseFacility> activeWarehouses(WarehouseContext ctx,
boolean inboundWarehouse) {
EdayunWarehouseDtos.ListActiveRequest body =
EdayunWarehouseMapper.toListActiveRequest(inboundWarehouse);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_WAREHOUSE_ACTIVE, bodyJson,
"warehouse.directory.warehouses.active");
EdayunWarehouseDtos.ListWarehouseResponse parsed =
json.fromJson(resp.body(), EdayunWarehouseDtos.ListWarehouseResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.directory.warehouses.active");
return EdayunWarehouseMapper.toFacilities(parsed == null ? null : parsed.data);
}
/**
* 客户自有物流服务(承运商)清单
* ({@code POST /webApi/carrier/v1/listCarrierByWarehouse})。
*
* <p>返回「承运商 → 物流服务」两层。{@code warehouseId} 只认数字;
* 非数字或为空时不下发,仓方会返回所有服务商。</p>
*
* <p>真机(2026-11-16):仓 2 → 11 个承运商;不传仓 → 22 个;
* 只按国家 US → 10 个。{@code ownLogisticList} 实测是数组(文档写成对象)。</p>
*/
@Override
public List<WarehouseCarrier> carrierDirectory(WarehouseContext ctx) {
EdayunCarrierDtos.ListCarrierRequest body =
EdayunCarrierMapper.toRequest(ctx.providerWarehouseId(), null);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_CARRIERS, bodyJson,
"warehouse.directory.carriers.detail");
EdayunCarrierDtos.ListCarrierResponse parsed =
json.fromJson(resp.body(), EdayunCarrierDtos.ListCarrierResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.directory.carriers.detail");
return EdayunCarrierMapper.toCarriers(parsed == null ? null : parsed.data);
}
// ------------------------------------------------------------------ internals
/** 发业务请求(自动取 token、算签名)。 */
private HttpResponse send(WarehouseContext ctx, String path, String bodyJson, String operation) {
AccessToken accessToken = token(ctx);
ChannelSecret secret = ctx.secret();
long timestamp = ctx.clock().millis();
HttpRequest req = requestFactory.business(
ctx.endpointBaseUrl(), path, "POST",
accessToken.value(), secret.appKey(), secret.appSecret(),
timestamp, bodyJson, operation);
return transport.execute(req);
}
/** HTTP 非 2xx 与业务码非 200 都要显式失败。 */
private void requireSuccess(WarehouseContext ctx, Integer code, String msg,
HttpResponse resp, String operation) {
int status = resp.statusCode();
if (status < 200 || status >= 300) {
throw WarehouseException.builder()
.message("edayun " + operation + " failed: http " + status
+ ", body=" + safeRelay(resp.body()))
.operation(operation)
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.platformCode(String.valueOf(status))
.rawResponse(safeRelay(resp.body()))
.retryable(status >= 500)
.build();
}
if (code == null || code != EdayunConstants.CODE_SUCCESS) {
throw WarehouseException.builder()
.message("edayun " + operation + " business error: code=" + code + ", msg=" + msg)
.operation(operation)
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.platformCode(code == null ? null : String.valueOf(code))
.rawResponse(safeRelay(resp.body()))
.retryable(false)
.build();
}
}
/** 原始响应可能含敏感信息,异常里只留长度与首段。 */
private static String safeRelay(String raw) {
if (raw == null) {
return null;
}
return raw.length() <= 300 ? raw : raw.substring(0, 300) + "...";
}
}