You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

267 lines
12 KiB

feat(hengjian): 对接运费测算与地址属性识别 两个接口都在 /v2/api/shipping 下,真机均确认可用(无 token 时的 参数校验响应与 404 对照组可区分)。 运费测算 /v2/api/shipping/calculate - 真机确认必填项是包裹四项 + 两个单位 + 收货方五项;文档标必填的 shipper* 系列实际可不传 - 单位 cm/g 与统一模型一致,不换算 - 包裹尺寸在恒健是 INTEGER,厘米值四舍五入(截断会让报价偏低) - totalRate 取 conversionTotalRate(折算价 / 客户实付), 不取 originalTotalRate(承运商牌价) - 恒健不按仓返回,统一结果只有一个实例,仓编码用账户仓填充 地址属性 /v2/api/shipping/addressClassification - 新增能力位 ADDRESS_CLASSIFICATION + AddressClassificationCapable + core 枚举 AddressType(BUSINESS/RESIDENTIAL/MIXED/UNKNOWN) - 真机确认 street1/zip/city/state/country 五项必填,本地先挡 - 认不出归 UNKNOWN 不猜;MIXED 在 residential() 里按住宅计 - 文档域名写的是 open-api.thebizark.com(别家),真机确认本仓域名可用 顺带修 core 缺陷:FeeEstimateQuery.logisticsServiceCode 原为构造期必填, 而恒健允许不传(由仓报全部渠道)。改为选填,并新增 hasLogisticsServiceCode(); 运去哪要求必填,改为在它的 mapper 里校验,不影响既有行为。 验证:mvn test 全量通过,恒健 180 个用例(+14)通过。 Co-Authored-By: Claude Code <noreply@anthropic.com>
5 days ago
package common.ecommerce.hengjian.adapter;
import common.ecommerce.hengjian.HengjianConstants;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.AddressType;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.FeeEstimateQuery;
import common.ecommerce.warehouse.model.FeeEstimateResult;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import org.junit.jupiter.api.Test;
import java.math.BigDecimal;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 运费测算({@code /v2/api/shipping/calculate})与地址属性
* ({@code /v2/api/shipping/addressClassification})契约测试。
*/
class HengjianEstimateTest {
private static final WarehouseContext CTX = WarehouseContext.of(
"HJ-EFCA", WarehouseProvider.HENGJIAN, "EFCA",
WarehouseConnection.of(HengjianConstants.TEST_BASE_URL,
ChannelSecret.builder().appSecret("token-1").build()),
"req-1", java.time.Clock.fixed(java.time.Instant.parse("2026-11-16T00:00:00Z"),
java.time.ZoneOffset.UTC));
private static HengjianAdapter adapter(RecordingTransport transport) {
return new HengjianAdapter(transport, new JacksonJsonCodec());
}
private static FeeEstimateQuery.Builder query() {
return FeeEstimateQuery.builder()
.lengthCm(new BigDecimal("10.4"))
.widthCm(new BigDecimal("10.6"))
.heightCm(new BigDecimal("9.4"))
.weightGrams(new BigDecimal("500"))
.receiveCountry("US")
.receiveState("CA")
.receiveCity("Los Angeles")
.receivePostal("90001")
.receiveAddress("1 Main St");
}
// ================================================================ 测算请求
private static final String ESTIMATE_BODY =
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"success\",\"data\":["
+ "{\"carrier\":\"FedEx\",\"logisticServiceCode\":\"FEDHD_HL\","
+ "\"serviceCode\":\"FEDHD\",\"conversionTotalRate\":18.38,"
+ "\"originalTotalRate\":36.76,\"currency\":\"USD\",\"isResidential\":1,"
+ "\"costItems\":[{\"costName\":\"Basic Rate\",\"estimatedCost\":9.38,"
+ "\"currency\":\"USD\",\"errorMsg\":null},"
+ "{\"costName\":\"Fuel Surcharge\",\"estimatedCost\":3.06,"
+ "\"currency\":\"USD\",\"errorMsg\":\"\"}]}]}";
private static RecordingTransport estimating() {
return RecordingTransport.create()
.route(HengjianConstants.PATH_FEE_ESTIMATE, req -> Responses.ok(ESTIMATE_BODY));
}
@Test
void estimatePostsToCalculate() {
RecordingTransport transport = estimating();
adapter(transport).estimate(CTX, query().build());
assertEquals("POST", transport.lastDataRequest().method());
assertEquals(HengjianConstants.TEST_BASE_URL + "/v2/api/shipping/calculate",
transport.lastDataRequest().url());
}
/** 真机确认的必填项都要出现;shipper* 不必传。 */
@Test
void estimateSendsMandatoryFields() {
RecordingTransport transport = estimating();
adapter(transport).estimate(CTX, query().build());
String body = transport.lastDataRequest().body();
String[] mandatory = {"parcelLength", "parcelWidth", "parcelHeight", "parcelWeight",
"parcelLengthUnit", "parcelWeightUnit", "receiverCountryCode", "receiverState",
"receiverCity", "receiverZipcode", "receiverAddressLine1"};
for (String field : mandatory) {
assertTrue(body.contains("\"" + field + "\""), "缺少必填字段 " + field + ",body=" + body);
}
// 真机校验信息里没有 shipper*,不发
assertFalse(body.contains("shipper"), body);
}
/** 单位直接用 cm / g,不做换算。 */
@Test
void estimateUsesCmAndGramsWithoutConversion() {
RecordingTransport transport = estimating();
adapter(transport).estimate(CTX, query().build());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"parcelLengthUnit\":\"cm\""), body);
assertTrue(body.contains("\"parcelWeightUnit\":\"g\""), body);
assertTrue(body.contains("\"parcelWeight\":500.0"), body);
}
/** 恒健的包裹尺寸是 INTEGER:四舍五入,不截断(截断会让报价偏低)。 */
@Test
void estimateRoundsDimensionsHalfUp() {
RecordingTransport transport = estimating();
adapter(transport).estimate(CTX, query().build());
String body = transport.lastDataRequest().body();
// 10.4 -> 10, 10.6 -> 11, 9.4 -> 9
assertTrue(body.contains("\"parcelLength\":10"), body);
assertTrue(body.contains("\"parcelWidth\":11"), body);
assertTrue(body.contains("\"parcelHeight\":9"), body);
}
/** 物流服务码是选填:不给也能调(由仓报全部渠道)。 */
@Test
void estimateWorksWithoutServiceCode() {
RecordingTransport transport = estimating();
adapter(transport).estimate(CTX, query().build());
String body = transport.lastDataRequest().body();
assertFalse(body.contains("serviceCode\""), body);
assertFalse(body.contains("\"carrier\""), body);
}
@Test
void estimateSendsServiceCodeWhenGiven() {
RecordingTransport transport = estimating();
adapter(transport).estimate(CTX, query()
.logisticsServiceCode("FEDHD").logisticsProductCode("FedEx").build());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"serviceCode\":\"FEDHD\""), body);
assertTrue(body.contains("\"carrier\":\"FedEx\""), body);
}
// ================================================================ 测算结果
@Test
void estimateMapsQuote() {
List<FeeEstimateResult> results = adapter(estimating()).estimate(CTX, query().build());
assertEquals(1, results.size(), "恒健不按仓维度返回,只有一个结果");
FeeEstimateResult result = results.get(0);
assertEquals(WarehouseProvider.HENGJIAN, result.sourceProvider());
assertEquals("EFCA", result.shipOrgWarehouseCode());
assertEquals(1, result.carriers().size());
FeeEstimateResult.CarrierQuote quote = result.carriers().get(0);
assertEquals("FedEx", quote.carrier());
// 优先用 logisticServiceCode(响应示例里那才是下单用的服务码)
assertEquals("FEDHD_HL", quote.logisticsServiceCode());
// 折算价(客户实付),不是官方牌价 36.76
assertEquals(18.38, quote.totalRate().amount().doubleValue(), 0.0001);
assertEquals("USD", quote.totalRate().currency().getCurrencyCode());
assertEquals(2, quote.costItems().size());
assertEquals("Fuel Surcharge", quote.costItems().get(1).costName());
assertEquals(3.06, quote.costItems().get(1).estimatedCost().amount().doubleValue(), 0.0001);
}
/** 没有报价时不抛,返回一个渠道为空的仓级结果。 */
@Test
void estimateEmptyQuotesIsNotAnError() {
RecordingTransport transport = RecordingTransport.create()
.route(HengjianConstants.PATH_FEE_ESTIMATE, req -> Responses.ok(
"{\"code\":200,\"message\":\"success\",\"data\":[]}"));
List<FeeEstimateResult> results = adapter(transport).estimate(CTX, query().build());
assertEquals(1, results.size());
assertTrue(results.get(0).carriers().isEmpty());
}
// ================================================================ 地址属性
private static RecordingTransport classifying(String data) {
return RecordingTransport.create()
.route(HengjianConstants.PATH_ADDRESS_CLASSIFICATION, req -> Responses.ok(
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"success\","
+ "\"data\":\"" + data + "\"}"));
}
@Test
void classifyPostsToAddressClassification() {
RecordingTransport transport = classifying("BUSINESS");
adapter(transport).classifyAddress(CTX, "1 Main St", null, "LA", "CA", "90001", "US");
assertEquals("POST", transport.lastDataRequest().method());
assertEquals(HengjianConstants.TEST_BASE_URL + "/v2/api/shipping/addressClassification",
transport.lastDataRequest().url());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"street1\":\"1 Main St\""), body);
assertTrue(body.contains("\"zip\":\"90001\""), body);
assertTrue(body.contains("\"country\":\"US\""), body);
// street2 没给就不发
assertFalse(body.contains("street2"), body);
}
/** 文档里的四个值都要映射对;认不出归 UNKNOWN。 */
@Test
void classifiesAllDocumentedValues() {
assertEquals(AddressType.BUSINESS, classifyAs("BUSINESS"));
assertEquals(AddressType.RESIDENTIAL, classifyAs("RESIDENTIAL"));
assertEquals(AddressType.MIXED, classifyAs("MIXED"));
assertEquals(AddressType.UNKNOWN, classifyAs("UNKNOWN"));
}
/** 仓方将来加新值:不猜,归 UNKNOWN。 */
@Test
void unknownValueIsNotGuessed() {
assertEquals(AddressType.UNKNOWN, classifyAs("SOMETHING_NEW"));
// 大小写不敏感,但只认文档里那四个
assertEquals(AddressType.BUSINESS, classifyAs("business"));
}
/** 住宅附加费按 RESIDENTIAL 与 MIXED 计。 */
@Test
void mixedCountsAsResidential() {
assertTrue(AddressType.RESIDENTIAL.residential());
assertTrue(AddressType.MIXED.residential());
assertFalse(AddressType.BUSINESS.residential());
assertFalse(AddressType.UNKNOWN.residential());
}
/** 真机确认五项必填:缺哪个报哪个,不发出去被仓方挡回来。 */
@Test
void classifyRejectsMissingRequiredParts() {
RecordingTransport transport = classifying("BUSINESS");
HengjianAdapter adapter = adapter(transport);
assertThrows(IllegalArgumentException.class,
() -> adapter.classifyAddress(CTX, null, null, "LA", "CA", "90001", "US"));
assertThrows(IllegalArgumentException.class,
() -> adapter.classifyAddress(CTX, "1 St", null, null, "CA", "90001", "US"));
assertThrows(IllegalArgumentException.class,
() -> adapter.classifyAddress(CTX, "1 St", null, "LA", null, "90001", "US"));
assertThrows(IllegalArgumentException.class,
() -> adapter.classifyAddress(CTX, "1 St", null, "LA", "CA", null, "US"));
assertThrows(IllegalArgumentException.class,
() -> adapter.classifyAddress(CTX, "1 St", null, "LA", "CA", "90001", null));
assertTrue(transport.dataRequests().isEmpty(), "本地校验失败不应发请求");
}
private static AddressType classifyAs(String raw) {
return adapter(classifying(raw)).classifyAddress(CTX, "1 St", null, "LA", "CA", "90001", "US");
}
// ================================================================ 能力位
@Test
void declaresEstimateAndAddressCapabilities() {
HengjianAdapter adapter = adapter(RecordingTransport.create());
assertTrue(adapter.capabilities().contains(WarehouseCapability.FEE_ESTIMATE));
assertTrue(adapter.capabilities().contains(WarehouseCapability.ADDRESS_CLASSIFICATION));
}
}