Browse Source

feat(lingxing): 接入销售出库单、物流面单、审核发货与编辑订单

新增 4 个 ERP 级接口,均复用 LingxingCall:
- POST /erp/sc/routing/wms/order/wmsOrderList
- POST /erp/sc/routing/wms/order/getWmsLogisticsLabels
- POST /basicOpen/openapi/multiplatform/order/review
- POST /pb/mp/order/editOrder

core:
- Capability 新增 OUTBOUND_ORDER / ORDER_EDIT / SHIPMENT_REVIEW
- 新增 OutboundOrderCapable / ShippingLabelCapable /
  ShipmentReviewCapable / OrderEditCapable
- Outbounds 扩展出库单、面单、审核发货;SalesOrders 扩展编辑订单
- 新增出库单、面单、审核结果、编辑请求/结果等不可变模型

lingxing:
- 补充 4 条接口路径与分页、批量上限
- wms 包下新增 4 个 Source 与对应 DTO
- LingxingAdapter 装配 4 个 Source 并声明对应能力

注意事项:
- editOrder 的 code 0/10000/10001 都是业务结果,不能走 LingxingEnvelope,
  逐单原因在 data.error_details[],且 global_order_no 按字符串解析
- 出库单默认按账户 externalStoreId 过滤,非数字时显式失败,
  避免不带 sid_arr 时跨店铺返回数据
- 面单 wo_number_arr 与 order_number_arr 二选一,单次上限 50
- 商品行 currency_code 可能是符号而非 ISO 代码,此时不构造 Money
- 编辑订单独立成 Capability.ORDER_EDIT:ERP 级接口,
  不依赖子平台的订单列表能力
feature/supplier-lingxing
lml 3 weeks ago
parent
commit
23a08e4e9d
  1. 23
      core/src/main/java/common/ecommerce/capability/OrderEditCapable.java
  2. 18
      core/src/main/java/common/ecommerce/capability/OutboundOrderCapable.java
  3. 35
      core/src/main/java/common/ecommerce/capability/Outbounds.java
  4. 12
      core/src/main/java/common/ecommerce/capability/SalesOrders.java
  5. 19
      core/src/main/java/common/ecommerce/capability/ShipmentReviewCapable.java
  6. 18
      core/src/main/java/common/ecommerce/capability/ShippingLabelCapable.java
  7. 6
      core/src/main/java/common/ecommerce/model/Capability.java
  8. 198
      core/src/main/java/common/ecommerce/model/fulfillment/DeclaredItem.java
  9. 74
      core/src/main/java/common/ecommerce/model/fulfillment/LabelQuery.java
  10. 216
      core/src/main/java/common/ecommerce/model/fulfillment/OrderEditRequest.java
  11. 96
      core/src/main/java/common/ecommerce/model/fulfillment/OrderEditResult.java
  12. 475
      core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrder.java
  13. 118
      core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrderLine.java
  14. 253
      core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrderQuery.java
  15. 105
      core/src/main/java/common/ecommerce/model/fulfillment/ShipmentReviewResult.java
  16. 154
      core/src/main/java/common/ecommerce/model/fulfillment/ShippingLabel.java
  17. 12
      lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java
  18. 7
      lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java
  19. 76
      lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java
  20. 17
      lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingLabelSource.java
  21. 17
      lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingOrderEditSource.java
  22. 16
      lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingOutboundOrderSource.java
  23. 16
      lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingShipmentReviewSource.java
  24. 152
      lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/OrderEditSource.java
  25. 90
      lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/ShipmentReviewSource.java
  26. 84
      lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/WmsLabelSource.java
  27. 290
      lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/WmsOutboundOrderSource.java
  28. 24
      lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/OrderEditErrorDto.java
  29. 33
      lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/ShipmentReviewDataDto.java
  30. 21
      lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/ShipmentReviewFailureDto.java
  31. 17
      lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/ShipmentReviewSuccessDto.java
  32. 47
      lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/WmsLogisticsLabelDto.java
  33. 162
      lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/WmsOutboundOrderDto.java
  34. 51
      lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/WmsOutboundOrderItemDto.java
  35. 34
      lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/WmsSurfaceFileDto.java
  36. 127
      lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingLiveSmokeTest.java

23
core/src/main/java/common/ecommerce/capability/OrderEditCapable.java

@ -0,0 +1,23 @@ @@ -0,0 +1,23 @@
package common.ecommerce.capability;
import common.ecommerce.model.Capability;
import common.ecommerce.model.fulfillment.OrderEditRequest;
import common.ecommerce.model.fulfillment.OrderEditResult;
import common.ecommerce.sdk.ChannelContext;
import java.util.List;
/**
* 订单编辑能力(仓库、物流方式、包裹预估规格、报关信息)。
*
* <p>写操作,必须经 {@code IdempotencyGuard} 执行;幂等键按系统单号。</p>
*
* <p>能力单独成一项 {@link Capability#ORDER_EDIT},不复用
* {@link Capability#SALES_ORDER}:编辑是 ERP 级接口,不依赖订单列表接口,
* 某些子平台只有编辑能力、没有订单同步能力。</p>
*/
public interface OrderEditCapable extends PlatformAdapter {
/** 批量编辑订单;平台按单返回失败原因。 */
OrderEditResult edit(ChannelContext ctx, List<OrderEditRequest> requests);
}

18
core/src/main/java/common/ecommerce/capability/OutboundOrderCapable.java

@ -0,0 +1,18 @@ @@ -0,0 +1,18 @@
package common.ecommerce.capability;
import common.ecommerce.model.fulfillment.OutboundOrder;
import common.ecommerce.model.fulfillment.OutboundOrderQuery;
import common.ecommerce.model.support.Page;
import common.ecommerce.sdk.ChannelContext;
/**
* 销售出库单(仓库出库单据)查询能力。
*
* <p>只读。主键是销售出库单号 {@code woNumber},不是订单号:
* 一张订单可以拆成多张出库单。</p>
*/
public interface OutboundOrderCapable extends PlatformAdapter {
/** 分页拉取销售出库单。 */
Page<OutboundOrder> pull(ChannelContext ctx, OutboundOrderQuery query);
}

35
core/src/main/java/common/ecommerce/capability/Outbounds.java

@ -3,14 +3,23 @@ package common.ecommerce.capability; @@ -3,14 +3,23 @@ package common.ecommerce.capability;
import common.ecommerce.error.ChannelException;
import common.ecommerce.model.Capability;
import common.ecommerce.model.account.ChannelAccount;
import common.ecommerce.model.fulfillment.LabelQuery;
import common.ecommerce.model.fulfillment.OutboundOrder;
import common.ecommerce.model.fulfillment.OutboundOrderQuery;
import common.ecommerce.model.fulfillment.OutboundPackage;
import common.ecommerce.model.fulfillment.OutboundResult;
import common.ecommerce.model.fulfillment.ShipmentReviewResult;
import common.ecommerce.model.fulfillment.ShippingLabel;
import common.ecommerce.model.support.Page;
import common.ecommerce.sdk.ChannelContext;
import java.util.List;
/**
* 门面持有的出库视图。调用前做能力检查,缺失时显式拒绝。
* 门面持有的履约视图:快速出库、销售出库单、面单、审核发货。
*
* <p>每个方法调用前做能力检查,缺失时显式拒绝;写操作仍由调用方包在
* {@code sdk.writes()} 里执行。</p>
*/
public final class Outbounds {
@ -34,9 +43,33 @@ public final class Outbounds { @@ -34,9 +43,33 @@ public final class Outbounds {
return ((OutboundCapable) adapter).results(ctx, globalOrderNos);
}
/** 销售出库单列表。 */
public Page<OutboundOrder> pull(OutboundOrderQuery query) {
require(Capability.OUTBOUND_ORDER, OutboundOrderCapable.class);
return ((OutboundOrderCapable) adapter).pull(ctx, query);
}
/** 销售出库单物流面单。 */
public List<ShippingLabel> labels(LabelQuery query) {
require(Capability.LABEL, ShippingLabelCapable.class);
return ((ShippingLabelCapable) adapter).labels(ctx, query);
}
/** 审核发货(写操作,调用方需包在 {@code sdk.writes()} 里)。 */
public ShipmentReviewResult review(List<String> globalOrderNos) {
require(Capability.SHIPMENT_REVIEW, ShipmentReviewCapable.class);
return ((ShipmentReviewCapable) adapter).review(ctx, globalOrderNos);
}
private void requireOutboundCapable() {
if (!adapter.supports(account, Capability.MARK_SHIPPED) || !(adapter instanceof OutboundCapable)) {
throw new ChannelException.UnsupportedCapabilityException(Capability.MARK_SHIPPED);
}
}
private void require(Capability capability, Class<?> type) {
if (!adapter.supports(account, capability) || !type.isInstance(adapter)) {
throw new ChannelException.UnsupportedCapabilityException(capability);
}
}
}

12
core/src/main/java/common/ecommerce/capability/SalesOrders.java

@ -3,12 +3,16 @@ package common.ecommerce.capability; @@ -3,12 +3,16 @@ package common.ecommerce.capability;
import common.ecommerce.model.Capability;
import common.ecommerce.model.account.ChannelAccount;
import common.ecommerce.error.ChannelException;
import common.ecommerce.model.fulfillment.OrderEditRequest;
import common.ecommerce.model.fulfillment.OrderEditResult;
import common.ecommerce.model.order.SalesOrder;
import common.ecommerce.model.order.SalesOrderQuery;
import common.ecommerce.model.order.SalesOrderRef;
import common.ecommerce.model.support.Page;
import common.ecommerce.sdk.ChannelContext;
import java.util.List;
/**
* 门面持有的销售订单视图。调用前做能力检查,缺失时显式拒绝。
*/
@ -34,6 +38,14 @@ public final class SalesOrders { @@ -34,6 +38,14 @@ public final class SalesOrders {
return ((SalesOrderCapable) adapter).get(ctx, SalesOrderRef.of(channelOrderId));
}
/** 批量编辑订单(写操作,调用方需包在 {@code sdk.writes()} 里)。 */
public OrderEditResult edit(List<OrderEditRequest> requests) {
if (!adapter.supports(account, Capability.ORDER_EDIT) || !(adapter instanceof OrderEditCapable)) {
throw new ChannelException.UnsupportedCapabilityException(Capability.ORDER_EDIT);
}
return ((OrderEditCapable) adapter).edit(ctx, requests);
}
private void requireSalesOrderCapable() {
if (!adapter.supports(account, Capability.SALES_ORDER) || !(adapter instanceof SalesOrderCapable)) {
throw new ChannelException.UnsupportedCapabilityException(Capability.SALES_ORDER);

19
core/src/main/java/common/ecommerce/capability/ShipmentReviewCapable.java

@ -0,0 +1,19 @@ @@ -0,0 +1,19 @@
package common.ecommerce.capability;
import common.ecommerce.model.fulfillment.ShipmentReviewResult;
import common.ecommerce.sdk.ChannelContext;
import java.util.List;
/**
* 审核发货能力(订单管理里的待审核发货)。
*
* <p>写操作,必须经 {@code IdempotencyGuard} 执行;幂等键按系统单号。
* 与 {@link OutboundCapable} 的快速出库不是同一动作:审核发货只推进订单状态,
* 不创建出库单。</p>
*/
public interface ShipmentReviewCapable extends PlatformAdapter {
/** 按系统单号批量审核发货;逐单返回成功或失败原因。 */
ShipmentReviewResult review(ChannelContext ctx, List<String> globalOrderNos);
}

18
core/src/main/java/common/ecommerce/capability/ShippingLabelCapable.java

@ -0,0 +1,18 @@ @@ -0,0 +1,18 @@
package common.ecommerce.capability;
import common.ecommerce.model.fulfillment.LabelQuery;
import common.ecommerce.model.fulfillment.ShippingLabel;
import common.ecommerce.sdk.ChannelContext;
import java.util.List;
/**
* 物流面单查询能力。
*
* <p>只读;面单以 base64 返回,SDK 不落文件、不访问对象存储。</p>
*/
public interface ShippingLabelCapable extends PlatformAdapter {
/** 按销售出库单号或系统单号批量取面单。 */
List<ShippingLabel> labels(ChannelContext ctx, LabelQuery query);
}

6
core/src/main/java/common/ecommerce/model/Capability.java

@ -16,6 +16,12 @@ public enum Capability { @@ -16,6 +16,12 @@ public enum Capability {
PURCHASE_ORDER,
/** 3P 标发 */
MARK_SHIPPED,
/** 审核发货(订单管理里的待审核发货) */
SHIPMENT_REVIEW,
/** 编辑自发货订单(仓库 / 物流方式 / 包裹规格 / 报关) */
ORDER_EDIT,
/** 销售出库单(仓库出库单据查询) */
OUTBOUND_ORDER,
/** 1P DF/DSV 发货确认 */
VENDOR_SHIPMENT,
/** 1P Retail ASN(856) */

198
core/src/main/java/common/ecommerce/model/fulfillment/DeclaredItem.java

@ -0,0 +1,198 @@ @@ -0,0 +1,198 @@
package common.ecommerce.model.fulfillment;
import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 编辑订单时的报关明细。
*
* <p>{@code id} 是原有报关明细主键,不是订单商品 id:编辑已有行时保留,
* 新增行可不传或传 0。</p>
*/
public final class DeclaredItem {
private final String sku;
private final Long id;
private final String cnName;
private final String enName;
private final BigDecimal unitPrice;
private final String currencyCode;
private final BigDecimal weight;
private final int quantity;
private final String hsCode;
private final List<String> specialAttributes;
private DeclaredItem(Builder b) {
this.sku = requireText(b.sku, "sku");
this.id = b.id;
this.cnName = requireText(b.cnName, "cnName");
this.enName = requireText(b.enName, "enName");
this.unitPrice = requirePositive(b.unitPrice, "unitPrice");
this.currencyCode = requireText(b.currencyCode, "currencyCode");
this.weight = requirePositive(b.weight, "weight");
this.quantity = requirePositive(b.quantity, "quantity");
this.hsCode = b.hsCode;
this.specialAttributes = Collections.unmodifiableList(
new ArrayList<String>(b.specialAttributes));
}
public static Builder builder() {
return new Builder();
}
/** 商品本地 SKU。 */
public String sku() {
return sku;
}
/** 原有报关明细主键;新增行为 null。 */
public Long id() {
return id;
}
public String cnName() {
return cnName;
}
public String enName() {
return enName;
}
/** 目的国申报单价,必须大于 0。 */
public BigDecimal unitPrice() {
return unitPrice;
}
public String currencyCode() {
return currencyCode;
}
/** 申报重量,单位 g,必须大于 0。 */
public BigDecimal weight() {
return weight;
}
public int quantity() {
return quantity;
}
public String hsCode() {
return hsCode;
}
/** 特殊属性编码:1 含电、2 纯电、3 液体、4 粉末、5 膏体、6 带磁、7 纺织品。 */
public List<String> specialAttributes() {
return specialAttributes;
}
private static String requireText(String value, String name) {
if (value == null || value.trim().isEmpty()) {
throw new IllegalArgumentException(name + " must not be blank");
}
return value.trim();
}
private static BigDecimal requirePositive(BigDecimal value, String name) {
if (value == null || value.signum() <= 0) {
throw new IllegalArgumentException(name + " must be positive");
}
return value;
}
private static int requirePositive(int value, String name) {
if (value <= 0) {
throw new IllegalArgumentException(name + " must be positive");
}
return value;
}
public static final class Builder {
private String sku;
private Long id;
private String cnName;
private String enName;
private BigDecimal unitPrice;
private String currencyCode;
private BigDecimal weight;
private int quantity;
private String hsCode;
private List<String> specialAttributes = Collections.emptyList();
public Builder sku(String sku) {
this.sku = sku;
return this;
}
public Builder id(Long id) {
this.id = id;
return this;
}
public Builder cnName(String cnName) {
this.cnName = cnName;
return this;
}
public Builder enName(String enName) {
this.enName = enName;
return this;
}
public Builder unitPrice(BigDecimal unitPrice) {
this.unitPrice = unitPrice;
return this;
}
public Builder unitPrice(String unitPrice) {
this.unitPrice = unitPrice == null ? null : new BigDecimal(unitPrice.trim());
return this;
}
public Builder currencyCode(String currencyCode) {
this.currencyCode = currencyCode;
return this;
}
public Builder weight(BigDecimal weight) {
this.weight = weight;
return this;
}
public Builder weight(String weight) {
this.weight = weight == null ? null : new BigDecimal(weight.trim());
return this;
}
public Builder quantity(int quantity) {
this.quantity = quantity;
return this;
}
public Builder hsCode(String hsCode) {
this.hsCode = hsCode;
return this;
}
public Builder specialAttributes(List<String> specialAttributes) {
this.specialAttributes = specialAttributes == null
? Collections.<String>emptyList() : specialAttributes;
return this;
}
public Builder specialAttributes(String... specialAttributes) {
List<String> values = new ArrayList<String>();
if (specialAttributes != null) {
Collections.addAll(values, specialAttributes);
}
this.specialAttributes = values;
return this;
}
public DeclaredItem build() {
return new DeclaredItem(this);
}
}
}

74
core/src/main/java/common/ecommerce/model/fulfillment/LabelQuery.java

@ -0,0 +1,74 @@ @@ -0,0 +1,74 @@
package common.ecommerce.model.fulfillment;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 物流面单查询条件。
*
* <p>销售出库单号与系统单号二选一:平台要求至少给一组,单次上限通常为 50。
* 两个都传属于调用方错误,适配器会显式拒绝,避免平台静默忽略其中一组。</p>
*/
public final class LabelQuery {
private final List<String> woNumbers;
private final List<String> orderNumbers;
private LabelQuery(Builder b) {
this.woNumbers = Collections.unmodifiableList(new ArrayList<String>(b.woNumbers));
this.orderNumbers = Collections.unmodifiableList(new ArrayList<String>(b.orderNumbers));
}
public static Builder builder() {
return new Builder();
}
/** 销售出库单号。 */
public List<String> woNumbers() {
return woNumbers;
}
/** 领星系统单号。 */
public List<String> orderNumbers() {
return orderNumbers;
}
public static final class Builder {
private List<String> woNumbers = Collections.emptyList();
private List<String> orderNumbers = Collections.emptyList();
public Builder woNumbers(List<String> woNumbers) {
this.woNumbers = woNumbers == null ? Collections.<String>emptyList() : woNumbers;
return this;
}
public Builder woNumbers(String... woNumbers) {
List<String> values = new ArrayList<String>();
if (woNumbers != null) {
Collections.addAll(values, woNumbers);
}
this.woNumbers = values;
return this;
}
public Builder orderNumbers(List<String> orderNumbers) {
this.orderNumbers = orderNumbers == null ? Collections.<String>emptyList() : orderNumbers;
return this;
}
public Builder orderNumbers(String... orderNumbers) {
List<String> values = new ArrayList<String>();
if (orderNumbers != null) {
Collections.addAll(values, orderNumbers);
}
this.orderNumbers = values;
return this;
}
public LabelQuery build() {
return new LabelQuery(this);
}
}
}

216
core/src/main/java/common/ecommerce/model/fulfillment/OrderEditRequest.java

@ -0,0 +1,216 @@ @@ -0,0 +1,216 @@
package common.ecommerce.model.fulfillment;
import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 编辑订单请求(订单管理里的待审核自发货订单)。
*
* <p>一次可以只改仓库/物流,只改包裹规格,或只改报关,也可以组合。适配器按
* 「非空才发送」处理,未设置的维度保持平台原值。</p>
*
* <p>平台约束:</p>
* <ul>
* <li>改仓库必须同时给 {@code logisticsTypeId}</li>
* <li>包裹预估长宽高与总重量必须四项一起给</li>
* <li>报关开关打开时,报关明细不能为空</li>
* </ul>
*/
public final class OrderEditRequest {
private final String globalOrderNo;
private final Long warehouseId;
private final Long logisticsTypeId;
private final BigDecimal packageLength;
private final BigDecimal packageWidth;
private final BigDecimal packageHeight;
private final BigDecimal packageWeight;
private final boolean modifyDeclared;
private final List<DeclaredItem> declaredItems;
private OrderEditRequest(Builder b) {
this.globalOrderNo = requireText(b.globalOrderNo, "globalOrderNo");
this.warehouseId = b.warehouseId;
this.logisticsTypeId = b.logisticsTypeId;
this.packageLength = b.packageLength;
this.packageWidth = b.packageWidth;
this.packageHeight = b.packageHeight;
this.packageWeight = b.packageWeight;
this.modifyDeclared = b.modifyDeclared;
this.declaredItems = Collections.unmodifiableList(new ArrayList<DeclaredItem>(b.declaredItems));
int packageFields = 0;
if (packageLength != null) {
packageFields++;
}
if (packageWidth != null) {
packageFields++;
}
if (packageHeight != null) {
packageFields++;
}
if (packageWeight != null) {
packageFields++;
}
if (packageFields != 0 && packageFields != 4) {
throw new IllegalArgumentException(
"packageLength/packageWidth/packageHeight/packageWeight must be set together");
}
if (modifyDeclared != !declaredItems.isEmpty()) {
// 打开开关必须有明细;有关闭开关却传明细说明调用方语义不一致
throw new IllegalArgumentException(
"modifyDeclared and declaredItems must be set consistently");
}
if (warehouseId == null && logisticsTypeId == null && packageFields == 0 && !modifyDeclared) {
throw new IllegalArgumentException("order edit request has nothing to change: " + globalOrderNo);
}
}
public static Builder builder() {
return new Builder();
}
/** 领星系统单号。 */
public String globalOrderNo() {
return globalOrderNo;
}
/** 发货仓库 wid。 */
public Long warehouseId() {
return warehouseId;
}
/** 物流方式 id。 */
public Long logisticsTypeId() {
return logisticsTypeId;
}
/** 包裹预估长,单位 cm。 */
public BigDecimal packageLength() {
return packageLength;
}
/** 包裹预估宽,单位 cm。 */
public BigDecimal packageWidth() {
return packageWidth;
}
/** 包裹预估高,单位 cm。 */
public BigDecimal packageHeight() {
return packageHeight;
}
/** 包裹预估总重量,单位 g。 */
public BigDecimal packageWeight() {
return packageWeight;
}
public boolean modifyDeclared() {
return modifyDeclared;
}
public List<DeclaredItem> declaredItems() {
return declaredItems;
}
private static String requireText(String value, String name) {
if (value == null || value.trim().isEmpty()) {
throw new IllegalArgumentException(name + " must not be blank");
}
return value.trim();
}
public static final class Builder {
private String globalOrderNo;
private Long warehouseId;
private Long logisticsTypeId;
private BigDecimal packageLength;
private BigDecimal packageWidth;
private BigDecimal packageHeight;
private BigDecimal packageWeight;
private boolean modifyDeclared;
private List<DeclaredItem> declaredItems = Collections.emptyList();
public Builder globalOrderNo(String globalOrderNo) {
this.globalOrderNo = globalOrderNo;
return this;
}
public Builder warehouseId(Long warehouseId) {
this.warehouseId = warehouseId;
return this;
}
public Builder logisticsTypeId(Long logisticsTypeId) {
this.logisticsTypeId = logisticsTypeId;
return this;
}
public Builder packageLength(BigDecimal packageLength) {
this.packageLength = packageLength;
return this;
}
public Builder packageLength(String packageLength) {
this.packageLength = packageLength == null ? null : new BigDecimal(packageLength.trim());
return this;
}
public Builder packageWidth(BigDecimal packageWidth) {
this.packageWidth = packageWidth;
return this;
}
public Builder packageWidth(String packageWidth) {
this.packageWidth = packageWidth == null ? null : new BigDecimal(packageWidth.trim());
return this;
}
public Builder packageHeight(BigDecimal packageHeight) {
this.packageHeight = packageHeight;
return this;
}
public Builder packageHeight(String packageHeight) {
this.packageHeight = packageHeight == null ? null : new BigDecimal(packageHeight.trim());
return this;
}
public Builder packageWeight(BigDecimal packageWeight) {
this.packageWeight = packageWeight;
return this;
}
public Builder packageWeight(String packageWeight) {
this.packageWeight = packageWeight == null ? null : new BigDecimal(packageWeight.trim());
return this;
}
public Builder modifyDeclared(boolean modifyDeclared) {
this.modifyDeclared = modifyDeclared;
return this;
}
public Builder declaredItems(List<DeclaredItem> declaredItems) {
this.declaredItems = declaredItems == null
? Collections.<DeclaredItem>emptyList() : declaredItems;
return this;
}
public Builder declaredItems(DeclaredItem... declaredItems) {
List<DeclaredItem> values = new ArrayList<DeclaredItem>();
if (declaredItems != null) {
Collections.addAll(values, declaredItems);
}
this.declaredItems = values;
return this;
}
public OrderEditRequest build() {
return new OrderEditRequest(this);
}
}
}

96
core/src/main/java/common/ecommerce/model/fulfillment/OrderEditResult.java

@ -0,0 +1,96 @@ @@ -0,0 +1,96 @@
package common.ecommerce.model.fulfillment;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 编辑订单结果。
*
* <p>平台按批返回三种业务码:{@code 0} 全部成功、{@code 10001} 部分成功、
* {@code 10000} 全部失败。即使整体失败,也要看 {@link #failures()} 里逐单的原因。</p>
*/
public final class OrderEditResult {
public static final String CODE_SUCCESS = "0";
public static final String CODE_ALL_FAILED = "10000";
public static final String CODE_PARTIAL = "10001";
private final String code;
private final String message;
private final List<Failure> failures;
private OrderEditResult(Builder b) {
this.code = b.code;
this.message = b.message;
this.failures = Collections.unmodifiableList(new ArrayList<Failure>(b.failures));
}
public static Builder builder() {
return new Builder();
}
/** 平台业务码。 */
public String code() {
return code;
}
public String message() {
return message;
}
public List<Failure> failures() {
return failures;
}
/** 全部成功。 */
public boolean allSucceeded() {
return CODE_SUCCESS.equals(code) && failures.isEmpty();
}
/** 单笔失败原因。 */
public static final class Failure {
private final String globalOrderNo;
private final String errorMessage;
public Failure(String globalOrderNo, String errorMessage) {
this.globalOrderNo = globalOrderNo;
this.errorMessage = errorMessage;
}
public String globalOrderNo() {
return globalOrderNo;
}
public String errorMessage() {
return errorMessage;
}
}
public static final class Builder {
private String code;
private String message;
private List<Failure> failures = Collections.emptyList();
public Builder code(String code) {
this.code = code;
return this;
}
public Builder message(String message) {
this.message = message;
return this;
}
public Builder failures(List<Failure> failures) {
this.failures = failures == null ? Collections.<Failure>emptyList() : failures;
return this;
}
public OrderEditResult build() {
return new OrderEditResult(this);
}
}
}

475
core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrder.java

@ -0,0 +1,475 @@ @@ -0,0 +1,475 @@
package common.ecommerce.model.fulfillment;
import common.ecommerce.model.ChannelProvider;
import common.ecommerce.model.support.Money;
import common.ecommerce.model.support.PlatformTime;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.Objects;
/**
* 销售出库单。
*
* <p>对应平台「仓库 &gt; 销售出库单」,是订单进入仓库作业后的单据视角:
* 一张销售订单可能拆成多张出库单,因此 {@code woNumber}(销售出库单号)才是主键,
* 不是 {@code orderNumber}(系统单号)。</p>
*
* <p>状态字段保留平台原值,由宿主解释:{@code status} 是出库单状态,
* {@code logisticsStatus} 是物流下单状态,两者不要混用。</p>
*/
public final class OutboundOrder {
private final String omsStoreId;
private final ChannelProvider sourceProvider;
private final String sourceAccountId;
private final String woNumber;
private final String woId;
private final String orderNumber;
private final List<String> platformOrderNos;
private final Integer sid;
private final String sellerName;
private final Integer warehouseId;
private final String warehouseName;
private final Integer warehouseType;
private final Integer status;
private final String statusName;
private final Integer logisticsStatus;
private final String logisticsStatusName;
private final String logisticsMessage;
private final Long logisticsProviderId;
private final String logisticsProviderName;
private final Long logisticsTypeId;
private final String logisticsTypeName;
private final String waybillNo;
private final String trackingNo;
private final Money orderAmount;
private final String targetCountry;
private final String packageWeight;
private final String packageRealWeight;
private final String packageFeeWeight;
private final String packageWeightUnit;
private final String surfaceFileUrl;
private final PlatformTime createdAt;
private final PlatformTime updatedAt;
private final PlatformTime deliveredAt;
private final PlatformTime purchasedAt;
private final List<OutboundOrderLine> lines;
private OutboundOrder(Builder b) {
this.omsStoreId = Objects.requireNonNull(b.omsStoreId, "omsStoreId");
this.sourceProvider = Objects.requireNonNull(b.sourceProvider, "sourceProvider");
this.sourceAccountId = b.sourceAccountId;
this.woNumber = Objects.requireNonNull(b.woNumber, "woNumber");
this.woId = b.woId;
this.orderNumber = b.orderNumber;
this.platformOrderNos = Collections.unmodifiableList(new ArrayList<String>(b.platformOrderNos));
this.sid = b.sid;
this.sellerName = b.sellerName;
this.warehouseId = b.warehouseId;
this.warehouseName = b.warehouseName;
this.warehouseType = b.warehouseType;
this.status = b.status;
this.statusName = b.statusName;
this.logisticsStatus = b.logisticsStatus;
this.logisticsStatusName = b.logisticsStatusName;
this.logisticsMessage = b.logisticsMessage;
this.logisticsProviderId = b.logisticsProviderId;
this.logisticsProviderName = b.logisticsProviderName;
this.logisticsTypeId = b.logisticsTypeId;
this.logisticsTypeName = b.logisticsTypeName;
this.waybillNo = b.waybillNo;
this.trackingNo = b.trackingNo;
this.orderAmount = b.orderAmount;
this.targetCountry = b.targetCountry;
this.packageWeight = b.packageWeight;
this.packageRealWeight = b.packageRealWeight;
this.packageFeeWeight = b.packageFeeWeight;
this.packageWeightUnit = b.packageWeightUnit;
this.surfaceFileUrl = b.surfaceFileUrl;
this.createdAt = b.createdAt;
this.updatedAt = b.updatedAt;
this.deliveredAt = b.deliveredAt;
this.purchasedAt = b.purchasedAt;
this.lines = Collections.unmodifiableList(new ArrayList<OutboundOrderLine>(b.lines));
}
public static Builder builder() {
return new Builder();
}
public String omsStoreId() {
return omsStoreId;
}
public ChannelProvider sourceProvider() {
return sourceProvider;
}
public String sourceAccountId() {
return sourceAccountId;
}
/** 销售出库单号,主键。 */
public String woNumber() {
return woNumber;
}
/** 领星出库单 id。 */
public String woId() {
return woId;
}
/** 领星系统单号。 */
public String orderNumber() {
return orderNumber;
}
/** 平台单号;合并单可能多于一个。 */
public List<String> platformOrderNos() {
return platformOrderNos;
}
/** 领星店铺 id。 */
public Integer sid() {
return sid;
}
public String sellerName() {
return sellerName;
}
public Integer warehouseId() {
return warehouseId;
}
public String warehouseName() {
return warehouseName;
}
/** 仓库类型:1 本地仓库、2 FBA 仓、3 第三方海外仓。 */
public Integer warehouseType() {
return warehouseType;
}
/** 出库单状态:1 物流下单、2 待出库、3 已出库、4 已截单。 */
public Integer status() {
return status;
}
public String statusName() {
return statusName;
}
/** 物流下单状态:1 待导入 … 5 下单完成 … 43 物流取消完成。 */
public Integer logisticsStatus() {
return logisticsStatus;
}
public String logisticsStatusName() {
return logisticsStatusName;
}
public String logisticsMessage() {
return logisticsMessage;
}
public Long logisticsProviderId() {
return logisticsProviderId;
}
public String logisticsProviderName() {
return logisticsProviderName;
}
public Long logisticsTypeId() {
return logisticsTypeId;
}
public String logisticsTypeName() {
return logisticsTypeName;
}
public String waybillNo() {
return waybillNo;
}
public String trackingNo() {
return trackingNo;
}
/** 订单金额;平台未给币种时为 null。 */
public Money orderAmount() {
return orderAmount;
}
public String targetCountry() {
return targetCountry;
}
/** 预估重量,保留平台原始字符串与单位。 */
public String packageWeight() {
return packageWeight;
}
/** 包裹实重,保留平台原始字符串。 */
public String packageRealWeight() {
return packageRealWeight;
}
/** 包裹计费重,保留平台原始字符串。 */
public String packageFeeWeight() {
return packageFeeWeight;
}
public String packageWeightUnit() {
return packageWeightUnit;
}
/** 面单文件链接;接口给的是 30 分钟有效的 COS 链接。 */
public String surfaceFileUrl() {
return surfaceFileUrl;
}
public PlatformTime createdAt() {
return createdAt;
}
public PlatformTime updatedAt() {
return updatedAt;
}
/** 出库时间【单据操作】。 */
public PlatformTime deliveredAt() {
return deliveredAt;
}
/** 下单时间。 */
public PlatformTime purchasedAt() {
return purchasedAt;
}
public List<OutboundOrderLine> lines() {
return lines;
}
public static final class Builder {
private String omsStoreId;
private ChannelProvider sourceProvider;
private String sourceAccountId;
private String woNumber;
private String woId;
private String orderNumber;
private List<String> platformOrderNos = Collections.emptyList();
private Integer sid;
private String sellerName;
private Integer warehouseId;
private String warehouseName;
private Integer warehouseType;
private Integer status;
private String statusName;
private Integer logisticsStatus;
private String logisticsStatusName;
private String logisticsMessage;
private Long logisticsProviderId;
private String logisticsProviderName;
private Long logisticsTypeId;
private String logisticsTypeName;
private String waybillNo;
private String trackingNo;
private Money orderAmount;
private String targetCountry;
private String packageWeight;
private String packageRealWeight;
private String packageFeeWeight;
private String packageWeightUnit;
private String surfaceFileUrl;
private PlatformTime createdAt;
private PlatformTime updatedAt;
private PlatformTime deliveredAt;
private PlatformTime purchasedAt;
private List<OutboundOrderLine> lines = Collections.emptyList();
public Builder omsStoreId(String omsStoreId) {
this.omsStoreId = omsStoreId;
return this;
}
public Builder sourceProvider(ChannelProvider sourceProvider) {
this.sourceProvider = sourceProvider;
return this;
}
public Builder sourceAccountId(String sourceAccountId) {
this.sourceAccountId = sourceAccountId;
return this;
}
public Builder woNumber(String woNumber) {
this.woNumber = woNumber;
return this;
}
public Builder woId(String woId) {
this.woId = woId;
return this;
}
public Builder orderNumber(String orderNumber) {
this.orderNumber = orderNumber;
return this;
}
public Builder platformOrderNos(List<String> platformOrderNos) {
this.platformOrderNos = platformOrderNos == null
? Collections.<String>emptyList() : platformOrderNos;
return this;
}
public Builder sid(Integer sid) {
this.sid = sid;
return this;
}
public Builder sellerName(String sellerName) {
this.sellerName = sellerName;
return this;
}
public Builder warehouseId(Integer warehouseId) {
this.warehouseId = warehouseId;
return this;
}
public Builder warehouseName(String warehouseName) {
this.warehouseName = warehouseName;
return this;
}
public Builder warehouseType(Integer warehouseType) {
this.warehouseType = warehouseType;
return this;
}
public Builder status(Integer status) {
this.status = status;
return this;
}
public Builder statusName(String statusName) {
this.statusName = statusName;
return this;
}
public Builder logisticsStatus(Integer logisticsStatus) {
this.logisticsStatus = logisticsStatus;
return this;
}
public Builder logisticsStatusName(String logisticsStatusName) {
this.logisticsStatusName = logisticsStatusName;
return this;
}
public Builder logisticsMessage(String logisticsMessage) {
this.logisticsMessage = logisticsMessage;
return this;
}
public Builder logisticsProviderId(Long logisticsProviderId) {
this.logisticsProviderId = logisticsProviderId;
return this;
}
public Builder logisticsProviderName(String logisticsProviderName) {
this.logisticsProviderName = logisticsProviderName;
return this;
}
public Builder logisticsTypeId(Long logisticsTypeId) {
this.logisticsTypeId = logisticsTypeId;
return this;
}
public Builder logisticsTypeName(String logisticsTypeName) {
this.logisticsTypeName = logisticsTypeName;
return this;
}
public Builder waybillNo(String waybillNo) {
this.waybillNo = waybillNo;
return this;
}
public Builder trackingNo(String trackingNo) {
this.trackingNo = trackingNo;
return this;
}
public Builder orderAmount(Money orderAmount) {
this.orderAmount = orderAmount;
return this;
}
public Builder targetCountry(String targetCountry) {
this.targetCountry = targetCountry;
return this;
}
public Builder packageWeight(String packageWeight) {
this.packageWeight = packageWeight;
return this;
}
public Builder packageRealWeight(String packageRealWeight) {
this.packageRealWeight = packageRealWeight;
return this;
}
public Builder packageFeeWeight(String packageFeeWeight) {
this.packageFeeWeight = packageFeeWeight;
return this;
}
public Builder packageWeightUnit(String packageWeightUnit) {
this.packageWeightUnit = packageWeightUnit;
return this;
}
public Builder surfaceFileUrl(String surfaceFileUrl) {
this.surfaceFileUrl = surfaceFileUrl;
return this;
}
public Builder createdAt(PlatformTime createdAt) {
this.createdAt = createdAt;
return this;
}
public Builder updatedAt(PlatformTime updatedAt) {
this.updatedAt = updatedAt;
return this;
}
public Builder deliveredAt(PlatformTime deliveredAt) {
this.deliveredAt = deliveredAt;
return this;
}
public Builder purchasedAt(PlatformTime purchasedAt) {
this.purchasedAt = purchasedAt;
return this;
}
public Builder lines(List<OutboundOrderLine> lines) {
this.lines = lines == null ? Collections.<OutboundOrderLine>emptyList() : lines;
return this;
}
public OutboundOrder build() {
return new OutboundOrder(this);
}
}
}

118
core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrderLine.java

@ -0,0 +1,118 @@ @@ -0,0 +1,118 @@
package common.ecommerce.model.fulfillment;
import common.ecommerce.model.support.Money;
import java.util.Objects;
/**
* 销售出库单商品行。
*
* <p>字段以领星「销售出库单列表」的 {@code product_info[]} 为准:
* {@code sku} 是领星本地 SKU,{@code sellerSku} 才是平台 MSKU。</p>
*/
public final class OutboundOrderLine {
private final String lineId;
private final String productId;
private final String sku;
private final String sellerSku;
private final String productName;
private final int quantity;
private final Money unitPrice;
private OutboundOrderLine(Builder b) {
this.lineId = Objects.requireNonNull(b.lineId, "lineId");
this.productId = b.productId;
this.sku = b.sku;
this.sellerSku = b.sellerSku;
this.productName = b.productName;
this.quantity = b.quantity;
this.unitPrice = b.unitPrice;
}
public static Builder builder() {
return new Builder();
}
/** 出库单明细 id,映射自 {@code wod_id}。 */
public String lineId() {
return lineId;
}
public String productId() {
return productId;
}
/** 领星本地 SKU。 */
public String sku() {
return sku;
}
/** 平台 MSKU。 */
public String sellerSku() {
return sellerSku;
}
public String productName() {
return productName;
}
public int quantity() {
return quantity;
}
/** 商品单价;平台未给币种时为 null。 */
public Money unitPrice() {
return unitPrice;
}
public static final class Builder {
private String lineId;
private String productId;
private String sku;
private String sellerSku;
private String productName;
private int quantity;
private Money unitPrice;
public Builder lineId(String lineId) {
this.lineId = lineId;
return this;
}
public Builder productId(String productId) {
this.productId = productId;
return this;
}
public Builder sku(String sku) {
this.sku = sku;
return this;
}
public Builder sellerSku(String sellerSku) {
this.sellerSku = sellerSku;
return this;
}
public Builder productName(String productName) {
this.productName = productName;
return this;
}
public Builder quantity(int quantity) {
this.quantity = quantity;
return this;
}
public Builder unitPrice(Money unitPrice) {
this.unitPrice = unitPrice;
return this;
}
public OutboundOrderLine build() {
return new OutboundOrderLine(this);
}
}
}

253
core/src/main/java/common/ecommerce/model/fulfillment/OutboundOrderQuery.java

@ -0,0 +1,253 @@ @@ -0,0 +1,253 @@
package common.ecommerce.model.fulfillment;
import java.time.Instant;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 销售出库单查询条件(单次查询,不推进水位线)。
*
* <p>平台一般要求时间窗;不传时由平台按默认区间返回(领星默认最近一个月)。
* 时间字段类型用 {@link #timeType()} 指定,取值见本类常量。</p>
*/
public final class OutboundOrderQuery {
/** 创建时间。 */
public static final String TIME_CREATED = "create_at";
/** 出库时间【单据操作】。 */
public static final String TIME_DELIVERED = "delivered_at";
/** 库存流水出库时间。 */
public static final String TIME_STOCK_DELIVERED = "stock_delivered_at";
/** 变更时间。 */
public static final String TIME_UPDATED = "update_at";
private final Instant after;
private final Instant before;
private final String timeType;
private final List<String> sids;
private final List<Integer> statuses;
private final List<Integer> logisticsStatuses;
private final List<String> platformOrderNos;
private final List<String> orderNumbers;
private final List<String> woNumbers;
private final int pageSize;
private final String cursor;
private OutboundOrderQuery(Builder b) {
this.after = b.after;
this.before = b.before;
this.timeType = b.timeType;
this.sids = Collections.unmodifiableList(new ArrayList<String>(b.sids));
this.statuses = Collections.unmodifiableList(new ArrayList<Integer>(b.statuses));
this.logisticsStatuses = Collections.unmodifiableList(new ArrayList<Integer>(b.logisticsStatuses));
this.platformOrderNos = Collections.unmodifiableList(new ArrayList<String>(b.platformOrderNos));
this.orderNumbers = Collections.unmodifiableList(new ArrayList<String>(b.orderNumbers));
this.woNumbers = Collections.unmodifiableList(new ArrayList<String>(b.woNumbers));
this.pageSize = b.pageSize;
this.cursor = b.cursor;
}
public static Builder builder() {
return new Builder();
}
/** 时间窗起点;为 null 时不传,由平台按默认区间处理。 */
public Instant after() {
return after;
}
/** 时间窗终点;为 null 时不传。 */
public Instant before() {
return before;
}
/** 时间字段类型,默认 {@link #TIME_UPDATED}。 */
public String timeType() {
return timeType;
}
/**
* 店铺 id 过滤;为空时适配器使用当前账户的店铺 id。
*
* <p>领星侧是内部 {@code sid},对亚马逊 SC 即店铺列表返回的 {@code sid}。</p>
*/
public List<String> sids() {
return sids;
}
/** 出库单状态:1 物流下单、2 待出库、3 已出库、4 已截单。 */
public List<Integer> statuses() {
return statuses;
}
/** 物流下单状态。 */
public List<Integer> logisticsStatuses() {
return logisticsStatuses;
}
public List<String> platformOrderNos() {
return platformOrderNos;
}
public List<String> orderNumbers() {
return orderNumbers;
}
public List<String> woNumbers() {
return woNumbers;
}
public int pageSize() {
return pageSize;
}
public String cursor() {
return cursor;
}
public Builder toBuilder() {
return builder()
.after(after)
.before(before)
.timeType(timeType)
.sids(sids)
.statuses(statuses)
.logisticsStatuses(logisticsStatuses)
.platformOrderNos(platformOrderNos)
.orderNumbers(orderNumbers)
.woNumbers(woNumbers)
.pageSize(pageSize)
.cursor(cursor);
}
public static final class Builder {
private Instant after;
private Instant before;
private String timeType = TIME_UPDATED;
private List<String> sids = Collections.emptyList();
private List<Integer> statuses = Collections.emptyList();
private List<Integer> logisticsStatuses = Collections.emptyList();
private List<String> platformOrderNos = Collections.emptyList();
private List<String> orderNumbers = Collections.emptyList();
private List<String> woNumbers = Collections.emptyList();
private int pageSize = 100;
private String cursor;
public Builder after(Instant after) {
this.after = after;
return this;
}
public Builder before(Instant before) {
this.before = before;
return this;
}
public Builder timeType(String timeType) {
this.timeType = timeType;
return this;
}
public Builder sids(List<String> sids) {
this.sids = sids == null ? Collections.<String>emptyList() : sids;
return this;
}
public Builder sids(String... sids) {
List<String> values = new ArrayList<String>();
if (sids != null) {
Collections.addAll(values, sids);
}
this.sids = values;
return this;
}
public Builder statuses(List<Integer> statuses) {
this.statuses = statuses == null ? Collections.<Integer>emptyList() : statuses;
return this;
}
public Builder statuses(Integer... statuses) {
List<Integer> values = new ArrayList<Integer>();
if (statuses != null) {
Collections.addAll(values, statuses);
}
this.statuses = values;
return this;
}
public Builder logisticsStatuses(List<Integer> logisticsStatuses) {
this.logisticsStatuses = logisticsStatuses == null
? Collections.<Integer>emptyList() : logisticsStatuses;
return this;
}
public Builder logisticsStatuses(Integer... logisticsStatuses) {
List<Integer> values = new ArrayList<Integer>();
if (logisticsStatuses != null) {
Collections.addAll(values, logisticsStatuses);
}
this.logisticsStatuses = values;
return this;
}
public Builder platformOrderNos(List<String> platformOrderNos) {
this.platformOrderNos = platformOrderNos == null
? Collections.<String>emptyList() : platformOrderNos;
return this;
}
public Builder platformOrderNos(String... platformOrderNos) {
List<String> values = new ArrayList<String>();
if (platformOrderNos != null) {
Collections.addAll(values, platformOrderNos);
}
this.platformOrderNos = values;
return this;
}
public Builder orderNumbers(List<String> orderNumbers) {
this.orderNumbers = orderNumbers == null ? Collections.<String>emptyList() : orderNumbers;
return this;
}
public Builder orderNumbers(String... orderNumbers) {
List<String> values = new ArrayList<String>();
if (orderNumbers != null) {
Collections.addAll(values, orderNumbers);
}
this.orderNumbers = values;
return this;
}
public Builder woNumbers(List<String> woNumbers) {
this.woNumbers = woNumbers == null ? Collections.<String>emptyList() : woNumbers;
return this;
}
public Builder woNumbers(String... woNumbers) {
List<String> values = new ArrayList<String>();
if (woNumbers != null) {
Collections.addAll(values, woNumbers);
}
this.woNumbers = values;
return this;
}
public Builder pageSize(int pageSize) {
this.pageSize = pageSize;
return this;
}
public Builder cursor(String cursor) {
this.cursor = cursor;
return this;
}
public OutboundOrderQuery build() {
return new OutboundOrderQuery(this);
}
}
}

105
core/src/main/java/common/ecommerce/model/fulfillment/ShipmentReviewResult.java

@ -0,0 +1,105 @@ @@ -0,0 +1,105 @@
package common.ecommerce.model.fulfillment;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 审核发货结果。
*
* <p>平台按单返回成功/失败,失败通常是「未设置仓库」「未设置物流」这类业务原因,
* 不影响同批其它订单。调用方必须逐单处理,不能只看整体是否成功。</p>
*/
public final class ShipmentReviewResult {
private final int successNum;
private final int failNum;
private final List<String> successGlobalOrderNos;
private final List<Failure> failures;
private ShipmentReviewResult(Builder b) {
this.successNum = b.successNum;
this.failNum = b.failNum;
this.successGlobalOrderNos = Collections.unmodifiableList(
new ArrayList<String>(b.successGlobalOrderNos));
this.failures = Collections.unmodifiableList(new ArrayList<Failure>(b.failures));
}
public static Builder builder() {
return new Builder();
}
public int successNum() {
return successNum;
}
public int failNum() {
return failNum;
}
public List<String> successGlobalOrderNos() {
return successGlobalOrderNos;
}
public List<Failure> failures() {
return failures;
}
/** 整批全部成功。 */
public boolean allSucceeded() {
return failNum == 0 && failures.isEmpty();
}
/** 单笔失败原因。 */
public static final class Failure {
private final String globalOrderNo;
private final String message;
public Failure(String globalOrderNo, String message) {
this.globalOrderNo = globalOrderNo;
this.message = message;
}
public String globalOrderNo() {
return globalOrderNo;
}
public String message() {
return message;
}
}
public static final class Builder {
private int successNum;
private int failNum;
private List<String> successGlobalOrderNos = Collections.emptyList();
private List<Failure> failures = Collections.emptyList();
public Builder successNum(int successNum) {
this.successNum = successNum;
return this;
}
public Builder failNum(int failNum) {
this.failNum = failNum;
return this;
}
public Builder successGlobalOrderNos(List<String> successGlobalOrderNos) {
this.successGlobalOrderNos = successGlobalOrderNos == null
? Collections.<String>emptyList() : successGlobalOrderNos;
return this;
}
public Builder failures(List<Failure> failures) {
this.failures = failures == null ? Collections.<Failure>emptyList() : failures;
return this;
}
public ShipmentReviewResult build() {
return new ShipmentReviewResult(this);
}
}
}

154
core/src/main/java/common/ecommerce/model/fulfillment/ShippingLabel.java

@ -0,0 +1,154 @@ @@ -0,0 +1,154 @@
package common.ecommerce.model.fulfillment;
import common.ecommerce.model.ChannelProvider;
import java.util.Objects;
/**
* 销售出库单物流面单。
*
* <p>内容以 base64 返回,不落文件;{@code fileType} 是扩展名(如 {@code pdf}),
* 由调用方决定解码与存储方式。</p>
*/
public final class ShippingLabel {
private final String omsStoreId;
private final ChannelProvider sourceProvider;
private final String woNumber;
private final String orderNumber;
private final Long logisticsProviderId;
private final Long logisticsTypeId;
private final Long fileId;
private final String fileType;
private final String fileSize;
private final String contentBase64;
private ShippingLabel(Builder b) {
this.omsStoreId = Objects.requireNonNull(b.omsStoreId, "omsStoreId");
this.sourceProvider = Objects.requireNonNull(b.sourceProvider, "sourceProvider");
this.woNumber = Objects.requireNonNull(b.woNumber, "woNumber");
this.orderNumber = b.orderNumber;
this.logisticsProviderId = b.logisticsProviderId;
this.logisticsTypeId = b.logisticsTypeId;
this.fileId = b.fileId;
this.fileType = b.fileType;
this.fileSize = b.fileSize;
this.contentBase64 = b.contentBase64;
}
public static Builder builder() {
return new Builder();
}
public String omsStoreId() {
return omsStoreId;
}
public ChannelProvider sourceProvider() {
return sourceProvider;
}
/** 销售出库单号。 */
public String woNumber() {
return woNumber;
}
public String orderNumber() {
return orderNumber;
}
public Long logisticsProviderId() {
return logisticsProviderId;
}
public Long logisticsTypeId() {
return logisticsTypeId;
}
public Long fileId() {
return fileId;
}
/** 文件类型,如 {@code pdf}。 */
public String fileType() {
return fileType;
}
/** 文件尺寸描述,平台原值。 */
public String fileSize() {
return fileSize;
}
/** 面单 base64;平台可能返回空串。 */
public String contentBase64() {
return contentBase64;
}
public static final class Builder {
private String omsStoreId;
private ChannelProvider sourceProvider;
private String woNumber;
private String orderNumber;
private Long logisticsProviderId;
private Long logisticsTypeId;
private Long fileId;
private String fileType;
private String fileSize;
private String contentBase64;
public Builder omsStoreId(String omsStoreId) {
this.omsStoreId = omsStoreId;
return this;
}
public Builder sourceProvider(ChannelProvider sourceProvider) {
this.sourceProvider = sourceProvider;
return this;
}
public Builder woNumber(String woNumber) {
this.woNumber = woNumber;
return this;
}
public Builder orderNumber(String orderNumber) {
this.orderNumber = orderNumber;
return this;
}
public Builder logisticsProviderId(Long logisticsProviderId) {
this.logisticsProviderId = logisticsProviderId;
return this;
}
public Builder logisticsTypeId(Long logisticsTypeId) {
this.logisticsTypeId = logisticsTypeId;
return this;
}
public Builder fileId(Long fileId) {
this.fileId = fileId;
return this;
}
public Builder fileType(String fileType) {
this.fileType = fileType;
return this;
}
public Builder fileSize(String fileSize) {
this.fileSize = fileSize;
return this;
}
public Builder contentBase64(String contentBase64) {
this.contentBase64 = contentBase64;
return this;
}
public ShippingLabel build() {
return new ShippingLabel(this);
}
}
}

12
lingxing/src/main/java/common/ecommerce/lingxing/LingxingApi.java

@ -94,6 +94,18 @@ public enum LingxingApi { @@ -94,6 +94,18 @@ public enum LingxingApi {
/** 快速出库结果查询。POST,qps 10,多平台通用。 */
FAST_OUTBOUND_RESULT("/pb/mp/order/v2/getFastOutboundResult", 10),
/** 销售出库单列表。POST,page/page_size 分页(上限 200),默认最近一个月,令牌桶 1。 */
OUTBOUND_ORDER_LIST("/erp/sc/routing/wms/order/wmsOrderList", 1),
/** 销售出库单物流面单。POST,按销售出库单号或系统单号查,单次上限 50。 */
LOGISTICS_LABEL_LIST("/erp/sc/routing/wms/order/getWmsLogisticsLabels", 1),
/** 审核发货。POST,global_order_no 数组,令牌桶 1。 */
ORDER_REVIEW("/basicOpen/openapi/multiplatform/order/review", 1),
/** 编辑订单(仓库 / 物流方式 / 包裹规格 / 报关)。POST,单次 1~50 单,令牌桶 10。 */
ORDER_EDIT("/pb/mp/order/editOrder", 10),
/** 多平台订单列表;当前实现使用的跨平台接口。 */
ORDER_LIST("/pb/mp/order/v2/list", 10);

7
lingxing/src/main/java/common/ecommerce/lingxing/LingxingConstants.java

@ -64,6 +64,13 @@ public final class LingxingConstants { @@ -64,6 +64,13 @@ public final class LingxingConstants {
/** 结算时间查询跨度上限:7 天(双闭区间)。 */
public static final int SETTLEMENT_MAX_QUERY_DAYS = 7;
/** 销售出库单分页 page_size 上限。 */
public static final int OUTBOUND_ORDER_MAX_PAGE_SIZE = 200;
/** 物流面单单次查询上限(销售出库单号与系统单号各自上限 50)。 */
public static final int LABEL_MAX_BATCH = 50;
/** 编辑订单单次上限。 */
public static final int ORDER_EDIT_MAX_BATCH = 50;
private LingxingConstants() {
}

76
lingxing/src/main/java/common/ecommerce/lingxing/adapter/LingxingAdapter.java

@ -1,10 +1,14 @@ @@ -1,10 +1,14 @@
package common.ecommerce.lingxing.adapter;
import common.ecommerce.capability.AggregatorCapable;
import common.ecommerce.capability.OrderEditCapable;
import common.ecommerce.capability.OutboundCapable;
import common.ecommerce.capability.OutboundOrderCapable;
import common.ecommerce.capability.ProductCapable;
import common.ecommerce.capability.SalesOrderCapable;
import common.ecommerce.capability.SettlementCapable;
import common.ecommerce.capability.ShipmentReviewCapable;
import common.ecommerce.capability.ShippingLabelCapable;
import common.ecommerce.error.AuthException;
import common.ecommerce.error.ChannelException;
import common.ecommerce.http.HttpTransport;
@ -15,10 +19,18 @@ import common.ecommerce.lingxing.auth.LingxingTokenClient; @@ -15,10 +19,18 @@ import common.ecommerce.lingxing.auth.LingxingTokenClient;
import common.ecommerce.lingxing.http.LingxingRateLimiter;
import common.ecommerce.lingxing.http.LingxingRequestFactory;
import common.ecommerce.lingxing.platform.LingxingCall;
import common.ecommerce.lingxing.platform.LingxingLabelSource;
import common.ecommerce.lingxing.platform.LingxingOrderEditSource;
import common.ecommerce.lingxing.platform.LingxingOutboundOrderSource;
import common.ecommerce.lingxing.platform.LingxingShipmentReviewSource;
import common.ecommerce.lingxing.platform.LingxingSubPlatform;
import common.ecommerce.lingxing.platform.LingxingSubPlatformDefaults;
import common.ecommerce.lingxing.platform.LingxingOutboundSource;
import common.ecommerce.lingxing.platform.LingxingSubPlatforms;
import common.ecommerce.lingxing.platform.wms.OrderEditSource;
import common.ecommerce.lingxing.platform.wms.ShipmentReviewSource;
import common.ecommerce.lingxing.platform.wms.WmsLabelSource;
import common.ecommerce.lingxing.platform.wms.WmsOutboundOrderSource;
import common.ecommerce.model.Capability;
import common.ecommerce.model.ChannelProvider;
import common.ecommerce.model.Platform;
@ -26,8 +38,15 @@ import common.ecommerce.model.account.ChannelAccount; @@ -26,8 +38,15 @@ import common.ecommerce.model.account.ChannelAccount;
import common.ecommerce.model.order.SalesOrder;
import common.ecommerce.model.order.SalesOrderQuery;
import common.ecommerce.model.order.SalesOrderRef;
import common.ecommerce.model.fulfillment.LabelQuery;
import common.ecommerce.model.fulfillment.OrderEditRequest;
import common.ecommerce.model.fulfillment.OrderEditResult;
import common.ecommerce.model.fulfillment.OutboundOrder;
import common.ecommerce.model.fulfillment.OutboundOrderQuery;
import common.ecommerce.model.fulfillment.OutboundPackage;
import common.ecommerce.model.fulfillment.OutboundResult;
import common.ecommerce.model.fulfillment.ShipmentReviewResult;
import common.ecommerce.model.fulfillment.ShippingLabel;
import common.ecommerce.model.product.ProductListing;
import common.ecommerce.model.product.ProductQuery;
import common.ecommerce.model.product.ProductRef;
@ -57,7 +76,8 @@ import java.util.Set; @@ -57,7 +76,8 @@ import java.util.Set;
* {@link LingxingSubPlatform}。</p>
*/
public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, SettlementCapable,
OutboundCapable, AggregatorCapable {
OutboundCapable, OutboundOrderCapable, ShippingLabelCapable, ShipmentReviewCapable,
OrderEditCapable, AggregatorCapable {
private final HttpTransport transport;
private final JacksonJsonCodec json;
@ -67,6 +87,15 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, @@ -67,6 +87,15 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable,
private final LingxingSubPlatforms subPlatforms;
/**
* ERP 级接口不区分平台,全部子平台共用同一实现,因此直接由适配器持有。
* 这些 Source 无状态,构造一次即可复用。
*/
private final LingxingOutboundOrderSource outboundOrderSource;
private final LingxingLabelSource labelSource;
private final LingxingShipmentReviewSource shipmentReviewSource;
private final LingxingOrderEditSource orderEditSource;
/**
* 适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用传入。
*
* <p>子平台装配默认用 {@code LingxingSubPlatformDefaults.all(...)};
@ -110,6 +139,10 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, @@ -110,6 +139,10 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable,
this.requestFactory = new LingxingRequestFactory(json, clock);
this.subPlatforms = subPlatforms != null ? subPlatforms
: LingxingSubPlatformDefaults.all(transport, json);
this.outboundOrderSource = new WmsOutboundOrderSource();
this.labelSource = new WmsLabelSource();
this.shipmentReviewSource = new ShipmentReviewSource();
this.orderEditSource = new OrderEditSource();
}
@Override
@ -132,7 +165,9 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, @@ -132,7 +165,9 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable,
@Override
public EnumSet<Capability> capabilities() {
return EnumSet.of(Capability.SALES_ORDER, Capability.PRODUCT, Capability.BILLING, Capability.MARK_SHIPPED);
return EnumSet.of(Capability.SALES_ORDER, Capability.PRODUCT, Capability.BILLING,
Capability.MARK_SHIPPED, Capability.OUTBOUND_ORDER, Capability.LABEL,
Capability.SHIPMENT_REVIEW, Capability.ORDER_EDIT);
}
/**
@ -163,6 +198,19 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, @@ -163,6 +198,19 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable,
if (capability == Capability.MARK_SHIPPED) {
return impl.outboundSource() != null;
}
// ERP 级接口(出库单 / 面单 / 审核发货)不按子平台区分,平台登记即支持
if (capability == Capability.OUTBOUND_ORDER) {
return outboundOrderSource != null;
}
if (capability == Capability.LABEL) {
return labelSource != null;
}
if (capability == Capability.SHIPMENT_REVIEW) {
return shipmentReviewSource != null;
}
if (capability == Capability.ORDER_EDIT) {
return orderEditSource != null;
}
return false;
}
@ -259,6 +307,30 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable, @@ -259,6 +307,30 @@ public final class LingxingAdapter implements SalesOrderCapable, ProductCapable,
return source;
}
/** 销售出库单列表(ERP 级,按店铺过滤)。 */
@Override
public Page<OutboundOrder> pull(ChannelContext ctx, OutboundOrderQuery query) {
return outboundOrderSource.outboundOrders(call(ctx), query);
}
/** 销售出库单物流面单。 */
@Override
public List<ShippingLabel> labels(ChannelContext ctx, LabelQuery query) {
return labelSource.labels(call(ctx), query);
}
/** 审核发货;逐单成败在返回值里,不靠异常表达。 */
@Override
public ShipmentReviewResult review(ChannelContext ctx, List<String> globalOrderNos) {
return shipmentReviewSource.review(call(ctx), globalOrderNos);
}
/** 批量编辑订单(仓库 / 物流方式 / 包裹规格 / 报关)。 */
@Override
public OrderEditResult edit(ChannelContext ctx, List<OrderEditRequest> requests) {
return orderEditSource.edit(call(ctx), requests);
}
@Override
public ProductSyncStrategy syncStrategy() {
// 亚马逊 Listing 支持按「All Listing 报表更新时间」增量;其它子平台接入时再各自声明

17
lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingLabelSource.java

@ -0,0 +1,17 @@ @@ -0,0 +1,17 @@
package common.ecommerce.lingxing.platform;
import common.ecommerce.model.fulfillment.LabelQuery;
import common.ecommerce.model.fulfillment.ShippingLabel;
import java.util.List;
/**
* 物流面单能力。
*
* <p>领星按销售出库单号或系统单号批量返回 base64 面单,不区分平台。</p>
*/
public interface LingxingLabelSource {
/** 批量取面单。 */
List<ShippingLabel> labels(LingxingCall call, LabelQuery query);
}

17
lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingOrderEditSource.java

@ -0,0 +1,17 @@ @@ -0,0 +1,17 @@
package common.ecommerce.lingxing.platform;
import common.ecommerce.model.fulfillment.OrderEditRequest;
import common.ecommerce.model.fulfillment.OrderEditResult;
import java.util.List;
/**
* 订单编辑能力(仓库 / 物流方式 / 包裹规格 / 报关)。
*
* <p>写操作;按领星系统单号批量编辑待审核的自发货订单。</p>
*/
public interface LingxingOrderEditSource {
/** 批量编辑订单。 */
OrderEditResult edit(LingxingCall call, List<OrderEditRequest> requests);
}

16
lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingOutboundOrderSource.java

@ -0,0 +1,16 @@ @@ -0,0 +1,16 @@
package common.ecommerce.lingxing.platform;
import common.ecommerce.model.fulfillment.OutboundOrder;
import common.ecommerce.model.fulfillment.OutboundOrderQuery;
import common.ecommerce.model.support.Page;
/**
* 子平台 / 账户的销售出库单能力。
*
* <p>领星这套接口不带平台维度,按当前账户的店铺 id 过滤,因此所有子平台共用同一实现。</p>
*/
public interface LingxingOutboundOrderSource {
/** 分页拉取销售出库单。 */
Page<OutboundOrder> outboundOrders(LingxingCall call, OutboundOrderQuery query);
}

16
lingxing/src/main/java/common/ecommerce/lingxing/platform/LingxingShipmentReviewSource.java

@ -0,0 +1,16 @@ @@ -0,0 +1,16 @@
package common.ecommerce.lingxing.platform;
import common.ecommerce.model.fulfillment.ShipmentReviewResult;
import java.util.List;
/**
* 审核发货能力。
*
* <p>写操作;按领星系统单号批量推进订单状态。</p>
*/
public interface LingxingShipmentReviewSource {
/** 批量审核发货。 */
ShipmentReviewResult review(LingxingCall call, List<String> globalOrderNos);
}

152
lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/OrderEditSource.java

@ -0,0 +1,152 @@ @@ -0,0 +1,152 @@
package common.ecommerce.lingxing.platform.wms;
import common.ecommerce.error.ChannelException;
import common.ecommerce.error.ValidationException;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.Responses;
import common.ecommerce.lingxing.LingxingApi;
import common.ecommerce.lingxing.LingxingConstants;
import common.ecommerce.lingxing.platform.LingxingCall;
import common.ecommerce.lingxing.platform.LingxingOrderEditSource;
import common.ecommerce.lingxing.platform.wms.dto.OrderEditErrorDto;
import common.ecommerce.model.ChannelProvider;
import common.ecommerce.model.fulfillment.DeclaredItem;
import common.ecommerce.model.fulfillment.OrderEditRequest;
import common.ecommerce.model.fulfillment.OrderEditResult;
import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* 领星 · 编辑订单({@code POST /pb/mp/order/editOrder})。
*
* <p>单次 1~50 单,可分别编辑仓库、物流方式、包裹预估规格与报关信息。</p>
*
* <p><b>业务码不能交给 {@code LingxingEnvelope} 判</b>:这个接口用
* {@code 0} / {@code 10000} / {@code 10001} 表示「全成功 / 全失败 / 部分成功」,
* 都属于<b>正常响应</b>,逐单原因在 {@code data.error_details[]}。
* 只有其它码(限流、token 失效、参数错误)才走统一信封抛异常。</p>
*/
public final class OrderEditSource implements LingxingOrderEditSource {
private static final String OP = "orders.edit";
private static final String CODE_SUCCESS = "0";
private static final String CODE_ALL_FAILED = "10000";
private static final String CODE_PARTIAL = "10001";
@Override
public OrderEditResult edit(LingxingCall call, List<OrderEditRequest> requests) {
if (requests == null || requests.isEmpty()) {
throw validation(call, "requests must not be empty");
}
if (requests.size() > LingxingConstants.ORDER_EDIT_MAX_BATCH) {
throw validation(call, "at most " + LingxingConstants.ORDER_EDIT_MAX_BATCH
+ " orders per call, got " + requests.size());
}
List<Map<String, Object>> orderList = new ArrayList<Map<String, Object>>(requests.size());
for (OrderEditRequest request : requests) {
orderList.add(toBody(request));
}
Map<String, Object> payload = new LinkedHashMap<String, Object>();
payload.put("order_list", orderList);
HttpRequest req = call.signed(LingxingApi.ORDER_EDIT, payload, OP);
HttpResponse resp = call.execute(req);
Responses.throwIfNotSuccess(resp, OP);
String body = resp.body();
String code = call.json().stringAt(body, "code");
if (!CODE_SUCCESS.equals(code) && !CODE_ALL_FAILED.equals(code) && !CODE_PARTIAL.equals(code)) {
// 非业务结果码:交给统一信封抛限流 / 鉴权 / 业务异常
call.envelope(resp, OP);
// 信封认为成功但码不在预期集合里(如 "200"),按业务失败处理
throw validation(call, "unexpected lingxing code=" + code + " on " + OP);
}
List<OrderEditErrorDto> errors =
call.json().listAt(body, "data.error_details", OrderEditErrorDto.class);
List<OrderEditResult.Failure> failures = new ArrayList<OrderEditResult.Failure>(errors.size());
for (OrderEditErrorDto error : errors) {
failures.add(new OrderEditResult.Failure(error.getGlobalOrderNo(), error.getErrorMessage()));
}
return OrderEditResult.builder()
.code(code)
.message(call.json().stringAt(body, "message"))
.failures(failures)
.build();
}
/** 统一模型 → 领星请求体;为空的维度不发送,未发送即保持平台原值。 */
private static Map<String, Object> toBody(OrderEditRequest request) {
Map<String, Object> item = new LinkedHashMap<String, Object>();
item.put("global_order_no", request.globalOrderNo());
Map<String, Object> logistics = new LinkedHashMap<String, Object>();
putIfNotNull(logistics, "sys_wid", request.warehouseId());
putIfNotNull(logistics, "logistics_type_id", request.logisticsTypeId());
putIfNotNull(logistics, "pre_pkg_length", decimal(request.packageLength()));
putIfNotNull(logistics, "pre_pkg_width", decimal(request.packageWidth()));
putIfNotNull(logistics, "pre_pkg_height", decimal(request.packageHeight()));
putIfNotNull(logistics, "pre_weight", decimal(request.packageWeight()));
if (!logistics.isEmpty()) {
item.put("logistics", logistics);
}
if (request.modifyDeclared()) {
item.put("modify_declared", 1);
List<Map<String, Object>> declared = new ArrayList<Map<String, Object>>(
request.declaredItems().size());
for (DeclaredItem declaredItem : request.declaredItems()) {
declared.add(toBody(declaredItem));
}
item.put("declared_info", declared);
}
return item;
}
private static Map<String, Object> toBody(DeclaredItem item) {
Map<String, Object> body = new LinkedHashMap<String, Object>();
body.put("sku", item.sku());
if (item.id() != null && item.id() > 0) {
body.put("id", item.id());
}
body.put("cn_name", item.cnName());
body.put("en_name", item.enName());
// 文档要求 unit_price / weight 是数字字符串,用 toPlainString 避免科学计数法
body.put("unit_price", decimal(item.unitPrice()));
body.put("currency_code", item.currencyCode());
body.put("weight", decimal(item.weight()));
body.put("quantity", item.quantity());
if (item.hsCode() != null && !item.hsCode().trim().isEmpty()) {
body.put("hs_code", item.hsCode().trim());
}
body.put("special_attr", new ArrayList<String>(item.specialAttributes()));
return body;
}
private static String decimal(BigDecimal value) {
return value == null ? null : value.toPlainString();
}
private static void putIfNotNull(Map<String, Object> body, String key, Object value) {
if (value != null) {
body.put(key, value);
}
}
private static ValidationException validation(LingxingCall call, String message) {
return new ValidationException(ChannelException.builder()
.message(message)
.operation(OP)
.provider(ChannelProvider.LINGXING.name())
.omsStoreId(call.ctx().omsStoreId())
.requestId(call.ctx().requestId())
.retryable(false));
}
}

90
lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/ShipmentReviewSource.java

@ -0,0 +1,90 @@ @@ -0,0 +1,90 @@
package common.ecommerce.lingxing.platform.wms;
import com.fasterxml.jackson.databind.JsonNode;
import common.ecommerce.error.ChannelException;
import common.ecommerce.error.ValidationException;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.lingxing.LingxingApi;
import common.ecommerce.lingxing.http.LingxingEnvelope;
import common.ecommerce.lingxing.platform.LingxingCall;
import common.ecommerce.lingxing.platform.LingxingShipmentReviewSource;
import common.ecommerce.lingxing.platform.wms.dto.ShipmentReviewDataDto;
import common.ecommerce.lingxing.platform.wms.dto.ShipmentReviewFailureDto;
import common.ecommerce.lingxing.platform.wms.dto.ShipmentReviewSuccessDto;
import common.ecommerce.model.ChannelProvider;
import common.ecommerce.model.fulfillment.ShipmentReviewResult;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* 领星 · 审核发货
* ({@code POST /basicOpen/openapi/multiplatform/order/review})。
*
* <p>对「订单管理 &gt; 待审核发货」的订单推进状态;接口本身返回 {@code code=0},
* 但单笔成败在 {@code data.success_info[]} / {@code data.failure_info[]} 里,
* 所以调用方必须逐单判断,不能只看 {@code code}。</p>
*
* <p>文档未给出批量上限,这里不自行加限;只拒绝空列表,避免发出无意义请求。</p>
*/
public final class ShipmentReviewSource implements LingxingShipmentReviewSource {
private static final String OP = "shipments.review";
@Override
public ShipmentReviewResult review(LingxingCall call, List<String> globalOrderNos) {
if (globalOrderNos == null || globalOrderNos.isEmpty()) {
throw validation(call, "globalOrderNos must not be empty");
}
Map<String, Object> body = new LinkedHashMap<String, Object>();
body.put("global_order_no", new ArrayList<String>(globalOrderNos));
HttpRequest req = call.signed(LingxingApi.ORDER_REVIEW, body, OP);
HttpResponse resp = call.execute(req);
LingxingEnvelope envelope = call.envelope(resp, OP);
JsonNode data = call.json().nodeAt(envelope.body(), "data");
ShipmentReviewDataDto dto = data == null || data.isNull()
? new ShipmentReviewDataDto()
: call.json().mapper().convertValue(data, ShipmentReviewDataDto.class);
List<ShipmentReviewSuccessDto> ok = dto.getSuccessInfo() == null
? new ArrayList<ShipmentReviewSuccessDto>() : dto.getSuccessInfo();
List<ShipmentReviewFailureDto> fail = dto.getFailureInfo() == null
? new ArrayList<ShipmentReviewFailureDto>() : dto.getFailureInfo();
List<String> successNos = new ArrayList<String>(ok.size());
for (ShipmentReviewSuccessDto item : ok) {
successNos.add(item.getGlobalOrderNo());
}
List<ShipmentReviewResult.Failure> failures = new ArrayList<ShipmentReviewResult.Failure>(fail.size());
for (ShipmentReviewFailureDto item : fail) {
failures.add(new ShipmentReviewResult.Failure(item.getGlobalOrderNo(), item.getMessage()));
}
// 计数缺失时用明细行数兜底,不把「没给计数」当成 0
int successNum = dto.getSuccessNum() == null ? successNos.size() : dto.getSuccessNum();
int failNum = dto.getFailNum() == null ? failures.size() : dto.getFailNum();
return ShipmentReviewResult.builder()
.successNum(successNum)
.failNum(failNum)
.successGlobalOrderNos(successNos)
.failures(failures)
.build();
}
private static ValidationException validation(LingxingCall call, String message) {
return new ValidationException(ChannelException.builder()
.message(message)
.operation(OP)
.provider(ChannelProvider.LINGXING.name())
.omsStoreId(call.ctx().omsStoreId())
.requestId(call.ctx().requestId())
.retryable(false));
}
}

84
lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/WmsLabelSource.java

@ -0,0 +1,84 @@ @@ -0,0 +1,84 @@
package common.ecommerce.lingxing.platform.wms;
import common.ecommerce.error.ChannelException;
import common.ecommerce.error.ValidationException;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.lingxing.LingxingApi;
import common.ecommerce.lingxing.LingxingConstants;
import common.ecommerce.lingxing.http.LingxingEnvelope;
import common.ecommerce.lingxing.platform.LingxingCall;
import common.ecommerce.lingxing.platform.LingxingLabelSource;
import common.ecommerce.lingxing.platform.wms.dto.WmsLogisticsLabelDto;
import common.ecommerce.model.ChannelProvider;
import common.ecommerce.model.fulfillment.LabelQuery;
import common.ecommerce.model.fulfillment.ShippingLabel;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* 领星 · 销售出库单物流面单
* ({@code POST /erp/sc/routing/wms/order/getWmsLogisticsLabels})。
*
* <p>销售出库单号与系统单号<b>二选一</b>,各自上限 50。两组都传平台只认其中一组,
* 所以这里显式拒绝,避免调用方以为两组都生效。</p>
*
* <p>返回的 {@code file_b64} 可能为空串(面单还没生成),SDK 原样返回,不补空、不重试。</p>
*/
public final class WmsLabelSource implements LingxingLabelSource {
private static final String OP = "shippingLabels.list";
@Override
public List<ShippingLabel> labels(LingxingCall call, LabelQuery query) {
boolean hasWo = !query.woNumbers().isEmpty();
boolean hasOrder = !query.orderNumbers().isEmpty();
if (hasWo == hasOrder) {
throw validation(call, "exactly one of woNumbers / orderNumbers must be provided");
}
List<String> values = hasWo ? query.woNumbers() : query.orderNumbers();
if (values.size() > LingxingConstants.LABEL_MAX_BATCH) {
throw validation(call, "at most " + LingxingConstants.LABEL_MAX_BATCH
+ " numbers per call, got " + values.size());
}
Map<String, Object> body = new LinkedHashMap<String, Object>();
body.put(hasWo ? "wo_number_arr" : "order_number_arr", new ArrayList<String>(values));
HttpRequest req = call.signed(LingxingApi.LOGISTICS_LABEL_LIST, body, OP);
HttpResponse resp = call.execute(req);
LingxingEnvelope envelope = call.envelope(resp, OP);
List<WmsLogisticsLabelDto> dtos = call.json().listAt(envelope.body(), "data", WmsLogisticsLabelDto.class);
List<ShippingLabel> labels = new ArrayList<ShippingLabel>(dtos.size());
for (WmsLogisticsLabelDto dto : dtos) {
labels.add(ShippingLabel.builder()
.omsStoreId(call.ctx().omsStoreId())
.sourceProvider(ChannelProvider.LINGXING)
.woNumber(dto.getWoNumber())
.orderNumber(dto.getOrderNumber())
.logisticsProviderId(dto.getLogisticsProviderId())
.logisticsTypeId(dto.getLogisticsTypeId())
.fileId(dto.getFileId())
.fileType(dto.getFileType())
.fileSize(dto.getFileSize())
.contentBase64(dto.getFileB64())
.build());
}
return labels;
}
private static ValidationException validation(LingxingCall call, String message) {
return new ValidationException(ChannelException.builder()
.message(message)
.operation(OP)
.provider(ChannelProvider.LINGXING.name())
.omsStoreId(call.ctx().omsStoreId())
.requestId(call.ctx().requestId())
.retryable(false));
}
}

290
lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/WmsOutboundOrderSource.java

@ -0,0 +1,290 @@ @@ -0,0 +1,290 @@
package common.ecommerce.lingxing.platform.wms;
import common.ecommerce.error.ChannelException;
import common.ecommerce.error.ValidationException;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.lingxing.LingxingApi;
import common.ecommerce.lingxing.LingxingConstants;
import common.ecommerce.lingxing.http.LingxingEnvelope;
import common.ecommerce.lingxing.mapper.LingxingOrderMapper;
import common.ecommerce.lingxing.platform.LingxingCall;
import common.ecommerce.lingxing.platform.LingxingOutboundOrderSource;
import common.ecommerce.lingxing.platform.wms.dto.WmsOutboundOrderDto;
import common.ecommerce.lingxing.platform.wms.dto.WmsOutboundOrderItemDto;
import common.ecommerce.lingxing.platform.wms.dto.WmsSurfaceFileDto;
import common.ecommerce.model.ChannelProvider;
import common.ecommerce.model.account.ChannelAccount;
import common.ecommerce.model.fulfillment.OutboundOrder;
import common.ecommerce.model.fulfillment.OutboundOrderLine;
import common.ecommerce.model.fulfillment.OutboundOrderQuery;
import common.ecommerce.model.support.Money;
import common.ecommerce.model.support.Page;
import common.ecommerce.model.support.PlatformTime;
import java.time.Instant;
import java.time.LocalDateTime;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* 领星 · 销售出库单列表
* ({@code POST /erp/sc/routing/wms/order/wmsOrderList})。
*
* <p>接口不带平台维度,按店铺 {@code sid_arr} 过滤,因此所有子平台共用同一实现:
* 默认用当前账户的 {@code externalStoreId},调用方也可以用
* {@link OutboundOrderQuery#sids()} 覆盖。</p>
*
* <p>分页是 {@code page} / {@code page_size}(上限 200),游标存的是<b>字符串化的页码</b>,
* 与 order 类接口的 offset 游标不同。</p>
*
* <p>时间窗按 ERP 系统时间(北京时间)解释,格式 {@code Y-m-d};
* 不传时由领星按「最近一个月」处理。</p>
*/
public final class WmsOutboundOrderSource implements LingxingOutboundOrderSource {
private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd");
private static final DateTimeFormatter DATE_TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
/** 领星用全零占位表示「没有时间」。 */
private static final String ZERO_DATE_TIME = "0000-00-00 00:00:00";
/** 文档未注明时区,按 ERP 系统时间(北京时间)解释。 */
private static final ZoneId SYSTEM_ZONE = PlatformTime.BEIJING_ZONE;
private static final List<String> TIME_TYPES = Collections.unmodifiableList(Arrays.asList(
OutboundOrderQuery.TIME_CREATED,
OutboundOrderQuery.TIME_DELIVERED,
OutboundOrderQuery.TIME_STOCK_DELIVERED,
OutboundOrderQuery.TIME_UPDATED));
private static final String OP = "outboundOrders.pull";
@Override
public Page<OutboundOrder> outboundOrders(LingxingCall call, OutboundOrderQuery query) {
ChannelAccount account = call.ctx().account();
String timeType = query.timeType() == null ? OutboundOrderQuery.TIME_UPDATED : query.timeType();
if (!TIME_TYPES.contains(timeType)) {
throw validation(call, OP, "unsupported time_type: " + timeType);
}
int pageSize = query.pageSize() <= 0 ? 20
: Math.min(query.pageSize(), LingxingConstants.OUTBOUND_ORDER_MAX_PAGE_SIZE);
int page = query.cursor() == null ? 1 : Integer.parseInt(query.cursor());
Map<String, Object> body = new LinkedHashMap<String, Object>();
body.put("page", page);
body.put("page_size", pageSize);
body.put("time_type", timeType);
putIfNotEmpty(body, "sid_arr", resolveSids(call, query));
putIfNotEmpty(body, "status_arr", query.statuses());
putIfNotEmpty(body, "logistics_status_arr", query.logisticsStatuses());
putIfNotEmpty(body, "platform_order_no_arr", query.platformOrderNos());
putIfNotEmpty(body, "order_number_arr", query.orderNumbers());
putIfNotEmpty(body, "wo_number_arr", query.woNumbers());
if (query.after() != null) {
body.put("start_date", DATE.format(LocalDateTime.ofInstant(query.after(), SYSTEM_ZONE)));
}
if (query.before() != null) {
body.put("end_date", DATE.format(LocalDateTime.ofInstant(query.before(), SYSTEM_ZONE)));
}
HttpRequest req = call.signed(LingxingApi.OUTBOUND_ORDER_LIST, body, OP);
HttpResponse resp = call.execute(req);
LingxingEnvelope envelope = call.envelope(resp, OP);
List<WmsOutboundOrderDto> dtos = call.json().listAt(envelope.body(), "data", WmsOutboundOrderDto.class);
ZoneId zone = ZoneId.of(account.marketplaceZone());
List<OutboundOrder> orders = new ArrayList<OutboundOrder>(dtos.size());
for (WmsOutboundOrderDto dto : dtos) {
try {
orders.add(toOutboundOrder(dto, call, account, zone));
} catch (RuntimeException e) {
throw mappingFailure(e, envelope, call);
}
}
boolean hasMore = dtos.size() >= pageSize
&& (envelope.total() < 0 || (long) page * pageSize < envelope.total());
return Page.of(orders, hasMore ? String.valueOf(page + 1) : null);
}
/**
* 店铺过滤:调用方显式给了 {@code sids} 就用它,否则用当前账户的店铺。
*
* <p>账户店铺 id 不是数字时<b>显式失败</b>:不带 {@code sid_arr} 会返回该 app 下
* 所有店铺的出库单,等于跨店铺泄露数据。</p>
*/
private static List<Long> resolveSids(LingxingCall call, OutboundOrderQuery query) {
if (!query.sids().isEmpty()) {
List<Long> sids = new ArrayList<Long>(query.sids().size());
for (String raw : query.sids()) {
Long sid = parseLong(raw);
if (sid == null) {
throw validation(call, OP, "sid must be numeric: " + raw);
}
sids.add(sid);
}
return sids;
}
Long sid = parseLong(call.ctx().account().externalStoreId());
if (sid == null) {
throw validation(call, OP, "account externalStoreId is not a numeric lingxing sid: "
+ call.ctx().account().externalStoreId() + "; set OutboundOrderQuery.sids explicitly");
}
return Collections.singletonList(sid);
}
private static OutboundOrder toOutboundOrder(WmsOutboundOrderDto dto, LingxingCall call,
ChannelAccount account, ZoneId zone) {
WmsSurfaceFileDto surface = dto.getSurfaceFile();
return OutboundOrder.builder()
.omsStoreId(call.ctx().omsStoreId())
.sourceProvider(ChannelProvider.LINGXING)
.sourceAccountId(dto.getSid() == null ? null : String.valueOf(dto.getSid()))
.woNumber(dto.getWoNumber())
.woId(dto.getWoId() == null ? null : String.valueOf(dto.getWoId()))
.orderNumber(trimToNull(dto.getOrderNumber()))
.platformOrderNos(safe(dto.getPlatformOrderNo()))
.sid(dto.getSid())
.sellerName(trimToNull(dto.getSellerName()))
.warehouseId(dto.getWid())
.warehouseName(trimToNull(dto.getWarehouseName()))
.warehouseType(dto.getWarehouseType())
.status(dto.getStatus())
.statusName(trimToNull(dto.getStatusName()))
.logisticsStatus(dto.getLogisticsStatus())
.logisticsStatusName(trimToNull(dto.getLogisticsStatusName()))
.logisticsMessage(trimToNull(dto.getLogisticsMessage()))
.logisticsProviderId(dto.getLogisticsProviderId())
.logisticsProviderName(trimToNull(dto.getLogisticsProviderName()))
.logisticsTypeId(dto.getLogisticsTypeId())
.logisticsTypeName(trimToNull(dto.getLogisticsTypeName()))
.waybillNo(trimToNull(dto.getWaybillNo()))
.trackingNo(trimToNull(dto.getTrackingNo()))
.orderAmount(moneyOrNull(dto.getOrderOriginAmount(), dto.getOrderCurrencyCode()))
.targetCountry(trimToNull(dto.getTargetCountry()))
.packageWeight(trimToNull(dto.getPkgWeight()))
.packageRealWeight(trimToNull(dto.getPkgRealWeight()))
.packageFeeWeight(trimToNull(dto.getPkgFeeWeight()))
.packageWeightUnit(trimToNull(dto.getPkgWeightUnit()))
.surfaceFileUrl(surfaceUrl(surface))
.createdAt(platformTime(dto.getCreateAt(), zone))
.updatedAt(platformTime(dto.getUpdateAt(), zone))
.deliveredAt(platformTime(dto.getDeliveredAt(), zone))
.purchasedAt(platformTime(dto.getPurchaseTime(), zone))
.lines(toLines(dto.getProductInfo()))
.build();
}
private static List<OutboundOrderLine> toLines(List<WmsOutboundOrderItemDto> items) {
List<OutboundOrderLine> lines = new ArrayList<OutboundOrderLine>(items.size());
for (WmsOutboundOrderItemDto item : items) {
lines.add(OutboundOrderLine.builder()
.lineId(item.getWodId() == null ? null : String.valueOf(item.getWodId()))
.productId(item.getProductId() == null ? null : String.valueOf(item.getProductId()))
.sku(trimToNull(item.getSku()))
.sellerSku(trimToNull(item.getSellerSku()))
.productName(trimToNull(item.getProductName()))
.quantity(item.getCount() == null ? 0 : item.getCount())
.unitPrice(moneyOrNull(item.getUnitPrice(), item.getCurrencyCode()))
.build());
}
return lines;
}
private static PlatformTime platformTime(String value, ZoneId zone) {
Instant instant = parseDateTime(value);
return instant == null ? null : PlatformTime.of(instant, zone);
}
/** 面单链接:优先 COS(30 分钟有效),旧 {@code uri} 仅兜底。 */
private static String surfaceUrl(WmsSurfaceFileDto surface) {
if (surface == null) {
return null;
}
String cos = trimToNull(surface.getCosUrl());
return cos != null ? cos : trimToNull(surface.getUri());
}
private static Instant parseDateTime(String value) {
String text = trimToNull(value);
if (text == null || ZERO_DATE_TIME.equals(text)) {
return null;
}
LocalDateTime local = LocalDateTime.parse(text, DATE_TIME);
return local.atZone(SYSTEM_ZONE).toInstant();
}
/**
* 金额映射。
*
* <p>领星商品行里的 {@code currency_code} 可能是符号(文档示例是 {@code $}),
* 不是 ISO 代码,此时只保留金额无意义,直接返回 null,不猜币种。</p>
*/
private static Money moneyOrNull(String amount, String currency) {
String cleaned = LingxingOrderMapper.cleanAmount(amount);
String code = trimToNull(currency);
if (cleaned == null || code == null || !code.matches("[A-Za-z]{3}")) {
return null;
}
return Money.of(cleaned, code.toUpperCase());
}
private static void putIfNotEmpty(Map<String, Object> body, String key, List<?> values) {
if (values != null && !values.isEmpty()) {
body.put(key, values);
}
}
private static Long parseLong(String value) {
String text = trimToNull(value);
if (text == null) {
return null;
}
try {
return Long.valueOf(text);
} catch (NumberFormatException e) {
return null;
}
}
private static <T> List<T> safe(List<T> in) {
return in == null ? Collections.<T>emptyList() : in;
}
private static String trimToNull(String value) {
if (value == null) {
return null;
}
String trimmed = value.trim();
return trimmed.isEmpty() ? null : trimmed;
}
private static ValidationException validation(LingxingCall call, String operation, String message) {
return new ValidationException(ChannelException.builder()
.message(message)
.operation(operation)
.provider(ChannelProvider.LINGXING.name())
.omsStoreId(call.ctx().omsStoreId())
.requestId(call.ctx().requestId())
.retryable(false));
}
private static ValidationException mappingFailure(RuntimeException e, LingxingEnvelope envelope,
LingxingCall call) {
return new ValidationException(ChannelException.builder()
.message("lingxing outbound order mapping failed: " + e.getMessage())
.operation(OP)
.provider(ChannelProvider.LINGXING.name())
.omsStoreId(call.ctx().omsStoreId())
.requestId(call.ctx().requestId())
.rawResponse(envelope.body()), e);
}
}

24
lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/OrderEditErrorDto.java

@ -0,0 +1,24 @@ @@ -0,0 +1,24 @@
package common.ecommerce.lingxing.platform.wms.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.Getter;
import lombok.Setter;
/**
* 编辑订单的逐单错误({@code data.error_details[]})。
*
* <p>平台把 {@code global_order_no} 作为 long 返回,这里按字符串接收,
* 避免超出 JS/JavaScript 与 double 的安全整数范围。</p>
*/
@Getter
@Setter
@JsonIgnoreProperties(ignoreUnknown = true)
public class OrderEditErrorDto {
@JsonProperty("global_order_no")
private String globalOrderNo;
@JsonProperty("error_message")
private String errorMessage;
}

33
lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/ShipmentReviewDataDto.java

@ -0,0 +1,33 @@ @@ -0,0 +1,33 @@
package common.ecommerce.lingxing.platform.wms.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.Getter;
import lombok.Setter;
import java.util.ArrayList;
import java.util.List;
/**
* 审核发货响应体({@code data})。
*
* <p>接口按单返回结果:{@code success_num} / {@code fail_num} 是计数,
* 逐单明细在 {@code success_info} / {@code failure_info} 里。</p>
*/
@Getter
@Setter
@JsonIgnoreProperties(ignoreUnknown = true)
public class ShipmentReviewDataDto {
@JsonProperty("success_num")
private Integer successNum;
@JsonProperty("fail_num")
private Integer failNum;
@JsonProperty("success_info")
private List<ShipmentReviewSuccessDto> successInfo = new ArrayList<ShipmentReviewSuccessDto>();
@JsonProperty("failure_info")
private List<ShipmentReviewFailureDto> failureInfo = new ArrayList<ShipmentReviewFailureDto>();
}

21
lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/ShipmentReviewFailureDto.java

@ -0,0 +1,21 @@ @@ -0,0 +1,21 @@
package common.ecommerce.lingxing.platform.wms.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.Getter;
import lombok.Setter;
/** 审核发货失败项({@code data.failure_info[]})。 */
@Getter
@Setter
@JsonIgnoreProperties(ignoreUnknown = true)
public class ShipmentReviewFailureDto {
/** 系统单号。 */
@JsonProperty("global_order_no")
private String globalOrderNo;
/** 失败原因,如「未设置物流」。 */
@JsonProperty("message")
private String message;
}

17
lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/ShipmentReviewSuccessDto.java

@ -0,0 +1,17 @@ @@ -0,0 +1,17 @@
package common.ecommerce.lingxing.platform.wms.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.Getter;
import lombok.Setter;
/** 审核发货成功项({@code data.success_info[]})。 */
@Getter
@Setter
@JsonIgnoreProperties(ignoreUnknown = true)
public class ShipmentReviewSuccessDto {
/** 系统单号。 */
@JsonProperty("global_order_no")
private String globalOrderNo;
}

47
lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/WmsLogisticsLabelDto.java

@ -0,0 +1,47 @@ @@ -0,0 +1,47 @@
package common.ecommerce.lingxing.platform.wms.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.Getter;
import lombok.Setter;
/**
* 领星 · 销售出库单物流面单
* ({@code /erp/sc/routing/wms/order/getWmsLogisticsLabels} 的 {@code data[]})。
*
* <p>面单内容以 base64 返回,SDK 不落文件。</p>
*/
@Getter
@Setter
@JsonIgnoreProperties(ignoreUnknown = true)
public class WmsLogisticsLabelDto {
/** 销售出库单号。 */
@JsonProperty("wo_number")
private String woNumber;
/** 领星系统单号。 */
@JsonProperty("order_number")
private String orderNumber;
@JsonProperty("logistics_provider_id")
private Long logisticsProviderId;
@JsonProperty("logistics_type_id")
private Long logisticsTypeId;
@JsonProperty("file_id")
private Long fileId;
/** 文件类型,如 pdf。 */
@JsonProperty("file_type")
private String fileType;
/** 文件尺寸。 */
@JsonProperty("file_size")
private String fileSize;
/** 面单 base64。 */
@JsonProperty("file_b64")
private String fileB64;
}

162
lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/WmsOutboundOrderDto.java

@ -0,0 +1,162 @@ @@ -0,0 +1,162 @@
package common.ecommerce.lingxing.platform.wms.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.Getter;
import lombok.Setter;
import java.util.ArrayList;
import java.util.List;
/**
* 领星 · 销售出库单
* ({@code /erp/sc/routing/wms/order/wmsOrderList} 的 {@code data[]})。
*
* <p>主键是 {@code wo_number}(销售出库单号),{@code order_number} 才是领星系统单号。</p>
*/
@Getter
@Setter
@JsonIgnoreProperties(ignoreUnknown = true)
public class WmsOutboundOrderDto {
/** 出库单 id。 */
@JsonProperty("wo_id")
private Long woId;
/** 销售出库单号。 */
@JsonProperty("wo_number")
private String woNumber;
/** 店铺 id(领星内部 sid)。 */
@JsonProperty("sid")
private Integer sid;
@JsonProperty("seller_name")
private String sellerName;
/** 站点名称,如 [Amazon].美国。 */
@JsonProperty("site_text")
private String siteText;
@JsonProperty("wid")
private Integer wid;
@JsonProperty("warehouse_name")
private String warehouseName;
/** 仓库类型:1 本地仓库、2 FBA 仓、3 第三方海外仓。 */
@JsonProperty("warehouse_type")
private Integer warehouseType;
/** 下单流程:1 物流、2 海外仓、3 仓配分离。 */
@JsonProperty("logistics_way")
private Integer logisticsWay;
@JsonProperty("batch_no")
private String batchNo;
@JsonProperty("reference_no")
private String referenceNo;
/** 运单号。 */
@JsonProperty("waybill_no")
private String waybillNo;
/** 跟踪号。 */
@JsonProperty("tracking_no")
private String trackingNo;
@JsonProperty("picker")
private String picker;
@JsonProperty("platform_name")
private String platformName;
/** 平台单号,数组。 */
@JsonProperty("platform_order_no")
private List<String> platformOrderNo = new ArrayList<String>();
/** 领星系统单号。 */
@JsonProperty("order_number")
private String orderNumber;
@JsonProperty("order_from")
private String orderFrom;
/** 订单类型:1 一单一件、2 多品多件、3 单品多件。 */
@JsonProperty("order_type")
private Integer orderType;
@JsonProperty("order_origin_amount")
private String orderOriginAmount;
@JsonProperty("order_currency_code")
private String orderCurrencyCode;
/** 出库单状态:1 物流下单、2 待出库、3 已出库、4 已截单。 */
@JsonProperty("status")
private Integer status;
@JsonProperty("status_name")
private String statusName;
/** 物流下单状态。 */
@JsonProperty("logistics_status")
private Integer logisticsStatus;
@JsonProperty("logistics_status_name")
private String logisticsStatusName;
@JsonProperty("logistics_message")
private String logisticsMessage;
@JsonProperty("logistics_provider_id")
private Long logisticsProviderId;
@JsonProperty("logistics_provider_name")
private String logisticsProviderName;
@JsonProperty("logistics_type_id")
private Long logisticsTypeId;
@JsonProperty("logistics_type_name")
private String logisticsTypeName;
@JsonProperty("target_country")
private String targetCountry;
@JsonProperty("pkg_weight")
private String pkgWeight;
@JsonProperty("pkg_real_weight")
private String pkgRealWeight;
@JsonProperty("pkg_fee_weight")
private String pkgFeeWeight;
@JsonProperty("pkg_weight_unit")
private String pkgWeightUnit;
/** 面单文件。 */
@JsonProperty("surface_file")
private WmsSurfaceFileDto surfaceFile;
@JsonProperty("delivered_at")
private String deliveredAt;
@JsonProperty("stock_delivered_at")
private String stockDeliveredAt;
@JsonProperty("create_at")
private String createAt;
@JsonProperty("update_at")
private String updateAt;
@JsonProperty("purchase_time")
private String purchaseTime;
/** 商品行。 */
@JsonProperty("product_info")
private List<WmsOutboundOrderItemDto> productInfo = new ArrayList<WmsOutboundOrderItemDto>();
}

51
lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/WmsOutboundOrderItemDto.java

@ -0,0 +1,51 @@ @@ -0,0 +1,51 @@
package common.ecommerce.lingxing.platform.wms.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.Getter;
import lombok.Setter;
/**
* 领星 · 销售出库单商品行({@code product_info[]})。
*
* <p>{@code sku} 是领星本地 SKU,{@code seller_sku} 才是平台 MSKU,两者不要混用。</p>
*/
@Getter
@Setter
@JsonIgnoreProperties(ignoreUnknown = true)
public class WmsOutboundOrderItemDto {
/** 出库单明细 id。 */
@JsonProperty("wod_id")
private Long wodId;
@JsonProperty("product_id")
private Long productId;
/** 领星本地 SKU。 */
@JsonProperty("sku")
private String sku;
/** 平台 MSKU。 */
@JsonProperty("seller_sku")
private String sellerSku;
@JsonProperty("product_name")
private String productName;
@JsonProperty("count")
private Integer count;
@JsonProperty("unit_price")
private String unitPrice;
/** 币种;领星可能给符号而非代码。 */
@JsonProperty("currency_code")
private String currencyCode;
@JsonProperty("item_unit_price")
private String itemUnitPrice;
@JsonProperty("item_total_price")
private String itemTotalPrice;
}

34
lingxing/src/main/java/common/ecommerce/lingxing/platform/wms/dto/WmsSurfaceFileDto.java

@ -0,0 +1,34 @@ @@ -0,0 +1,34 @@
package common.ecommerce.lingxing.platform.wms.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonProperty;
import lombok.Getter;
import lombok.Setter;
/**
* 领星 · 出库单面单文件({@code surface_file})。
*
* <p>{@code cos_url} 是 30 分钟有效的 COS 链接,过期后需要重新查询;
* {@code uri} 官方已标记废弃,只做兜底。</p>
*/
@Getter
@Setter
@JsonIgnoreProperties(ignoreUnknown = true)
public class WmsSurfaceFileDto {
/** COS 地址链接,30 分钟有效。 */
@JsonProperty("cos_url")
private String cosUrl;
/** 旧链接,已废弃。 */
@JsonProperty("uri")
private String uri;
/** 文件后缀,如 pdf。 */
@JsonProperty("ext")
private String ext;
/** 文件尺寸。 */
@JsonProperty("size")
private String size;
}

127
lingxing/src/test/java/common/ecommerce/lingxing/adapter/LingxingLiveSmokeTest.java

@ -12,6 +12,11 @@ import common.ecommerce.model.ChannelProvider; @@ -12,6 +12,11 @@ import common.ecommerce.model.ChannelProvider;
import common.ecommerce.model.Platform;
import common.ecommerce.model.account.AccountKey;
import common.ecommerce.model.account.ChannelAccount;
import common.ecommerce.model.fulfillment.LabelQuery;
import common.ecommerce.model.fulfillment.OutboundOrder;
import common.ecommerce.model.fulfillment.OutboundOrderLine;
import common.ecommerce.model.fulfillment.OutboundOrderQuery;
import common.ecommerce.model.fulfillment.ShippingLabel;
import common.ecommerce.model.order.SalesOrder;
import common.ecommerce.model.order.SalesOrderQuery;
import common.ecommerce.model.order.SalesOrderRef;
@ -32,6 +37,7 @@ import java.time.Clock; @@ -32,6 +37,7 @@ import java.time.Clock;
import java.time.Duration;
import java.time.Instant;
import java.time.LocalDate;
import java.util.ArrayList;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertFalse;
@ -64,6 +70,9 @@ class LingxingLiveSmokeTest { @@ -64,6 +70,9 @@ class LingxingLiveSmokeTest {
private static final int PLATFORM_CODE = 10008;
private static final String BASE_URL = LingxingConstants.PRODUCTION_BASE_URL;
/** 面单冒烟只取前几单,避免把大段 base64 刷到控制台。 */
private static final int LABEL_SMOKE_LIMIT = 5;
private final JacksonJsonCodec json = new JacksonJsonCodec();
private final LoggingTransport transport = new LoggingTransport(new OkHttpTransport("common-ecommerce-smoke"));
private final InMemoryTokenStore tokenStore = new InMemoryTokenStore();
@ -346,8 +355,126 @@ class LingxingLiveSmokeTest { @@ -346,8 +355,126 @@ class LingxingLiveSmokeTest {
}
}
/**
* 第 7 步(仓库):拉一页销售出库单,打印单据与商品行,人工核对字段映射。
*
* <p>{@code /erp/sc/routing/wms/order/wmsOrderList} 按店铺<b>数字 sid</b> 过滤,
* 所以用亚马逊店铺列表返回的 {@code sid},而不是多平台的 {@code store_id}
* (后者不是数字,适配器会直接拒绝,避免跨店铺返回数据)。</p>
*/
@Test
void pullsOutboundOrders() {
requireCredentials();
LingxingAdapter adapter = adapter();
// String sid = firstAmazonShopSid(adapter);
// if (sid == null) {
// System.out.println("[outbound orders] 没有亚马逊店铺(WMS 需要数字 sid),跳过");
// return;
// }
String sid = "15898";
ChannelContext ctx = context(amazonAccount(sid), "smoke-outbound-orders-");
Page<OutboundOrder> page = pullOneOutboundPage(adapter, ctx);
System.out.println("[outbound orders] sid=" + sid
+ " window=最近 30 天 items=" + page.size()
+ " nextCursor=" + page.nextCursor());
for (OutboundOrder o : page.items()) {
System.out.println(" wo_number=" + o.woNumber()
+ " order_number=" + o.orderNumber()
+ " status=" + o.status() + "/" + o.statusName()
+ " logistics=" + o.logisticsStatus() + "/" + o.logisticsStatusName()
+ " warehouse=" + o.warehouseId() + "/" + o.warehouseName()
+ " waybillNO=" + o.waybillNo()
+ " amount=" + o.orderAmount()
+ " lines=" + o.lines().size()
+ " createdAt=" + (o.createdAt() == null ? null : o.createdAt().utc())
+ " surface=" + o.surfaceFileUrl());
for (OutboundOrderLine line : o.lines()) {
System.out.println(" sku=" + line.sku()
+ " msku=" + line.sellerSku()
+ " qty=" + line.quantity()
+ " unit=" + line.unitPrice());
}
}
assertFalse(page.size() > 20, "pageSize 未被平台遵守");
}
/**
* 第 8 步(面单):用上一步的出库单号取面单,再按系统单号查一次。
*
* <p>{@code wo_number_arr} 与 {@code order_number_arr} 二选一,两条路径都跑,
* 确认字段名与 base64 返回。文档提示面单可能尚未生成,此时 {@code file_b64} 为空串。</p>
*/
@Test
void pullsShippingLabels() {
requireCredentials();
LingxingAdapter adapter = adapter();
// String sid = firstAmazonShopSid(adapter);
// if (sid == null) {
// System.out.println("[labels] 没有亚马逊店铺(WMS 需要数字 sid),跳过");
// return;
// }
String sid = "15898";
ChannelContext ctx = context(amazonAccount(sid), "smoke-labels-");
Page<OutboundOrder> page = pullOneOutboundPage(adapter, ctx);
if (page.items().isEmpty()) {
System.out.println("[labels] 最近 30 天没有出库单,跳过");
return;
}
List<String> woNumbers = new ArrayList<>();
List<String> orderNumbers = new ArrayList<>();
for (OutboundOrder o : page.items()) {
if (woNumbers.size() >= LABEL_SMOKE_LIMIT) {
break;
}
woNumbers.add(o.woNumber());
if (o.orderNumber() != null) {
orderNumbers.add(o.orderNumber());
}
}
printLabels("wo_number_arr", adapter.labels(ctx,
LabelQuery.builder().woNumbers(woNumbers).build()));
if (!orderNumbers.isEmpty()) {
printLabels("order_number_arr", adapter.labels(ctx,
LabelQuery.builder().orderNumbers(orderNumbers).build()));
}
}
// ---------------------------------------------------------------- helpers
/** 拉一页销售出库单(最近 30 天,按创建时间),两个仓储用例共用。 */
private static Page<OutboundOrder> pullOneOutboundPage(LingxingAdapter adapter, ChannelContext ctx) {
Instant to = Instant.now();
Instant from = to.minus(Duration.ofDays(30));
return adapter.pull(ctx, OutboundOrderQuery.builder()
.after(from)
.before(to)
.timeType(OutboundOrderQuery.TIME_CREATED)
.pageSize(20)
.build());
}
/** 只打 base64 长度,避免把整张面单刷到控制台。 */
private static void printLabels(String queryKey, List<ShippingLabel> labels) {
System.out.println("[labels] " + queryKey + " count=" + labels.size());
for (ShippingLabel label : labels) {
String base64 = label.contentBase64();
System.out.println(" wo_number=" + label.woNumber()
+ " order_number=" + label.orderNumber()
+ " provider=" + label.logisticsProviderId()
+ " typeId=" + label.logisticsTypeId()
+ " fileType=" + label.fileType()
+ " fileSize=" + label.fileSize()
+ " b64=" + (base64 == null ? "null" : base64.length() + " chars"));
}
}
/** 认证只需要 AppID/AppSecret。 */
private static void requireCredentials() {
org.junit.jupiter.api.Assumptions.assumeTrue(

Loading…
Cancel
Save