diff --git a/docs-warehouse/edayun/README.md b/docs-warehouse/edayun/README.md index 8abcb1b..e497d31 100644 --- a/docs-warehouse/edayun/README.md +++ b/docs-warehouse/edayun/README.md @@ -13,7 +13,8 @@ | 查询面单 | ✅ 已对接(`POST /webApi/order/v1/getOrderLabel`) | | 取消前校验 | ✅ 已对接(`POST /webApi/order/v1/checkCancelStatus`) | | 取消订单 | ✅ 已对接(`POST /webApi/order/v1/cancelOrder`) | -| 交易明细(费用) | ✅ 已对接(`POST /webApi/accountFlow/list`) | +| 交易明细(账户流水) | ✅ 已对接(`POST /webApi/accountFlow/list`) | +| 订单费用明细 | ✅ 已对接(`POST /webApi/order/cost/v1/selectOrderCostInfoList`) | | 其它业务接口 | ⬜ 等文档 | | 回调 | ⬜ 等文档 | | 真机验证 | ⬜ 等测试环境 | @@ -347,6 +348,73 @@ POST /webApi/accountFlow/list → List `BillingDocument` 新增 `serialNumber()`(流水号)与 `accountBalance()`(变动后余额)。 +## 订单费用明细 + +``` +POST /webApi/order/cost/v1/selectOrderCostInfoList → List +``` + +**与交易明细的区别**(两个都是费用,但口径完全不同): + +| | 交易明细 `accountFlow/list` | 订单费用 `selectOrderCostInfoList` | +|---|---|---| +| 视角 | **账户流水** | **按订单拆的费用报价** | +| 金额 | `billingAmount`(string,可为负) | `应收 / 折扣 / 实付` 三个 | +| 粒度 | 一条流水一个计费项 | 一个订单展开成多条计费项 | +| 附带 | 账户余额、汇率 | 计费重、计费分区、是否偏远 | + +### 金额取**实付** + +每个计费项有三个金额: + +```json +"amountReceivable": 20.187, // 应收 +"discountPrice": 5.745, // 折扣 +"realPayPrice": 14.442 // 实付 +``` + +落库金额取 **`realPayPrice`**——对账要以实际发生为准,应收只是报价。 + +### 一个订单展开成多条 + +响应结构是 `rows[] → chargeDetails[] → feeDetails[]`,按**计费项**展开: + +``` +一个订单 → 「尾程-运费」「尾程-出库处理费」… 各一条 BillingDocument +``` + +多条记录的 `documentNo` 相同,靠 `feeName` 区分。 + +若某层只有 `chargeDetails` 汇总、没有 `feeDetails`,按汇总记一条「订单费用」。 + +### 单号类型要配合 + +```json +"type": 0, // 0 订单号 / 1 平台单号 / 2 追踪号 +"orderNo": "..." +``` + +统一模型新增 `FeeQuery.noType()`(`FeeQueryNoType` 枚举)。 +**传了不支持的类型会显式拒绝**——静默按别的口径查会让对账金额对不上。 + +### 时间窗 ≤ 3 个月 + +文档写明「最大查询 3 个月」。超过在本地拒绝。 + +既没有单号也没有时间窗时同样拒绝(避免拉全量)。 + +### 费用类型按中文名推断 + +`billingName` 是中文(如「尾程-出库处理费」),按关键字归类: + +| 关键字 | 归类 | +|---|---| +| 仓储 / storage / 仓租 | `STORAGE` | +| 处理费 / operation / 操作 | `OPERATION` | +| 尾程 / 运费 / 燃油 / 附加费 | `LAST_MILE` | +| 增值 / 贴标 / 打包 | `VALUE_ADDED` | +| 认不出 | null(不猜) | + ## 待确认(问易达云) | # | 要确认 | diff --git a/docs-warehouse/edayun/TODO.md b/docs-warehouse/edayun/TODO.md index b337234..4487ab8 100644 --- a/docs-warehouse/edayun/TODO.md +++ b/docs-warehouse/edayun/TODO.md @@ -13,6 +13,7 @@ | 5 | 出库单 `getOrderInfo` 的 `carrierInfoList` 是否总与追踪号一一对应 | 按数组原样映射 | 多包裹场景 | | 11 | 交易明细超过 200 条时如何翻页 | 当前只取第一页 | 大账户对账会漏 | | 12 | `billingCode` 有没有完整字典(现在按关键字推断) | 认不出归 null | 费用分类准确度 | +| 13 | 订单费用明细的 `billingId` 能否作为幂等键 | 当前未用作主键 | 重复拉取去重 | ## 待业务确认 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 c5b2a83..f525398 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 @@ -28,4 +28,20 @@ public interface WarehouseFeeCapable extends WarehouseAdapter { * 仓不支持该查询维度 */ List settlements(WarehouseContext ctx, FeeQuery query); + + /** + * 按订单维度拉取费用拆分(应收 / 折扣 / 实付)。 + * + *

与 {@link #settlements} 的区别:那个是账户流水(充值 / 扣费 / 退费), + * 这个是单个订单的费用明细,带计费重、计费分区、逐计费项的折扣。

+ * + *

默认不支持——只有提供该接口的仓才覆盖。

+ * + * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException + * 该仓不提供按订单的费用明细 + */ + default List orderCosts(WarehouseContext ctx, FeeQuery query) { + throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( + common.ecommerce.warehouse.enums.WarehouseCapability.FEE_SETTLEMENT); + } } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/FeeQueryNoType.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/FeeQueryNoType.java new file mode 100644 index 0000000..8a544fb --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/FeeQueryNoType.java @@ -0,0 +1,46 @@ +package common.ecommerce.warehouse.enums; + +/** + * 费用查询时「业务单号」的类型。 + * + *

有的仓要求明确告诉它这个单号是哪种(易达云的 {@code type}: + * 0 订单号 / 1 平台单号 / 2 追踪号),有的仓只有一种查法。统一成枚举, + * 不支持的取值由适配器显式拒绝——静默按别的口径查会让对账金额对不上。

+ */ +public enum FeeQueryNoType { + + /** 仓侧订单号(如易达云的 ORD 号)。 */ + PROVIDER_ORDER_NO(10, "仓侧订单号"), + /** 平台订单号(客户单号 / poNumber)。 */ + PLATFORM_ORDER_NO(20, "平台单号"), + /** 物流追踪号。 */ + TRACKING_NO(30, "追踪号"); + + private final int code; + private final String label; + + FeeQueryNoType(int code, String label) { + this.code = code; + this.label = label; + } + + /** 落库用的稳定码;由 SDK 分配,永不复用、永不重排。 */ + public int code() { + return code; + } + + /** 中文显示名。 */ + public String label() { + return label; + } + + /** 按落库码反查。 */ + public static FeeQueryNoType ofCode(int code) { + for (FeeQueryNoType t : values()) { + if (t.code == code) { + return t; + } + } + return null; + } +} 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 39b4f9e..e3a808c 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 @@ -42,16 +42,6 @@ public final class BillingDocument { * 费用只到订单 / 仓粒度。

*/ private final String providerSku; - /** 账户流水号;同一计费项的多条记录靠它区分。 */ - public String serialNumber() { - return serialNumber; - } - - /** 该笔变动后的账户余额;仓方未给时为 null。 */ - public Money accountBalance() { - return accountBalance; - } - /** 关联的销售订单号(仓侧)。 */ private final String saleOrderNo; /** @@ -115,6 +105,16 @@ public final class BillingDocument { return estimated; } + /** 账户流水号;同一计费项的多条记录靠它区分。 */ + public String serialNumber() { + return serialNumber; + } + + /** 该笔变动后的账户余额;仓方未给时为 null。 */ + public Money accountBalance() { + return accountBalance; + } + public Money amount() { return amount; } 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 index fdae445..9a5884a 100644 --- 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 @@ -30,6 +30,14 @@ public final class FeeQuery { private final java.time.Instant settledAfter; /** 计费时间窗终点(UTC);与 {@link #settledAfter()} 成对。 */ private final java.time.Instant settledBefore; + /** + * 业务单号的类型;null 表示由适配器按自己的默认口径解释。 + * + *

有的仓要求明确「这个单号是订单号、平台单号还是追踪号」 + * (易达云的 {@code type}),有的仓只有一种查法。用统一枚举表达, + * 适配器不支持的类型要显式拒绝。

+ */ + private final common.ecommerce.warehouse.enums.FeeQueryNoType noType; private FeeQuery(Builder b) { if (b.snapshotStartDate != null && b.snapshotEndDate != null @@ -56,6 +64,7 @@ public final class FeeQuery { } this.settledAfter = b.settledAfter; this.settledBefore = b.settledBefore; + this.noType = b.noType; } public static Builder builder() { @@ -89,6 +98,11 @@ public final class FeeQuery { return settledBefore; } + /** 业务单号的类型;null 由适配器按默认口径解释。 */ + public common.ecommerce.warehouse.enums.FeeQueryNoType noType() { + return noType; + } + /** 是否给了计费时间窗。 */ public boolean hasSettledRange() { return settledAfter != null && settledBefore != null; @@ -140,6 +154,7 @@ public final class FeeQuery { private LocalDate snapshotEndDate; private java.time.Instant settledAfter; private java.time.Instant settledBefore; + private common.ecommerce.warehouse.enums.FeeQueryNoType noType; /** 销售订单号;运去哪要求数字单号({@code providerOrderId}),非来源单号。 */ public Builder saleOrderNo(String v) { @@ -185,6 +200,12 @@ public final class FeeQuery { return this; } + /** 业务单号类型;决定适配器按哪个字段查。 */ + public Builder noType(common.ecommerce.warehouse.enums.FeeQueryNoType v) { + this.noType = v; + return this; + } + public FeeQuery build() { return new FeeQuery(this); } 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 a122c7c..4189af8 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 @@ -605,6 +605,22 @@ public final class WarehouseOperations { () -> ((WarehouseChannelRecommendCapable) adapter).recommend(ctx, query)); } + /** + * 按订单维度拉取费用拆分(应收 / 折扣 / 实付)。 + * + *

与 {@link #settlements} 不同:那个是账户流水,这个是单订单的费用明细。 + * 只读,不走幂等。

+ */ + public List orderCosts(FeeQuery query) { + require(WarehouseCapability.FEE_SETTLEMENT, WarehouseFeeCapable.class); + return CallSupport.observe(observer, ctx, "warehouse.fee.orderCosts", + CallSupport.params("saleOrderNo", query.saleOrderNo(), + "externalOrderNo", query.externalOrderNo(), + "noType", query.noType()), + List::size, + () -> ((WarehouseFeeCapable) adapter).orderCosts(ctx, query)); + } + /** 按条件拉取费用明细(预估与实际用 BillingDocument.estimated() 区分)。 */ public List settlements(FeeQuery query) { require(WarehouseCapability.FEE_SETTLEMENT, WarehouseFeeCapable.class); diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java index 2f71ab8..a50d030 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java @@ -54,6 +54,9 @@ public final class EdayunConstants { /** 查询交易明细({@code POST /webApi/accountFlow/list})。 */ public static final String PATH_ACCOUNT_FLOW = "/webApi/accountFlow/list"; + /** 查询订单费用明细({@code POST /webApi/order/cost/v1/selectOrderCostInfoList})。 */ + public static final String PATH_ORDER_COST = "/webApi/order/cost/v1/selectOrderCostInfoList"; + /** 物流增值:签收服务。 */ public static final String ADD_SERVICE_SIGNATURE = "is_signature"; diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java index 9ef8a1d..276dc4c 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java @@ -8,6 +8,7 @@ import common.ecommerce.edayun.dto.EdayunCancelDtos; import common.ecommerce.edayun.dto.EdayunCreateProductDtos; import common.ecommerce.edayun.dto.EdayunGetOrderDtos; import common.ecommerce.edayun.dto.EdayunGetOrderLabelDtos; +import common.ecommerce.edayun.dto.EdayunOrderCostDtos; import common.ecommerce.edayun.enums.EdayunCancelStatus; import common.ecommerce.edayun.http.EdayunRequestFactory; import common.ecommerce.http.HttpRequest; @@ -393,6 +394,37 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa return out; } + /** + * 查询订单费用明细 + * ({@code POST /webApi/order/cost/v1/selectOrderCostInfoList})。 + * + *

与 {@link #settlements}(账户流水)不同:这个按订单拆费用, + * 带应收 / 折扣 / 实付与计费重。落库金额取实付。 + * + *

一个订单可能展开成多条 {@link BillingDocument}(逐计费项)。

+ */ + @Override + public List orderCosts(WarehouseContext ctx, FeeQuery query) { + EdayunOrderCostDtos.SelectOrderCostRequest body = EdayunOrderCostMapper.toRequest(query); + String bodyJson = json.toJson(body); + + HttpResponse resp = send(ctx, EdayunConstants.PATH_ORDER_COST, bodyJson, + "warehouse.fee.orderCosts"); + EdayunOrderCostDtos.SelectOrderCostResponse parsed = + json.fromJson(resp.body(), EdayunOrderCostDtos.SelectOrderCostResponse.class); + requireSuccess(ctx, parsed == null ? null : parsed.code, + parsed == null ? null : parsed.msg, resp, "warehouse.fee.orderCosts"); + + if (parsed.rows == null || parsed.rows.isEmpty()) { + return java.util.Collections.emptyList(); + } + List out = new ArrayList(); + for (EdayunOrderCostDtos.OrderCostRow row : parsed.rows) { + out.addAll(EdayunOrderCostMapper.toDocuments(row, ctx.warehouseCode())); + } + return out; + } + // ------------------------------------------------------------------ internals /** 发业务请求(自动取 token、算签名)。 */ diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderCostMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderCostMapper.java new file mode 100644 index 0000000..b272265 --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderCostMapper.java @@ -0,0 +1,205 @@ +package common.ecommerce.edayun.adapter; + +import common.ecommerce.edayun.dto.EdayunOrderCostDtos; +import common.ecommerce.shared.support.Money; +import common.ecommerce.warehouse.enums.FeeQueryNoType; +import common.ecommerce.warehouse.enums.WarehouseFeeType; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.BillingDocument; +import common.ecommerce.warehouse.model.FeeQuery; + +import java.math.BigDecimal; +import java.time.Duration; +import java.time.Instant; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 易达云订单费用明细映射 + * ({@code POST /webApi/order/cost/v1/selectOrderCostInfoList})。 + * + *

与交易明细({@code accountFlow/list})的区别:

+ *
    + *
  • 交易明细 = 账户流水,带账户余额,金额为负表示扣费
  • + *
  • 订单费用 = 按订单拆的报价,带应收 / 折扣 / 实付三个金额与计费重
  • + *
+ * + *

金额口径:{@code realPayPrice} 是实付(应收 - 折扣), + * 落到 {@link BillingDocument#amount()} 的是实付——对账要以实际发生为准。

+ */ +public final class EdayunOrderCostMapper { + + /** 计费时间窗上限 3 个月。 */ + static final int MAX_RANGE_MONTHS = 3; + + /** 单页上限。 */ + static final int MAX_PAGE_SIZE = 200; + + private EdayunOrderCostMapper() { + } + + /** 统一查询条件 → 订单费用查询请求。 */ + public static EdayunOrderCostDtos.SelectOrderCostRequest toRequest(FeeQuery query) { + EdayunOrderCostDtos.SelectOrderCostRequest req = + new EdayunOrderCostDtos.SelectOrderCostRequest(); + req.pageNum = 1; + req.pageSize = MAX_PAGE_SIZE; + + // 单号 + 类型:两者要配合使用 + String orderNo = firstNonBlank(query.externalOrderNo(), query.saleOrderNo()); + req.orderNo = orderNo; + req.type = typeOf(query.noType()); + + if (query.hasSettledRange()) { + long months = Duration.between(query.settledAfter(), query.settledBefore()).toDays() / 30; + if (months > MAX_RANGE_MONTHS) { + throw new IllegalArgumentException( + "edayun order cost query range must not exceed 3 months, got about " + + months + " months"); + } + req.beginBillingTime = query.settledAfter().toEpochMilli(); + req.endBillingTime = query.settledBefore().toEpochMilli(); + } else if (!hasText(orderNo)) { + throw new IllegalArgumentException( + "edayun order cost query requires an order number or a billing time range;" + + " refusing to pull all costs"); + } + + req.skuCode = query.providerSku(); + return req; + } + + /** + * 统一单号类型 → 易达云 {@code type}。 + * + *

不支持的取值显式拒绝:静默按别的口径查会让对账金额对不上。

+ */ + static Integer typeOf(FeeQueryNoType noType) { + if (noType == null) { + return null; + } + switch (noType) { + case PROVIDER_ORDER_NO: + return 0; + case PLATFORM_ORDER_NO: + return 1; + case TRACKING_NO: + return 2; + default: + throw new IllegalArgumentException( + "edayun order cost query does not support noType: " + noType); + } + } + + /** + * 一行订单费用 → 若干条 {@link BillingDocument}。 + * + *

一层里可能有多个 {@code chargeDetails},每个下面又有多个 {@code feeDetails}。 + * 这里按计费项展开:每个 feeDetail 一条记录,对账才能落到具体费用项。

+ * + *

如果没有 {@code feeDetails} 但有 {@code chargeDetails} 汇总,就按汇总记一条。

+ */ + public static List toDocuments(EdayunOrderCostDtos.OrderCostRow row, + String warehouseCode) { + List out = new ArrayList(); + if (row.chargeDetails == null || row.chargeDetails.isEmpty()) { + // 只有汇总金额的情况下退化为一条「订单总费用」 + out.add(baseBuilder(row, warehouseCode) + .feeName("订单总费用") + .feeType(null) + .amount(Money.zero(defaultCurrency(row))) + .build()); + return out; + } + + for (EdayunOrderCostDtos.ChargeDetail charge : row.chargeDetails) { + if (charge.feeDetails != null && !charge.feeDetails.isEmpty()) { + for (EdayunOrderCostDtos.FeeDetail fee : charge.feeDetails) { + out.add(baseBuilder(row, warehouseCode) + .feeName(fee.billingName) + .feeType(feeTypeOf(fee.billingName)) + .amount(moneyOf(fee.realPayPrice, + firstNonBlank(fee.currencyCode, fee.quotationCurrency, + defaultCurrency(row)))) + .build()); + } + } else { + out.add(baseBuilder(row, warehouseCode) + .feeName("订单费用") + .feeType(null) + .amount(moneyOf(charge.realPayPrice, + firstNonBlank(charge.currencyCode, charge.quotationCurrency, + defaultCurrency(row)))) + .build()); + } + } + return out; + } + + private static BillingDocument.Builder baseBuilder(EdayunOrderCostDtos.OrderCostRow row, + String warehouseCode) { + return BillingDocument.builder() + .warehouseCode(firstNonBlank(row.warehouseName, warehouseCode)) + .sourceProvider(WarehouseProvider.EDAYUN) + .documentNo(row.orderCode) + .serialNumber(row.trackingNo) + // 订单费用是实际发生的,不是预估 + .estimated(false) + .settledAt(row.billingTime == null ? null : Instant.ofEpochMilli(row.billingTime)) + .saleOrderNo(firstNonBlank(row.poNumber, row.orderCode)); + } + + /** + * 按计费项名称归类。 + * + *

易达云的名称是中文(如「尾程-出库处理费」),按关键字推断; + * 认不出返回 null,不猜——对账时宁可不分类,也不能分错。

+ */ + static WarehouseFeeType feeTypeOf(String name) { + if (!hasText(name)) { + return null; + } + String n = name.toLowerCase(); + if (n.contains("仓储") || n.contains("storage") || n.contains("仓租")) { + return WarehouseFeeType.STORAGE; + } + if (n.contains("处理费") || n.contains("operation") || n.contains("handling") + || n.contains("操作")) { + return WarehouseFeeType.OPERATION; + } + if (n.contains("尾程") || n.contains("运费") || n.contains("freight") + || n.contains("delivery") || n.contains("燃油") || n.contains("附加费")) { + return WarehouseFeeType.LAST_MILE; + } + if (n.contains("增值") || n.contains("service") || n.contains("贴标") + || n.contains("label") || n.contains("打包")) { + return WarehouseFeeType.VALUE_ADDED; + } + return null; + } + + private static String defaultCurrency(EdayunOrderCostDtos.OrderCostRow row) { + return "USD"; + } + + private static Money moneyOf(Double amount, String currency) { + if (amount == null) { + return Money.zero(currency == null ? "USD" : currency); + } + return Money.of(BigDecimal.valueOf(amount), currency == null ? "USD" : currency); + } + + private static String firstNonBlank(String... values) { + for (String v : values) { + if (hasText(v)) { + return v.trim(); + } + } + return null; + } + + private static boolean hasText(String v) { + return v != null && !v.trim().isEmpty(); + } +} diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunOrderCostDtos.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunOrderCostDtos.java new file mode 100644 index 0000000..74c938d --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunOrderCostDtos.java @@ -0,0 +1,151 @@ +package common.ecommerce.edayun.dto; + +import com.fasterxml.jackson.annotation.JsonInclude; + +import java.util.List; + +/** + * 易达云报文结构:查询订单费用明细 + * ({@code POST /webApi/order/cost/v1/selectOrderCostInfoList})。 + * + *

一个文件对应一个接口,只放该接口的请求 / 响应与内嵌子结构。

+ * + *

与「交易明细」({@code accountFlow/list})的区别:那个是账户流水 + * (充值 / 扣费 / 退费,带账户余额),这个是按订单的费用拆分 + * (应收 / 折扣 / 实付,带计费重与分区)。

+ */ +public final class EdayunOrderCostDtos { + + private EdayunOrderCostDtos() { + } + + /** 查询请求。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class SelectOrderCostRequest { + + /** 页码,从 1 开始。必填。 */ + public Integer pageNum; + /** 每页条数,最大 200。必填。 */ + public Integer pageSize; + /** 物流产品 id。 */ + public Long carrierProductId; + + /** 单号类型:0 订单号 / 1 平台单号 / 2 追踪号。 */ + public Integer type; + /** 订单号 / 平台单号 / 追踪号;配合 {@link #type}。 */ + public String orderNo; + /** 仓库 id。 */ + public String warehouseId; + /** 国家二字码。 */ + public String countryCode; + /** SKU。 */ + public String skuCode; + + /** 计费时间开始(毫秒);最大查询 3 个月。 */ + public Long beginBillingTime; + /** 计费时间结束(毫秒)。 */ + public Long endBillingTime; + } + + /** 查询响应。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class SelectOrderCostResponse { + public Long total; + public List rows; + public Integer code; + public String msg; + /** 文档标为 object,实际可能是字符串;保留 Object 避免解析失败。 */ + public Object traceId; + } + + /** 一条订单费用记录。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class OrderCostRow { + + public String customerCode; + /** 仓侧订单号。 */ + public String orderCode; + /** 销售平台。 */ + public String channelName; + public String channelAccountName; + /** 平台订单号。 */ + public String poNumber; + public String warehouseId; + public String warehouseName; + public String carrierProductId; + public String carrierProductName; + public String trackingNo; + + /** 订单发货时间(毫秒)。 */ + public Long beginOutboundTime; + /** 计费时间(毫秒)。 */ + public Long billingTime; + /** 创建时间(毫秒)。 */ + public Long createTime; + + public String buyerName; + public String buyerPhone; + public String email; + public String destCountry; + public String destProvince; + public String zipCode; + + /** 包裹信息,格式 {@code 长*宽*高*重}。 */ + public String outboundParcel; + /** SKU 和数量,格式 {@code sku*数量}。 */ + public String productSkuNumber; + /** 燃油附加费费率。 */ + public Double fuelfee; + + /** 运费计费重;文档标为 string。 */ + public String freightBillingWeight; + /** 运费计费重单位,如 {@code g}。 */ + public String freightUnitType; + /** 出库处理费计费重。 */ + public String processBillingWeight; + /** 出库处理费计费重单位,如 {@code kg}。 */ + public String processUnitType; + + /** 计费分区。 */ + public String billingZone; + /** 是否偏远地区:0 否 / 1 是。 */ + public Integer isFaraway; + + /** 计费详情。 */ + public List chargeDetails; + } + + /** 计费详情:一个报价单元(可能含多条费用明细)。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ChargeDetail { + + /** 应收金额。 */ + public Double amountReceivable; + /** 报价币种。 */ + public String quotationCurrency; + /** 折扣金额。 */ + public Double discountPrice; + /** 实付金额。 */ + public Double realPayPrice; + /** 结算币种。 */ + public String currencyCode; + + /** 费用明细(逐计费项)。 */ + public List feeDetails; + } + + /** 单条计费项。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class FeeDetail { + + /** 计费项 id。 */ + public String billingId; + /** 计费项名称,如「尾程-出库处理费」。 */ + public String billingName; + public Double amountReceivable; + public String quotationCurrency; + public Double discountPrice; + public Double realPayPrice; + public String currencyCode; + } +} diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunOrderCostTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunOrderCostTest.java new file mode 100644 index 0000000..3916de6 --- /dev/null +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunOrderCostTest.java @@ -0,0 +1,197 @@ +package common.ecommerce.edayun.adapter; + +import common.ecommerce.edayun.dto.EdayunOrderCostDtos; +import common.ecommerce.warehouse.enums.FeeQueryNoType; +import common.ecommerce.warehouse.enums.WarehouseFeeType; +import common.ecommerce.warehouse.model.BillingDocument; +import common.ecommerce.warehouse.model.FeeQuery; +import org.junit.jupiter.api.Test; + +import java.math.BigDecimal; +import java.time.Instant; +import java.util.List; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 订单费用明细({@code selectOrderCostInfoList})映射。 + * + *

重点:金额取实付、按计费项展开成多条、单号类型要配合、时间窗 ≤3 个月。

+ */ +class EdayunOrderCostTest { + + // ------------------------------------------------------------ 请求 + + @Test + void mapsOrderNumberAndType() { + EdayunOrderCostDtos.SelectOrderCostRequest req = EdayunOrderCostMapper.toRequest( + FeeQuery.builder() + .externalOrderNo("60044642") + .noType(FeeQueryNoType.PLATFORM_ORDER_NO) + .build()); + + assertEquals("60044642", req.orderNo); + assertEquals(Integer.valueOf(1), req.type); // 1 平台单号 + assertEquals(Integer.valueOf(1), req.pageNum); + assertEquals(Integer.valueOf(200), req.pageSize); + } + + /** 三种单号类型都要映射对。 */ + @Test + void allNoTypesMap() { + assertEquals(Integer.valueOf(0), + EdayunOrderCostMapper.typeOf(FeeQueryNoType.PROVIDER_ORDER_NO)); + assertEquals(Integer.valueOf(1), + EdayunOrderCostMapper.typeOf(FeeQueryNoType.PLATFORM_ORDER_NO)); + assertEquals(Integer.valueOf(2), + EdayunOrderCostMapper.typeOf(FeeQueryNoType.TRACKING_NO)); + assertNull(EdayunOrderCostMapper.typeOf(null)); + } + + /** 既不传单号也不传时间窗时本地拒绝。 */ + @Test + void withoutOrderNoOrRangeIsRejected() { + IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, + () -> EdayunOrderCostMapper.toRequest(FeeQuery.builder().build())); + assertTrue(ex.getMessage().contains("order number or a billing time range"), ex.getMessage()); + } + + /** 时间窗不能超过 3 个月。 */ + @Test + void rangeOver3MonthsIsRejected() { + FeeQuery tooLong = FeeQuery.builder() + .settledAfter(Instant.parse("2026-01-01T00:00:00Z")) + .settledBefore(Instant.parse("2026-06-01T00:00:00Z")) + .build(); + + IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, + () -> EdayunOrderCostMapper.toRequest(tooLong)); + assertTrue(ex.getMessage().contains("3 months"), ex.getMessage()); + } + + @Test + void rangeWithin3MonthsIsAccepted() { + EdayunOrderCostDtos.SelectOrderCostRequest req = EdayunOrderCostMapper.toRequest( + FeeQuery.builder() + .settledAfter(Instant.parse("2026-01-01T00:00:00Z")) + .settledBefore(Instant.parse("2026-02-15T00:00:00Z")) + .build()); + + assertEquals(Long.valueOf(Instant.parse("2026-01-01T00:00:00Z").toEpochMilli()), + req.beginBillingTime); + } + + // ------------------------------------------------------------ 响应 + + private static EdayunOrderCostDtos.OrderCostRow twoFeeRow() { + EdayunOrderCostDtos.OrderCostRow row = new EdayunOrderCostDtos.OrderCostRow(); + row.orderCode = "ORD26091260233"; + row.poNumber = "60044642"; + row.warehouseName = "美西1仓"; + row.trackingNo = "877399075299"; + row.billingTime = 1789781258000L; + + EdayunOrderCostDtos.FeeDetail freight = new EdayunOrderCostDtos.FeeDetail(); + freight.billingName = "尾程-运费"; + freight.amountReceivable = 20.0; + freight.discountPrice = 5.0; + freight.realPayPrice = 15.0; + freight.currencyCode = "USD"; + + EdayunOrderCostDtos.FeeDetail handling = new EdayunOrderCostDtos.FeeDetail(); + handling.billingName = "尾程-出库处理费"; + handling.amountReceivable = 0.54; + handling.discountPrice = 0.162; + handling.realPayPrice = 0.378; + handling.currencyCode = "USD"; + + EdayunOrderCostDtos.ChargeDetail charge = new EdayunOrderCostDtos.ChargeDetail(); + charge.currencyCode = "USD"; + charge.feeDetails = java.util.Arrays.asList(freight, handling); + row.chargeDetails = java.util.Collections.singletonList(charge); + return row; + } + + /** 一层 chargeDetails 里多个 feeDetails → 展开成多条记录。 */ + @Test + void expandsToMultipleDocuments() { + List docs = EdayunOrderCostMapper.toDocuments(twoFeeRow(), "EDY-WH"); + + assertEquals(2, docs.size()); + assertEquals("尾程-运费", docs.get(0).feeName()); + assertEquals("尾程-出库处理费", docs.get(1).feeName()); + } + + /** 落库金额取实付(应收 - 折扣),不是应收。 */ + @Test + void amountIsRealPayNotReceivable() { + List docs = EdayunOrderCostMapper.toDocuments(twoFeeRow(), "W"); + + assertEquals(new BigDecimal("15.0"), docs.get(0).amount().amount()); + assertEquals(new BigDecimal("0.378"), docs.get(1).amount().amount()); + } + + @Test + void mapsHeaderFields() { + List docs = EdayunOrderCostMapper.toDocuments(twoFeeRow(), "W"); + BillingDocument first = docs.get(0); + + assertEquals("ORD26091260233", first.documentNo()); + assertEquals("60044642", first.saleOrderNo()); + assertEquals("877399075299", first.serialNumber()); + assertEquals(Instant.ofEpochMilli(1789781258000L), first.settledAt()); + // 实际发生,不是预估 + assertEquals(Boolean.FALSE, first.estimated()); + } + + /** 费用类型按中文名推断;认不出不猜。 */ + @Test + void feeTypeIsInferredFromChineseName() { + assertEquals(WarehouseFeeType.LAST_MILE, EdayunOrderCostMapper.feeTypeOf("尾程-运费")); + assertEquals(WarehouseFeeType.OPERATION, EdayunOrderCostMapper.feeTypeOf("尾程-出库处理费")); + assertEquals(WarehouseFeeType.STORAGE, EdayunOrderCostMapper.feeTypeOf("仓储费")); + assertEquals(WarehouseFeeType.VALUE_ADDED, EdayunOrderCostMapper.feeTypeOf("增值服务-贴标")); + assertNull(EdayunOrderCostMapper.feeTypeOf("某个新费用")); + assertNull(EdayunOrderCostMapper.feeTypeOf(null)); + } + + /** 没有 feeDetails 但有 chargeDetails 汇总时,按汇总记一条。 */ + @Test + void fallsBackToChargeSummary() { + EdayunOrderCostDtos.OrderCostRow row = twoFeeRow(); + EdayunOrderCostDtos.ChargeDetail onlySummary = new EdayunOrderCostDtos.ChargeDetail(); + onlySummary.realPayPrice = 14.442; + onlySummary.currencyCode = "USD"; + row.chargeDetails = java.util.Collections.singletonList(onlySummary); + + List docs = EdayunOrderCostMapper.toDocuments(row, "W"); + + assertEquals(1, docs.size()); + assertEquals("订单费用", docs.get(0).feeName()); + assertEquals(new BigDecimal("14.442"), docs.get(0).amount().amount()); + } + + /** 完全没有 chargeDetails 时不抛异常,返回一条零金额占位。 */ + @Test + void noChargeDetailsYieldsZeroPlaceholder() { + EdayunOrderCostDtos.OrderCostRow row = twoFeeRow(); + row.chargeDetails = null; + + List docs = EdayunOrderCostMapper.toDocuments(row, "W"); + + assertEquals(1, docs.size()); + assertEquals(BigDecimal.ZERO, docs.get(0).amount().amount()); + } + + /** 一个订单的多个 feeDetail 都挂同一个 documentNo,靠 feeName 区分。 */ + @Test + void documentsShareOrderNumberButDifferByFeeName() { + List docs = EdayunOrderCostMapper.toDocuments(twoFeeRow(), "W"); + + assertEquals(docs.get(0).documentNo(), docs.get(1).documentNo()); + assertTrue(!docs.get(0).feeName().equals(docs.get(1).feeName())); + } +}