Browse Source

feat(edayun): 对接查询订单费用明细

POST /webApi/order/cost/v1/selectOrderCostInfoList → List<BillingDocument>

与交易明细(accountFlow/list)是两回事:
- 交易明细 = 账户流水,带余额,金额为负表示扣费
- 订单费用 = 按订单拆的报价,带应收/折扣/实付与计费重、分区

三处关键口径:

1. **金额取实付**(realPayPrice = 应收 - 折扣)。应收只是报价,
   对账要以实际发生为准。三个金额都保留在 DTO 里。

2. **一个订单展开成多条**。响应是 rows → chargeDetails → feeDetails,
   按计费项展开,多条记录 documentNo 相同、靠 feeName 区分。
   只有汇总没有 feeDetails 时按汇总记一条。

3. **单号类型要配合**(type: 0 订单号 / 1 平台单号 / 2 追踪号)。
   统一模型新增 FeeQueryNoType 枚举与 FeeQuery.noType(),
   不支持的类型显式拒绝——静默按别的口径查会让对账金额对不上。

时间窗 ≤3 个月(文档约束),无单号且无时间窗时本地拒绝。

能力接口新增 WarehouseFeeCapable.orderCosts(默认抛不支持),
门面 fees().orderCosts(query)。

顺带补 BillingDocument 里遗漏的 serialNumber() / accountBalance() getter
(上一提交只加了字段没加 getter,测试编译不过)。

测试 12 个。只跑 edayun 模块:93 个全绿;yqn / xincang 未受影响。

Co-Authored-By: Claude <noreply@anthropic.com>
master
chenchuchuan 1 week ago
parent
commit
fbf2363c06
  1. 70
      docs-warehouse/edayun/README.md
  2. 1
      docs-warehouse/edayun/TODO.md
  3. 16
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseFeeCapable.java
  4. 46
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/FeeQueryNoType.java
  5. 20
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java
  6. 21
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java
  7. 16
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  8. 3
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java
  9. 32
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java
  10. 205
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderCostMapper.java
  11. 151
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunOrderCostDtos.java
  12. 197
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunOrderCostTest.java

70
docs-warehouse/edayun/README.md

@ -13,7 +13,8 @@ @@ -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> @@ -347,6 +348,73 @@ POST /webApi/accountFlow/list → List<BillingDocument>
`BillingDocument` 新增 `serialNumber()`(流水号)与 `accountBalance()`(变动后余额)。
## 订单费用明细
```
POST /webApi/order/cost/v1/selectOrderCostInfoList → List<BillingDocument>
```
**与交易明细的区别**(两个都是费用,但口径完全不同):
| | 交易明细 `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(不猜) |
## 待确认(问易达云)
| # | 要确认 |

1
docs-warehouse/edayun/TODO.md

@ -13,6 +13,7 @@ @@ -13,6 +13,7 @@
| 5 | 出库单 `getOrderInfo` 的 `carrierInfoList` 是否总与追踪号一一对应 | 按数组原样映射 | 多包裹场景 |
| 11 | 交易明细超过 200 条时如何翻页 | 当前只取第一页 | 大账户对账会漏 |
| 12 | `billingCode` 有没有完整字典(现在按关键字推断) | 认不出归 null | 费用分类准确度 |
| 13 | 订单费用明细的 `billingId` 能否作为幂等键 | 当前未用作主键 | 重复拉取去重 |
## 待业务确认

16
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseFeeCapable.java

@ -28,4 +28,20 @@ public interface WarehouseFeeCapable extends WarehouseAdapter { @@ -28,4 +28,20 @@ public interface WarehouseFeeCapable extends WarehouseAdapter {
* 仓不支持该查询维度
*/
List<BillingDocument> settlements(WarehouseContext ctx, FeeQuery query);
/**
* 按订单维度拉取费用拆分(应收 / 折扣 / 实付)。
*
* <p>与 {@link #settlements} 的区别:那个是<b>账户流水</b>(充值 / 扣费 / 退费),
* 这个是<b>单个订单的费用明细</b>,带计费重、计费分区、逐计费项的折扣。</p>
*
* <p>默认不支持——只有提供该接口的仓才覆盖。</p>
*
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
* 该仓不提供按订单的费用明细
*/
default List<BillingDocument> orderCosts(WarehouseContext ctx, FeeQuery query) {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
common.ecommerce.warehouse.enums.WarehouseCapability.FEE_SETTLEMENT);
}
}

46
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/FeeQueryNoType.java

@ -0,0 +1,46 @@ @@ -0,0 +1,46 @@
package common.ecommerce.warehouse.enums;
/**
* 费用查询时「业务单号」的类型。
*
* <p>有的仓要求明确告诉它这个单号是哪种(易达云的 {@code type}:
* 0 订单号 / 1 平台单号 / 2 追踪号),有的仓只有一种查法。统一成枚举,
* 不支持的取值由适配器<b>显式拒绝</b>——静默按别的口径查会让对账金额对不上。</p>
*/
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;
}
}

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

@ -42,16 +42,6 @@ public final class BillingDocument { @@ -42,16 +42,6 @@ public final class BillingDocument {
* 费用只到订单 / 仓粒度。</p>
*/
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 { @@ -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;
}

21
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java

@ -30,6 +30,14 @@ public final class FeeQuery { @@ -30,6 +30,14 @@ public final class FeeQuery {
private final java.time.Instant settledAfter;
/** 计费时间窗终点(UTC);与 {@link #settledAfter()} 成对。 */
private final java.time.Instant settledBefore;
/**
* 业务单号的类型;null 表示由适配器按自己的默认口径解释。
*
* <p>有的仓要求明确「这个单号是订单号、平台单号还是追踪号」
* (易达云的 {@code type}),有的仓只有一种查法。用统一枚举表达,
* 适配器不支持的类型要显式拒绝。</p>
*/
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 { @@ -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 { @@ -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 { @@ -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 { @@ -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);
}

16
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java

@ -605,6 +605,22 @@ public final class WarehouseOperations { @@ -605,6 +605,22 @@ public final class WarehouseOperations {
() -> ((WarehouseChannelRecommendCapable) adapter).recommend(ctx, query));
}
/**
* 按订单维度拉取费用拆分(应收 / 折扣 / 实付)。
*
* <p>与 {@link #settlements} 不同:那个是账户流水,这个是单订单的费用明细。
* 只读,不走幂等。</p>
*/
public List<BillingDocument> 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<BillingDocument> settlements(FeeQuery query) {
require(WarehouseCapability.FEE_SETTLEMENT, WarehouseFeeCapable.class);

3
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java

@ -54,6 +54,9 @@ public final class EdayunConstants { @@ -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";

32
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java

@ -8,6 +8,7 @@ import common.ecommerce.edayun.dto.EdayunCancelDtos; @@ -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 @@ -393,6 +394,37 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
return out;
}
/**
* 查询订单费用明细
* ({@code POST /webApi/order/cost/v1/selectOrderCostInfoList})。
*
* <p>与 {@link #settlements}(账户流水)不同:这个按订单拆费用,
* 带应收 / 折扣 / 实付与计费重。落库金额取<b>实付</b>。
*
* <p>一个订单可能展开成多条 {@link BillingDocument}(逐计费项)。</p>
*/
@Override
public List<BillingDocument> 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<BillingDocument> out = new ArrayList<BillingDocument>();
for (EdayunOrderCostDtos.OrderCostRow row : parsed.rows) {
out.addAll(EdayunOrderCostMapper.toDocuments(row, ctx.warehouseCode()));
}
return out;
}
// ------------------------------------------------------------------ internals
/** 发业务请求(自动取 token、算签名)。 */

205
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderCostMapper.java

@ -0,0 +1,205 @@ @@ -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})。
*
* <p>与交易明细({@code accountFlow/list})的区别:</p>
* <ul>
* <li>交易明细 = 账户流水,带账户余额,金额为负表示扣费</li>
* <li>订单费用 = 按订单拆的报价,带<b>应收 / 折扣 / 实付</b>三个金额与计费重</li>
* </ul>
*
* <p>金额口径:{@code realPayPrice} 是实付(应收 - 折扣),
* 落到 {@link BillingDocument#amount()} 的是<b>实付</b>——对账要以实际发生为准。</p>
*/
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}。
*
* <p>不支持的取值<b>显式拒绝</b>:静默按别的口径查会让对账金额对不上。</p>
*/
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}。
*
* <p>一层里可能有多个 {@code chargeDetails},每个下面又有多个 {@code feeDetails}。
* 这里按<b>计费项</b>展开:每个 feeDetail 一条记录,对账才能落到具体费用项。</p>
*
* <p>如果没有 {@code feeDetails} 但有 {@code chargeDetails} 汇总,就按汇总记一条。</p>
*/
public static List<BillingDocument> toDocuments(EdayunOrderCostDtos.OrderCostRow row,
String warehouseCode) {
List<BillingDocument> out = new ArrayList<BillingDocument>();
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));
}
/**
* 按计费项名称归类。
*
* <p>易达云的名称是中文(如「尾程-出库处理费」),按关键字推断;
* 认不出返回 null,不猜——对账时宁可不分类,也不能分错。</p>
*/
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();
}
}

151
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunOrderCostDtos.java

@ -0,0 +1,151 @@ @@ -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})。
*
* <p>一个文件对应一个接口,只放该接口的请求 / 响应与内嵌子结构。</p>
*
* <p>与「交易明细」({@code accountFlow/list})的区别:那个是<b>账户流水</b>
* (充值 / 扣费 / 退费,带账户余额),这个是<b>按订单的费用拆分</b>
* (应收 / 折扣 / 实付,带计费重与分区)。</p>
*/
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;
/** 计费时间开始(毫秒);<b>最大查询 3 个月</b>。 */
public Long beginBillingTime;
/** 计费时间结束(毫秒)。 */
public Long endBillingTime;
}
/** 查询响应。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class SelectOrderCostResponse {
public Long total;
public List<OrderCostRow> 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<ChargeDetail> 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<FeeDetail> 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;
}
}

197
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunOrderCostTest.java

@ -0,0 +1,197 @@ @@ -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})映射。
*
* <p>重点:金额取<b>实付</b>、按计费项展开成多条、单号类型要配合、时间窗 ≤3 个月。</p>
*/
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<BillingDocument> docs = EdayunOrderCostMapper.toDocuments(twoFeeRow(), "EDY-WH");
assertEquals(2, docs.size());
assertEquals("尾程-运费", docs.get(0).feeName());
assertEquals("尾程-出库处理费", docs.get(1).feeName());
}
/** 落库金额取实付(应收 - 折扣),不是应收。 */
@Test
void amountIsRealPayNotReceivable() {
List<BillingDocument> 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<BillingDocument> 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<BillingDocument> 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<BillingDocument> docs = EdayunOrderCostMapper.toDocuments(row, "W");
assertEquals(1, docs.size());
assertEquals(BigDecimal.ZERO, docs.get(0).amount().amount());
}
/** 一个订单的多个 feeDetail 都挂同一个 documentNo,靠 feeName 区分。 */
@Test
void documentsShareOrderNumberButDifferByFeeName() {
List<BillingDocument> docs = EdayunOrderCostMapper.toDocuments(twoFeeRow(), "W");
assertEquals(docs.get(0).documentNo(), docs.get(1).documentNo());
assertTrue(!docs.get(0).feeName().equals(docs.get(1).feeName()));
}
}
Loading…
Cancel
Save