Browse Source
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
9 changed files with 477 additions and 75 deletions
@ -1,44 +1,31 @@ |
|||||||
package common.ecommerce.warehouse.capability; |
package common.ecommerce.warehouse.capability; |
||||||
|
|
||||||
import common.ecommerce.warehouse.model.BillingDocument; |
import common.ecommerce.warehouse.model.BillingDocument; |
||||||
|
import common.ecommerce.warehouse.model.FeeQuery; |
||||||
import common.ecommerce.warehouse.sdk.WarehouseAdapter; |
import common.ecommerce.warehouse.sdk.WarehouseAdapter; |
||||||
import common.ecommerce.warehouse.sdk.WarehouseContext; |
import common.ecommerce.warehouse.sdk.WarehouseContext; |
||||||
|
|
||||||
import java.time.Instant; |
|
||||||
import java.util.Collections; |
|
||||||
import java.util.List; |
import java.util.List; |
||||||
|
|
||||||
/** |
/** |
||||||
* 费用能力:账单 / 订单费用 / 仓租 / 账户流水 / 试算。 |
* 费用能力:按条件拉取结算明细。 |
||||||
* |
* |
||||||
* <p>信仓只有订单维度总费用,其余方法应抛 |
* <p>各仓的收费维度不一样(有的只能按订单查、有的能按结算单、有的能按日期), |
||||||
* {@code WarehouseUnsupportedCapabilityException},能力位如实反映。</p> |
* 统一成一个 {@link FeeQuery},由适配器把不支持的维度<b>显式拒绝</b>—— |
||||||
|
* 静默忽略过滤条件会让对账金额对不上。</p> |
||||||
|
* |
||||||
|
* <p>预估费用与最终账单用 {@link BillingDocument#estimated()} 区分, |
||||||
|
* 仓一般在发货后先给预估、收货约一周后才出实际结算。</p> |
||||||
*/ |
*/ |
||||||
public interface WarehouseFeeCapable extends WarehouseAdapter { |
public interface WarehouseFeeCapable extends WarehouseAdapter { |
||||||
|
|
||||||
/** 费用单据(尾程 / 仓储 / 操作费)。 */ |
/** |
||||||
List<BillingDocument> settlements(WarehouseContext ctx, Instant periodStart, Instant periodEnd); |
* 拉取费用明细。 |
||||||
|
* |
||||||
/** 订单维度费用。 */ |
* @param query 查询条件;{@link FeeQuery#isEmpty()} 为 true 时适配器必须拒绝, |
||||||
default List<BillingDocument> orderCosts(WarehouseContext ctx, String orderRef) { |
* 避免无条件下拉全量 |
||||||
return Collections.emptyList(); |
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException |
||||||
} |
* 仓不支持该查询维度 |
||||||
|
*/ |
||||||
/** 仓租明细。 */ |
List<BillingDocument> settlements(WarehouseContext ctx, FeeQuery query); |
||||||
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); |
|
||||||
} |
|
||||||
} |
} |
||||||
|
|||||||
@ -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); |
||||||
|
} |
||||||
|
} |
||||||
|
} |
||||||
@ -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 |
||||||
|
} |
||||||
@ -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(); |
||||||
|
} |
||||||
|
} |
||||||
Loading…
Reference in new issue