From d0649fed38bfcda7acb68fe6c63dbc610b9d3fbf Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Mon, 9 Nov 2026 16:27:02 +0800 Subject: [PATCH] =?UTF-8?q?feat(yqn):=20=E6=8C=89=20API=20133=20=E5=AF=B9?= =?UTF-8?q?=E6=8E=A5=E7=BB=93=E7=AE=97=E6=98=8E=E7=BB=86=EF=BC=8C=E8=B4=B9?= =?UTF-8?q?=E7=94=A8=E6=9F=A5=E8=AF=A2=E6=94=B9=E7=94=A8=20FeeQuery?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit API 133 是「一个接口按条件查四种费用」,不是 Spec §6.2 设想的 settlements/orderCosts/rentDetails/accountFlows 四个方法: - 路径 /fee/SettlementDetails → /v1/warehouse/operation/costs/detail - 入参:saleOrderNo / billingTransNo / costType / sku / externalOrderNo / snapshotStartDate / snapshotEndDate,全部可选 所以 WarehouseFeeCapable 收敛为单个 settlements(ctx, FeeQuery),删掉 orderCosts / rentDetails / accountFlows / estimate:文档里没有对应接口, 留着就是四个永远抛 Unsupported 的空壳。 新增 FeeQuery / WarehouseFeeType,映射层做三条文档约束: - 空条件直接拒绝,避免无条件下拉全量 - 按日期查只支持仓储费,且区间不超过 30 天 - saleOrderNo 在运去哪是数字,非数字直接拒绝(传错类型仓侧静默查不到) BillingDocument 按响应重写:补 feeName / feeType / settledAt / estimated / saleOrderNo;estimated 由 settlementType 决定(1 实际 / 2 预估), 对账时必须把预估和实际分开,否则会把预估值当已发生成本。 Co-Authored-By: Claude --- .../warehouse/capability/WarehouseFeeCapable.java | 47 ++---- .../ecommerce/warehouse/model/BillingDocument.java | 90 +++++++---- .../common/ecommerce/warehouse/model/FeeQuery.java | 133 +++++++++++++++ .../warehouse/model/WarehouseFeeType.java | 19 +++ .../warehouse/sdk/WarehouseOperations.java | 16 +- .../java/common/ecommerce/yqn/YqnConstants.java | 6 +- .../common/ecommerce/yqn/adapter/YqnAdapter.java | 30 +++- .../common/ecommerce/yqn/adapter/YqnFeeMapper.java | 178 +++++++++++++++++++++ .../java/common/ecommerce/yqn/dto/YqnDtos.java | 33 ++++ 9 files changed, 477 insertions(+), 75 deletions(-) create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFeeType.java create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeMapper.java diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseFeeCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseFeeCapable.java index e1fcf12..c5b2a83 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseFeeCapable.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseFeeCapable.java @@ -1,44 +1,31 @@ package common.ecommerce.warehouse.capability; import common.ecommerce.warehouse.model.BillingDocument; +import common.ecommerce.warehouse.model.FeeQuery; import common.ecommerce.warehouse.sdk.WarehouseAdapter; import common.ecommerce.warehouse.sdk.WarehouseContext; -import java.time.Instant; -import java.util.Collections; import java.util.List; /** - * 费用能力:账单 / 订单费用 / 仓租 / 账户流水 / 试算。 + * 费用能力:按条件拉取结算明细。 * - *

信仓只有订单维度总费用,其余方法应抛 - * {@code WarehouseUnsupportedCapabilityException},能力位如实反映。

+ *

各仓的收费维度不一样(有的只能按订单查、有的能按结算单、有的能按日期), + * 统一成一个 {@link FeeQuery},由适配器把不支持的维度显式拒绝—— + * 静默忽略过滤条件会让对账金额对不上。

+ * + *

预估费用与最终账单用 {@link BillingDocument#estimated()} 区分, + * 仓一般在发货后先给预估、收货约一周后才出实际结算。

*/ public interface WarehouseFeeCapable extends WarehouseAdapter { - /** 费用单据(尾程 / 仓储 / 操作费)。 */ - List settlements(WarehouseContext ctx, Instant periodStart, Instant periodEnd); - - /** 订单维度费用。 */ - default List orderCosts(WarehouseContext ctx, String orderRef) { - return Collections.emptyList(); - } - - /** 仓租明细。 */ - default List rentDetails(WarehouseContext ctx, Instant periodStart, Instant periodEnd) { - throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( - common.ecommerce.warehouse.WarehouseCapability.FEE_SETTLEMENT); - } - - /** 账户流水。 */ - default List accountFlows(WarehouseContext ctx, Instant periodStart, Instant periodEnd) { - throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( - common.ecommerce.warehouse.WarehouseCapability.FEE_SETTLEMENT); - } - - /** 费用试算;信仓 11 月上线前不可用。 */ - default BillingDocument estimate(WarehouseContext ctx, String quoteRequest) { - throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( - common.ecommerce.warehouse.WarehouseCapability.FEE_ESTIMATE); - } + /** + * 拉取费用明细。 + * + * @param query 查询条件;{@link FeeQuery#isEmpty()} 为 true 时适配器必须拒绝, + * 避免无条件下拉全量 + * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException + * 仓不支持该查询维度 + */ + List settlements(WarehouseContext ctx, FeeQuery query); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java index 4c11384..4350c98 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java @@ -4,28 +4,40 @@ import common.ecommerce.shared.support.Money; import java.time.Instant; -/** 费用单据(尾程 / 仓储 / 操作费)。 */ +/** + * 费用单据(尾程 / 仓储 / 操作费)。 + * + *

{@link #estimated()} 区分预估与最终账单:仓一般发货后先给预估, + * 一周后才出实际结算。对账时必须按这个标记分开,否则会把预估值当成已发生成本。

+ */ public final class BillingDocument { private final String warehouseCode; private final String documentNo; - /** ORDER_FEE / RENT / ACCOUNT_FLOW。 */ - private final String type; - private final Instant periodStart; - private final Instant periodEnd; + /** 仓方费用名称原值,如「尾程运费」「仓储费」。 */ + private final String feeName; + /** 业务语义类型;无法归类时为 null。 */ + private final WarehouseFeeType feeType; + /** 结算时间(UTC);仓方给的结算/计费时间点。 */ + private final Instant settledAt; + /** 是否预估费用;true 预估值,false 实际结算。 */ + private final boolean estimated; + /** 金额币种;仓方未标时按 USD。 */ private final Money amount; private final String providerSku; - private final String orderRef; + /** 关联的销售订单号(仓侧)。 */ + private final String saleOrderNo; private BillingDocument(Builder b) { this.warehouseCode = require(b.warehouseCode, "warehouseCode"); - this.documentNo = require(b.documentNo, "documentNo"); - this.type = b.type; - this.periodStart = b.periodStart; - this.periodEnd = b.periodEnd; + this.documentNo = b.documentNo; + this.feeName = b.feeName; + this.feeType = b.feeType; + this.settledAt = b.settledAt; + this.estimated = b.estimated; this.amount = java.util.Objects.requireNonNull(b.amount, "amount"); this.providerSku = b.providerSku; - this.orderRef = b.orderRef; + this.saleOrderNo = b.saleOrderNo; } public static Builder builder() { @@ -40,16 +52,24 @@ public final class BillingDocument { return documentNo; } - public String type() { - return type; + /** 仓方费用名称原值,如「尾程运费」「仓储费」。 */ + public String feeName() { + return feeName; } - public Instant periodStart() { - return periodStart; + /** 业务语义类型;无法归类时为 null。 */ + public WarehouseFeeType feeType() { + return feeType; } - public Instant periodEnd() { - return periodEnd; + /** 结算时间(UTC)。 */ + public Instant settledAt() { + return settledAt; + } + + /** 是否预估费用。对账时必须与最终账单分开统计。 */ + public boolean estimated() { + return estimated; } public Money amount() { @@ -61,8 +81,9 @@ public final class BillingDocument { return providerSku; } - public String orderRef() { - return orderRef; + /** 关联的销售订单号(仓侧)。 */ + public String saleOrderNo() { + return saleOrderNo; } private static String require(String v, String n) { @@ -75,12 +96,13 @@ public final class BillingDocument { public static final class Builder { private String warehouseCode; private String documentNo; - private String type; - private Instant periodStart; - private Instant periodEnd; + private String feeName; + private WarehouseFeeType feeType; + private Instant settledAt; + private boolean estimated; private Money amount; private String providerSku; - private String orderRef; + private String saleOrderNo; public Builder warehouseCode(String v) { this.warehouseCode = v; @@ -92,18 +114,24 @@ public final class BillingDocument { return this; } - public Builder type(String v) { - this.type = v; + public Builder feeName(String v) { + this.feeName = v; + return this; + } + + public Builder feeType(WarehouseFeeType v) { + this.feeType = v; return this; } - public Builder periodStart(Instant v) { - this.periodStart = v; + public Builder settledAt(Instant v) { + this.settledAt = v; return this; } - public Builder periodEnd(Instant v) { - this.periodEnd = v; + /** true 预估 / false 实际结算。 */ + public Builder estimated(boolean v) { + this.estimated = v; return this; } @@ -117,8 +145,8 @@ public final class BillingDocument { return this; } - public Builder orderRef(String v) { - this.orderRef = v; + public Builder saleOrderNo(String v) { + this.saleOrderNo = v; return this; } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java new file mode 100644 index 0000000..e8fdf23 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java @@ -0,0 +1,133 @@ +package common.ecommerce.warehouse.model; + +import java.time.LocalDate; + +/** + * 费用查询条件。 + * + *

各仓支持的查询维度不同:运去哪要求「销售订单号」或「结算单号」二选一, + * 按日期区间只能查仓储费且区间不超过 30 天。不支持的维度由适配器显式拒绝, + * 不静默忽略——忽略一个过滤条件会让对账金额对不上。

+ */ +public final class FeeQuery { + + private final String saleOrderNo; + private final String billingTransNo; + private final WarehouseFeeType costType; + private final String providerSku; + private final String externalOrderNo; + private final LocalDate snapshotStartDate; + private final LocalDate snapshotEndDate; + + private FeeQuery(Builder b) { + if (b.snapshotStartDate != null && b.snapshotEndDate != null + && b.snapshotStartDate.isAfter(b.snapshotEndDate)) { + throw new IllegalArgumentException("snapshotStartDate must not be after snapshotEndDate"); + } + if ((b.snapshotStartDate == null) != (b.snapshotEndDate == null)) { + throw new IllegalArgumentException( + "snapshotStartDate and snapshotEndDate must be set together"); + } + this.saleOrderNo = b.saleOrderNo; + this.billingTransNo = b.billingTransNo; + this.costType = b.costType; + this.providerSku = b.providerSku; + this.externalOrderNo = b.externalOrderNo; + this.snapshotStartDate = b.snapshotStartDate; + this.snapshotEndDate = b.snapshotEndDate; + } + + public static Builder builder() { + return new Builder(); + } + + /** 销售订单号(运去哪的 {@code orderNo})。 */ + public String saleOrderNo() { + return saleOrderNo; + } + + /** 结算单号;仓储费 / 增值服务费按它查。 */ + public String billingTransNo() { + return billingTransNo; + } + + /** 费用类型;null 表示不限制。 */ + public WarehouseFeeType costType() { + return costType; + } + + public String providerSku() { + return providerSku; + } + + public String externalOrderNo() { + return externalOrderNo; + } + + /** 快照开始日期;仅仓储费支持按日期查。 */ + public LocalDate snapshotStartDate() { + return snapshotStartDate; + } + + /** 快照结束日期。 */ + public LocalDate snapshotEndDate() { + return snapshotEndDate; + } + + /** 是否按日期区间查。 */ + public boolean hasDateRange() { + return snapshotStartDate != null; + } + + /** 是否给了任何查询条件;全空时适配器应拒绝,避免拉全量。 */ + public boolean isEmpty() { + return saleOrderNo == null && billingTransNo == null && costType == null + && providerSku == null && externalOrderNo == null && !hasDateRange(); + } + + public static final class Builder { + + private String saleOrderNo; + private String billingTransNo; + private WarehouseFeeType costType; + private String providerSku; + private String externalOrderNo; + private LocalDate snapshotStartDate; + private LocalDate snapshotEndDate; + + public Builder saleOrderNo(String v) { + this.saleOrderNo = v; + return this; + } + + public Builder billingTransNo(String v) { + this.billingTransNo = v; + return this; + } + + public Builder costType(WarehouseFeeType v) { + this.costType = v; + return this; + } + + public Builder providerSku(String v) { + this.providerSku = v; + return this; + } + + public Builder externalOrderNo(String v) { + this.externalOrderNo = v; + return this; + } + + public Builder snapshotDateRange(LocalDate start, LocalDate end) { + this.snapshotStartDate = start; + this.snapshotEndDate = end; + return this; + } + + public FeeQuery build() { + return new FeeQuery(this); + } + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFeeType.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFeeType.java new file mode 100644 index 0000000..439ba50 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFeeType.java @@ -0,0 +1,19 @@ +package common.ecommerce.warehouse.model; + +/** + * 仓费用类型。 + * + *

各仓的枚举值不同,由适配器维护映射;这里只保留业务语义。 + * 运去哪 API 133 的 {@code costType} 是 1 作业费 / 2 仓储费 / 3 增值服务费 / 4 尾程费用。

+ */ +public enum WarehouseFeeType { + + /** 作业费(出入库操作费)。 */ + OPERATION, + /** 仓储费 / 仓租。 */ + STORAGE, + /** 增值服务费。 */ + VALUE_ADDED, + /** 尾程运费。 */ + LAST_MILE +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java index 0b87275..3f1c9b7 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java @@ -17,6 +17,7 @@ import common.ecommerce.warehouse.capability.WarehouseReturnCapable; import common.ecommerce.warehouse.capability.WarehouseWebhookCapable; import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException; import common.ecommerce.warehouse.model.BillingDocument; +import common.ecommerce.warehouse.model.FeeQuery; import common.ecommerce.warehouse.model.DestructionOrder; import common.ecommerce.warehouse.model.InboundCommand; import common.ecommerce.warehouse.model.InboundOrder; @@ -227,17 +228,16 @@ public final class WarehouseOperations { /** 费用视图。 */ public final class FeeView { - public List settlements(Instant periodStart, Instant periodEnd) { + /** 按条件拉取费用明细(预估与实际用 BillingDocument.estimated() 区分)。 */ + public List settlements(FeeQuery query) { require(WarehouseCapability.FEE_SETTLEMENT, WarehouseFeeCapable.class); return CallSupport.observe(observer, ctx, "warehouse.fee.settlements", - CallSupport.params("periodStart", periodStart, "periodEnd", periodEnd), + CallSupport.params("saleOrderNo", query.saleOrderNo(), + "billingTransNo", query.billingTransNo(), + "costType", query.costType(), + "hasDateRange", query.hasDateRange()), List::size, - () -> ((WarehouseFeeCapable) adapter).settlements(ctx, periodStart, periodEnd)); - } - - public List orderCosts(String orderRef) { - require(WarehouseCapability.FEE_SETTLEMENT, WarehouseFeeCapable.class); - return ((WarehouseFeeCapable) adapter).orderCosts(ctx, orderRef); + () -> ((WarehouseFeeCapable) adapter).settlements(ctx, query)); } } } diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java index 55f5525..4e9cac8 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java @@ -48,10 +48,8 @@ public final class YqnConstants { public static final String PATH_DESTRUCTION_CREATE = "/destroyplan/DestructionPlanCreate"; /** 物流轨迹。 */ public static final String PATH_TRACKING = "/cloudship/expressdelivery/GetTrackingStatus"; - /** 费用账单。 */ - public static final String PATH_FEE_SETTLEMENT = "/fee/SettlementDetails"; - /** 费用试算。 */ - public static final String PATH_FEE_ESTIMATE = "/fee/SalesOrderCalculation"; + /** 结算明细(API 133):作业费 / 仓储费 / 增值服务费 / 尾程费。 */ + public static final String PATH_FEE_DETAIL = "/v1/warehouse/operation/costs/detail"; /** Spec §7.5:三家仓均未公开限流值,保守默认 2 req/s/仓。 */ public static final int PERMITS_PER_SECOND = 2; 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 5364680..724da2e 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 @@ -9,7 +9,10 @@ import common.ecommerce.shared.support.Page; import common.ecommerce.warehouse.WarehouseCapability; import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.capability.OutboundCapable; +import common.ecommerce.warehouse.model.BillingDocument; +import common.ecommerce.warehouse.model.FeeQuery; import common.ecommerce.warehouse.capability.WarehouseProduct; +import common.ecommerce.warehouse.capability.WarehouseFeeCapable; import common.ecommerce.warehouse.capability.WarehouseProductCapable; import common.ecommerce.warehouse.error.OutboundCancelBlockedException; import common.ecommerce.warehouse.error.WarehouseException; @@ -46,7 +49,8 @@ import java.util.Map; *

字段级契约待打样核对(Spec §8.6):本类只做「拼请求 + 解析响应」, * 字段差异收敛在 {@link YqnDtos} 与 {@link YqnOutboundMapper}。

*/ -public final class YqnAdapter implements OutboundCapable, WarehouseProductCapable { +public final class YqnAdapter implements OutboundCapable, WarehouseProductCapable, + WarehouseFeeCapable { /** 运去哪请求里的时间格式;待核对。 */ private static final DateTimeFormatter REQUEST_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); @@ -78,7 +82,8 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl return java.util.EnumSet.of( WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND, - WarehouseCapability.SPLIT); + WarehouseCapability.SPLIT, + WarehouseCapability.FEE_SETTLEMENT); } // ------------------------------------------------------------------ 商品 @@ -256,6 +261,27 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl : YqnOutboundMapper.toPackages(detail); } + // ------------------------------------------------------------------ 费用 + + /** + * 结算明细(API 133)。 + * + *

预估与实际由 {@code settlementType} 区分(1 实际 / 2 预估), + * 映射到 {@link BillingDocument#estimated()}。仓一般发货后可查预估, + * 收货约一周后才出实际账单。

+ */ + @Override + public List settlements(WarehouseContext ctx, FeeQuery query) { + YqnDtos.CostDetailRequest body = YqnFeeMapper.toRequest(query); + String raw = execute(ctx, YqnConstants.PATH_FEE_DETAIL, body, "warehouse.fee.settlements"); + List rows = json.listAt(raw, "data", YqnDtos.CostDetail.class); + List out = new ArrayList(rows.size()); + for (YqnDtos.CostDetail row : rows) { + out.add(YqnFeeMapper.toDocument(row, ctx.warehouseCode(), zoneOf(ctx))); + } + return out; + } + // ------------------------------------------------------------------ internals /** 面单模式必须与仓能力匹配;不支持时拒绝,不静默降级。 */ 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 new file mode 100644 index 0000000..9565d0d --- /dev/null +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeMapper.java @@ -0,0 +1,178 @@ +package common.ecommerce.yqn.adapter; + +import common.ecommerce.shared.support.Money; +import common.ecommerce.warehouse.model.BillingDocument; +import common.ecommerce.warehouse.model.FeeQuery; +import common.ecommerce.warehouse.model.WarehouseFeeType; +import common.ecommerce.warehouse.sdk.WarehouseContext; +import common.ecommerce.yqn.dto.YqnDtos; + +import java.time.Instant; +import java.time.LocalDate; +import java.time.ZoneId; +import java.time.format.DateTimeFormatter; +import java.time.format.DateTimeParseException; +import java.util.ArrayList; +import java.util.List; + +/** + * 运去哪费用报文映射(API 133)。 + */ +public final class YqnFeeMapper { + + /** 运去哪所有金额都是 USD。 */ + private static final String CURRENCY = "USD"; + + /** 仓储费按日期查的上限。 */ + static final int MAX_SNAPSHOT_DAYS = 30; + + 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 YqnFeeMapper() { + } + + /** + * 统一查询条件 → 运去哪请求。 + * + *

运去哪的约束:

+ *
    + *
  • 作业费 / 尾程费按 {@code saleOrderNo} 查,仓储费 / 增值服务费按 {@code billingTransNo} 查; + * 按日期查只支持仓储费,且区间不超过 30 天
  • + *
  • {@code saleOrderNo} 在运去哪是数字,非数字直接拒绝——传错类型仓侧会静默查不到
  • + *
+ */ + public static YqnDtos.CostDetailRequest toRequest(FeeQuery query) { + if (query.isEmpty()) { + throw new IllegalArgumentException( + "yqn fee query requires at least one condition; refusing to pull all costs"); + } + YqnDtos.CostDetailRequest req = new YqnDtos.CostDetailRequest(); + req.saleOrderNo = saleOrderNoOf(query.saleOrderNo()); + req.billingTransNo = query.billingTransNo(); + req.costType = costTypeOf(query.costType()); + req.sku = query.providerSku(); + req.externalOrderNo = query.externalOrderNo(); + + if (query.hasDateRange()) { + requireStorageOnly(query); + req.snapshotStartDate = DATE.format(query.snapshotStartDate()); + req.snapshotEndDate = DATE.format(query.snapshotEndDate()); + } + return req; + } + + /** 运去哪的要求:按时间查只能查仓储费。 */ + private static void requireStorageOnly(FeeQuery query) { + if (query.costType() != WarehouseFeeType.STORAGE) { + throw new IllegalArgumentException( + "yqn supports snapshot date range only for STORAGE cost; " + + "operation / last-mile costs must be queried by saleOrderNo, " + + "value-added by billingTransNo"); + } + long days = java.time.temporal.ChronoUnit.DAYS.between( + query.snapshotStartDate(), query.snapshotEndDate()); + if (days < 0 || days > MAX_SNAPSHOT_DAYS) { + throw new IllegalArgumentException( + "yqn snapshot date range must be within " + MAX_SNAPSHOT_DAYS + " days, got " + days); + } + } + + private static Long saleOrderNoOf(String raw) { + if (raw == null || raw.trim().isEmpty()) { + return null; + } + try { + return Long.valueOf(raw.trim()); + } catch (NumberFormatException e) { + throw new IllegalArgumentException( + "yqn saleOrderNo must be numeric, got: " + raw + + " (use the warehouse order id, not your own order number)"); + } + } + + /** 业务类型 → 运去哪 costType;null 不限制。 */ + static Integer costTypeOf(WarehouseFeeType type) { + if (type == null) { + return null; + } + switch (type) { + case OPERATION: + return 1; + case STORAGE: + return 2; + case VALUE_ADDED: + return 3; + case LAST_MILE: + return 4; + default: + return null; + } + } + + /** 一条运去哪费用 → 统一账单。 */ + public static BillingDocument toDocument(YqnDtos.CostDetail detail, String warehouseCode, ZoneId zone) { + return BillingDocument.builder() + .warehouseCode(firstNonBlank(detail.warehouseCode, warehouseCode)) + .feeName(detail.costName) + .feeType(feeTypeOf(detail.costName)) + .settledAt(parseTime(detail.settlementTime, zone)) + // 1 实际结算 → estimated=false;2 预估结算 → true + .estimated(detail.settlementType != null && detail.settlementType == 2) + .amount(detail.costAmount == null ? Money.zero(CURRENCY) + : Money.of(java.math.BigDecimal.valueOf(detail.costAmount), CURRENCY)) + .saleOrderNo(detail.saleOrderNo == null ? null : String.valueOf(detail.saleOrderNo)) + .build(); + } + + /** + * 按费用名称归类。 + * + *

运去哪只给中文名,没有类型码(查询用的 {@code costType} 不回报)。 + * 认不出来就留 null,不猜——对账时按名字分类比猜错安全。

+ */ + static WarehouseFeeType feeTypeOf(String costName) { + if (costName == null) { + return null; + } + String name = costName.trim(); + if (name.contains("仓储") || name.contains("仓租")) { + return WarehouseFeeType.STORAGE; + } + if (name.contains("尾程") || name.contains("运费") || name.contains("快递")) { + return WarehouseFeeType.LAST_MILE; + } + if (name.contains("增值")) { + return WarehouseFeeType.VALUE_ADDED; + } + if (name.contains("操作") || name.contains("作业")) { + return WarehouseFeeType.OPERATION; + } + return null; + } + + static Instant parseTime(String value, ZoneId zone) { + if (value == null || value.trim().isEmpty()) { + return null; + } + String v = value.trim(); + try { + return java.time.LocalDateTime.parse(v, TIME) + .atZone(zone == null ? DEFAULT_ZONE : zone).toInstant(); + } catch (DateTimeParseException e) { + try { + return Instant.parse(v); + } catch (DateTimeParseException ignored) { + return null; + } + } + } + + private static String firstNonBlank(String a, String b) { + if (a != null && !a.trim().isEmpty()) { + return a.trim(); + } + return b == null ? null : b.trim(); + } +} diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java index d0a4144..c7edff2 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java @@ -439,4 +439,37 @@ public final class YqnDtos { } + + /** 结算明细请求(API 133)。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CostDetailRequest { + + /** 销售订单号(数字);作业费 / 尾程费按它查。 */ + public Long saleOrderNo; + /** 结算单编号;仓储费 / 增值服务费按它查。 */ + public String billingTransNo; + /** 1 作业费 / 2 仓储费 / 3 增值服务费 / 4 尾程费。 */ + public Integer costType; + public String sku; + public String externalOrderNo; + /** 快照开始日期 yyyy-MM-dd;仅仓储费支持,区间不超过 30 天。 */ + public String snapshotStartDate; + /** 快照结束日期 yyyy-MM-dd。 */ + public String snapshotEndDate; + } + + /** 结算明细的一条记录(API 133 {@code data[]})。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CostDetail { + + /** 销售订单号(数字)。 */ + public Long saleOrderNo; + public String warehouseCode; + /** 费用金额,币种 USD。 */ + public Double costAmount; + public String costName; + public String settlementTime; + /** 1 实际结算 / 2 预估结算。 */ + public Integer settlementType; + } }