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 +``` + +### 三条与其它仓不同的口径 + +**① 同一单号的同一计费项有多条数据——不去重** + +文档原文:「同一个单号(ORD-发货单 / REV-收货单)的某个计费项有多条数据」。 + +所以每条流水都映射成一条 `BillingDocument`,靠 **`serialNumber()`**(账户流水号)区分。 +按单号去重会丢账。 + +**② 金额是 string 且可为负** + +```json +"billingAmount": "-0.500" +``` + +负数 = 扣费,正数 = 充值 / 退费。**不能取绝对值**——那会让扣费和退费变成同一笔。 + +**③ 币种有两个,优先账户币种** + +| 字段 | 含义 | +|---|---| +| `accountCurrency` | 账户币种(**优先**) | +| `originalCurrency` | 原币 | + +跨币种账户时两者不同,`exchangeRate` 是汇率。 + +### 查询约束 + +| 约束 | 处理 | +|---|---| +| 没给业务单号时,时间段必填 | 不传 bizNo 又没有时间窗 → 本地拒绝 | +| 时间段不能超过 180 天 | 超过且没有 bizNo → 本地拒绝 | +| `pageNum` / `pageSize` 必填 | 固定第 1 页、每页 200(上限) | +| `bizNo` 支持模糊匹配 | 文档标注「不建议」,我们按精确值传 | + +**分页**:当前只取第一页(200 条),超过时截断。需要翻页的话要扩展——见 TODO。 + +### 计费项分类 + +`billingCode` 是编码(如 `farawayFee`)而不是分类码,只能按关键字推断: + +| 关键字 | 归类 | +|---|---| +| storage / warehouse | `STORAGE` | +| operation / handle / handling | `OPERATION` | +| freight / shipping / delivery / faraway / remote | `LAST_MILE` | +| service / value / pack / label | `VALUE_ADDED` | +| **认不出** | **null(不猜)** | + +对账时宁可不分类,也不能分错。 + +### 统一模型扩展 + +`FeeQuery` 新增 **计费时间窗**(`settledAfter()` / `settledBefore()`), +与已有的「快照日期」(`snapshotStartDate`,运去哪按仓储费快照查)**语义不同**: + +| 字段 | 用于 | +|---|---| +| `snapshotStartDate/EndDate` | 运去哪仓储费的快照日期 | +| `settledAfter/Before` | 易达云按 `billingTime` 查 | + +`BillingDocument` 新增 `serialNumber()`(流水号)与 `accountBalance()`(变动后余额)。 + ## 待确认(问易达云) | # | 要确认 | diff --git a/docs-warehouse/edayun/TODO.md b/docs-warehouse/edayun/TODO.md index 834c6de..b337234 100644 --- a/docs-warehouse/edayun/TODO.md +++ b/docs-warehouse/edayun/TODO.md @@ -11,6 +11,8 @@ | 3 | 业务接口能否用 `openApiAdminSecret` 免签 | 当前一律用 `appSecret` 算 MD5 | 若只有 token 接口免签,现在是正确的 | | 4 | 创建产品同 SKU 重复调用的行为 | 按「创建」语义处理,无更新接口 | 重复建档会报错 | | 5 | 出库单 `getOrderInfo` 的 `carrierInfoList` 是否总与追踪号一一对应 | 按数组原样映射 | 多包裹场景 | +| 11 | 交易明细超过 200 条时如何翻页 | 当前只取第一页 | 大账户对账会漏 | +| 12 | `billingCode` 有没有完整字典(现在按关键字推断) | 认不出归 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 3b9d8c6..39b4f9e 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,8 +42,26 @@ public final class BillingDocument { * 费用只到订单 / 仓粒度。

*/ private final String providerSku; + /** 账户流水号;同一计费项的多条记录靠它区分。 */ + public String serialNumber() { + return serialNumber; + } + + /** 该笔变动后的账户余额;仓方未给时为 null。 */ + public Money accountBalance() { + return accountBalance; + } + /** 关联的销售订单号(仓侧)。 */ private final String saleOrderNo; + /** + * 仓方账户流水号。 + * + *

同一业务单号的同一计费项会有多条流水,靠它区分。

+ */ + 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 capabilities() { - return EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND); + return EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND, + WarehouseCapability.FEE_SETTLEMENT); } /** @@ -354,6 +360,39 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa return v != null && !v.trim().isEmpty(); } + // ------------------------------------------------------------------ 费用 + + /** + * 查询交易明细({@code POST /webApi/accountFlow/list})。 + * + *

文档说明「同一个单号的某个计费项有多条数据」,所以不做去重, + * 每条流水都映射成一条 {@link BillingDocument},靠 {@code serialNumber} 区分。

+ * + *

分页:文档要求 {@code pageNum} / {@code pageSize} 必填,当前只取第一页 + * (200 条);超过时截断——待确认是否需要翻页。

+ */ + @Override + public List settlements(WarehouseContext ctx, FeeQuery query) { + EdayunAccountFlowDtos.ListFlowRequest body = EdayunFeeMapper.toRequest(query); + String bodyJson = json.toJson(body); + + HttpResponse resp = send(ctx, EdayunConstants.PATH_ACCOUNT_FLOW, bodyJson, + "warehouse.fee.settlements"); + EdayunAccountFlowDtos.ListFlowResponse parsed = + json.fromJson(resp.body(), EdayunAccountFlowDtos.ListFlowResponse.class); + requireSuccess(ctx, parsed == null ? null : parsed.code, + parsed == null ? null : parsed.msg, resp, "warehouse.fee.settlements"); + + if (parsed.rows == null || parsed.rows.isEmpty()) { + return java.util.Collections.emptyList(); + } + List out = new ArrayList(parsed.rows.size()); + for (EdayunAccountFlowDtos.FlowRow row : parsed.rows) { + out.add(EdayunFeeMapper.toDocument(row, ctx.warehouseCode())); + } + return out; + } + // ------------------------------------------------------------------ internals /** 发业务请求(自动取 token、算签名)。 */ diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunFeeMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunFeeMapper.java new file mode 100644 index 0000000..7b207bb --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunFeeMapper.java @@ -0,0 +1,150 @@ +package common.ecommerce.edayun.adapter; + +import common.ecommerce.edayun.dto.EdayunAccountFlowDtos; +import common.ecommerce.shared.support.Money; +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.Instant; +import java.util.ArrayList; +import java.util.List; + +/** + * 易达云交易明细映射({@code POST /webApi/accountFlow/list})。 + * + *

三个口径差异:

+ *
    + *
  • 不按单号去重:同一单号的同一计费项有多条流水,每条都是独立账目
  • + *
  • 金额是 string 且可为负:{@code "-0.500"} 是扣费,正数是充值 / 退费
  • + *
  • 页码必填:文档明确 {@code pageNum} / {@code pageSize} 必填, + * 所以统一模型不做「不传就全量」
  • + *
+ */ +public final class EdayunFeeMapper { + + /** 没给业务单号时,计费时间段必填且不超过 180 天。 */ + static final int MAX_RANGE_DAYS = 180; + + /** 单页上限。 */ + static final int MAX_PAGE_SIZE = 200; + + private EdayunFeeMapper() { + } + + /** + * 统一查询条件 → 交易明细请求。 + * + * @throws IllegalArgumentException 既没有业务单号也没有计费时间窗 + */ + public static EdayunAccountFlowDtos.ListFlowRequest toRequest(FeeQuery query) { + EdayunAccountFlowDtos.ListFlowRequest req = new EdayunAccountFlowDtos.ListFlowRequest(); + + // 业务单号:统一模型里对应 externalOrderNo(仓方单号) + req.bizNo = firstNonBlank(query.externalOrderNo(), query.saleOrderNo()); + + if (query.hasSettledRange()) { + long days = java.time.Duration.between( + query.settledAfter(), query.settledBefore()).toDays(); + if (!hasText(req.bizNo) && days > MAX_RANGE_DAYS) { + throw new IllegalArgumentException( + "edayun account flow query without bizNo requires a range <= 180 days, got " + days); + } + req.beginBillingTime = query.settledAfter().toEpochMilli(); + req.endBillingTime = query.settledBefore().toEpochMilli(); + } else if (!hasText(req.bizNo)) { + throw new IllegalArgumentException( + "edayun account flow query requires a bizNo or a billing time range;" + + " refusing to pull all flows"); + } + + req.pageNum = 1; + req.pageSize = MAX_PAGE_SIZE; + return req; + } + + /** 一条流水 → 统一费用单据。 */ + public static BillingDocument toDocument(EdayunAccountFlowDtos.FlowRow row, String warehouseCode) { + return BillingDocument.builder() + .warehouseCode(warehouseCode) + .sourceProvider(WarehouseProvider.EDAYUN) + .documentNo(row.relateBusinessCode) + .serialNumber(row.serialNumber) + .feeName(row.billingName) + .feeType(feeTypeOf(row.billingCode)) + // 交易明细是已发生账目,不是预估 + .estimated(false) + .settledAt(instantOf(row.billingTime)) + .amount(amountOf(row)) + .accountBalance(moneyOrNull(row.accountBalance, row.accountCurrency)) + .saleOrderNo(firstNonBlank(row.poNumber, row.relateBusinessCode)) + .build(); + } + + /** + * 金额:{@code billingAmount} 是 string,可为负。 + * + *

币种优先用 {@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 warehouseIdList; + } + + /** 查询响应。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ListFlowResponse { + + /** 总条数。 */ + public Long total; + public List rows; + public Integer code; + public String msg; + public String traceId; + } + + /** 一条交易流水。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class FlowRow { + + /** 账户流水号;同一计费项的多条记录靠它区分。 */ + public String serialNumber; + /** 关联业务单号,如 {@code ORD25037232211}。 */ + public String relateBusinessCode; + /** 平台单号。 */ + public String poNumber; + /** 操作类型:0 扣费 / 1 充值 / 2 补扣 / 3 退费 / 4 返利 / 5 还款 / 6 调额。 */ + public Integer operateType; + /** 账户类型:0 预付款 / 1 固定信用 / 2 临时信用。 */ + public Integer accountType; + public Integer businessType; + public String billingName; + /** 计费项编码。 */ + public String billingCode; + /** 原币。 */ + public String originalCurrency; + /** 计费金额;文档标为 string,且可为负数。 */ + public String billingAmount; + /** 账户币种。 */ + public String accountCurrency; + /** 汇率。 */ + public Double exchangeRate; + /** 变动后账户余额。 */ + public Double accountBalance; + /** 计费时间(毫秒)。 */ + public Long billingTime; + /** 服务类型;文档示例出现 -1(全部)。 */ + public Integer serviceType; + /** 计费重量(克)。 */ + public Long billingWeightG; + public String serviceTypeName; + public String operateTypeName; + public String accountTypeName; + public String businessTypeName; + } +} diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunFeeTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunFeeTest.java new file mode 100644 index 0000000..85c424f --- /dev/null +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunFeeTest.java @@ -0,0 +1,174 @@ +package common.ecommerce.edayun.adapter; + +import common.ecommerce.edayun.dto.EdayunAccountFlowDtos; +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 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 POST /webApi/accountFlow/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())); + } +}