@ -161,6 +161,13 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
@@ -161,6 +161,13 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
private static final String OP_DESTRUCTION_GET = "warehouse.destruction.get" ;
private static final String OP_RETURN_GET = "warehouse.return.get" ;
private static final String OP_RETURN_QUERY = "warehouse.return.query" ;
/** 退货列表的时间窗格式(恒健文档:{@code yyyy-MM-dd HH:mm:ss},UTC)。 */
private static final java . time . format . DateTimeFormatter HENGJIAN_TIME =
java . time . format . DateTimeFormatter . ofPattern ( "yyyy-MM-dd HH:mm:ss" ) ;
/** 恒健 {@code queryType}:来源单号。 */
private static final String QUERY_TYPE_SOURCE_NO = "2" ;
/** 恒健 {@code queryType}:退货 tracking。 */
private static final String QUERY_TYPE_TRACKING = "4" ;
private static final String OP_RETURN_HANDLES = "warehouse.return.handles" ;
private static final String OP_RETURN_PROCESS = "warehouse.return.process" ;
/** 退货列表默认页大小(文档没写,按同站惯例 100)。 */
@ -315,51 +322,85 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
@@ -315,51 +322,85 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti
/ * *
* 分页查退货计划 ( { @code POST / v1 / saleReturn / thirdParty / getReturnPlanOrderPage } ) 。
*
* < p > 统一模型这个入口只有游标 , 恒健的列表支持更多条件 ; 这里把游标当页码 ,
* 其余条件为空 — — 需要按状态 / 时间窗筛时用 { @link # queryReturnsAdvanced } 。 < / p >
* < p > 支持的维度见 { @link ReturnQuery } ; < b > 不支持的维度直接拒绝 < / b > ,
* 静默忽略会让调用方以为筛过 。 < / p >
*
* < p > 恒健的三处限制 : < / p >
* < ul >
* < li > 状态是 < b > 单值 < / b > ( { @code returnPlanStatus } 不是数组 ) , 给多个即拒绝 ; < / li >
* < li > 没有 SKU 过滤 ; < / li >
* < li > 「 单号 」 与 「 自由查询条件 」 共用一组 { @code queryType / queryValue } ,
* 所以不能同时给 { @code orderNo } 和 { @code trackingNo } 。 < / li >
* < / ul >
* /
@Override
public Page < WarehouseReturn > queryReturns ( WarehouseContext ctx , ReturnQuery query ) {
// 统一入口只带游标 / 每页条数与仓库;其余条件为空——需要按状态 / 时间窗筛时
// 用 queryReturnsAdvanced。ReturnQuery 里给了这里不支持的维度时显式拒绝,
// 静默忽略会让调用方以为筛过。
if ( query ! = null & & ( query . hasCreatedRange ( ) | | query . orderNo ( ) ! = null
| | query . trackingNo ( ) ! = null | | query . providerSku ( ) ! = null
| | ! query . statuses ( ) . isEmpty ( ) ) ) {
ReturnQuery q = query = = null ? ReturnQuery . builder ( ) . build ( ) : query ;
if ( q . providerSku ( ) ! = null ) {
throw validation ( ctx , OP_RETURN_QUERY ,
"hengjian return list does not take these filters through the unified entry;"
+ " use queryReturnsAdvanced (statuses / time window / order no / sku)" ) ;
"hengjian return list has no sku filter" ) ;
}
if ( q . statuses ( ) . size ( ) > 1 | | q . rawStatuses ( ) . size ( ) > 1 ) {
throw validation ( ctx , OP_RETURN_QUERY ,
"hengjian return list supports a single status; got statuses=" + q . statuses ( )
+ " rawStatuses=" + q . rawStatuses ( ) ) ;
}
if ( q . orderNo ( ) ! = null & & q . trackingNo ( ) ! = null ) {
throw validation ( ctx , OP_RETURN_QUERY ,
"hengjian return list shares one queryType/queryValue pair;"
+ " give orderNo or trackingNo, not both" ) ;
}
return queryReturnsAdvanced ( ctx , null , null , null , null , null , null ,
query = = null ? null : query . cursor ( ) ) ;
}
/ * *
* 多条件分页查退货计划 。
*
* < p > < b > 恒健只支持单个状态过滤 < / b > ( { @code returnPlanStatus } 是单值不是数组 ) ,
* 给多个状态时拒绝 — — 静默只取一个会让调用方以为筛全了 。 < / p >
* /
public Page < WarehouseReturn > queryReturnsAdvanced ( WarehouseContext ctx ,
List < ReturnStatus > statuses ,
String startTime , String endTime ,
Integer queryDataType ,
String queryType , String queryValue ,
String cursor ) {
if ( statuses ! = null & & statuses . size ( ) > 1 ) {
ReturnStatus single = q . statuses ( ) . isEmpty ( ) ? null : q . statuses ( ) . get ( 0 ) ;
// 原值优先:调用方明确给了仓方码就用它,别让统一枚举再折一次
String rawStatus = q . rawStatuses ( ) . isEmpty ( ) ? null : q . rawStatuses ( ) . get ( 0 ) ;
if ( rawStatus ! = null & & single ! = null ) {
throw validation ( ctx , OP_RETURN_QUERY ,
"hengjian return list supports a single status filter, got " + statuses ) ;
"statuses and rawStatuses are mutually exclusive" ) ;
}
ReturnStatus single = statuses = = null | | statuses . isEmpty ( ) ? null : statuses . get ( 0 ) ;
int page = HengjianReturnQueryMapper . pageOf ( cursor ) ;
int size = HengjianReturnQueryMapper . rowsOf ( PAGE_SIZE_DEFAULT ) ;
String startTime = null ;
String endTime = null ;
if ( q . hasCreatedRange ( ) ) {
startTime = HENGJIAN_TIME . format ( q . createdAfter ( ) . atOffset ( java . time . ZoneOffset . UTC ) ) ;
endTime = HENGJIAN_TIME . format ( q . createdBefore ( ) . atOffset ( java . time . ZoneOffset . UTC ) ) ;
} else if ( q . createdAfter ( ) ! = null | | q . createdBefore ( ) ! = null ) {
throw validation ( ctx , OP_RETURN_QUERY ,
"hengjian return time window needs both createdAfter and createdBefore" ) ;
}
// 单号 / tracking 与自由查询条件共用一组 queryType/queryValue
String queryType = q . queryTypeValue ( ) ;
String queryValue = q . queryValue ( ) ;
if ( q . orderNo ( ) ! = null ) {
queryType = QUERY_TYPE_SOURCE_NO ;
queryValue = q . orderNo ( ) ;
} else if ( q . trackingNo ( ) ! = null ) {
queryType = QUERY_TYPE_TRACKING ;
queryValue = q . trackingNo ( ) ;
} else if ( ( queryType = = null ) ! = ( queryValue = = null ) ) {
throw validation ( ctx , OP_RETURN_QUERY ,
"hengjian return queryTypeValue and queryValue must be given together" ) ;
}
int page = HengjianReturnQueryMapper . pageOf ( q . cursor ( ) ) ;
int size = q . pageSize ( ) > 0
? HengjianReturnQueryMapper . rowsOf ( q . pageSize ( ) )
: HengjianReturnQueryMapper . rowsOf ( PAGE_SIZE_DEFAULT ) ;
List < String > warehouseCodes = q . warehouseCode ( ) = = null
? null : java . util . Collections . singletonList ( q . warehouseCode ( ) ) ;
HengjianReturnListDtos . ListRequest body = HengjianReturnQueryMapper . toListRequest (
statuses , single , startTime , endTime , queryDataType , queryType , queryValue ,
null , page , size ) ;
q . statuses ( ) , single , startTime , endTime , q . queryDataType ( ) ,
queryType , queryValue , warehouseCodes , page , size ) ;
if ( rawStatus ! = null ) {
// 原值直接落进报文:statusCodeOf 只认统一枚举,表达不了 20 / 35 的区分
body . params . returnPlanStatus = rawStatus ;
}
String raw = execute ( ctx , HengjianConstants . PATH_RETURN_PLAN_PAGE , body , OP_RETURN_QUERY ) ;
HengjianReturnListDtos . ListResponse resp =
json . fromJson ( raw , HengjianReturnListDtos . ListResponse . class ) ;
return HengjianReturnQueryMapper . toPage ( resp = = null ? null : resp . data , cursor , size ) ;
return HengjianReturnQueryMapper . toPage ( resp = = null ? null : resp . data , q . cursor ( ) , size ) ;
}
/ * *