ye4s_wms/application/index/library/new_wms/notify/WaybillTraceHandler.php
liufumingren 396e9d0581 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>
2026-11-11 20:34:06 +08:00

136 lines
4.2 KiB
PHP
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?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;
}
}