Browse Source

feat(edayun): 对接查询交易明细(POST /webApi/accountFlow/list)

三条与其它仓不同的口径,都做了针对性处理:

1. **同一单号的同一计费项有多条流水,不能去重**。
   文档原文说明这一点,所以每条流水映射成一条 BillingDocument,
   靠新增的 serialNumber()(账户流水号)区分。按单号去重会丢账。

2. **金额是 string 且可为负**。billingAmount="-0.500" 是扣费,
   正数是充值 / 退费。用 BigDecimal 解析保留符号,不取绝对值。

3. **币种有两个**:accountCurrency(账户币种,优先)与 originalCurrency
   (原币)。跨币种账户时两者不同,靠 exchangeRate 换算。

统一模型扩展:
- FeeQuery 新增 settledAfter / settledBefore(计费时间窗,毫秒)。
  与已有的 snapshotStartDate(运去哪按仓储费快照查)语义不同,
  Javadoc 写明不要互相替代。
- BillingDocument 新增 serialNumber(流水号)与 accountBalance(变动后余额)。

查询约束在本地校验:
- 没给业务单号时时间段必填,且不能超过 180 天
- pageNum / pageSize 必填,当前固定第 1 页 / 每页 200(上限)
- 超过 200 条的翻页待确认(已记 TODO)

计费项分类按 billingCode 关键字推断,认不出归 null 不猜。

测试 10 个。只跑 edayun 模块:81 个全绿。

Co-Authored-By: Claude <noreply@anthropic.com>
master
chenchuchuan 1 week ago
parent
commit
ad41104cc6
  1. 70
      docs-warehouse/edayun/README.md
  2. 2
      docs-warehouse/edayun/TODO.md
  3. 32
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java
  4. 51
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java
  5. 3
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java
  6. 43
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java
  7. 150
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunFeeMapper.java
  8. 110
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunAccountFlowDtos.java
  9. 174
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunFeeTest.java

70
docs-warehouse/edayun/README.md

@ -13,6 +13,7 @@
| 查询面单 | ✅ 已对接(`POST /webApi/order/v1/getOrderLabel`) | | 查询面单 | ✅ 已对接(`POST /webApi/order/v1/getOrderLabel`) |
| 取消前校验 | ✅ 已对接(`POST /webApi/order/v1/checkCancelStatus`) | | 取消前校验 | ✅ 已对接(`POST /webApi/order/v1/checkCancelStatus`) |
| 取消订单 | ✅ 已对接(`POST /webApi/order/v1/cancelOrder`) | | 取消订单 | ✅ 已对接(`POST /webApi/order/v1/cancelOrder`) |
| 交易明细(费用) | ✅ 已对接(`POST /webApi/accountFlow/list`) |
| 其它业务接口 | ⬜ 等文档 | | 其它业务接口 | ⬜ 等文档 |
| 回调 | ⬜ 等文档 | | 回调 | ⬜ 等文档 |
| 真机验证 | ⬜ 等测试环境 | | 真机验证 | ⬜ 等测试环境 |
@ -277,6 +278,75 @@ POST /webApi/order/v1/cancelOrder → CancelResult
`query`(列表查询)显式抛 `WarehouseUnsupportedCapabilityException`——文档还没给。 `query`(列表查询)显式抛 `WarehouseUnsupportedCapabilityException`——文档还没给。
## 交易明细(费用)
```
POST /webApi/accountFlow/list → List<BillingDocument>
```
### 三条与其它仓不同的口径
**① 同一单号的同一计费项有多条数据——不去重**
文档原文:「同一个单号(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()`(变动后余额)。
## 待确认(问易达云) ## 待确认(问易达云)
| # | 要确认 | | # | 要确认 |

2
docs-warehouse/edayun/TODO.md

@ -11,6 +11,8 @@
| 3 | 业务接口能否用 `openApiAdminSecret` 免签 | 当前一律用 `appSecret` 算 MD5 | 若只有 token 接口免签,现在是正确的 | | 3 | 业务接口能否用 `openApiAdminSecret` 免签 | 当前一律用 `appSecret` 算 MD5 | 若只有 token 接口免签,现在是正确的 |
| 4 | 创建产品同 SKU 重复调用的行为 | 按「创建」语义处理,无更新接口 | 重复建档会报错 | | 4 | 创建产品同 SKU 重复调用的行为 | 按「创建」语义处理,无更新接口 | 重复建档会报错 |
| 5 | 出库单 `getOrderInfo` 的 `carrierInfoList` 是否总与追踪号一一对应 | 按数组原样映射 | 多包裹场景 | | 5 | 出库单 `getOrderInfo` 的 `carrierInfoList` 是否总与追踪号一一对应 | 按数组原样映射 | 多包裹场景 |
| 11 | 交易明细超过 200 条时如何翻页 | 当前只取第一页 | 大账户对账会漏 |
| 12 | `billingCode` 有没有完整字典(现在按关键字推断) | 认不出归 null | 费用分类准确度 |
## 待业务确认 ## 待业务确认

32
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java

@ -42,8 +42,26 @@ public final class BillingDocument {
* 费用只到订单 / 仓粒度。</p> * 费用只到订单 / 仓粒度。</p>
*/ */
private final String providerSku; private final String providerSku;
/** 账户流水号;同一计费项的多条记录靠它区分。 */
public String serialNumber() {
return serialNumber;
}
/** 该笔变动后的账户余额;仓方未给时为 null。 */
public Money accountBalance() {
return accountBalance;
}
/** 关联的销售订单号(仓侧)。 */ /** 关联的销售订单号(仓侧)。 */
private final String saleOrderNo; private final String saleOrderNo;
/**
* 仓方账户流水号。
*
* <p>同一业务单号的同一计费项会有<b>多条</b>流水,靠它区分。</p>
*/
private final String serialNumber;
/** 该笔变动后的账户余额;仓方未给时为 null。 */
private final Money accountBalance;
private BillingDocument(Builder b) { private BillingDocument(Builder b) {
this.warehouseCode = require(b.warehouseCode, "warehouseCode"); this.warehouseCode = require(b.warehouseCode, "warehouseCode");
@ -56,6 +74,8 @@ public final class BillingDocument {
this.amount = java.util.Objects.requireNonNull(b.amount, "amount"); this.amount = java.util.Objects.requireNonNull(b.amount, "amount");
this.providerSku = b.providerSku; this.providerSku = b.providerSku;
this.saleOrderNo = b.saleOrderNo; this.saleOrderNo = b.saleOrderNo;
this.serialNumber = b.serialNumber;
this.accountBalance = b.accountBalance;
} }
public static Builder builder() { public static Builder builder() {
@ -127,6 +147,8 @@ public final class BillingDocument {
private Money amount; private Money amount;
private String providerSku; private String providerSku;
private String saleOrderNo; private String saleOrderNo;
private String serialNumber;
private Money accountBalance;
public Builder warehouseCode(String v) { public Builder warehouseCode(String v) {
this.warehouseCode = v; this.warehouseCode = v;
@ -174,6 +196,16 @@ public final class BillingDocument {
return this; 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) { public Builder saleOrderNo(String v) {
this.saleOrderNo = v; this.saleOrderNo = v;
return this; return this;

51
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 String externalOrderNo;
private final LocalDate snapshotStartDate; private final LocalDate snapshotStartDate;
private final LocalDate snapshotEndDate; private final LocalDate snapshotEndDate;
/**
* 计费时间窗起点(UTC);与 {@link #settledAfter()} 成对。
*
* <p>与 {@link #snapshotStartDate()} 的区别:那个是仓方的「快照日期」
* (运去哪按仓储费快照查),这个是<b>计费时间</b>(易达云按 billingTime 查)。
* 两者语义不同,不要互相替代。</p>
*/
private final java.time.Instant settledAfter;
/** 计费时间窗终点(UTC);与 {@link #settledAfter()} 成对。 */
private final java.time.Instant settledBefore;
private FeeQuery(Builder b) { private FeeQuery(Builder b) {
if (b.snapshotStartDate != null && b.snapshotEndDate != null if (b.snapshotStartDate != null && b.snapshotEndDate != null
@ -37,6 +47,15 @@ public final class FeeQuery {
this.externalOrderNo = b.externalOrderNo; this.externalOrderNo = b.externalOrderNo;
this.snapshotStartDate = b.snapshotStartDate; this.snapshotStartDate = b.snapshotStartDate;
this.snapshotEndDate = b.snapshotEndDate; 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() { public static Builder builder() {
@ -60,6 +79,21 @@ public final class FeeQuery {
return billingTransNo; 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 表示不限制。 */ /** 费用类型;null 表示不限制。 */
public WarehouseFeeType costType() { public WarehouseFeeType costType() {
return costType; return costType;
@ -91,7 +125,8 @@ public final class FeeQuery {
/** 是否给了任何查询条件;全空时适配器应拒绝,避免拉全量。 */ /** 是否给了任何查询条件;全空时适配器应拒绝,避免拉全量。 */
public boolean isEmpty() { public boolean isEmpty() {
return saleOrderNo == null && billingTransNo == null && costType == null return saleOrderNo == null && billingTransNo == null && costType == null
&& providerSku == null && externalOrderNo == null && !hasDateRange(); && providerSku == null && externalOrderNo == null
&& !hasDateRange() && !hasSettledRange();
} }
public static final class Builder { public static final class Builder {
@ -103,6 +138,8 @@ public final class FeeQuery {
private String externalOrderNo; private String externalOrderNo;
private LocalDate snapshotStartDate; private LocalDate snapshotStartDate;
private LocalDate snapshotEndDate; private LocalDate snapshotEndDate;
private java.time.Instant settledAfter;
private java.time.Instant settledBefore;
/** 销售订单号;运去哪要求数字单号({@code providerOrderId}),非来源单号。 */ /** 销售订单号;运去哪要求数字单号({@code providerOrderId}),非来源单号。 */
public Builder saleOrderNo(String v) { public Builder saleOrderNo(String v) {
@ -136,6 +173,18 @@ public final class FeeQuery {
return this; 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() { public FeeQuery build() {
return new FeeQuery(this); return new FeeQuery(this);
} }

3
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})。 */ /** 取消订单({@code POST /webApi/order/v1/cancelOrder})。 */
public static final String PATH_ORDER_CANCEL = "/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"; public static final String ADD_SERVICE_SIGNATURE = "is_signature";

43
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.EdayunConstants;
import common.ecommerce.edayun.auth.EdayunTokenClient; import common.ecommerce.edayun.auth.EdayunTokenClient;
import common.ecommerce.edayun.dto.EdayunCreateOrderDtos; import common.ecommerce.edayun.dto.EdayunCreateOrderDtos;
import common.ecommerce.edayun.dto.EdayunAccountFlowDtos;
import common.ecommerce.edayun.dto.EdayunCancelDtos; import common.ecommerce.edayun.dto.EdayunCancelDtos;
import common.ecommerce.edayun.dto.EdayunCreateProductDtos; import common.ecommerce.edayun.dto.EdayunCreateProductDtos;
import common.ecommerce.edayun.dto.EdayunGetOrderDtos; 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.spi.TokenStore;
import common.ecommerce.shared.support.Page; import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.capability.OutboundCapable; import common.ecommerce.warehouse.capability.OutboundCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeCapable;
import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable; import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.enums.CancelEligibility; 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.WarehouseException;
import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException; import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.model.CancelCommand; import common.ecommerce.warehouse.model.CancelCommand;
import common.ecommerce.warehouse.model.BillingDocument;
import common.ecommerce.warehouse.model.CancelResult; import common.ecommerce.warehouse.model.CancelResult;
import common.ecommerce.warehouse.model.FeeQuery;
import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundOrder; import common.ecommerce.warehouse.model.OutboundOrder;
import common.ecommerce.warehouse.model.OutboundQuery; import common.ecommerce.warehouse.model.OutboundQuery;
@ -40,6 +44,7 @@ import common.ecommerce.warehouse.sdk.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseContext; import common.ecommerce.warehouse.sdk.WarehouseContext;
import java.time.Clock; import java.time.Clock;
import java.util.ArrayList;
import java.util.EnumSet; import java.util.EnumSet;
import java.util.List; import java.util.List;
@ -53,7 +58,7 @@ import java.util.List;
* {@code WarehouseConnection} 传入。</p> * {@code WarehouseConnection} 传入。</p>
*/ */
public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCapable, public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCapable,
OutboundCapable { OutboundCapable, WarehouseFeeCapable {
private final HttpTransport transport; private final HttpTransport transport;
private final JacksonJsonCodec json; private final JacksonJsonCodec json;
@ -103,7 +108,8 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
*/ */
@Override @Override
public EnumSet<WarehouseCapability> capabilities() { public EnumSet<WarehouseCapability> 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(); return v != null && !v.trim().isEmpty();
} }
// ------------------------------------------------------------------ 费用
/**
* 查询交易明细({@code POST /webApi/accountFlow/list})。
*
* <p>文档说明「同一个单号的某个计费项有多条数据」,所以<b>不做去重</b>,
* 每条流水都映射成一条 {@link BillingDocument},靠 {@code serialNumber} 区分。</p>
*
* <p>分页:文档要求 {@code pageNum} / {@code pageSize} 必填,当前只取第一页
* (200 条);超过时截断——<b>待确认是否需要翻页</b>。</p>
*/
@Override
public List<BillingDocument> 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<BillingDocument> out = new ArrayList<BillingDocument>(parsed.rows.size());
for (EdayunAccountFlowDtos.FlowRow row : parsed.rows) {
out.add(EdayunFeeMapper.toDocument(row, ctx.warehouseCode()));
}
return out;
}
// ------------------------------------------------------------------ internals // ------------------------------------------------------------------ internals
/** 发业务请求(自动取 token、算签名)。 */ /** 发业务请求(自动取 token、算签名)。 */

150
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})。
*
* <p>三个口径差异:</p>
* <ul>
* <li><b>不按单号去重</b>:同一单号的同一计费项有多条流水,每条都是独立账目</li>
* <li><b>金额是 string 且可为负</b>:{@code "-0.500"} 是扣费,正数是充值 / 退费</li>
* <li><b>页码必填</b>:文档明确 {@code pageNum} / {@code pageSize} 必填,
* 所以统一模型不做「不传就全量」</li>
* </ul>
*/
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,可为负。
*
* <p>币种优先用 {@code accountCurrency}(账户币种),缺失才退回
* {@code originalCurrency}。两者可能不同——跨币种账户会有汇率。</p>
*/
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);
}
/**
* 计费项编码 → 业务语义。
*
* <p>易达云用编码(如 {@code farawayFee})而不是分类码,所以只能按关键字推断;
* <b>认不出返回 null</b>,不猜——对账时宁可不分类,也不能分类错。</p>
*/
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();
}
}

110
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})。
*
* <p>一个文件对应一个接口,只放该接口的请求 / 响应与内嵌子结构。</p>
*
* <p><b>注意</b>:原文说明「同一个单号(ORD-发货单 / REV-收货单)的某个计费项
* 有多条数据」——所以不能按单号去重,每条流水都是独立的账目,靠
* {@code serialNumber} 区分。</p>
*/
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;
/**
* 计费时间起点(毫秒)。
*
* <p><b>约束</b>:没给业务单号时时间段必填,且区间不能超过 180 天。</p>
*/
public Long beginBillingTime;
/** 计费时间终点(毫秒)。 */
public Long endBillingTime;
/** 页码,从 1 开始。<b>必填</b>。 */
public Integer pageNum;
/** 每页条数,最大 200。<b>必填</b>。 */
public Integer pageSize;
/** 费收类型:0 标准(默认)/ 1 非标准。 */
public Integer expenseType;
/** 仓库 id 列表。 */
public List<Integer> warehouseIdList;
}
/** 查询响应。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ListFlowResponse {
/** 总条数。 */
public Long total;
public List<FlowRow> 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;
/** 计费金额;<b>文档标为 string</b>,且可为负数。 */
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;
}
}

174
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})映射。
*
* <p>重点:不按单号去重、金额是 string 可为负、无业务单号时时间段必填且 ≤180 天。</p>
*/
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()));
}
}
Loading…
Cancel
Save