ye4s_wms/application/index/library/new_wms/notify/WaybillTraceHandler.php
liufumingren d953976391 feat(wms): waybill 入参支持「单号|手机号后四位」,查询轨迹时透传
- WaybillCodes 支持拆分单号与手机号后四位(去空格/非数字,超长取后四位),
  按单号去重保序,无后缀时行为与原来完全一致
- express/Trace 支持 phone:buildQueryString 在有 phone 时追加第 4 段
  (单号|单号|公司代码|后四位),无 phone 时保持原格式;去重键改为 单号|phone
- waybill.getTrace / waybill.getreceive 均透传 phone,响应中单号仍不含手机号

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-12 03:54:52 +08:00

148 lines
4.7 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|8000","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(WaybillCodes::parse($body, self::MAX_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 $items [{waybill_code, phone}, ...]
* @return array [运单号 => 轨迹数组]
*/
protected function queryTraces(array $items)
{
$map = [];
$inputs = [];
foreach ($items as $item) {
$map[$item['waybill_code']] = [];
$inputs[] = [
'postnum' => $item['waybill_code'],
'phone' => $item['phone'],
];
}
if (empty($inputs)) {
return $map;
}
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($inputs);
} catch (\Throwable $e) {
\think\Log::error('[WmsNotify] waybill.getTrace 轨迹查询异常: ' . $e->getMessage());
return $map;
}
foreach ($list as $index => $result) {
$code = isset($inputs[$index]['postnum']) ? $inputs[$index]['postnum'] : '';
if ($code === '' || empty($result['ok']) || empty($result['raw'])) {
continue;
}
$map[$code] = $this->flattenTraces($result['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;
}
}