diff --git a/docs-warehouse/edayun/README.md b/docs-warehouse/edayun/README.md
index 0d43f26..8abcb1b 100644
--- a/docs-warehouse/edayun/README.md
+++ b/docs-warehouse/edayun/README.md
@@ -13,6 +13,7 @@
| 查询面单 | ✅ 已对接(`POST /webApi/order/v1/getOrderLabel`) |
| 取消前校验 | ✅ 已对接(`POST /webApi/order/v1/checkCancelStatus`) |
| 取消订单 | ✅ 已对接(`POST /webApi/order/v1/cancelOrder`) |
+| 交易明细(费用) | ✅ 已对接(`POST /webApi/accountFlow/list`) |
| 其它业务接口 | ⬜ 等文档 |
| 回调 | ⬜ 等文档 |
| 真机验证 | ⬜ 等测试环境 |
@@ -277,6 +278,75 @@ POST /webApi/order/v1/cancelOrder → CancelResult
`query`(列表查询)显式抛 `WarehouseUnsupportedCapabilityException`——文档还没给。
+## 交易明细(费用)
+
+```
+POST /webApi/accountFlow/list → List
同一业务单号的同一计费项会有多条流水,靠它区分。
+ */ + private final String serialNumber; + /** 该笔变动后的账户余额;仓方未给时为 null。 */ + private final Money accountBalance; private BillingDocument(Builder b) { this.warehouseCode = require(b.warehouseCode, "warehouseCode"); @@ -56,6 +74,8 @@ public final class BillingDocument { this.amount = java.util.Objects.requireNonNull(b.amount, "amount"); this.providerSku = b.providerSku; this.saleOrderNo = b.saleOrderNo; + this.serialNumber = b.serialNumber; + this.accountBalance = b.accountBalance; } public static Builder builder() { @@ -127,6 +147,8 @@ public final class BillingDocument { private Money amount; private String providerSku; private String saleOrderNo; + private String serialNumber; + private Money accountBalance; public Builder warehouseCode(String v) { this.warehouseCode = v; @@ -174,6 +196,16 @@ public final class BillingDocument { return this; } + public Builder serialNumber(String v) { + this.serialNumber = v; + return this; + } + + public Builder accountBalance(Money v) { + this.accountBalance = v; + return this; + } + 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 index 27bc859..fdae445 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 @@ -20,6 +20,16 @@ public final class FeeQuery { private final String externalOrderNo; private final LocalDate snapshotStartDate; private final LocalDate snapshotEndDate; + /** + * 计费时间窗起点(UTC);与 {@link #settledAfter()} 成对。 + * + *与 {@link #snapshotStartDate()} 的区别:那个是仓方的「快照日期」 + * (运去哪按仓储费快照查),这个是计费时间(易达云按 billingTime 查)。 + * 两者语义不同,不要互相替代。
+ */ + private final java.time.Instant settledAfter; + /** 计费时间窗终点(UTC);与 {@link #settledAfter()} 成对。 */ + private final java.time.Instant settledBefore; private FeeQuery(Builder b) { if (b.snapshotStartDate != null && b.snapshotEndDate != null @@ -37,6 +47,15 @@ public final class FeeQuery { this.externalOrderNo = b.externalOrderNo; this.snapshotStartDate = b.snapshotStartDate; this.snapshotEndDate = b.snapshotEndDate; + if ((b.settledAfter == null) != (b.settledBefore == null)) { + throw new IllegalArgumentException( + "settledAfter and settledBefore must be set together"); + } + if (b.settledAfter != null && b.settledAfter.isAfter(b.settledBefore)) { + throw new IllegalArgumentException("settledAfter must not be after settledBefore"); + } + this.settledAfter = b.settledAfter; + this.settledBefore = b.settledBefore; } public static Builder builder() { @@ -60,6 +79,21 @@ public final class FeeQuery { return billingTransNo; } + /** 计费时间窗起点(UTC);null 表示不限。 */ + public java.time.Instant settledAfter() { + return settledAfter; + } + + /** 计费时间窗终点(UTC);null 表示不限。 */ + public java.time.Instant settledBefore() { + return settledBefore; + } + + /** 是否给了计费时间窗。 */ + public boolean hasSettledRange() { + return settledAfter != null && settledBefore != null; + } + /** 费用类型;null 表示不限制。 */ public WarehouseFeeType costType() { return costType; @@ -91,7 +125,8 @@ public final class FeeQuery { /** 是否给了任何查询条件;全空时适配器应拒绝,避免拉全量。 */ public boolean isEmpty() { return saleOrderNo == null && billingTransNo == null && costType == null - && providerSku == null && externalOrderNo == null && !hasDateRange(); + && providerSku == null && externalOrderNo == null + && !hasDateRange() && !hasSettledRange(); } public static final class Builder { @@ -103,6 +138,8 @@ public final class FeeQuery { private String externalOrderNo; private LocalDate snapshotStartDate; private LocalDate snapshotEndDate; + private java.time.Instant settledAfter; + private java.time.Instant settledBefore; /** 销售订单号;运去哪要求数字单号({@code providerOrderId}),非来源单号。 */ public Builder saleOrderNo(String v) { @@ -136,6 +173,18 @@ public final class FeeQuery { return this; } + /** 计费时间窗起点;必须与 {@link #settledBefore} 成对设置。 */ + public Builder settledAfter(java.time.Instant v) { + this.settledAfter = v; + return this; + } + + /** 计费时间窗终点。 */ + public Builder settledBefore(java.time.Instant v) { + this.settledBefore = v; + return this; + } + public FeeQuery build() { return new FeeQuery(this); } 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 7ba395f..2f71ab8 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 @@ -51,6 +51,9 @@ public final class EdayunConstants { /** 取消订单({@code POST /webApi/order/v1/cancelOrder})。 */ public static final String PATH_ORDER_CANCEL = "/webApi/order/v1/cancelOrder"; + /** 查询交易明细({@code POST /webApi/accountFlow/list})。 */ + public static final String PATH_ACCOUNT_FLOW = "/webApi/accountFlow/list"; + /** 物流增值:签收服务。 */ 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 37d7e9b..9ef8a1d 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 @@ -3,6 +3,7 @@ package common.ecommerce.edayun.adapter; import common.ecommerce.edayun.EdayunConstants; import common.ecommerce.edayun.auth.EdayunTokenClient; import common.ecommerce.edayun.dto.EdayunCreateOrderDtos; +import common.ecommerce.edayun.dto.EdayunAccountFlowDtos; import common.ecommerce.edayun.dto.EdayunCancelDtos; import common.ecommerce.edayun.dto.EdayunCreateProductDtos; import common.ecommerce.edayun.dto.EdayunGetOrderDtos; @@ -20,6 +21,7 @@ import common.ecommerce.shared.spi.LockProvider; import common.ecommerce.shared.spi.TokenStore; import common.ecommerce.shared.support.Page; import common.ecommerce.warehouse.capability.OutboundCapable; +import common.ecommerce.warehouse.capability.WarehouseFeeCapable; import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.WarehouseProductCapable; import common.ecommerce.warehouse.enums.CancelEligibility; @@ -29,7 +31,9 @@ import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.error.WarehouseException; import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException; import common.ecommerce.warehouse.model.CancelCommand; +import common.ecommerce.warehouse.model.BillingDocument; import common.ecommerce.warehouse.model.CancelResult; +import common.ecommerce.warehouse.model.FeeQuery; import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundOrder; import common.ecommerce.warehouse.model.OutboundQuery; @@ -40,6 +44,7 @@ import common.ecommerce.warehouse.sdk.WarehouseAdapter; import common.ecommerce.warehouse.sdk.WarehouseContext; import java.time.Clock; +import java.util.ArrayList; import java.util.EnumSet; import java.util.List; @@ -53,7 +58,7 @@ import java.util.List; * {@code WarehouseConnection} 传入。 */ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCapable, - OutboundCapable { + OutboundCapable, WarehouseFeeCapable { private final HttpTransport transport; private final JacksonJsonCodec json; @@ -103,7 +108,8 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa */ @Override public EnumSet文档说明「同一个单号的某个计费项有多条数据」,所以不做去重, + * 每条流水都映射成一条 {@link BillingDocument},靠 {@code serialNumber} 区分。
+ * + *分页:文档要求 {@code pageNum} / {@code pageSize} 必填,当前只取第一页 + * (200 条);超过时截断——待确认是否需要翻页。
+ */ + @Override + public List三个口径差异:
+ *币种优先用 {@code accountCurrency}(账户币种),缺失才退回 + * {@code originalCurrency}。两者可能不同——跨币种账户会有汇率。
+ */ + static Money amountOf(EdayunAccountFlowDtos.FlowRow row) { + String currency = firstNonBlank(row.accountCurrency, row.originalCurrency); + if (!hasText(row.billingAmount)) { + return Money.zero(currency == null ? "USD" : currency); + } + return Money.of(new BigDecimal(row.billingAmount.trim()), + currency == null ? "USD" : currency); + } + + /** + * 计费项编码 → 业务语义。 + * + *易达云用编码(如 {@code farawayFee})而不是分类码,所以只能按关键字推断; + * 认不出返回 null,不猜——对账时宁可不分类,也不能分类错。
+ */ + static WarehouseFeeType feeTypeOf(String billingCode) { + if (!hasText(billingCode)) { + return null; + } + String code = billingCode.toLowerCase(); + if (code.contains("storage") || code.contains("warehouse")) { + return WarehouseFeeType.STORAGE; + } + if (code.contains("operation") || code.contains("handle") || code.contains("handling")) { + return WarehouseFeeType.OPERATION; + } + if (code.contains("freight") || code.contains("shipping") || code.contains("delivery") + || code.contains("faraway") || code.contains("remote")) { + return WarehouseFeeType.LAST_MILE; + } + if (code.contains("service") || code.contains("value") || code.contains("pack") + || code.contains("label")) { + return WarehouseFeeType.VALUE_ADDED; + } + return null; + } + + private static Instant instantOf(Long millis) { + return millis == null || millis <= 0 ? null : Instant.ofEpochMilli(millis); + } + + private static Money moneyOrNull(Double amount, String currency) { + if (amount == null) { + return null; + } + return Money.of(BigDecimal.valueOf(amount), hasText(currency) ? currency.trim() : "USD"); + } + + private static String firstNonBlank(String a, String b) { + if (hasText(a)) { + return a.trim(); + } + return hasText(b) ? b.trim() : 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/EdayunAccountFlowDtos.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunAccountFlowDtos.java new file mode 100644 index 0000000..6a3bd93 --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunAccountFlowDtos.java @@ -0,0 +1,110 @@ +package common.ecommerce.edayun.dto; + +import com.fasterxml.jackson.annotation.JsonInclude; + +import java.util.List; + +/** + * 易达云报文结构:查询交易明细({@code POST /webApi/accountFlow/list})。 + * + *一个文件对应一个接口,只放该接口的请求 / 响应与内嵌子结构。
+ * + *注意:原文说明「同一个单号(ORD-发货单 / REV-收货单)的某个计费项 + * 有多条数据」——所以不能按单号去重,每条流水都是独立的账目,靠 + * {@code serialNumber} 区分。
+ */ +public final class EdayunAccountFlowDtos { + + private EdayunAccountFlowDtos() { + } + + /** 查询请求。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ListFlowRequest { + + /** 业务单号;支持模糊匹配(文档不建议)。 */ + public String bizNo; + /** 服务类型,字典 {@code trading_service_type}。 */ + public Integer serviceType; + /** 计费项名称。 */ + public String billingName; + /** 计费项编码。 */ + public String billingCode; + /** 操作类型,字典 {@code account_operate_type}。 */ + public Integer operateType; + /** 账户类型,字典 {@code account_type}。 */ + public Integer accountType; + /** 流水号。 */ + public String serialNumber; + + /** + * 计费时间起点(毫秒)。 + * + *约束:没给业务单号时时间段必填,且区间不能超过 180 天。
+ */ + public Long beginBillingTime; + /** 计费时间终点(毫秒)。 */ + public Long endBillingTime; + + /** 页码,从 1 开始。必填。 */ + public Integer pageNum; + /** 每页条数,最大 200。必填。 */ + public Integer pageSize; + /** 费收类型:0 标准(默认)/ 1 非标准。 */ + public Integer expenseType; + /** 仓库 id 列表。 */ + public List重点:不按单号去重、金额是 string 可为负、无业务单号时时间段必填且 ≤180 天。
+ */ +class EdayunFeeTest { + + // ------------------------------------------------------------ 请求 + + /** 有业务单号时不强制时间段。 */ + @Test + void bizNoAloneIsEnough() { + EdayunAccountFlowDtos.ListFlowRequest req = EdayunFeeMapper.toRequest( + FeeQuery.builder().externalOrderNo("ORD25037232211").build()); + + assertEquals("ORD25037232211", req.bizNo); + assertNull(req.beginBillingTime); + assertEquals(Integer.valueOf(1), req.pageNum); + assertEquals(Integer.valueOf(200), req.pageSize); + } + + /** 没业务单号时必须给时间段。 */ + @Test + void withoutBizNoRangeIsRequired() { + IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, + () -> EdayunFeeMapper.toRequest(FeeQuery.builder().build())); + assertTrue(ex.getMessage().contains("bizNo or a billing time range"), ex.getMessage()); + } + + /** 没业务单号时时间段不能超过 180 天。 */ + @Test + void rangeOver180DaysWithoutBizNoIsRejected() { + FeeQuery tooLong = FeeQuery.builder() + .settledAfter(Instant.parse("2026-01-01T00:00:00Z")) + .settledBefore(Instant.parse("2026-12-31T00:00:00Z")) + .build(); + + IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, + () -> EdayunFeeMapper.toRequest(tooLong)); + assertTrue(ex.getMessage().contains("180"), ex.getMessage()); + } + + /** 有业务单号时时间段可以长一些(文档只说「没有业务单号时」有 180 天限制)。 */ + @Test + void rangeOver180DaysAllowedWithBizNo() { + EdayunAccountFlowDtos.ListFlowRequest req = EdayunFeeMapper.toRequest(FeeQuery.builder() + .externalOrderNo("ORD-1") + .settledAfter(Instant.parse("2026-01-01T00:00:00Z")) + .settledBefore(Instant.parse("2026-12-31T00:00:00Z")) + .build()); + + assertEquals("ORD-1", req.bizNo); + assertEquals(Long.valueOf(Instant.parse("2026-01-01T00:00:00Z").toEpochMilli()), + req.beginBillingTime); + } + + /** 时间是毫秒。 */ + @Test + void rangeIsInMillis() { + EdayunAccountFlowDtos.ListFlowRequest req = EdayunFeeMapper.toRequest(FeeQuery.builder() + .settledAfter(Instant.parse("2026-11-01T00:00:00Z")) + .settledBefore(Instant.parse("2026-11-10T00:00:00Z")) + .build()); + + assertEquals(Long.valueOf(Instant.parse("2026-11-10T00:00:00Z").toEpochMilli()), + req.endBillingTime); + } + + // ------------------------------------------------------------ 响应 + + private static EdayunAccountFlowDtos.FlowRow chargeRow() { + EdayunAccountFlowDtos.FlowRow row = new EdayunAccountFlowDtos.FlowRow(); + row.serialNumber = "LF-1741871641090"; + row.relateBusinessCode = "ORD25037232211"; + row.poNumber = "P-20261112"; + row.operateType = 0; + row.accountType = 0; + row.billingName = "运费附加费计费项-偏远附加费"; + row.billingCode = "farawayFee"; + row.originalCurrency = "USD"; + row.billingAmount = "-0.500"; + row.accountCurrency = "USD"; + row.exchangeRate = 1.1; + row.accountBalance = 998869.12; + row.billingTime = 1741145821000L; + return row; + } + + @Test + void mapsDocument() { + BillingDocument doc = EdayunFeeMapper.toDocument(chargeRow(), "EDY-WH-1"); + + assertEquals("ORD25037232211", doc.documentNo()); + assertEquals("LF-1741871641090", doc.serialNumber()); + assertEquals("运费附加费计费项-偏远附加费", doc.feeName()); + assertEquals(Instant.ofEpochMilli(1741145821000L), doc.settledAt()); + assertEquals("P-20261112", doc.saleOrderNo()); + // 交易明细是已发生账目,不是预估 + assertEquals(Boolean.FALSE, doc.estimated()); + assertEquals(new BigDecimal("998869.12"), + doc.accountBalance().amount()); + } + + /** 金额是 string 且可为负——扣费是负数,不能取绝对值。 */ + @Test + void amountKeepsSign() { + BillingDocument charge = EdayunFeeMapper.toDocument(chargeRow(), "W"); + assertEquals(new BigDecimal("-0.500"), charge.amount().amount()); + assertEquals("USD", charge.amount().currency().getCurrencyCode()); + + EdayunAccountFlowDtos.FlowRow refund = chargeRow(); + refund.billingAmount = "12.30"; + assertEquals(new BigDecimal("12.30"), + EdayunFeeMapper.toDocument(refund, "W").amount().amount()); + } + + /** 币种优先账户币种,缺失才用原币。 */ + @Test + void amountCurrencyPrefersAccountCurrency() { + EdayunAccountFlowDtos.FlowRow row = chargeRow(); + row.accountCurrency = "CNY"; + row.originalCurrency = "USD"; + + assertEquals("CNY", EdayunFeeMapper.toDocument(row, "W").amount().currency().getCurrencyCode()); + + row.accountCurrency = null; + assertEquals("USD", EdayunFeeMapper.toDocument(row, "W").amount().currency().getCurrencyCode()); + } + + /** 计费项按编码关键字推断;认不出返回 null,不猜。 */ + @Test + void feeTypeIsInferredFromCode() { + assertEquals(WarehouseFeeType.STORAGE, EdayunFeeMapper.feeTypeOf("storageFee")); + assertEquals(WarehouseFeeType.OPERATION, EdayunFeeMapper.feeTypeOf("handlingFee")); + assertEquals(WarehouseFeeType.LAST_MILE, EdayunFeeMapper.feeTypeOf("farawayFee")); + assertEquals(WarehouseFeeType.VALUE_ADDED, EdayunFeeMapper.feeTypeOf("labelServiceFee")); + // 认不出不猜 + assertNull(EdayunFeeMapper.feeTypeOf("someUnknownCode")); + assertNull(EdayunFeeMapper.feeTypeOf(null)); + } + + /** 同一单号的同一计费项多条流水——每条都要保留,不能去重。 */ + @Test + void multipleRowsForSameOrderAreKept() { + EdayunAccountFlowDtos.FlowRow a = chargeRow(); + a.serialNumber = "LF-1"; + EdayunAccountFlowDtos.FlowRow b = chargeRow(); + b.serialNumber = "LF-2"; + + BillingDocument d1 = EdayunFeeMapper.toDocument(a, "W"); + BillingDocument d2 = EdayunFeeMapper.toDocument(b, "W"); + + // 单号与计费项都相同,但流水号不同 → 是两笔 + assertEquals(d1.documentNo(), d2.documentNo()); + assertEquals(d1.feeName(), d2.feeName()); + assertTrue(!d1.serialNumber().equals(d2.serialNumber())); + } +}