Browse Source
四个接口真机均确认存在,但都不做参数校验(thirdParty 那两个回 403, handlePage / handlingMethod 回 500+999999),必填项按文档实现。 - 请求形态两套:thirdParty 两个是双层包裹 params,handlePage 与 handlingMethod 是平铺;发错形态仓方当成空请求 - 详情:SKU 明细落 lines,换标明细 changeSku 落 newSku; 待处理 / 已处理列表不塞进 lines(那是 SKU 维度) - sourceType 两页文档顺序相反(创建页 1 无来源、详情页 1 销售), 适配器不解释,原值保留在 type() - 列表:page/size 文档标 string 转字符串下发;状态过滤是单值,多给即拒绝; 仓库 code 收逗号拼接;RETURNING 对应 20 或 35,无法唯一映射返回 null - 处理单列表:过滤条件全是数组;返回仓方处理行(无对应统一模型); 时间戳是 ISO 带时区,解析转换后使用 - 处理方式:四项定位(returnPlanNo+returnNo+erpSku+tracking)不用行 id; 两级处理方式;继续拍照必须给 photosQuantity - core ReturnProcessCommand:lineId 改 Long 可空、disposition 改可空 (与 primaryHandlingMethod 至少给一个)、补 6 个字段;运去哪缺 lineId 时 在适配器里显式拒绝,已加守卫 验证:mvn test 全量通过,恒健 293 个用例(+18)通过。 Co-Authored-By: Claude Code <noreply@anthropic.com>feature/Walmart
11 changed files with 1842 additions and 30 deletions
@ -0,0 +1,486 @@
@@ -0,0 +1,486 @@
|
||||
package common.ecommerce.hengjian.adapter; |
||||
|
||||
import common.ecommerce.hengjian.dto.HengjianReturnDetailDtos; |
||||
import common.ecommerce.hengjian.dto.HengjianReturnHandleDtos; |
||||
import common.ecommerce.hengjian.dto.HengjianReturnListDtos; |
||||
import common.ecommerce.hengjian.enums.HengjianReturnPlanStatus; |
||||
import common.ecommerce.shared.support.Page; |
||||
import common.ecommerce.warehouse.enums.ReturnProcessDisposition; |
||||
import common.ecommerce.warehouse.enums.ReturnStatus; |
||||
import common.ecommerce.warehouse.enums.WarehouseProvider; |
||||
import common.ecommerce.warehouse.model.ReturnProcessCommand; |
||||
import common.ecommerce.warehouse.model.WarehouseAttachment; |
||||
import common.ecommerce.warehouse.model.WarehouseReturn; |
||||
|
||||
import java.time.Instant; |
||||
import java.time.LocalDate; |
||||
import java.time.LocalDateTime; |
||||
import java.time.ZoneOffset; |
||||
import java.time.format.DateTimeFormatter; |
||||
import java.time.format.DateTimeParseException; |
||||
import java.util.ArrayList; |
||||
import java.util.List; |
||||
import java.util.Locale; |
||||
|
||||
/** |
||||
* 恒健退货查询 / 处理方式映射。 |
||||
* |
||||
* <h2>三套码表,别混</h2> |
||||
* <table border="1"> |
||||
* <tr><th>码表</th><th>取值</th></tr> |
||||
* <tr><td>计划状态 {@code returnPlanStatus}</td> |
||||
* <td>0 草稿 / 5 待审核 / 10 审核拒回 / 15 待收货 / 20 待处理 / |
||||
* 25 已完成 / 30 已取消 / 35 处理中</td></tr> |
||||
* <tr><td>处理状态 {@code handlingStatus}</td> |
||||
* <td>5 待处理 / 10 处理中 / 15 已完成 / 20 已取消</td></tr> |
||||
* <tr><td>主要处理方式 {@code primaryHandlingMethod}</td> |
||||
* <td>101 拍外观 / 102 拆箱拍照 / 103 拆箱拍照并封箱 / 201 销毁 / |
||||
* 202 上架良品 / 203 换标上架 / 204 卖家自提 / 205 重新包装 / |
||||
* 206 仓库拆箱判断</td></tr> |
||||
* </table> |
||||
* <p><b>三套互不通用</b>:同样是 {@code 20},在计划状态里是「待处理」、 |
||||
* 在处理状态里是「已取消」。</p> |
||||
* |
||||
* <h2>sourceType 两页顺序相反</h2> |
||||
* <p>创建页写「1 无来源退货 2 销售退货」,详情页写「1 销售退货 2 无来源退货」。 |
||||
* <b>两页矛盾</b>,适配器不解释该字段,原值保留在 {@code WarehouseReturn.type()}。</p> |
||||
* |
||||
* <h2>请求形态两套</h2> |
||||
* <p>{@code getReturnPlanOrderInfo} / {@code getReturnPlanOrderPage} 是 |
||||
* <b>双层包裹</b>({@code {"params":{...}}});{@code getReturnPlanHandlePage} / |
||||
* {@code handlingMethod} 是<b>平铺</b>。发错形态仓方会当成空请求。</p> |
||||
*/ |
||||
public final class HengjianReturnQueryMapper { |
||||
|
||||
private static final DateTimeFormatter DATE_TIME = |
||||
DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); |
||||
private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd"); |
||||
|
||||
/** 退货计划列表 rows 上限:文档没写,按同站惯例取 100。 */ |
||||
static final int MAX_ROWS = 100; |
||||
|
||||
/** 处理单列表单页上限:文档没写,取 100;超限拒绝不截断。 */ |
||||
static final int HANDLE_MAX_ROWS = 100; |
||||
|
||||
private HengjianReturnQueryMapper() { |
||||
} |
||||
|
||||
// ================================================================ 详情
|
||||
|
||||
/** 详情请求:双层包裹。 */ |
||||
public static HengjianReturnDetailDtos.DetailRequest toDetailRequest(String orderNo) { |
||||
HengjianReturnDetailDtos.DetailParams params = new HengjianReturnDetailDtos.DetailParams(); |
||||
params.orderNo = orderNo; |
||||
HengjianReturnDetailDtos.DetailRequest req = new HengjianReturnDetailDtos.DetailRequest(); |
||||
req.params = params; |
||||
return req; |
||||
} |
||||
|
||||
/** 详情 → 统一模型。 */ |
||||
public static WarehouseReturn toReturn(HengjianReturnDetailDtos.PlanDetail detail) { |
||||
String sourceNo = trimToNull(detail.sourceOrderNo); |
||||
String planNo = trimToNull(detail.returnPlanNo); |
||||
String requestNo = sourceNo != null ? sourceNo : planNo; |
||||
if (requestNo == null) { |
||||
throw new IllegalArgumentException( |
||||
"hengjian return detail has neither sourceOrderNo nor returnPlanNo"); |
||||
} |
||||
WarehouseReturn.Builder builder = WarehouseReturn.builder() |
||||
.returnRequestNo(requestNo) |
||||
.providerReturnId(planNo) |
||||
.warehouseCode(firstNonBlank(detail.orgWarehouseCode, null)) |
||||
.orderRef(trimToNull(detail.saleOrderNo)) |
||||
// sourceType 两页文档顺序相反,原值保留不解释
|
||||
.type(trimToNull(detail.sourceType)) |
||||
.status(HengjianReturnPlanStatus.toCore(detail.returnPlanStatus)) |
||||
.rawStatus(trimToNull(detail.returnPlanStatus)) |
||||
.sourceProvider(WarehouseProvider.HENGJIAN) |
||||
.createdAt(parseTime(detail.createdAt)) |
||||
.actualReceivedAt(parseTime(detail.checkApproveTime)) |
||||
.relatedProcessNo(null); |
||||
// 详情文档没有 lineName 字段:不映射,保持 null(列表才有 lineName)
|
||||
if (detail.returnPlanSkuList != null) { |
||||
for (HengjianReturnDetailDtos.PlanDetail.PlanSku sku : detail.returnPlanSkuList) { |
||||
if (sku == null) { |
||||
continue; |
||||
} |
||||
WarehouseReturn.ReturnLine.Builder line = WarehouseReturn.ReturnLine.builder() |
||||
.providerSku(trimToNull(sku.erpSku)) |
||||
.quantity(intOf(sku.returnQuantity)) |
||||
.processedQuantity(intOf(sku.receivedQuantity)) |
||||
// 外观破损处理方式:仓方原值,语义由调用方解释
|
||||
.suggestedDisposition(trimToNull(sku.treatmentMethodForAppearanceDamage)) |
||||
.newSku(trimToNull( |
||||
sku.relabelShelfSkuItems == null || sku.relabelShelfSkuItems.isEmpty() |
||||
? null : sku.relabelShelfSkuItems.get(0).changeSku)); |
||||
if (sku.relabelShelfSkuItems != null) { |
||||
for (HengjianReturnDetailDtos.PlanDetail.PlanSku.RelabelItem item |
||||
: sku.relabelShelfSkuItems) { |
||||
if (item != null) { |
||||
line.newSku(trimToNull(item.changeSku)); |
||||
} |
||||
} |
||||
} |
||||
builder.line(line.build()); |
||||
} |
||||
} |
||||
// 待处理 / 已处理列表:作为附件承载不了,统一模型没有对应字段,
|
||||
// 这里不塞进 lines(那是 SKU 维度),需要时单独用处理单列表接口查
|
||||
return builder.build(); |
||||
} |
||||
|
||||
// ================================================================ 列表
|
||||
|
||||
/** |
||||
* 列表请求:双层包裹,分页参数按文档转字符串。 |
||||
* |
||||
* @param statuses 统一模型的状态过滤;恒健只支持单个状态,多个时拒绝 |
||||
*/ |
||||
public static HengjianReturnListDtos.ListRequest toListRequest( |
||||
List<ReturnStatus> statuses, ReturnStatus singleStatus, |
||||
String startTime, String endTime, Integer queryDataType, |
||||
String queryType, String queryValue, |
||||
List<String> warehouseCodes, int page, int size) { |
||||
HengjianReturnListDtos.ListParams params = new HengjianReturnListDtos.ListParams(); |
||||
params.page = String.valueOf(page); |
||||
params.size = String.valueOf(size); |
||||
if (queryDataType != null) { |
||||
params.queryDataType = String.valueOf(queryDataType); |
||||
} |
||||
params.queryStartValue = startTime; |
||||
params.queryEndValue = endTime; |
||||
if (warehouseCodes != null && !warehouseCodes.isEmpty()) { |
||||
// 恒健收逗号拼接的字符串
|
||||
params.orgWarehouseCode = join(warehouseCodes); |
||||
} |
||||
if (singleStatus != null) { |
||||
params.returnPlanStatus = statusCodeOf(singleStatus); |
||||
} |
||||
params.queryType = queryType; |
||||
params.queryValue = queryValue; |
||||
HengjianReturnListDtos.ListRequest req = new HengjianReturnListDtos.ListRequest(); |
||||
req.params = params; |
||||
return req; |
||||
} |
||||
|
||||
/** 核心状态 → 恒健计划状态码;认不出返回 null。 */ |
||||
static String statusCodeOf(ReturnStatus status) { |
||||
if (status == null) { |
||||
return null; |
||||
} |
||||
switch (status) { |
||||
case DRAFT: |
||||
return "0"; |
||||
case PENDING_REVIEW: |
||||
return "5"; |
||||
case REJECTED: |
||||
return "10"; |
||||
case PENDING_RECEIPT: |
||||
return "15"; |
||||
case COMPLETED: |
||||
return "25"; |
||||
case CLOSED: |
||||
return "30"; |
||||
case RETURNING: |
||||
// RETURNING 在恒健对应「待处理(20)」或「处理中(35)」,
|
||||
// 无法二选一时返回 null —— 让调用方明确选一个,不猜
|
||||
return null; |
||||
default: |
||||
return null; |
||||
} |
||||
} |
||||
|
||||
/** 列表 → 统一 Page。 */ |
||||
public static Page<WarehouseReturn> toPage(HengjianReturnListDtos.PageData data, |
||||
String cursor, int requestedRows) { |
||||
if (data == null) { |
||||
return Page.last(new ArrayList<WarehouseReturn>()); |
||||
} |
||||
List<WarehouseReturn> out = new ArrayList<WarehouseReturn>(); |
||||
if (data.content != null) { |
||||
for (HengjianReturnListDtos.PlanRow row : data.content) { |
||||
if (row != null) { |
||||
out.add(toReturn(row)); |
||||
} |
||||
} |
||||
} |
||||
boolean last = data.last != null ? data.last |
||||
: (data.numberOfElements != null && data.numberOfElements < requestedRows); |
||||
if (last) { |
||||
return Page.last(out); |
||||
} |
||||
// 响应 number 是 0 基,请求 page 是 1 基:下一页 = number + 2
|
||||
int next = (data.number == null ? 0 : data.number) + 2; |
||||
return Page.of(out, String.valueOf(next)); |
||||
} |
||||
|
||||
/** 列表行 → 统一模型。 */ |
||||
public static WarehouseReturn toReturn(HengjianReturnListDtos.PlanRow row) { |
||||
String sourceNo = trimToNull(row.sourceOrderNo); |
||||
String planNo = trimToNull(row.returnPlanNo); |
||||
String requestNo = sourceNo != null ? sourceNo : planNo; |
||||
if (requestNo == null) { |
||||
throw new IllegalArgumentException( |
||||
"hengjian return list row has neither sourceOrderNo nor returnPlanNo"); |
||||
} |
||||
// 列表的仓库字段两套写法都可能出现
|
||||
String warehouse = firstNonBlank(row.warehouseCode, row.orgWarehouseCode); |
||||
return WarehouseReturn.builder() |
||||
.returnRequestNo(requestNo) |
||||
.providerReturnId(planNo) |
||||
.warehouseCode(warehouse == null ? "" : warehouse) |
||||
.orderRef(trimToNull(row.saleOrderNo)) |
||||
.status(HengjianReturnPlanStatus.toCore(row.returnPlanStatus)) |
||||
.rawStatus(trimToNull(row.returnPlanStatus)) |
||||
.sourceProvider(WarehouseProvider.HENGJIAN) |
||||
.createdAt(parseTime(row.createdAt)) |
||||
.lineName(trimToNull(row.lineName)) |
||||
.inspectedQuantity(null) |
||||
.build(); |
||||
} |
||||
|
||||
// ================================================================ 处理单列表
|
||||
|
||||
/** 处理单列表请求:<b>平铺</b>,无 params 包裹。 */ |
||||
public static HengjianReturnHandleDtos.HandleListRequest toHandleListRequest( |
||||
List<String> returnPlanNos, List<String> trackingNos, |
||||
List<String> warehouseCodes, List<Integer> handlingStatuses, |
||||
String createdStart, String createdEnd, int page, int size) { |
||||
HengjianReturnHandleDtos.HandleListRequest req = |
||||
new HengjianReturnHandleDtos.HandleListRequest(); |
||||
req.returnPlanNoList = emptyToNull(returnPlanNos); |
||||
req.trackingList = emptyToNull(trackingNos); |
||||
req.orgWarehouseCodeList = emptyToNull(warehouseCodes); |
||||
req.handlingStatusList = emptyToNull(handlingStatuses); |
||||
req.createdStartTime = trimToNull(createdStart); |
||||
req.createdEndTime = trimToNull(createdEnd); |
||||
req.page = page; |
||||
req.size = size; |
||||
return req; |
||||
} |
||||
|
||||
/** 处理单列表 → 统一 Page(每行是一条处理单,不是退货单)。 */ |
||||
public static Page<HengjianReturnHandleDtos.HandleRow> toHandlePage( |
||||
HengjianReturnHandleDtos.HandlePageData data, String cursor, int requestedRows) { |
||||
if (data == null) { |
||||
return Page.last(new ArrayList<HengjianReturnHandleDtos.HandleRow>()); |
||||
} |
||||
List<HengjianReturnHandleDtos.HandleRow> out = new ArrayList<HengjianReturnHandleDtos.HandleRow>(); |
||||
if (data.content != null) { |
||||
for (HengjianReturnHandleDtos.HandleRow row : data.content) { |
||||
if (row != null) { |
||||
out.add(row); |
||||
} |
||||
} |
||||
} |
||||
boolean last = data.last != null ? data.last |
||||
: out.size() < requestedRows; |
||||
if (last) { |
||||
return Page.last(out); |
||||
} |
||||
int next = (data.number == null ? 0 : data.number) + 2; |
||||
return Page.of(out, String.valueOf(next)); |
||||
} |
||||
|
||||
// ================================================================ 处理方式
|
||||
|
||||
/** |
||||
* 处理方式请求:<b>平铺</b>,四项定位 + 两级处理方式。 |
||||
* |
||||
* @throws IllegalArgumentException 缺四项定位字段或处理方式 |
||||
*/ |
||||
public static HengjianReturnHandleDtos.HandlingMethodRequest toHandlingMethodRequest( |
||||
ReturnProcessCommand cmd) { |
||||
HengjianReturnHandleDtos.HandlingMethodRequest req = |
||||
new HengjianReturnHandleDtos.HandlingMethodRequest(); |
||||
req.returnPlanNo = requireText(cmd.providerReturnNo(), "returnPlanNo"); |
||||
req.returnNo = requireText(cmd.returnNo(), "returnNo"); |
||||
req.erpSku = requireText(cmd.erpSku(), "erpSku"); |
||||
req.tracking = requireText(cmd.tracking(), "tracking"); |
||||
req.handlingMethod = requireHandlingMethod(cmd); |
||||
req.primaryHandlingMethod = requirePrimaryHandlingMethod(cmd); |
||||
req.photosQuantity = cmd.photosQuantity(); |
||||
req.changeErpsku = trimToNull(cmd.newSku()); |
||||
req.remark = trimToNull(cmd.remark()); |
||||
// “继续拍照”必须给拍照数量,否则仓方不知道拍几张
|
||||
if (req.handlingMethod == HANDLING_CONTINUE_PHOTO |
||||
&& (req.photosQuantity == null || req.photosQuantity <= 0)) { |
||||
throw new IllegalArgumentException( |
||||
"hengjian handlingMethod=1 (continue photo) requires positive photosQuantity"); |
||||
} |
||||
return req; |
||||
} |
||||
|
||||
/** 处理方式:1 继续拍照。 */ |
||||
static final int HANDLING_CONTINUE_PHOTO = 1; |
||||
|
||||
private static Integer requireHandlingMethod(ReturnProcessCommand cmd) { |
||||
Integer v = cmd.handlingMethod(); |
||||
if (v == null) { |
||||
throw new IllegalArgumentException( |
||||
"hengjian handling method requires handlingMethod (1 continue photo / 2 dispose)"); |
||||
} |
||||
if (v != 1 && v != 2) { |
||||
throw new IllegalArgumentException( |
||||
"hengjian handlingMethod must be 1 or 2, got " + v); |
||||
} |
||||
return v; |
||||
} |
||||
|
||||
/** |
||||
* 主要处理方式。 |
||||
* |
||||
* <p>优先用调用方给的仓方原值;没给时按 core 的 {@link ReturnProcessDisposition} |
||||
* 映射四个能对应上的值(销毁 / 上架良品 / 换标上架 / 卖家自提)。 |
||||
* 拍照类(101~103)与重新包装(205)/ 仓库拆箱判断(206)core 没有对应值, |
||||
* 只能由调用方显式给原值。</p> |
||||
*/ |
||||
private static Integer requirePrimaryHandlingMethod(ReturnProcessCommand cmd) { |
||||
String explicit = trimToNull(cmd.primaryHandlingMethod()); |
||||
if (explicit != null) { |
||||
try { |
||||
return Integer.valueOf(explicit); |
||||
} catch (NumberFormatException e) { |
||||
throw new IllegalArgumentException( |
||||
"hengjian primaryHandlingMethod must be numeric, got " + explicit); |
||||
} |
||||
} |
||||
ReturnProcessDisposition disposition = cmd.disposition(); |
||||
Integer mapped = primaryCodeOf(disposition); |
||||
if (mapped == null) { |
||||
throw new IllegalArgumentException( |
||||
"hengjian has no primaryHandlingMethod for disposition " + disposition |
||||
+ "; pass it explicitly (101-103 / 205 / 206)"); |
||||
} |
||||
return mapped; |
||||
} |
||||
|
||||
/** core 处理方式 → 恒健 primaryHandlingMethod;对应不上的返回 null。 */ |
||||
static Integer primaryCodeOf(ReturnProcessDisposition disposition) { |
||||
if (disposition == null) { |
||||
return null; |
||||
} |
||||
switch (disposition) { |
||||
case DESTROY: |
||||
return 201; |
||||
case RESTOCK: |
||||
return 202; |
||||
case RESTOCK_RELABEL: |
||||
return 203; |
||||
case CUSTOMER_PICKUP: |
||||
return 204; |
||||
default: |
||||
// RESTOCK_UNSELLABLE / UNKNOWN:恒健没有独立的「不良品上架」码
|
||||
return null; |
||||
} |
||||
} |
||||
|
||||
// ================================================================ 分页
|
||||
|
||||
/** 页码:游标是字符串化页码,空游标表示第 1 页(入参 1 基)。 */ |
||||
static int pageOf(String cursor) { |
||||
String v = trimToNull(cursor); |
||||
if (v == null) { |
||||
return 1; |
||||
} |
||||
try { |
||||
int page = Integer.parseInt(v); |
||||
return page < 1 ? 1 : page; |
||||
} catch (NumberFormatException e) { |
||||
throw new IllegalArgumentException( |
||||
"hengjian return cursor must be a page number, got " + v); |
||||
} |
||||
} |
||||
|
||||
/** 退货计划列表每页条数;超上限拒绝不截断。 */ |
||||
static int rowsOf(int requested) { |
||||
if (requested <= 0) { |
||||
return MAX_ROWS; |
||||
} |
||||
if (requested > MAX_ROWS) { |
||||
throw new IllegalArgumentException( |
||||
"hengjian return rows must not exceed " + MAX_ROWS + ", got " + requested); |
||||
} |
||||
return requested; |
||||
} |
||||
|
||||
/** 处理单列表每页条数;超上限拒绝不截断。 */ |
||||
static int handleRowsOf(int requested) { |
||||
if (requested <= 0) { |
||||
return HANDLE_MAX_ROWS; |
||||
} |
||||
if (requested > HANDLE_MAX_ROWS) { |
||||
throw new IllegalArgumentException( |
||||
"hengjian return handle rows must not exceed " + HANDLE_MAX_ROWS |
||||
+ ", got " + requested); |
||||
} |
||||
return requested; |
||||
} |
||||
|
||||
// ================================================================ 工具
|
||||
|
||||
static Instant parseTime(String value) { |
||||
String v = trimToNull(value); |
||||
if (v == null) { |
||||
return null; |
||||
} |
||||
try { |
||||
return LocalDateTime.parse(v, DATE_TIME).toInstant(ZoneOffset.UTC); |
||||
} catch (DateTimeParseException e) { |
||||
// 处理单列表的时间戳是 ISO 带时区(2025-08-14T01:32:32.000+0000)
|
||||
try { |
||||
return Instant.parse(v.replace("+0000", "Z")); |
||||
} catch (DateTimeParseException ignored) { |
||||
try { |
||||
return LocalDate.parse(v, DATE).atStartOfDay().toInstant(ZoneOffset.UTC); |
||||
} catch (DateTimeParseException alsoIgnored) { |
||||
return null; |
||||
} |
||||
} |
||||
} |
||||
} |
||||
|
||||
static int intOf(Integer v) { |
||||
return v == null ? 0 : v; |
||||
} |
||||
|
||||
private static <T> List<T> emptyToNull(List<T> list) { |
||||
return list == null || list.isEmpty() ? null : list; |
||||
} |
||||
|
||||
private static String join(List<String> values) { |
||||
StringBuilder sb = new StringBuilder(); |
||||
for (String v : values) { |
||||
String t = trimToNull(v); |
||||
if (t == null) { |
||||
continue; |
||||
} |
||||
if (sb.length() > 0) { |
||||
sb.append(','); |
||||
} |
||||
sb.append(t); |
||||
} |
||||
return sb.length() == 0 ? null : sb.toString(); |
||||
} |
||||
|
||||
private static String requireText(String value, String field) { |
||||
String v = trimToNull(value); |
||||
if (v == null) { |
||||
throw new IllegalArgumentException("hengjian handling method requires " + field); |
||||
} |
||||
return v; |
||||
} |
||||
|
||||
private static String firstNonBlank(String a, String b) { |
||||
String x = trimToNull(a); |
||||
return x != null ? x : trimToNull(b); |
||||
} |
||||
|
||||
private static String trimToNull(String v) { |
||||
if (v == null) { |
||||
return null; |
||||
} |
||||
String t = v.trim(); |
||||
return t.isEmpty() ? null : t; |
||||
} |
||||
} |
||||
@ -0,0 +1,252 @@
@@ -0,0 +1,252 @@
|
||||
package common.ecommerce.hengjian.dto; |
||||
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties; |
||||
import com.fasterxml.jackson.annotation.JsonInclude; |
||||
import com.fasterxml.jackson.annotation.JsonProperty; |
||||
|
||||
import java.util.List; |
||||
|
||||
/** |
||||
* 恒健报文结构:退货计划详情({@code POST /v1/saleReturn/thirdParty/getReturnPlanOrderInfo})。 |
||||
* |
||||
* <p><b>请求是双层包裹</b>:{@code {"params":{"orderNo":"..."}}},与创建一致。 |
||||
* 无 token 时直接 403、不做参数校验。</p> |
||||
* |
||||
* <p>详情比列表多出三块:{@code returnPlanSkuList}(计划 SKU 明细)、 |
||||
* {@code returnPlanHandleList}(待处理)、{@code returnPlanExecuteDetails}(已处理)。</p> |
||||
*/ |
||||
public final class HengjianReturnDetailDtos { |
||||
|
||||
private HengjianReturnDetailDtos() { |
||||
} |
||||
|
||||
@JsonInclude(JsonInclude.Include.NON_NULL) |
||||
public static final class DetailRequest { |
||||
|
||||
public DetailParams params; |
||||
} |
||||
|
||||
@JsonInclude(JsonInclude.Include.NON_NULL) |
||||
public static final class DetailParams { |
||||
|
||||
/** 计划单号;必填。 */ |
||||
public String orderNo; |
||||
} |
||||
|
||||
/** 响应外层。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class DetailResponse { |
||||
|
||||
@JsonProperty("code") |
||||
public Integer code; |
||||
|
||||
@JsonProperty("message") |
||||
public String message; |
||||
|
||||
@JsonProperty("data") |
||||
public PlanDetail data; |
||||
} |
||||
|
||||
/** |
||||
* 退货计划详情。 |
||||
* |
||||
* <p>字段多且类型不一致(数量类有的标 string 有的标 integer),一律用 String 接, |
||||
* 解析时再转——避免类型漂移炸掉整单。</p> |
||||
*/ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class PlanDetail { |
||||
|
||||
/** 计划单号。 */ |
||||
@JsonProperty("returnPlanNo") |
||||
public String returnPlanNo; |
||||
|
||||
/** 计划状态码:0/5/10/15/20/25/30/35。 */ |
||||
@JsonProperty("returnPlanStatus") |
||||
public String returnPlanStatus; |
||||
|
||||
/** 来源单号(我们下发的退货单)。 */ |
||||
@JsonProperty("sourceOrderNo") |
||||
public String sourceOrderNo; |
||||
/** 关联单号。 */ |
||||
@JsonProperty("associatedNo") |
||||
public String associatedNo; |
||||
/** 来源类型:1 销售退货 / 2 无来源退货(<b>与创建接口的顺序相反</b>)。 */ |
||||
@JsonProperty("sourceType") |
||||
public String sourceType; |
||||
|
||||
@JsonProperty("saleOrderNo") |
||||
public String saleOrderNo; |
||||
@JsonProperty("channelAccount") |
||||
public String channelAccount; |
||||
@JsonProperty("orgWarehouseId") |
||||
public String orgWarehouseId; |
||||
@JsonProperty("orgWarehouseCode") |
||||
public String orgWarehouseCode; |
||||
@JsonProperty("lineId") |
||||
public String lineId; |
||||
|
||||
@JsonProperty("returnTracking") |
||||
public String returnTracking; |
||||
|
||||
@JsonProperty("consignor") |
||||
public String consignor; |
||||
@JsonProperty("country") |
||||
public String country; |
||||
@JsonProperty("province") |
||||
public String province; |
||||
@JsonProperty("city") |
||||
public String city; |
||||
@JsonProperty("addressOne") |
||||
public String addressOne; |
||||
@JsonProperty("addressTwo") |
||||
public String addressTwo; |
||||
@JsonProperty("zipCode") |
||||
public String zipCode; |
||||
@JsonProperty("phone") |
||||
public String phone; |
||||
|
||||
@JsonProperty("threeRdAccount") |
||||
public String threeRdAccount; |
||||
@JsonProperty("returnReason") |
||||
public String returnReason; |
||||
@JsonProperty("remark") |
||||
public String remark; |
||||
|
||||
@JsonProperty("createdAt") |
||||
public String createdAt; |
||||
@JsonProperty("updatedAt") |
||||
public String updatedAt; |
||||
@JsonProperty("returnDate") |
||||
public String returnDate; |
||||
@JsonProperty("createdName") |
||||
public String createdName; |
||||
@JsonProperty("updatedName") |
||||
public String updatedName; |
||||
|
||||
/** 状态节点时间(详情页展示用)。 */ |
||||
@JsonProperty("submitTime") |
||||
public String submitTime; |
||||
@JsonProperty("checkApproveTime") |
||||
public String checkApproveTime; |
||||
@JsonProperty("inboundCreateTime") |
||||
public String inboundCreateTime; |
||||
@JsonProperty("completeTime") |
||||
public String completeTime; |
||||
@JsonProperty("cancelTime") |
||||
public String cancelTime; |
||||
|
||||
/** 计划 SKU 明细。 */ |
||||
@JsonProperty("returnPlanSkuList") |
||||
public List<PlanSku> returnPlanSkuList; |
||||
|
||||
/** 待处理列表(与「退货处理单列表」同结构)。 */ |
||||
@JsonProperty("returnPlanHandleList") |
||||
public List<HandleItem> returnPlanHandleList; |
||||
|
||||
/** 已处理列表。 */ |
||||
@JsonProperty("returnPlanExecuteDetails") |
||||
public List<HandleItem> returnPlanExecuteDetails; |
||||
|
||||
/** 计划 SKU 明细行。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class PlanSku { |
||||
|
||||
@JsonProperty("erpSku") |
||||
public String erpSku; |
||||
@JsonProperty("sellerSku") |
||||
public String sellerSku; |
||||
@JsonProperty("returnQuantity") |
||||
public Integer returnQuantity; |
||||
@JsonProperty("receivedQuantity") |
||||
public Integer receivedQuantity; |
||||
@JsonProperty("tracking") |
||||
public String tracking; |
||||
/** 外观破损处理方式:1 客户自提 / 2 拍照 / 3 销毁 / 4 上架 / 5 换标上架 / 6 重新包装。 */ |
||||
@JsonProperty("treatmentMethodForAppearanceDamage") |
||||
public String treatmentMethodForAppearanceDamage; |
||||
@JsonProperty("returnShippingMethod") |
||||
public String returnShippingMethod; |
||||
/** 检验后的分流数量。 */ |
||||
@JsonProperty("saleableQty") |
||||
public Integer saleableQty; |
||||
@JsonProperty("unsaleableQty") |
||||
public Integer unsaleableQty; |
||||
@JsonProperty("shelfQty") |
||||
public Integer shelfQty; |
||||
@JsonProperty("relabelShelfQty") |
||||
public Integer relabelShelfQty; |
||||
@JsonProperty("destroyQty") |
||||
public Integer destroyQty; |
||||
@JsonProperty("customerPickupQty") |
||||
public Integer customerPickupQty; |
||||
/** 换标上架明细。 */ |
||||
@JsonProperty("relabelShelfSkuItems") |
||||
public List<RelabelItem> relabelShelfSkuItems; |
||||
@JsonProperty("createdAt") |
||||
public String createdAt; |
||||
|
||||
/** 换标上架明细行。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class RelabelItem { |
||||
|
||||
@JsonProperty("changeSku") |
||||
public String changeSku; |
||||
@JsonProperty("saleableQty") |
||||
public String saleableQty; |
||||
@JsonProperty("unsaleableQty") |
||||
public String unsaleableQty; |
||||
} |
||||
} |
||||
|
||||
/** |
||||
* 一条退货处理(待处理 / 已处理共用)。 |
||||
* |
||||
* <p>{@code handlingStatus} 码表:5 待处理 / 10 处理中 / 15 已完成 / 20 已取消。 |
||||
* {@code primaryHandlingMethod} 码表:101~103 拍照类、201 销毁、202 上架良品、 |
||||
* 203 换标上架、204 卖家自提、205 重新包装、206 仓库拆箱判断。</p> |
||||
*/ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class HandleItem { |
||||
|
||||
/** 退货编码 / 处理单号。 */ |
||||
@JsonProperty("returnNo") |
||||
public String returnNo; |
||||
@JsonProperty("sourceNo") |
||||
public String sourceNo; |
||||
@JsonProperty("orgWarehouseCode") |
||||
public String orgWarehouseCode; |
||||
/** 处理状态:5/10/15/20。 */ |
||||
@JsonProperty("handlingStatus") |
||||
public String handlingStatus; |
||||
/** 处理方式:1 继续拍照 / 2 处理方式。 */ |
||||
@JsonProperty("handlingMethod") |
||||
public String handlingMethod; |
||||
/** 主要处理方式:101~206。 */ |
||||
@JsonProperty("primaryHandlingMethod") |
||||
public String primaryHandlingMethod; |
||||
@JsonProperty("erpSku") |
||||
public String erpSku; |
||||
@JsonProperty("quantity") |
||||
public Integer quantity; |
||||
@JsonProperty("handlingQuantity") |
||||
public Integer handlingQuantity; |
||||
/** 换标 SKU。 */ |
||||
@JsonProperty("changeErpsku") |
||||
public String changeErpsku; |
||||
/** 照片链接列表(字段类型标 string,实际可能是数组;用 Object 接住)。 */ |
||||
@JsonProperty("fileUrlList") |
||||
public Object fileUrlList; |
||||
@JsonProperty("photosQuantity") |
||||
public Integer photosQuantity; |
||||
/** 二次拍照列表。 */ |
||||
@JsonProperty("handleFileUrlList") |
||||
public Object handleFileUrlList; |
||||
@JsonProperty("remark") |
||||
public String remark; |
||||
@JsonProperty("createdAt") |
||||
public String createdAt; |
||||
@JsonProperty("updatedAt") |
||||
public String updatedAt; |
||||
} |
||||
} |
||||
} |
||||
@ -0,0 +1,214 @@
@@ -0,0 +1,214 @@
|
||||
package common.ecommerce.hengjian.dto; |
||||
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties; |
||||
import com.fasterxml.jackson.annotation.JsonInclude; |
||||
import com.fasterxml.jackson.annotation.JsonProperty; |
||||
|
||||
import java.util.List; |
||||
|
||||
/** |
||||
* 恒健报文结构:退货处理单列表({@code POST /v1/saleReturn/getReturnPlanHandlePage}) |
||||
* 与「填写退货处理方式」({@code POST /v1/saleReturn/handlingMethod})。 |
||||
* |
||||
* <p><b>注意与另一套接口的差异</b>:这两个接口的请求是<b>平铺</b>的 |
||||
* (无 {@code params} 包裹),而 {@code getReturnPlanOrderInfo} / {@code getReturnPlanOrderPage} |
||||
* 是双层包裹。两种形态不能混。</p> |
||||
* |
||||
* <p>无 token 时的表现也不同:这两个接口回 |
||||
* {@code 500 + code 999999 + "查询失败/处理失败:Unauthorized"}, |
||||
* 而 thirdParty 那两个直接回 {@code 403}。</p> |
||||
*/ |
||||
public final class HengjianReturnHandleDtos { |
||||
|
||||
private HengjianReturnHandleDtos() { |
||||
} |
||||
|
||||
// ================================================================ 处理单列表
|
||||
|
||||
@JsonInclude(JsonInclude.Include.NON_NULL) |
||||
public static final class HandleListRequest { |
||||
|
||||
/** 退货计划单号列表。 */ |
||||
public List<String> returnPlanNoList; |
||||
/** 退货入库单号列表。 */ |
||||
public List<String> returnInboundNoList; |
||||
/** 退货处理单号列表。 */ |
||||
public List<String> returnPlanHandleNoList; |
||||
/** tracking 号列表。 */ |
||||
public List<String> trackingList; |
||||
/** ERP SKU 列表。 */ |
||||
public List<String> erpSkuList; |
||||
/** 仓库 code 列表。 */ |
||||
public List<String> orgWarehouseCodeList; |
||||
/** 处理状态:5 待处理 / 10 处理中 / 15 已完成 / 20 已取消。 */ |
||||
public List<Integer> handlingStatusList; |
||||
/** 主要处理方式:101~206。 */ |
||||
public List<Integer> primaryHandlingMethodList; |
||||
|
||||
/** 创建时间区间 {@code yyyy-MM-dd HH:mm:ss}。 */ |
||||
public String createdStartTime; |
||||
public String createdEndTime; |
||||
|
||||
/** 页码,默认 1。 */ |
||||
public Integer page; |
||||
/** 每页大小,默认 20。 */ |
||||
public Integer size; |
||||
} |
||||
|
||||
/** 处理单列表响应。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class HandleListResponse { |
||||
|
||||
@JsonProperty("code") |
||||
public Integer code; |
||||
|
||||
@JsonProperty("message") |
||||
public String message; |
||||
|
||||
@JsonProperty("data") |
||||
public HandlePageData data; |
||||
} |
||||
|
||||
/** 分页数据。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class HandlePageData { |
||||
|
||||
@JsonProperty("content") |
||||
public List<HandleRow> content; |
||||
|
||||
@JsonProperty("totalElements") |
||||
public Integer totalElements; |
||||
|
||||
@JsonProperty("last") |
||||
public Boolean last; |
||||
|
||||
@JsonProperty("size") |
||||
public Integer size; |
||||
|
||||
/** 当前页码,<b>0 基</b>。 */ |
||||
@JsonProperty("number") |
||||
public Integer number; |
||||
} |
||||
|
||||
/** 一条退货处理单。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class HandleRow { |
||||
|
||||
/** 外部来源单号。 */ |
||||
@JsonProperty("openSourceNo") |
||||
public String openSourceNo; |
||||
/** 主要处理方式:101~206。 */ |
||||
@JsonProperty("primaryHandlingMethod") |
||||
public String primaryHandlingMethod; |
||||
@JsonProperty("inboundRemark") |
||||
public String inboundRemark; |
||||
@JsonProperty("remark") |
||||
public String remark; |
||||
|
||||
/** 退货处理单号。 */ |
||||
@JsonProperty("returnPlanHandleItemsNo") |
||||
public String returnPlanHandleItemsNo; |
||||
/** 退货计划单号。 */ |
||||
@JsonProperty("returnPlanNo") |
||||
public String returnPlanNo; |
||||
/** 退货入库单号。 */ |
||||
@JsonProperty("returnInboundNo") |
||||
public String returnInboundNo; |
||||
|
||||
@JsonProperty("tracking") |
||||
public String tracking; |
||||
@JsonProperty("createdAt") |
||||
public String createdAt; |
||||
@JsonProperty("updatedAt") |
||||
public String updatedAt; |
||||
@JsonProperty("completeAt") |
||||
public String completeAt; |
||||
|
||||
/** 照片 / 处理照片链接(文档标 string,实际可能是数组)。 */ |
||||
@JsonProperty("fileUrlList") |
||||
public Object fileUrlList; |
||||
@JsonProperty("handleFileUrlList") |
||||
public Object handleFileUrlList; |
||||
|
||||
/** 换标 SKU。 */ |
||||
@JsonProperty("changeErpsku") |
||||
public String changeErpsku; |
||||
|
||||
/** 异常:0 无异常 / 1 推送异常。 */ |
||||
@JsonProperty("errorStatus") |
||||
public String errorStatus; |
||||
/** 库存类型:0 可售 / 1 不可售。 */ |
||||
@JsonProperty("inventoryType") |
||||
public String inventoryType; |
||||
|
||||
@JsonProperty("quantity") |
||||
public Integer quantity; |
||||
@JsonProperty("handlingQuantity") |
||||
public Integer handlingQuantity; |
||||
@JsonProperty("photosQuantity") |
||||
public Integer photosQuantity; |
||||
|
||||
@JsonProperty("sourceNo") |
||||
public String sourceNo; |
||||
@JsonProperty("orgWarehouseCode") |
||||
public String orgWarehouseCode; |
||||
@JsonProperty("erpSku") |
||||
public String erpSku; |
||||
|
||||
/** 处理状态:5 待处理 / 10 处理中 / 15 已完成 / 20 已取消。 */ |
||||
@JsonProperty("handlingStatus") |
||||
public String handlingStatus; |
||||
} |
||||
|
||||
// ================================================================ 填写处理方式
|
||||
|
||||
/** |
||||
* 请求:<b>平铺</b>,没有 {@code params} 包裹。 |
||||
* |
||||
* <p>示例里还混了 {@code organizationId} / {@code openSourceNo}——字段表没列, |
||||
* 不发(客户组织由认证身份确定,见《库存变动明细查询》那页的说明)。</p> |
||||
*/ |
||||
@JsonInclude(JsonInclude.Include.NON_NULL) |
||||
public static final class HandlingMethodRequest { |
||||
|
||||
/** 计划单号;必填。 */ |
||||
public String returnPlanNo; |
||||
|
||||
/** 退货编码(处理单号);必填。 */ |
||||
public String returnNo; |
||||
|
||||
/** ERP SKU;必填。 */ |
||||
public String erpSku; |
||||
|
||||
/** tracking;必填。 */ |
||||
public String tracking; |
||||
|
||||
/** 处理方式:1 继续拍照 / 2 处理方式;必填。 */ |
||||
public Integer handlingMethod; |
||||
|
||||
/** 主要处理方式:101~206;必填。 */ |
||||
public Integer primaryHandlingMethod; |
||||
|
||||
/** 拍照数量;选填。 */ |
||||
public Integer photosQuantity; |
||||
|
||||
/** 换标 SKU;选填。 */ |
||||
public String changeErpsku; |
||||
|
||||
public String remark; |
||||
} |
||||
|
||||
/** 响应。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class HandlingMethodResponse { |
||||
|
||||
@JsonProperty("code") |
||||
public Integer code; |
||||
|
||||
@JsonProperty("message") |
||||
public String message; |
||||
|
||||
@JsonProperty("data") |
||||
public HandleRow data; |
||||
} |
||||
} |
||||
@ -0,0 +1,152 @@
@@ -0,0 +1,152 @@
|
||||
package common.ecommerce.hengjian.dto; |
||||
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties; |
||||
import com.fasterxml.jackson.annotation.JsonInclude; |
||||
import com.fasterxml.jackson.annotation.JsonProperty; |
||||
|
||||
import java.util.List; |
||||
|
||||
/** |
||||
* 恒健报文结构:退货计划列表({@code POST /v1/saleReturn/thirdParty/getReturnPlanOrderPage})。 |
||||
* |
||||
* <p><b>请求是双层包裹</b>,且分页参数 {@code page} / {@code size} 在文档里标 |
||||
* <b>string</b>(不是 integer)——照抄,下发时转字符串。</p> |
||||
* |
||||
* <p>查询是「时间类型 + 时间区间」与「查询类型 + 查询值」两组二选一的组合: |
||||
* {@code queryDataType} 1 创建 / 2 修改 / 4 完成;{@code queryType} 1 计划单号 / |
||||
* 2 来源单号 / 3 关联订单号 / 4 tracking。</p> |
||||
*/ |
||||
public final class HengjianReturnListDtos { |
||||
|
||||
private HengjianReturnListDtos() { |
||||
} |
||||
|
||||
@JsonInclude(JsonInclude.Include.NON_NULL) |
||||
public static final class ListRequest { |
||||
|
||||
public ListParams params; |
||||
} |
||||
|
||||
@JsonInclude(JsonInclude.Include.NON_NULL) |
||||
public static final class ListParams { |
||||
|
||||
/** 页码;文档标 string。 */ |
||||
public String page; |
||||
|
||||
/** 每页条数;文档标 string。 */ |
||||
public String size; |
||||
|
||||
/** 查询时间类型:1 创建 / 2 修改 / 4 完成。 */ |
||||
public String queryDataType; |
||||
|
||||
/** 开始时间 {@code yyyy-MM-dd HH:mm:ss};与结束时间成对。 */ |
||||
public String queryStartValue; |
||||
|
||||
/** 结束时间。 */ |
||||
public String queryEndValue; |
||||
|
||||
/** 仓库 code;多个用逗号拼接。 */ |
||||
public String orgWarehouseCode; |
||||
|
||||
/** 计划状态码(单个,不是数组)。 */ |
||||
public String returnPlanStatus; |
||||
|
||||
/** 查询类型:1 计划单号 / 2 来源单号 / 3 关联订单号 / 4 tracking。 */ |
||||
public String queryType; |
||||
|
||||
/** 查询值;需结合 queryType。 */ |
||||
public String queryValue; |
||||
} |
||||
|
||||
/** 响应外层。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class ListResponse { |
||||
|
||||
@JsonProperty("code") |
||||
public Integer code; |
||||
|
||||
@JsonProperty("message") |
||||
public String message; |
||||
|
||||
@JsonProperty("data") |
||||
public PageData data; |
||||
} |
||||
|
||||
/** 分页数据。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class PageData { |
||||
|
||||
@JsonProperty("content") |
||||
public List<PlanRow> content; |
||||
|
||||
@JsonProperty("totalElements") |
||||
public Integer totalElements; |
||||
|
||||
@JsonProperty("totalPages") |
||||
public Integer totalPages; |
||||
|
||||
@JsonProperty("numberOfElements") |
||||
public Integer numberOfElements; |
||||
|
||||
/** 当前页码,<b>0 基</b>。 */ |
||||
@JsonProperty("number") |
||||
public Integer number; |
||||
|
||||
@JsonProperty("size") |
||||
public Integer size; |
||||
|
||||
@JsonProperty("last") |
||||
public Boolean last; |
||||
} |
||||
|
||||
/** 一行退货计划。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class PlanRow { |
||||
|
||||
@JsonProperty("id") |
||||
public Long id; |
||||
@JsonProperty("returnPlanNo") |
||||
public String returnPlanNo; |
||||
@JsonProperty("sourceOrderNo") |
||||
public String sourceOrderNo; |
||||
@JsonProperty("associatedNo") |
||||
public String associatedNo; |
||||
|
||||
/** 退货追踪号集合(列表是数组,详情是单值 {@code returnTracking})。 */ |
||||
@JsonProperty("trackingList") |
||||
public List<String> trackingList; |
||||
|
||||
@JsonProperty("lineName") |
||||
public String lineName; |
||||
@JsonProperty("returnPlanStatus") |
||||
public String returnPlanStatus; |
||||
/** 仓库 code;文档标 null 类型,示例里有值,用 String 接。 */ |
||||
@JsonProperty("warehouseCode") |
||||
public String warehouseCode; |
||||
/** 同站的详情字段叫 orgWarehouseCode;列表的字段表写 warehouseCode。 */ |
||||
@JsonProperty("orgWarehouseCode") |
||||
public String orgWarehouseCode; |
||||
|
||||
@JsonProperty("createdAt") |
||||
public String createdAt; |
||||
@JsonProperty("updatedAt") |
||||
public String updatedAt; |
||||
@JsonProperty("saleOrderNo") |
||||
public String saleOrderNo; |
||||
@JsonProperty("saleOrderType") |
||||
public String saleOrderType; |
||||
|
||||
/** 退货 / 接收数量;文档标 string。 */ |
||||
@JsonProperty("returnQuantity") |
||||
public String returnQuantity; |
||||
@JsonProperty("receivedQuantity") |
||||
public String receivedQuantity; |
||||
/** 是否接收全部:1 是 / 0 否;文档标 string。 */ |
||||
@JsonProperty("isReceiveAll") |
||||
public String isReceiveAll; |
||||
|
||||
/** 待处理列表(结构同详情)。 */ |
||||
@JsonProperty("returnPlanHandleList") |
||||
public List<HengjianReturnDetailDtos.PlanDetail.HandleItem> returnPlanHandleList; |
||||
} |
||||
} |
||||
@ -0,0 +1,368 @@
@@ -0,0 +1,368 @@
|
||||
package common.ecommerce.hengjian.adapter; |
||||
|
||||
import common.ecommerce.hengjian.HengjianConstants; |
||||
import common.ecommerce.hengjian.dto.HengjianReturnHandleDtos; |
||||
import common.ecommerce.http.JacksonJsonCodec; |
||||
import common.ecommerce.shared.spi.ChannelSecret; |
||||
import common.ecommerce.shared.support.Page; |
||||
import common.ecommerce.shared.testkit.RecordingTransport; |
||||
import common.ecommerce.shared.testkit.Responses; |
||||
import common.ecommerce.warehouse.enums.ReturnProcessDisposition; |
||||
import common.ecommerce.warehouse.enums.ReturnStatus; |
||||
import common.ecommerce.warehouse.model.ReturnProcessCommand; |
||||
import common.ecommerce.warehouse.model.WarehouseReturn; |
||||
import common.ecommerce.warehouse.sdk.WarehouseConnection; |
||||
import common.ecommerce.warehouse.sdk.WarehouseContext; |
||||
import org.junit.jupiter.api.Test; |
||||
|
||||
import java.time.Clock; |
||||
import java.time.Instant; |
||||
import java.time.ZoneOffset; |
||||
import java.util.Collections; |
||||
|
||||
import static org.junit.jupiter.api.Assertions.assertEquals; |
||||
import static org.junit.jupiter.api.Assertions.assertFalse; |
||||
import static org.junit.jupiter.api.Assertions.assertNull; |
||||
import static org.junit.jupiter.api.Assertions.assertThrows; |
||||
import static org.junit.jupiter.api.Assertions.assertTrue; |
||||
|
||||
/** |
||||
* 退货计划详情 / 列表 / 处理单列表 / 处理方式契约测试。 |
||||
*/ |
||||
class HengjianReturnQueryTest { |
||||
|
||||
private static final WarehouseContext CTX = WarehouseContext.of( |
||||
"HJ-EFCA", WarehouseProviderForTest.HENGJIAN, "EFCA", |
||||
WarehouseConnection.of(HengjianConstants.TEST_BASE_URL, |
||||
ChannelSecret.builder().appSecret("token-1").build()), |
||||
"req-1", Clock.fixed(Instant.parse("2026-11-16T00:00:00Z"), ZoneOffset.UTC)); |
||||
|
||||
/** 只为了让静态导入少一层嵌套。 */ |
||||
private static final class WarehouseProviderForTest { |
||||
static final common.ecommerce.warehouse.enums.WarehouseProvider HENGJIAN = |
||||
common.ecommerce.warehouse.enums.WarehouseProvider.HENGJIAN; |
||||
} |
||||
|
||||
private static HengjianAdapter adapter(RecordingTransport transport) { |
||||
return new HengjianAdapter(transport, new JacksonJsonCodec()); |
||||
} |
||||
|
||||
// ================================================================ 详情
|
||||
|
||||
private static final String DETAIL_BODY = |
||||
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"success\",\"data\":{" |
||||
+ "\"returnPlanNo\":\"RC25081500018\",\"returnPlanStatus\":20," |
||||
+ "\"sourceOrderNo\":\"RT-1\",\"saleOrderNo\":\"SO-1\"," |
||||
+ "\"orgWarehouseCode\":\"EFCA\",\"lineId\":\"943\"," |
||||
+ "\"returnTracking\":\"1Z999\",\"sourceType\":2," |
||||
+ "\"consignor\":\"张三\",\"country\":\"US\",\"province\":\"IL\"," |
||||
+ "\"city\":\"Quincy\",\"addressOne\":\"620 North\",\"addressTwo\":\"\"," |
||||
+ "\"zipCode\":\"62305\",\"phone\":\"555\"," |
||||
+ "\"createdAt\":\"2025-08-15 09:27:10\"," |
||||
+ "\"checkApproveTime\":\"2025-08-16 10:00:00\"," |
||||
+ "\"returnPlanSkuList\":[{" |
||||
+ "\"erpSku\":\"SKU-A\",\"returnQuantity\":2,\"receivedQuantity\":2," |
||||
+ "\"tracking\":\"1Z999\",\"treatmentMethodForAppearanceDamage\":\"2\"," |
||||
+ "\"saleableQty\":1,\"unsaleableQty\":1," |
||||
+ "\"relabelShelfSkuItems\":[{\"changeSku\":\"SKU-NEW\"," |
||||
+ "\"saleableQty\":\"1\",\"unsaleableQty\":\"0\"}]}]," |
||||
+ "\"returnPlanHandleList\":[{\"returnNo\":\"TH25081500018\"," |
||||
+ "\"handlingStatus\":5,\"primaryHandlingMethod\":102," |
||||
+ "\"erpSku\":\"SKU-A\",\"quantity\":2}]," |
||||
+ "\"returnPlanExecuteDetails\":[]}}"; |
||||
|
||||
private static RecordingTransport detailing() { |
||||
return RecordingTransport.create() |
||||
.route(HengjianConstants.PATH_RETURN_PLAN_DETAIL, req -> Responses.ok(DETAIL_BODY)); |
||||
} |
||||
|
||||
@Test |
||||
void detailPostsWrappedParams() { |
||||
RecordingTransport transport = detailing(); |
||||
adapter(transport).getReturn(CTX, "RT-1"); |
||||
|
||||
assertEquals("POST", transport.lastDataRequest().method()); |
||||
assertEquals(HengjianConstants.TEST_BASE_URL |
||||
+ "/v1/saleReturn/thirdParty/getReturnPlanOrderInfo", |
||||
transport.lastDataRequest().url()); |
||||
String body = transport.lastDataRequest().body(); |
||||
assertTrue(body.startsWith("{\"params\":{"), "必须是双层包裹,body=" + body); |
||||
assertEquals("{\"params\":{\"orderNo\":\"RT-1\"}}", body); |
||||
} |
||||
|
||||
@Test |
||||
void detailMapsFields() { |
||||
WarehouseReturn ret = adapter(detailing()).getReturn(CTX, "RT-1"); |
||||
|
||||
assertEquals("RT-1", ret.returnRequestNo(), "来源单号优先作为业务键"); |
||||
assertEquals("RC25081500018", ret.providerReturnId()); |
||||
assertEquals("EFCA", ret.warehouseCode()); |
||||
assertEquals(ReturnStatus.RETURNING, ret.status(), "20 待处理"); |
||||
assertEquals("20", ret.rawStatus()); |
||||
assertEquals("SO-1", ret.orderRef()); |
||||
assertEquals("2", ret.type(), "sourceType 原值保留(两页文档顺序相反,不解释)"); |
||||
assertEquals(Instant.parse("2025-08-15T09:27:10Z"), ret.createdAt()); |
||||
assertEquals(Instant.parse("2025-08-16T10:00:00Z"), ret.actualReceivedAt()); |
||||
} |
||||
|
||||
@Test |
||||
void detailMapsSkuLines() { |
||||
WarehouseReturn ret = adapter(detailing()).getReturn(CTX, "RT-1"); |
||||
|
||||
assertEquals(1, ret.lines().size()); |
||||
WarehouseReturn.ReturnLine line = ret.lines().get(0); |
||||
assertEquals("SKU-A", line.providerSku()); |
||||
assertEquals(2, line.quantity()); |
||||
assertEquals(Integer.valueOf(2), line.processedQuantity()); |
||||
assertEquals("2", line.suggestedDisposition(), "外观破损处理方式原值"); |
||||
assertEquals("SKU-NEW", line.newSku(), "换标上架明细里的 changeSku"); |
||||
} |
||||
|
||||
@Test |
||||
void detailReturnsNullWhenDataMissing() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route(HengjianConstants.PATH_RETURN_PLAN_DETAIL, req -> Responses.ok( |
||||
"{\"code\":200,\"message\":\"not found\"}")); |
||||
|
||||
assertNull(adapter(transport).getReturn(CTX, "RT-NONE")); |
||||
} |
||||
|
||||
// ================================================================ 列表
|
||||
|
||||
private static final String LIST_BODY = |
||||
"{\"code\":200,\"message\":\"ok\",\"data\":{" |
||||
+ "\"totalElements\":1,\"totalPages\":1,\"numberOfElements\":1," |
||||
+ "\"number\":0,\"size\":100,\"last\":true,\"content\":[{" |
||||
+ "\"id\":27859,\"returnPlanNo\":\"RC25032800006\"," |
||||
+ "\"sourceOrderNo\":\"BI250328000202\",\"returnPlanStatus\":35," |
||||
+ "\"warehouseCode\":\"EFCA\",\"lineName\":\"Default\"," |
||||
+ "\"saleOrderNo\":\"SO-1\",\"createdAt\":\"2025-03-28 10:31:06\"}]}}"; |
||||
|
||||
private static RecordingTransport listing() { |
||||
return RecordingTransport.create() |
||||
.route(HengjianConstants.PATH_RETURN_PLAN_PAGE, req -> Responses.ok(LIST_BODY)); |
||||
} |
||||
|
||||
@Test |
||||
void listPostsWrappedStringPaging() { |
||||
RecordingTransport transport = listing(); |
||||
adapter(transport).queryReturns(CTX, null); |
||||
|
||||
String body = transport.lastDataRequest().body(); |
||||
assertTrue(body.startsWith("{\"params\":{"), body); |
||||
// 分页参数文档标 string
|
||||
assertTrue(body.contains("\"page\":\"1\""), body); |
||||
assertTrue(body.contains("\"size\":\"100\""), body); |
||||
} |
||||
|
||||
/** 状态过滤是单值;给多个时拒绝。 */ |
||||
@Test |
||||
void listRejectsMultipleStatuses() { |
||||
RecordingTransport transport = listing(); |
||||
RuntimeException ex = assertThrows(RuntimeException.class, |
||||
() -> adapter(transport).queryReturnsAdvanced(CTX, |
||||
java.util.Arrays.asList(ReturnStatus.PENDING_RECEIPT, ReturnStatus.COMPLETED), |
||||
null, null, null, null, null, null)); |
||||
|
||||
assertTrue(ex.getMessage().contains("single status"), ex.getMessage()); |
||||
assertTrue(transport.dataRequests().isEmpty()); |
||||
} |
||||
|
||||
@Test |
||||
void listSendsSingleStatusAsString() { |
||||
RecordingTransport transport = listing(); |
||||
adapter(transport).queryReturnsAdvanced(CTX, |
||||
Collections.singletonList(ReturnStatus.PENDING_RECEIPT), |
||||
"2026-10-01 00:00:00", "2026-10-31 23:59:59", 1, "1", "RC1", null); |
||||
|
||||
String body = transport.lastDataRequest().body(); |
||||
assertTrue(body.contains("\"returnPlanStatus\":\"15\""), body); |
||||
assertTrue(body.contains("\"queryDataType\":\"1\""), body); |
||||
assertTrue(body.contains("\"queryStartValue\":\"2026-10-01 00:00:00\""), body); |
||||
assertTrue(body.contains("\"queryType\":\"1\""), body); |
||||
assertTrue(body.contains("\"queryValue\":\"RC1\""), body); |
||||
} |
||||
|
||||
@Test |
||||
void listMapsRows() { |
||||
Page<WarehouseReturn> page = adapter(listing()).queryReturns(CTX, null); |
||||
|
||||
assertEquals(1, page.size()); |
||||
assertFalse(page.hasMore()); |
||||
WarehouseReturn ret = page.items().get(0); |
||||
assertEquals("BI250328000202", ret.returnRequestNo()); |
||||
assertEquals("RC25032800006", ret.providerReturnId()); |
||||
assertEquals(ReturnStatus.RETURNING, ret.status(), "35 处理中"); |
||||
assertEquals("EFCA", ret.warehouseCode()); |
||||
} |
||||
|
||||
/** RETURNING 无法唯一映射回恒健状态:返回 null 让调用方明确选,不猜。 */ |
||||
@Test |
||||
void returningStatusIsNotMappedBack() { |
||||
assertEquals("15", HengjianReturnQueryMapper.statusCodeOf(ReturnStatus.PENDING_RECEIPT)); |
||||
assertNull(HengjianReturnQueryMapper.statusCodeOf(ReturnStatus.RETURNING)); |
||||
} |
||||
|
||||
// ================================================================ 处理单列表
|
||||
|
||||
private static final String HANDLE_BODY = |
||||
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"查询成功\",\"data\":{" |
||||
+ "\"totalElements\":15,\"last\":false,\"size\":1,\"number\":0,\"content\":[{" |
||||
+ "\"primaryHandlingMethod\":203," |
||||
+ "\"returnPlanHandleItemsNo\":\"RP25081400001\"," |
||||
+ "\"tracking\":\"KUADIHAO0813\"," |
||||
+ "\"createdAt\":\"2025-08-14T01:32:32.000+0000\"," |
||||
+ "\"changeErpsku\":\"C-2077-BU\",\"errorStatus\":0," |
||||
+ "\"returnPlanNo\":\"RC25081300010\",\"orgWarehouseCode\":\"EFCA\"," |
||||
+ "\"inventoryType\":1,\"quantity\":100,\"handlingQuantity\":100," |
||||
+ "\"sourceNo\":\"BI250813000205\"," |
||||
+ "\"returnInboundNo\":\"SR2025081300007\",\"erpSku\":\"C-2077-BK\"," |
||||
+ "\"completeAt\":\"2025-08-14 01:35:06\",\"handlingStatus\":15}]}}"; |
||||
|
||||
private static RecordingTransport handling() { |
||||
return RecordingTransport.create() |
||||
.route(HengjianConstants.PATH_RETURN_HANDLE_PAGE, req -> Responses.ok(HANDLE_BODY)); |
||||
} |
||||
|
||||
/** 处理单列表请求是平铺的,无 params 包裹。 */ |
||||
@Test |
||||
void handleListPostsFlatBody() { |
||||
RecordingTransport transport = handling(); |
||||
adapter(transport).queryReturnHandles(CTX, |
||||
Collections.singletonList("RC1"), null, null, |
||||
Collections.singletonList(15), null, null, null); |
||||
|
||||
String body = transport.lastDataRequest().body(); |
||||
assertFalse(body.contains("\"params\""), "这个接口是平铺的,body=" + body); |
||||
assertTrue(body.contains("\"returnPlanNoList\":[\"RC1\"]"), body); |
||||
assertTrue(body.contains("\"handlingStatusList\":[15]"), body); |
||||
assertTrue(body.contains("\"page\":1"), body); |
||||
assertTrue(body.contains("\"size\":20"), body); |
||||
} |
||||
|
||||
@Test |
||||
void handleListMapsRows() { |
||||
Page<HengjianReturnHandleDtos.HandleRow> page = |
||||
adapter(handling()).queryReturnHandles(CTX, |
||||
Collections.singletonList("RC1"), null, null, null, null, null, null); |
||||
|
||||
assertEquals(1, page.size()); |
||||
assertTrue(page.hasMore(), "last=false 应给出下一页"); |
||||
assertEquals("2", page.nextCursor()); |
||||
HengjianReturnHandleDtos.HandleRow row = page.items().get(0); |
||||
assertEquals("RC25081300010", row.returnPlanNo); |
||||
assertEquals("RP25081400001", row.returnPlanHandleItemsNo); |
||||
assertEquals("15", row.handlingStatus); |
||||
assertEquals("203", row.primaryHandlingMethod); |
||||
assertEquals("C-2077-BU", row.changeErpsku); |
||||
} |
||||
|
||||
// ================================================================ 处理方式
|
||||
|
||||
private static RecordingTransport processing() { |
||||
return RecordingTransport.create() |
||||
.route(HengjianConstants.PATH_RETURN_HANDLING_METHOD, req -> Responses.ok( |
||||
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"success\"," |
||||
+ "\"data\":{\"returnPlanHandleItemsNo\":\"RP25090200001\"," |
||||
+ "\"handlingStatus\":5}}")); |
||||
} |
||||
|
||||
@Test |
||||
void processPostsFlatBody() { |
||||
RecordingTransport transport = processing(); |
||||
adapter(transport).process(CTX, ReturnProcessCommand.builder() |
||||
.providerReturnNo("RC25081500018") |
||||
.returnNo("TH25081500018") |
||||
.erpSku("SKU-A") |
||||
.tracking("1Z999") |
||||
.handlingMethod(2) |
||||
.primaryHandlingMethod("201") |
||||
.disposition(ReturnProcessDisposition.DESTROY) |
||||
.remark("确认销毁") |
||||
.build()); |
||||
|
||||
assertEquals("POST", transport.lastDataRequest().method()); |
||||
assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/saleReturn/handlingMethod", |
||||
transport.lastDataRequest().url()); |
||||
String body = transport.lastDataRequest().body(); |
||||
assertFalse(body.contains("\"params\""), body); |
||||
assertTrue(body.contains("\"returnPlanNo\":\"RC25081500018\""), body); |
||||
assertTrue(body.contains("\"returnNo\":\"TH25081500018\""), body); |
||||
assertTrue(body.contains("\"erpSku\":\"SKU-A\""), body); |
||||
assertTrue(body.contains("\"tracking\":\"1Z999\""), body); |
||||
assertTrue(body.contains("\"handlingMethod\":2"), body); |
||||
assertTrue(body.contains("\"primaryHandlingMethod\":201"), body); |
||||
} |
||||
|
||||
/** 四项定位字段缺一不可(不用行 id)。 */ |
||||
@Test |
||||
void processRequiresFourLocators() { |
||||
HengjianAdapter adapter = adapter(processing()); |
||||
|
||||
assertThrows(IllegalArgumentException.class, |
||||
() -> adapter.process(CTX, ReturnProcessCommand.builder() |
||||
.providerReturnNo("RC1").returnNo(null).erpSku("S").tracking("T") |
||||
.handlingMethod(2).primaryHandlingMethod("201").build())); |
||||
assertThrows(IllegalArgumentException.class, |
||||
() -> adapter.process(CTX, ReturnProcessCommand.builder() |
||||
.providerReturnNo("RC1").returnNo("TH1").erpSku("S").tracking(null) |
||||
.handlingMethod(2).primaryHandlingMethod("201").build())); |
||||
} |
||||
|
||||
/** core 处理方式能映射四个;拍照类必须显式给原值。 */ |
||||
@Test |
||||
void primaryMethodMapping() { |
||||
assertEquals(Integer.valueOf(201), |
||||
HengjianReturnQueryMapper.primaryCodeOf(ReturnProcessDisposition.DESTROY)); |
||||
assertEquals(Integer.valueOf(202), |
||||
HengjianReturnQueryMapper.primaryCodeOf(ReturnProcessDisposition.RESTOCK)); |
||||
assertEquals(Integer.valueOf(203), |
||||
HengjianReturnQueryMapper.primaryCodeOf(ReturnProcessDisposition.RESTOCK_RELABEL)); |
||||
assertEquals(Integer.valueOf(204), |
||||
HengjianReturnQueryMapper.primaryCodeOf(ReturnProcessDisposition.CUSTOMER_PICKUP)); |
||||
assertNull(HengjianReturnQueryMapper.primaryCodeOf(ReturnProcessDisposition.RESTOCK_UNSELLABLE)); |
||||
} |
||||
|
||||
/** 「继续拍照」必须给拍照数量。 */ |
||||
@Test |
||||
void continuePhotoRequiresPhotosQuantity() { |
||||
HengjianAdapter adapter = adapter(processing()); |
||||
assertThrows(IllegalArgumentException.class, |
||||
() -> adapter.process(CTX, ReturnProcessCommand.builder() |
||||
.providerReturnNo("RC1").returnNo("TH1").erpSku("S").tracking("T") |
||||
.handlingMethod(1).primaryHandlingMethod("102") |
||||
.disposition(ReturnProcessDisposition.DESTROY) |
||||
.build())); |
||||
} |
||||
|
||||
/** 不给 handlingMethod 时拒绝。 */ |
||||
@Test |
||||
void processRequiresHandlingMethod() { |
||||
HengjianAdapter adapter = adapter(processing()); |
||||
assertThrows(IllegalArgumentException.class, |
||||
() -> adapter.process(CTX, ReturnProcessCommand.builder() |
||||
.providerReturnNo("RC1").returnNo("TH1").erpSku("S").tracking("T") |
||||
.primaryHandlingMethod("201").build())); |
||||
} |
||||
|
||||
// ================================================================ 三套码表
|
||||
|
||||
/** 同样是 20:计划状态是「待处理」,处理状态是「已取消」。 */ |
||||
@Test |
||||
void threeCodeTablesAreDistinct() { |
||||
assertEquals(ReturnStatus.RETURNING, |
||||
common.ecommerce.hengjian.enums.HengjianReturnPlanStatus.toCore("20")); |
||||
// 处理状态的 20 是已取消;这里只验证计划状态表,避免误用
|
||||
assertEquals("20", common.ecommerce.hengjian.enums.HengjianReturnPlanStatus.PENDING_PROCESS.rawCode()); |
||||
} |
||||
|
||||
// ================================================================ 分页边界
|
||||
|
||||
@Test |
||||
void rejectsRowsAboveLimit() { |
||||
assertThrows(IllegalArgumentException.class, |
||||
() -> HengjianReturnQueryMapper.rowsOf(500)); |
||||
assertThrows(IllegalArgumentException.class, |
||||
() -> HengjianReturnQueryMapper.handleRowsOf(500)); |
||||
} |
||||
} |
||||
Loading…
Reference in new issue