Browse Source
三条与其它仓不同的口径,都做了针对性处理: 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
9 changed files with 632 additions and 3 deletions
@ -0,0 +1,150 @@
@@ -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(); |
||||
} |
||||
} |
||||
@ -0,0 +1,110 @@
@@ -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; |
||||
} |
||||
} |
||||
@ -0,0 +1,174 @@
@@ -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…
Reference in new issue