diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundLine.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundLine.java index 98745d2..09c8871 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundLine.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundLine.java @@ -63,6 +63,12 @@ public final class OutboundLine { return declareName; } + /** + * 行申报金额。 + * + *
语义是单价(单件申报价值);需要行总额时由适配器乘以 + * {@link #quantity()} 后再下发,不要在本类里预乘。
+ */ public Money declareValue() { return declareValue; } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseConnection.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseConnection.java index a5355d6..a022d47 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseConnection.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseConnection.java @@ -25,16 +25,29 @@ public final class WarehouseConnection { */ private final String auxEndpointBaseUrl; + /** + * 本次调用用来解释「无时区的本地时间」的时区。 + * + *由 OMS 显式传入:仓方给的 {@code yyyy-MM-dd HH:mm:ss} 不带时区, + * 需要知道它属于哪个地方。SDK 不做地理推断、也不依赖账户配置—— + * 账户时区不一定有,且同一 provider 下多仓可能分布在不同时区。
+ * + *null 表示调用方没指定;此时按 UTC 解释(不猜成北京时间)。
+ */ + private final java.time.ZoneId zone; + /** 凭据。 */ private final ChannelSecret secret; - private WarehouseConnection(String endpointBaseUrl, String auxEndpointBaseUrl, ChannelSecret secret) { + private WarehouseConnection(String endpointBaseUrl, String auxEndpointBaseUrl, + ChannelSecret secret, java.time.ZoneId zone) { if (endpointBaseUrl == null || endpointBaseUrl.trim().isEmpty()) { throw new IllegalArgumentException("endpointBaseUrl must not be blank"); } this.endpointBaseUrl = trimTrailingSlash(endpointBaseUrl.trim()); this.auxEndpointBaseUrl = auxEndpointBaseUrl == null || auxEndpointBaseUrl.trim().isEmpty() ? null : trimTrailingSlash(auxEndpointBaseUrl.trim()); + this.zone = zone; Objects.requireNonNull(secret, "secret"); // 端点写回凭据:需要换 token 的仓,TokenManager 的 refresh 回调只拿得到 ChannelSecret this.secret = ChannelSecret.builder() @@ -49,7 +62,17 @@ public final class WarehouseConnection { /** 构造连接:基址去空白、去末尾斜杠,并把基址写回凭据副本。 */ public static WarehouseConnection of(String endpointBaseUrl, ChannelSecret secret) { - return new WarehouseConnection(endpointBaseUrl, null, secret); + return new WarehouseConnection(endpointBaseUrl, null, secret, null); + } + + /** + * 带时区的连接。 + * + * @param zone 解释仓方「无时区本地时间」用的时区;null 按 UTC + */ + public static WarehouseConnection of(String endpointBaseUrl, ChannelSecret secret, + java.time.ZoneId zone) { + return new WarehouseConnection(endpointBaseUrl, null, secret, zone); } /** @@ -60,12 +83,28 @@ public final class WarehouseConnection { */ public static WarehouseConnection of(String endpointBaseUrl, String auxEndpointBaseUrl, ChannelSecret secret) { - return new WarehouseConnection(endpointBaseUrl, auxEndpointBaseUrl, secret); + return new WarehouseConnection(endpointBaseUrl, auxEndpointBaseUrl, secret, null); + } + + /** 带辅助基址与时区的连接。 */ + public static WarehouseConnection of(String endpointBaseUrl, String auxEndpointBaseUrl, + ChannelSecret secret, java.time.ZoneId zone) { + return new WarehouseConnection(endpointBaseUrl, auxEndpointBaseUrl, secret, zone); } /** 复制一份连接,附加辅助基址。 */ public WarehouseConnection withAuxEndpoint(String auxEndpointBaseUrl) { - return new WarehouseConnection(endpointBaseUrl, auxEndpointBaseUrl, secret); + return new WarehouseConnection(endpointBaseUrl, auxEndpointBaseUrl, secret, zone); + } + + /** 复制一份连接,替换时区。 */ + public WarehouseConnection withZone(java.time.ZoneId zone) { + return new WarehouseConnection(endpointBaseUrl, auxEndpointBaseUrl, secret, zone); + } + + /** 时区;未指定时为 null(按 UTC 解释)。 */ + public java.time.ZoneId zone() { + return zone; } /** 目标基址,末尾斜杠已去掉。 */ diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseContext.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseContext.java index ea1abbd..c598a41 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseContext.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseContext.java @@ -87,6 +87,17 @@ public final class WarehouseContext implements CallScope { return connection.auxEndpointBaseUrl(); } + /** + * 解释仓方无时区本地时间的时区。 + * + *由 OMS 经 {@link WarehouseConnection} 传入;未指定时为 {@code UTC} + * (不猜成北京时间)。
+ */ + public java.time.ZoneId zone() { + java.time.ZoneId zone = connection.zone(); + return zone == null ? java.time.ZoneOffset.UTC : zone; + } + /** 本次调用的凭据,SDK 不落盘。 */ public common.ecommerce.shared.spi.ChannelSecret secret() { return connection.secret(); diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java index a9a9e30..e2dac0f 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java @@ -174,7 +174,7 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl public OutboundReceipt create(WarehouseContext ctx, OutboundCommand cmd) { requirePlatformLabelSupported(ctx, cmd.labelMode()); requireLabelContentForPlatformLabel(cmd); - YqnCreateOrderDtos.CreateOrderRequest body = YqnOutboundMapper.toRequest(cmd, warehouseId(ctx, cmd.warehouseId())); + YqnCreateOrderDtos.CreateOrderRequest body = YqnOutboundMapper.toRequest(cmd, warehouseId(ctx, cmd.warehouseId()), zoneOf(ctx)); String raw = execute(ctx, YqnConstants.PATH_ORDER_CREATE, body, "warehouse.outbound.create"); // API 123 只回 data.orderId(仓内部数字 id),不回字符串单号 @@ -844,9 +844,14 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl return ctx.providerWarehouseId(); } + /** + * 解释仓方「无时区本地时间」的时区。 + * + *由 OMS 经 {@code WarehouseConnection} 传入;没传就按 UTC,不猜成北京时间—— + * 运去哪仓在美国,猜错会让所有时间整体平移 13–16 小时。
+ */ private static ZoneId zoneOf(WarehouseContext ctx) { - // 账户时区由 WarehouseAccount 提供;上下文没带时回退北京 - return ZoneId.of("Asia/Shanghai"); + return ctx.zone(); } /** 发请求并校验信封。 */ diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeMapper.java index 1adf568..a9902ab 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeMapper.java @@ -10,6 +10,7 @@ import common.ecommerce.warehouse.sdk.WarehouseContext; import java.time.Instant; import java.time.LocalDate; import java.time.ZoneId; +import java.time.ZoneOffset; import java.time.format.DateTimeFormatter; import java.time.format.DateTimeParseException; import java.util.ArrayList; @@ -28,7 +29,7 @@ public final class YqnFeeMapper { private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd"); private static final DateTimeFormatter TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); - private static final ZoneId DEFAULT_ZONE = ZoneId.of("Asia/Shanghai"); + private static final ZoneId DEFAULT_ZONE = ZoneOffset.UTC; private YqnFeeMapper() { } diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java index 085cf9d..5b00039 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java @@ -14,6 +14,7 @@ import common.ecommerce.yqn.enums.YqnInboundStatus; import java.time.Instant; import java.time.LocalDate; import java.time.ZoneId; +import java.time.ZoneOffset; import java.time.format.DateTimeFormatter; import java.time.format.DateTimeParseException; import java.util.ArrayList; @@ -325,5 +326,5 @@ public final class YqnInboundMapper { return b; } - private static final ZoneId DEFAULT_ZONE = ZoneId.of("Asia/Shanghai"); + private static final ZoneId DEFAULT_ZONE = ZoneOffset.UTC; } \ No newline at end of file diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInventoryMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInventoryMapper.java index cf2880d..9d12538 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInventoryMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInventoryMapper.java @@ -7,6 +7,7 @@ import common.ecommerce.warehouse.model.InventorySnapshot; import java.time.Instant; import java.time.ZoneId; +import java.time.ZoneOffset; import java.time.format.DateTimeFormatter; import java.time.format.DateTimeParseException; import java.util.ArrayList; @@ -23,7 +24,7 @@ public final class YqnInventoryMapper { static final int MAX_ROWS = 500; private static final DateTimeFormatter TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); - private static final ZoneId DEFAULT_ZONE = ZoneId.of("Asia/Shanghai"); + private static final ZoneId DEFAULT_ZONE = ZoneOffset.UTC; private YqnInventoryMapper() { } diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java index b2d4e21..6a90c59 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java @@ -17,6 +17,7 @@ import common.ecommerce.warehouse.enums.WarehouseProvider; import java.time.Instant; import java.time.ZoneId; +import java.time.ZoneOffset; import java.time.format.DateTimeFormatter; import java.time.format.DateTimeParseException; import java.util.ArrayList; @@ -37,7 +38,13 @@ public final class YqnOutboundMapper { private static final DateTimeFormatter TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); /** 运去哪时间按仓所在地解释;账户未配时回退北京时区。 */ - private static final ZoneId DEFAULT_ZONE = ZoneId.of("Asia/Shanghai"); + /** + * 兜底时区。 + * + *只在调用方没传 zone 时使用;按 UTC 解释,不猜成北京时间。 + * 正常路径应当由 OMS 经 {@code WarehouseConnection.zone()} 显式指定。
+ */ + private static final ZoneId DEFAULT_ZONE = ZoneOffset.UTC; /** 附件类型:0 面单 / 1 装箱单 / 2 BOL / 3 其他 / 4 箱标 / 5 托盘标 / 6 商品标 / 7 发票 / 8 发货计划。 */ private static final int ATTACH_TYPE_SHIPPING_LABEL = 0; @@ -50,6 +57,14 @@ public final class YqnOutboundMapper { /** 统一命令 → 运去哪创建销售订单请求(API 123)。 */ public static YqnCreateOrderDtos.CreateOrderRequest toRequest(OutboundCommand cmd, String warehouseCode) { + return toRequest(cmd, warehouseCode, null); + } + + /** + * @param zone 下发时间时使用的时区(仓所在地);null 按 UTC + */ + public static YqnCreateOrderDtos.CreateOrderRequest toRequest(OutboundCommand cmd, String warehouseCode, + ZoneId zone) { YqnCreateOrderDtos.CreateOrderRequest req = new YqnCreateOrderDtos.CreateOrderRequest(); req.orderNo = cmd.outboundRequestNo(); req.poNumber = cmd.orderRef(); @@ -58,8 +73,8 @@ public final class YqnOutboundMapper { req.carrierCode = cmd.carrierCode(); req.currency = cmd.currency() == null ? DEFAULT_CURRENCY : cmd.currency(); req.shipServiceLevel = cmd.shipServiceLevel(); - req.latestShipDate = formatTime(cmd.latestShipDate()); - req.estimatedDeliveryTime = formatTime(cmd.estimatedDeliveryTime()); + req.latestShipDate = formatTime(cmd.latestShipDate(), zone); + req.estimatedDeliveryTime = formatTime(cmd.estimatedDeliveryTime(), zone); req.salesPlatform = salesPlatformOf(cmd.salesPlatform()); req.remark = cmd.remark(); // 店铺:仓方按店铺做路由/计费;标准模型对应 shopName @@ -130,7 +145,11 @@ public final class YqnOutboundMapper { item.lineNo = line.lineNo(); Money value = line.declareValue(); if (value != null) { - item.skuAmount = value.amount().doubleValue(); + // 运去哪的 skuAmount 是「当前 SKU 总金额」,不是单价: + // 必须乘以行数量,否则整单申报额少算 quantity 倍 + item.skuAmount = value.amount() + .multiply(java.math.BigDecimal.valueOf(line.quantity())) + .doubleValue(); } items.add(item); } @@ -243,9 +262,17 @@ public final class YqnOutboundMapper { return slash < 0 || slash == mime.length() - 1 ? null : mime.substring(slash + 1); } - /** 运去哪时间格式 {@code yyyy-MM-dd HH:mm:ss}。 */ + /** 运去哪时间格式 {@code yyyy-MM-dd HH:mm:ss};按 UTC 输出。 */ static String formatTime(Instant instant) { - return instant == null ? null : TIME_FORMAT.format(instant.atZone(DEFAULT_ZONE)); + return formatTime(instant, null); + } + + /** 按指定时区格式化下发时间;{@code zone} 为 null 时按 UTC。 */ + static String formatTime(Instant instant, ZoneId zone) { + if (instant == null) { + return null; + } + return TIME_FORMAT.format(instant.atZone(zone == null ? DEFAULT_ZONE : zone)); } /** 订单详情 → 统一出库单(API 128)。 */ diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java index 1c97b9a..f3a03d7 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java @@ -13,6 +13,7 @@ import common.ecommerce.yqn.enums.YqnTransferType; import java.time.Instant; import java.time.LocalDate; import java.time.ZoneId; +import java.time.ZoneOffset; import java.time.format.DateTimeFormatter; import java.time.format.DateTimeParseException; import java.util.ArrayList; @@ -24,7 +25,7 @@ import java.util.List; public final class YqnTransferMapper { private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd"); - private static final ZoneId DEFAULT_ZONE = ZoneId.of("Asia/Shanghai"); + private static final ZoneId DEFAULT_ZONE = ZoneOffset.UTC; private YqnTransferMapper() { } diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnAdapterTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnAdapterTest.java index 40850c5..03ee948 100644 --- a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnAdapterTest.java +++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnAdapterTest.java @@ -136,8 +136,9 @@ class YqnAdapterTest { assertEquals("TRK1", order.trackingNumber()); assertEquals("FEDEX", order.carrier()); assertEquals("WLC-FEDEX", order.carrierCode()); - assertEquals(Instant.parse("2026-11-08T01:00:00Z"), order.paidAt()); - assertEquals(Instant.parse("2026-11-08T04:00:00Z"), order.shippedAt()); + // 未指定时区时按 UTC 解释(不再是北京时间) + assertEquals(Instant.parse("2026-11-08T09:00:00Z"), order.paidAt()); + assertEquals(Instant.parse("2026-11-08T12:00:00Z"), order.shippedAt()); assertEquals(1, order.lines().size()); assertEquals(2, order.lines().get(0).quantity()); assertEquals("US", order.shipTo().countryCode()); @@ -226,6 +227,29 @@ class YqnAdapterTest { assertNull(YqnOutboundMapper.parseTime("", null)); } + /** 指定时区后,仓方本地时间按该时区解释(美国仓不能再按北京时间算)。 */ + @Test + void usesConnectionZoneWhenProvided() { + RecordingTransport transport = RecordingTransport.create() + .route(YqnConstants.PATH_ORDER_FIND_ONE, req -> Responses.ok( + "{\"code\":200,\"message\":\"ok\",\"data\":{\"orderNo\":\"OB-Z\"," + + "\"paidAt\":\"2026-11-08 09:00:00\"," + + "\"orderStatusEnum\":\"unshipped\",\"currency\":\"USD\"," + + "\"productItems\":[{\"sku\":\"DM1\",\"quantity\":1}]}}")); + YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); + WarehouseContext nyCtx = WarehouseContext.of("YQN-RF_NY_US", WarehouseProvider.YQN, "RF_NY_US", + WarehouseConnection.of(YqnConstants.PR_BASE_URL, + ChannelSecret.builder().appSecret("key-1").build(), + java.time.ZoneId.of("America/New_York")), + "req-zone", CLOCK); + + common.ecommerce.warehouse.model.OutboundOrder order = + adapter.get(nyCtx, OutboundRef.ofRequestNo("OB-Z")); + + // 纽约 09:00(EST, UTC-5)→ 14:00Z + assertEquals(Instant.parse("2026-11-08T14:00:00Z"), order.paidAt()); + } + /** * 回归:UNSHIPPED(未发货)曾被 contains("SHIP") 命中判成已交运, * 导致未发货单被当成已发出、取消被锁。现在必须精确匹配。