feat(wms): 新增运单轨迹查询回调 waybill.getTrace

- notify/WaybillTraceHandler:按 {request:{waybill_codes}} 批量查询轨迹(10 单并发),
  输出裸数组 [{waybillNo, trace:[{opTime,outBizCode,memo,opOrgCityName,weight,scanType}]}]
- notify/WaybillCodes:抽取 waybill.* 系列共用的入参解析(兼容平铺结构、去空、去重保序、限量)
- WaybillReceiveHandler 改用 WaybillCodes,行为不变
- express/Trace::parseResult 增加 raw(上游原始轨迹),供 getTrace 原样透出
- Dispatcher 注册 waybill.getTrace

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
liufumingren 2026-11-11 20:34:06 +08:00
parent 980aa88294
commit 396e9d0581
5 changed files with 195 additions and 31 deletions

View File

@ -576,6 +576,7 @@ class Trace
'company' => Recognizer::companyName($task['postcode']),
'ok' => true,
'traces' => $traces,
'raw' => $raw,
'status' => $status,
'type' => $type,
'type_text' => self::typeText($type),

View File

@ -58,6 +58,9 @@ class Dispatcher
if (!isset(self::$handlers['waybill.getreceive'])) {
self::register('waybill.getreceive', [new WaybillReceiveHandler(), 'handle']);
}
if (!isset(self::$handlers['waybill.getTrace'])) {
self::register('waybill.getTrace', [new WaybillTraceHandler(), 'handle']);
}
}
// ==================== 处理器注册 ====================

View File

@ -0,0 +1,55 @@
<?php
namespace app\index\library\new_wms\notify;
/**
* 入站回调运单号参数解析
*
* waybill.* 系列方法的请求体统一为 { request: { waybill_codes: [...] } },
* 这里统一做「兼容平铺结构 + 去空 + 去重保序 + 限量」,供各处理器复用。
*/
class WaybillCodes
{
/** 默认单次最多处理的运单号数量 */
const DEFAULT_MAX = 50;
/**
* @param array $body 请求体
* @param int $max 最多返回条数
* @return array 去重保序后的运单号列表
*/
public static function extract(array $body, $max = self::DEFAULT_MAX)
{
$raw = [];
if (isset($body['request']['waybill_codes'])) {
$raw = $body['request']['waybill_codes'];
} elseif (isset($body['request']['waybillCodes'])) {
$raw = $body['request']['waybillCodes'];
} elseif (isset($body['waybill_codes'])) {
$raw = $body['waybill_codes'];
} elseif (isset($body['waybillCodes'])) {
$raw = $body['waybillCodes'];
}
if (!is_array($raw)) {
$raw = [$raw];
}
$codes = [];
foreach ($raw as $item) {
if (is_array($item) || is_object($item)) {
continue;
}
$code = trim((string)$item);
if ($code === '' || isset($codes[$code])) {
continue;
}
$codes[$code] = $code;
if (count($codes) >= $max) {
break;
}
}
return array_values($codes);
}
}

View File

@ -76,37 +76,7 @@ class WaybillReceiveHandler
*/
protected function extractCodes(array $body)
{
$raw = [];
if (isset($body['request']['waybill_codes'])) {
$raw = $body['request']['waybill_codes'];
} elseif (isset($body['request']['waybillCodes'])) {
$raw = $body['request']['waybillCodes'];
} elseif (isset($body['waybill_codes'])) {
$raw = $body['waybill_codes'];
} elseif (isset($body['waybillCodes'])) {
$raw = $body['waybillCodes'];
}
if (!is_array($raw)) {
$raw = [$raw];
}
$codes = [];
foreach ($raw as $item) {
if (is_array($item) || is_object($item)) {
continue;
}
$code = trim((string)$item);
if ($code === '' || isset($codes[$code])) {
continue;
}
$codes[$code] = $code;
if (count($codes) >= self::MAX_CODES) {
break;
}
}
return array_values($codes);
return WaybillCodes::extract($body, self::MAX_CODES);
}
/**

View File

@ -0,0 +1,135 @@
<?php
namespace app\index\library\new_wms\notify;
use app\index\library\express\Trace;
/**
* waybill.getTrace — 运单物流轨迹查询
*
* 调用方(WMS 平台)按仓库异步任务批量拉取运单轨迹,单批最多 10 单,
* 签名模式 simple:md5(appSecret + timestamp + bodyJson)。
*
* 请求体:
* {"request":{"waybill_codes":["770358128188071","319415577176711"]}}
* 响应体(裸数组,不套 {code,msg,data} 外壳):
* [
* {"waybillNo":"770358128188071","trace":[
* {"opTime":"2026-11-10 04:26:39","outBizCode":"...","memo":"...",
* "opOrgCityName":"广州市","weight":"0.99","scanType":"收件"}, ...]},
* {"waybillNo":"319415577176711","trace":[...]}
* ]
*
* 说明:
* - 只查快递轨迹接口(express\Trace),与本地订单/快递表无关;
* - 每个运单一条记录,trace 为该运单的轨迹数组(按时间升序);查不到时为 [];
* - 轨迹字段原样透出上游(opTime / outBizCode / memo / opOrgCityName / weight / scanType)。
*/
class WaybillTraceHandler
{
/** 单次最多处理的运单号数量(调用方 10 单一批,这里放宽兜底) */
const MAX_CODES = 50;
/** 轨迹接口超时(秒),需保证整体小于调用方 30s 回调超时 */
const TRACE_TIMEOUT = 10;
/** 轨迹接口并发数 */
const TRACE_CONCURRENCY = 10;
/**
* @param array $body 请求体 { request: { waybill_codes: [...] } }
* @param array $query URL query 参数
* @return RawResponse
*/
public function handle(array $body, array $query)
{
$codes = WaybillCodes::extract($body, self::MAX_CODES);
if (empty($codes)) {
return new RawResponse([]);
}
$traceMap = $this->queryTraces($codes);
$rows = [];
$count = 0;
foreach ($codes as $code) {
$traces = isset($traceMap[$code]) ? $traceMap[$code] : [];
$count += count($traces);
$rows[] = [
'waybillNo' => $code,
'trace' => $traces,
];
}
\think\Log::info('[WmsNotify] waybill.getTrace 处理完成: 共 ' . count($codes) . ' 单,轨迹 ' . $count . ' 条');
return new RawResponse($rows);
}
/**
* 批量查询轨迹(10 单并发)
*
* @param array $codes
* @return array [运单号 => 轨迹数组]
*/
protected function queryTraces(array $codes)
{
$map = array_fill_keys($codes, []);
try {
$traceOptions = [
'timeout' => self::TRACE_TIMEOUT,
'concurrency' => self::TRACE_CONCURRENCY,
'batch_size' => 1,
'retries' => 0,
];
$traceBaseUrl = config('wms.trace_base_url');
if (!empty($traceBaseUrl)) {
$traceOptions['base_url'] = $traceBaseUrl;
}
$trace = new Trace($traceOptions);
$list = $trace->query($codes);
} catch (\Throwable $e) {
\think\Log::error('[WmsNotify] waybill.getTrace 轨迹查询异常: ' . $e->getMessage());
return $map;
}
foreach ($list as $index => $item) {
$code = isset($codes[$index]) ? $codes[$index] : '';
if ($code === '' || empty($item['ok']) || empty($item['raw'])) {
continue;
}
$map[$code] = $this->flattenTraces($item['raw']);
}
return $map;
}
/**
* 上游返回 [{waybillNo, trace:{opTime,...}}, ...],这里取内层 trace 对象,
* 输出成调用方需要的 [{opTime, outBizCode, memo, opOrgCityName, weight, scanType}, ...]
*
* @param array $raw
* @return array
*/
protected function flattenTraces($raw)
{
if (!is_array($raw)) {
return [];
}
$traces = [];
foreach ($raw as $item) {
if (!is_array($item)) {
continue;
}
if (isset($item['trace']) && is_array($item['trace'])) {
$traces[] = $item['trace'];
} else {
$traces[] = $item;
}
}
return $traces;
}
}