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()));
+ }
+}