Browse Source

feat(yqn): 按 API 133 对接结算明细,费用查询改用 FeeQuery

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 <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 2 weeks ago
parent
commit
d0649fed38
  1. 47
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseFeeCapable.java
  2. 90
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java
  3. 133
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java
  4. 19
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFeeType.java
  5. 16
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  6. 6
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java
  7. 30
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
  8. 178
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeMapper.java
  9. 33
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java

47
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseFeeCapable.java

@ -1,44 +1,31 @@ @@ -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;
/**
* 费用能力:账单 / 订单费用 / 仓租 / 账户流水 / 试算。
* 费用能力:按条件拉取结算明细。
*
* <p>信仓只有订单维度总费用,其余方法应抛
* {@code WarehouseUnsupportedCapabilityException},能力位如实反映。</p>
* <p>各仓的收费维度不一样(有的只能按订单查、有的能按结算单、有的能按日期),
* 统一成一个 {@link FeeQuery},由适配器把不支持的维度<b>显式拒绝</b>——
* 静默忽略过滤条件会让对账金额对不上。</p>
*
* <p>预估费用与最终账单用 {@link BillingDocument#estimated()} 区分,
* 仓一般在发货后先给预估、收货约一周后才出实际结算。</p>
*/
public interface WarehouseFeeCapable extends WarehouseAdapter {
/** 费用单据(尾程 / 仓储 / 操作费)。 */
List<BillingDocument> settlements(WarehouseContext ctx, Instant periodStart, Instant periodEnd);
/** 订单维度费用。 */
default List<BillingDocument> orderCosts(WarehouseContext ctx, String orderRef) {
return Collections.emptyList();
}
/** 仓租明细。 */
default List<BillingDocument> rentDetails(WarehouseContext ctx, Instant periodStart, Instant periodEnd) {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
common.ecommerce.warehouse.WarehouseCapability.FEE_SETTLEMENT);
}
/** 账户流水。 */
default List<BillingDocument> 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<BillingDocument> settlements(WarehouseContext ctx, FeeQuery query);
}

90
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java

@ -4,28 +4,40 @@ import common.ecommerce.shared.support.Money; @@ -4,28 +4,40 @@ import common.ecommerce.shared.support.Money;
import java.time.Instant;
/** 费用单据(尾程 / 仓储 / 操作费)。 */
/**
* 费用单据(尾程 / 仓储 / 操作费)。
*
* <p>{@link #estimated()} 区分预估与最终账单:仓一般发货后先给预估,
* 一周后才出实际结算。对账时必须按这个标记分开,否则会把预估值当成已发生成本。</p>
*/
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 { @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -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;
}

133
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java

@ -0,0 +1,133 @@ @@ -0,0 +1,133 @@
package common.ecommerce.warehouse.model;
import java.time.LocalDate;
/**
* 费用查询条件。
*
* <p>各仓支持的查询维度不同:运去哪要求「销售订单号」或「结算单号」二选一,
* 按日期区间只能查仓储费且区间不超过 30 天。不支持的维度由适配器显式拒绝,
* 不静默忽略——忽略一个过滤条件会让对账金额对不上。</p>
*/
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);
}
}
}

19
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFeeType.java

@ -0,0 +1,19 @@ @@ -0,0 +1,19 @@
package common.ecommerce.warehouse.model;
/**
* 仓费用类型。
*
* <p>各仓的枚举值不同,由适配器维护映射;这里只保留业务语义。
* 运去哪 API 133 的 {@code costType} 是 1 作业费 / 2 仓储费 / 3 增值服务费 / 4 尾程费用。</p>
*/
public enum WarehouseFeeType {
/** 作业费(出入库操作费)。 */
OPERATION,
/** 仓储费 / 仓租。 */
STORAGE,
/** 增值服务费。 */
VALUE_ADDED,
/** 尾程运费。 */
LAST_MILE
}

16
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java

@ -17,6 +17,7 @@ import common.ecommerce.warehouse.capability.WarehouseReturnCapable; @@ -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 { @@ -227,17 +228,16 @@ public final class WarehouseOperations {
/** 费用视图。 */
public final class FeeView {
public List<BillingDocument> settlements(Instant periodStart, Instant periodEnd) {
/** 按条件拉取费用明细(预估与实际用 BillingDocument.estimated() 区分)。 */
public List<BillingDocument> 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<BillingDocument> orderCosts(String orderRef) {
require(WarehouseCapability.FEE_SETTLEMENT, WarehouseFeeCapable.class);
return ((WarehouseFeeCapable) adapter).orderCosts(ctx, orderRef);
() -> ((WarehouseFeeCapable) adapter).settlements(ctx, query));
}
}
}

6
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java

@ -48,10 +48,8 @@ public final class YqnConstants { @@ -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;

30
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java

@ -9,7 +9,10 @@ import common.ecommerce.shared.support.Page; @@ -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; @@ -46,7 +49,8 @@ import java.util.Map;
* <p>字段级契约待打样核对(Spec §8.6):本类只做「拼请求 + 解析响应」,
* 字段差异收敛在 {@link YqnDtos} 与 {@link YqnOutboundMapper}。</p>
*/
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 @@ -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 @@ -256,6 +261,27 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
: YqnOutboundMapper.toPackages(detail);
}
// ------------------------------------------------------------------ 费用
/**
* 结算明细(API 133)。
*
* <p>预估与实际由 {@code settlementType} 区分(1 实际 / 2 预估),
* 映射到 {@link BillingDocument#estimated()}。仓一般发货后可查预估,
* 收货约一周后才出实际账单。</p>
*/
@Override
public List<BillingDocument> settlements(WarehouseContext ctx, FeeQuery query) {
YqnDtos.CostDetailRequest body = YqnFeeMapper.toRequest(query);
String raw = execute(ctx, YqnConstants.PATH_FEE_DETAIL, body, "warehouse.fee.settlements");
List<YqnDtos.CostDetail> rows = json.listAt(raw, "data", YqnDtos.CostDetail.class);
List<BillingDocument> out = new ArrayList<BillingDocument>(rows.size());
for (YqnDtos.CostDetail row : rows) {
out.add(YqnFeeMapper.toDocument(row, ctx.warehouseCode(), zoneOf(ctx)));
}
return out;
}
// ------------------------------------------------------------------ internals
/** 面单模式必须与仓能力匹配;不支持时拒绝,不静默降级。 */

178
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeMapper.java

@ -0,0 +1,178 @@ @@ -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() {
}
/**
* 统一查询条件 → 运去哪请求。
*
* <p>运去哪的约束:</p>
* <ul>
* <li>作业费 / 尾程费按 {@code saleOrderNo} 查,仓储费 / 增值服务费按 {@code billingTransNo} 查;
* 按日期查<b>只支持仓储费</b>,且区间不超过 30 天</li>
* <li>{@code saleOrderNo} 在运去哪是数字,非数字直接拒绝——传错类型仓侧会静默查不到</li>
* </ul>
*/
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();
}
/**
* 按费用名称归类。
*
* <p>运去哪只给中文名,没有类型码(查询用的 {@code costType} 不回报)。
* 认不出来就留 null,不猜——对账时按名字分类比猜错安全。</p>
*/
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();
}
}

33
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java

@ -439,4 +439,37 @@ public final class YqnDtos { @@ -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;
}
}

Loading…
Cancel
Save