diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/BolCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/BolCapable.java new file mode 100644 index 0000000..a14e13e --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/BolCapable.java @@ -0,0 +1,33 @@ +package common.ecommerce.warehouse.capability; + +import common.ecommerce.warehouse.model.BolDocument; +import common.ecommerce.warehouse.sdk.WarehouseAdapter; +import common.ecommerce.warehouse.sdk.WarehouseContext; + +import java.util.List; + +/** + * BOL(提单 / 提货凭证)查询能力。 + * + *
与 {@link InboundCapable#bols} 不是一回事:那个是头程入库计划单的 BOL
+ * 文件地址({@code List
只读能力,不声明 {@code WarehouseCapability.BOL} 的仓默认拒绝。
+ */ +public interface BolCapable extends WarehouseAdapter { + + /** + * 查某张订单的 BOL 清单。 + * + *方法名带 {@code order} 前缀:{@link InboundCapable} 已有同签名的
+ * {@code bols(ctx, String)}(返回 {@code List
与 {@link WarehouseAttachment} 的区别:附件只是「名字 + 类型 + URL」, + * BOL 还带提货状态、约定 / 实际提货量、POD 签收凭证,是独立的业务单据。
+ * + *SDK 不落文件、不访问对象存储:所有 URL 原样给出,下载由宿主负责。
+ */ +public final class BolDocument { + + /** 仓方 BOL 编号。 */ + private final String bolCode; + /** BOL 文件地址。 */ + private final String fileUrl; + /** 签收后的 BOL(带签章)地址;未签收为 null。 */ + private final String signedFileUrl; + /** POD(签收凭证)地址;未妥投为 null。 */ + private final String podFileUrl; + /** POD 上传时间(UTC)。 */ + private final Instant podUploadedAt; + + /** 仓方状态码原值;语义由适配器解释。 */ + private final Integer rawStatus; + /** 状态中文名原值。 */ + private final String statusName; + + /** 约定提货日期(仓方原值,可能是日期字符串或时间戳)。 */ + private final String scheduledPickupDate; + /** 实际提货日期(仓方原值)。 */ + private final String actualPickupDate; + /** 约定提货件数。 */ + private final Integer scheduledPickupQuantity; + /** 实际提货件数。 */ + private final Integer actualPickupQuantity; + + /** 卡车公司。 */ + private final String truckCompany; + /** 跟踪号;卡车单可能是 BOL 号。 */ + private final String trackingNo; + + private BolDocument(Builder b) { + this.bolCode = require(b.bolCode, "bolCode"); + this.fileUrl = b.fileUrl; + this.signedFileUrl = b.signedFileUrl; + this.podFileUrl = b.podFileUrl; + this.podUploadedAt = b.podUploadedAt; + this.rawStatus = b.rawStatus; + this.statusName = b.statusName; + this.scheduledPickupDate = b.scheduledPickupDate; + this.actualPickupDate = b.actualPickupDate; + this.scheduledPickupQuantity = b.scheduledPickupQuantity; + this.actualPickupQuantity = b.actualPickupQuantity; + this.truckCompany = b.truckCompany; + this.trackingNo = b.trackingNo; + } + + public static Builder builder() { + return new Builder(); + } + + /** 仓方 BOL 编号。 */ + public String bolCode() { + return bolCode; + } + + public String fileUrl() { + return fileUrl; + } + + /** 签收后的 BOL 地址;未签收为 null。 */ + public String signedFileUrl() { + return signedFileUrl; + } + + /** POD 签收凭证地址;未妥投为 null。 */ + public String podFileUrl() { + return podFileUrl; + } + + public Instant podUploadedAt() { + return podUploadedAt; + } + + /** 仓方状态码原值。 */ + public Integer rawStatus() { + return rawStatus; + } + + /** 仓方状态名原值。 */ + public String statusName() { + return statusName; + } + + /** 约定提货日期(仓方原值)。 */ + public String scheduledPickupDate() { + return scheduledPickupDate; + } + + /** 实际提货日期(仓方原值)。 */ + public String actualPickupDate() { + return actualPickupDate; + } + + public Integer scheduledPickupQuantity() { + return scheduledPickupQuantity; + } + + public Integer actualPickupQuantity() { + return actualPickupQuantity; + } + + public String truckCompany() { + return truckCompany; + } + + public String trackingNo() { + return trackingNo; + } + + private static String require(String v, String name) { + if (v == null || v.trim().isEmpty()) { + throw new IllegalArgumentException(name + " must not be blank"); + } + return v.trim(); + } + + public static final class Builder { + private String bolCode; + private String fileUrl; + private String signedFileUrl; + private String podFileUrl; + private Instant podUploadedAt; + private Integer rawStatus; + private String statusName; + private String scheduledPickupDate; + private String actualPickupDate; + private Integer scheduledPickupQuantity; + private Integer actualPickupQuantity; + private String truckCompany; + private String trackingNo; + + public Builder bolCode(String v) { + this.bolCode = v; + return this; + } + + public Builder fileUrl(String v) { + this.fileUrl = v; + return this; + } + + public Builder signedFileUrl(String v) { + this.signedFileUrl = v; + return this; + } + + public Builder podFileUrl(String v) { + this.podFileUrl = v; + return this; + } + + public Builder podUploadedAt(Instant v) { + this.podUploadedAt = v; + return this; + } + + public Builder rawStatus(Integer v) { + this.rawStatus = v; + return this; + } + + public Builder statusName(String v) { + this.statusName = v; + return this; + } + + public Builder scheduledPickupDate(String v) { + this.scheduledPickupDate = v; + return this; + } + + public Builder actualPickupDate(String v) { + this.actualPickupDate = v; + return this; + } + + public Builder scheduledPickupQuantity(Integer v) { + this.scheduledPickupQuantity = v; + return this; + } + + public Builder actualPickupQuantity(Integer v) { + this.actualPickupQuantity = v; + return this; + } + + public Builder truckCompany(String v) { + this.truckCompany = v; + return this; + } + + public Builder trackingNo(String v) { + this.trackingNo = v; + return this; + } + + public BolDocument build() { + Objects.requireNonNull(bolCode, "bolCode"); + return new BolDocument(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 4afdb7f..c5d803b 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 @@ -4,6 +4,7 @@ import common.ecommerce.shared.audit.CallObserver; import common.ecommerce.shared.audit.CallSupport; import common.ecommerce.shared.idempotency.IdempotencyGuard; import common.ecommerce.shared.support.Page; +import common.ecommerce.warehouse.capability.BolCapable; import common.ecommerce.warehouse.capability.DestructionCapable; import common.ecommerce.warehouse.capability.InboundCapable; import common.ecommerce.warehouse.capability.InventoryCapable; @@ -323,6 +324,21 @@ public final class WarehouseOperations { () -> ((LogisticsProductCapable) adapter).products(ctx, warehouseCode)); } + /** + * 查平台仓订单 / 店铺订单的 BOL(提单 / 提货凭证)。 + * + *与 {@code inbound().bols()} 不同:那个是入库计划单的 BOL 文件地址, + * 这个带提货状态与 POD。只读,不走幂等。
+ * + * @param providerOrderNo 仓方(或平台仓)订单号 + */ + public List店铺订单与平台仓订单共用,{@code orderNo} 传 EDA 的平台仓订单号 + * (如 {@code FBA473182144})。没有 BOL 时返回空列表,不是错误。
+ */ + @Override + public List只是字段搬运 + 时间戳转换;状态码表只有 {@code 11=已妥投} 确认, + * 其余靠 {@code statusName} 中文名兜底。
+ */ +public final class EdayunBolMapper { + + private EdayunBolMapper() { + } + + /** 查询请求。 */ + public static EdayunBolDtos.GetBolRequest toRequest(String orderNo) { + if (orderNo == null || orderNo.trim().isEmpty()) { + throw new IllegalArgumentException("edayun needs an orderNo to query BOL list"); + } + EdayunBolDtos.GetBolRequest req = new EdayunBolDtos.GetBolRequest(); + req.orderNo = orderNo.trim(); + return req; + } + + /** 响应 → BOL 列表;没有 BOL 时返回空列表。 */ + public static List一个文件对应一个接口,只放该请求 / 响应与内嵌子结构。
+ * + *店铺订单 / 平台仓订单共用本接口,{@code orderNo} 传 EDA 的平台仓订单号。
+ */ +public final class EdayunBolDtos { + + private EdayunBolDtos() { + } + + /** 查询请求。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class GetBolRequest { + /** EDA 的平台仓订单号,如 {@code FBA473182144}。必填。 */ + public String orderNo; + } + + /** 查询响应。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class GetBolResponse { + public Integer code; + public String msg; + public BolData data; + public String traceId; + } + + /** BOL 数据。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class BolData { + /** BOL 总数。 */ + public Integer totalNum; + /** 未提货数。 */ + public Integer unPickupNum; + public List只有一个码值是文档确认的:{@code 11 = 已妥投}(文档响应示例)。 + * 完整码表易达云没给,所以其余状态只按 {@code statusName} 中文名兜底, + * 认不出就把原值透出({@link BolState#UNKNOWN})——不猜。
+ */ +public enum EdayunBolStatus { + + /** 11 已妥投(文档示例)。 */ + DELIVERED(11, BolState.DELIVERED), + /** 无法识别。 */ + UNKNOWN(null, BolState.UNKNOWN); + + /** 归一化的提货状态;只区分宿主真正会分支处理的几档。 */ + public enum BolState { + /** 未提货。 */ + PENDING_PICKUP, + /** 已提货 / 运输中。 */ + PICKED_UP, + /** 已妥投 / 已签收。 */ + DELIVERED, + /** 无法识别。 */ + UNKNOWN + } + + private final Integer rawCode; + private final BolState state; + + EdayunBolStatus(Integer rawCode, BolState state) { + this.rawCode = rawCode; + this.state = state; + } + + public Integer rawCode() { + return rawCode; + } + + public BolState state() { + return state; + } + + /** 状态码 + 中文名 → 归一化状态;码值优先,认不出码再看中文名。 */ + public static BolState toState(Integer status, String statusName) { + for (EdayunBolStatus v : values()) { + if (v.rawCode != null && v.rawCode.equals(status)) { + return v.state; + } + } + return byName(statusName); + } + + /** 按中文名推断;认不出返回 {@link BolState#UNKNOWN}。 */ + static BolState byName(String statusName) { + if (statusName == null || statusName.trim().isEmpty()) { + return BolState.UNKNOWN; + } + String n = statusName.trim(); + if (n.contains("妥投") || n.contains("签收") || n.contains("完成")) { + return BolState.DELIVERED; + } + if (n.contains("已提") || n.contains("提货") || n.contains("运输") + || n.contains("在途") || n.contains("发出")) { + return BolState.PICKED_UP; + } + if (n.contains("未提") || n.contains("待提") || n.contains("待约") + || n.contains("预约")) { + return BolState.PENDING_PICKUP; + } + return BolState.UNKNOWN; + } +} diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunBolTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunBolTest.java new file mode 100644 index 0000000..7398b4e --- /dev/null +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunBolTest.java @@ -0,0 +1,169 @@ +package common.ecommerce.edayun.adapter; + +import common.ecommerce.edayun.dto.EdayunBolDtos; +import common.ecommerce.edayun.enums.EdayunBolStatus; +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.WarehouseProvider; +import common.ecommerce.warehouse.model.BolDocument; +import common.ecommerce.warehouse.sdk.WarehouseConnection; +import common.ecommerce.warehouse.sdk.WarehouseContext; +import org.junit.jupiter.api.Test; + +import java.time.Clock; +import java.time.Instant; +import java.time.ZoneOffset; +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; + +/** + * BOL 信息({@code /webApi/fbaOrder/v1/getOrderBolList})映射。 + * + *重点:只有 11=已妥投 确认,其余按中文名兜底;空 bolList 返回空列表不是错误。
+ */ +class EdayunBolTest { + + private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-16T00:00:00Z"), ZoneOffset.UTC); + + private static WarehouseContext ctx() { + return WarehouseContext.of("EDY-WH", WarehouseProvider.EDAYUN, "2", + WarehouseConnection.of("https://test.example/openapi", + ChannelSecret.builder().appKey("k").appSecret("s") + .clientId("c").clientSecret("cs").build()), + "req-bol", CLOCK); + } + + private static RecordingTransport stub(String body) { + return RecordingTransport.create() + .route(common.ecommerce.edayun.EdayunConstants.PATH_TOKEN, req -> Responses.ok( + "{\"access_token\":\"T1\",\"token_type\":\"bearer\"}")) + .route(common.ecommerce.edayun.EdayunConstants.PATH_BOL_LIST, + req -> Responses.ok(body)); + } + + // ------------------------------------------------------------ 请求 + + @Test + void requiresOrderNo() { + assertThrows(IllegalArgumentException.class, + () -> EdayunBolMapper.toRequest(" ")); + assertEquals("FBA473182144", EdayunBolMapper.toRequest(" FBA473182144 ").orderNo); + } + + // ------------------------------------------------------------ 响应 + + private static EdayunBolDtos.Bol bol() { + EdayunBolDtos.Bol bol = new EdayunBolDtos.Bol(); + bol.bolCode = "cp005"; + bol.bolFileUrl = "https://oss/FBA0012958017-BOL.pdf"; + bol.signBolFileUrl = "https://oss/signed.pdf"; + bol.podFileUrl = "https://oss/pod.pdf"; + bol.podFileTime = 1740910561000L; + bol.status = 11; + bol.statusName = "已妥投"; + bol.pickupTime = "2025-03-02"; + bol.actualPickupTime = "2025-03-02"; + bol.orderPickupNum = 1; + bol.actualPickupNum = 1; + bol.truckCompany = "123"; + bol.trackingNo = "123123"; + return bol; + } + + @Test + void mapsBolFields() { + BolDocument doc = EdayunBolMapper.toDocument(bol()); + + assertEquals("cp005", doc.bolCode()); + assertEquals("https://oss/FBA0012958017-BOL.pdf", doc.fileUrl()); + assertEquals("https://oss/signed.pdf", doc.signedFileUrl()); + assertEquals("https://oss/pod.pdf", doc.podFileUrl()); + assertEquals(Instant.ofEpochMilli(1740910561000L), doc.podUploadedAt()); + assertEquals(Integer.valueOf(11), doc.rawStatus()); + assertEquals("已妥投", doc.statusName()); + assertEquals("2025-03-02", doc.scheduledPickupDate()); + assertEquals("2025-03-02", doc.actualPickupDate()); + assertEquals(Integer.valueOf(1), doc.scheduledPickupQuantity()); + assertEquals(Integer.valueOf(1), doc.actualPickupQuantity()); + assertEquals("123", doc.truckCompany()); + assertEquals("123123", doc.trackingNo()); + } + + /** 只有 11 确认;其余码按中文名兜底。 */ + @Test + void statusOnly11IsConfirmed() { + assertEquals(EdayunBolStatus.BolState.DELIVERED, + EdayunBolStatus.toState(11, null)); + // 未知码 + 中文名能认 → 按名字 + assertEquals(EdayunBolStatus.BolState.PICKED_UP, + EdayunBolStatus.toState(99, "已提货")); + // 都认不出 → UNKNOWN + assertEquals(EdayunBolStatus.BolState.UNKNOWN, + EdayunBolStatus.toState(99, "某个新状态")); + assertEquals(EdayunBolStatus.BolState.UNKNOWN, + EdayunBolStatus.toState(null, null)); + } + + /** podFileTime 为 0 时不造 1970 年。 */ + @Test + void zeroPodTimeIsNull() { + EdayunBolDtos.Bol b = bol(); + b.podFileTime = 0L; + assertNull(EdayunBolMapper.toDocument(b).podUploadedAt()); + } + + /** 没有 bolList 时返回空列表,不是错误。 */ + @Test + void emptyBolListYieldsEmptyResult() { + EdayunBolDtos.GetBolResponse resp = new EdayunBolDtos.GetBolResponse(); + resp.code = 200; + resp.data = new EdayunBolDtos.BolData(); + + assertTrue(EdayunBolMapper.toDocuments(resp).isEmpty()); + assertTrue(EdayunBolMapper.toDocuments(null).isEmpty()); + } + + /** 没有 bolCode 的行跳过——BolDocument 要求 bolCode 非空。 */ + @Test + void rowsWithoutBolCodeAreSkipped() { + EdayunBolDtos.Bol bad = bol(); + bad.bolCode = " "; + EdayunBolDtos.BolData data = new EdayunBolDtos.BolData(); + data.bolList = java.util.Arrays.asList(bad, bol()); + EdayunBolDtos.GetBolResponse resp = new EdayunBolDtos.GetBolResponse(); + resp.data = data; + + assertEquals(1, EdayunBolMapper.toDocuments(resp).size()); + } + + @Test + void adapterQueriesBolList() { + RecordingTransport transport = stub("{\"code\":200,\"msg\":\"操作成功\",\"data\":{" + + "\"totalNum\":1,\"unPickupNum\":0,\"bolList\":[{\"bolCode\":\"cp005\"," + + "\"status\":11,\"statusName\":\"已妥投\",\"pickupTime\":\"2025-03-02\"," + + "\"orderPickupNum\":1,\"bolFileUrl\":\"https://oss/b.pdf\"}]}}"); + + List