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 @@
@@ -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); |
||||
} |
||||
|
||||
@ -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); |
||||
} |
||||
} |
||||
} |
||||
@ -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 |
||||
} |
||||
@ -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(); |
||||
} |
||||
} |
||||
Loading…
Reference in new issue