ye4s_wms/application/index/library/new_wms/notify/WaybillReceiveHandler.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

198 lines
6.4 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.getreceive — 运单揽收状态查询
*
* 调用方(WMS 平台)按仓库异步任务批量询问:这些运单是否已被我们(银河仓)揽收。
* 单批最多 10 单,签名模式 simple:md5(appSecret + timestamp + bodyJson)。
*
* 请求体:
* {"request":{"waybill_codes":["773361284774644|8000","321457247679904"]}}
* 单号可带「收件人手机号后四位」后缀,不带则按原格式查询。
* 响应体(裸数组,不套 {code,msg,data} 外壳):
* [{"waybill_code":"773361284774644","is_galaxy_receive":1},
* {"waybill_code":"321457247679904","is_galaxy_receive":0}]
*
* 判定口径:
* - 只查快递轨迹接口(express\Trace),与本地订单/快递/揽收记录无关;
* - 轨迹非空即视为「已揽收」;
* - 已揽收结果缓存 24 小时,命中缓存直接返回、不再请求轨迹接口(不做负缓存);
* - 未揽收 / 查不到 / 识别不出快递公司 / 接口失败 一律返回 0。
*/
class WaybillReceiveHandler
{
/** 单次最多处理的运单号数量(调用方 10 单一批,这里放宽兜底) */
const MAX_CODES = 50;
/** 已揽收结果缓存时长(秒) */
const CACHE_TTL = 86400;
/** 缓存 key 前缀 */
const CACHE_PREFIX = 'wms_waybill_receive:';
/** 轨迹接口超时(秒),需保证整体小于调用方 30s 回调超时 */
const TRACE_TIMEOUT = 10;
/** 轨迹接口并发数 */
const TRACE_CONCURRENCY = 10;
/**
* 处理 waybill.getreceive
*
* @param array $body 请求体 { request: { waybill_codes: [...] } },兼容平铺的 waybill_codes
* @param array $query URL query 参数
* @return RawResponse
*/
public function handle(array $body, array $query)
{
$items = $this->parseCodes($body);
if (empty($items)) {
return new RawResponse([]);
}
$received = $this->resolve($items);
$rows = [];
foreach ($items as $item) {
$code = $item['waybill_code'];
$rows[] = [
'waybill_code' => $code,
'is_galaxy_receive' => !empty($received[$code]) ? 1 : 0,
];
}
\think\Log::info('[WmsNotify] waybill.getreceive 处理完成: 共 ' . count($items) . ' 单,已揽收 ' . count(array_filter($received)) . ' 单');
return new RawResponse($rows);
}
/**
* 解析运单号(去空、去重、保序、限量,并拆分『单号|手机号后四位』)
*
* @param array $body
* @return array [{waybill_code, phone}, ...]
*/
protected function parseCodes(array $body)
{
return WaybillCodes::parse($body, self::MAX_CODES);
}
/**
* 逐单判定是否已揽收:缓存优先,其余并发查询轨迹接口
*
* @param array $items [{waybill_code, phone}, ...]
* @return array [运单号 => 1|0]
*/
protected function resolve(array $items)
{
$received = [];
$redis = $this->connectRedis();
$pending = [];
foreach ($items as $item) {
$code = $item['waybill_code'];
$received[$code] = 0;
if ($redis !== null && $this->cacheHit($redis, $code)) {
$received[$code] = 1;
continue;
}
$pending[] = $item;
}
if (empty($pending)) {
\think\Log::info('[WmsNotify] waybill.getreceive 命中缓存,跳过轨迹接口: ' . count($items) . ' 单');
return $received;
}
try {
$traceOptions = [
'timeout' => self::TRACE_TIMEOUT,
'concurrency' => self::TRACE_CONCURRENCY,
'batch_size' => 1,
'retries' => 0,
];
// 轨迹接口地址可通过 application/extra/wms.php 的 trace_base_url 覆盖(便于测试/灰度)
$traceBaseUrl = config('wms.trace_base_url');
if (!empty($traceBaseUrl)) {
$traceOptions['base_url'] = $traceBaseUrl;
}
$inputs = [];
foreach ($pending as $item) {
$inputs[] = [
'postnum' => $item['waybill_code'],
'phone' => $item['phone'],
];
}
$trace = new Trace($traceOptions);
$list = $trace->query($inputs);
} catch (\Throwable $e) {
\think\Log::error('[WmsNotify] waybill.getreceive 轨迹查询异常: ' . $e->getMessage());
return $received;
}
foreach ($list as $index => $result) {
$code = isset($pending[$index]['waybill_code']) ? $pending[$index]['waybill_code'] : '';
if ($code === '' || empty($result['ok']) || empty($result['traces'])) {
continue;
}
$received[$code] = 1;
if ($redis !== null) {
$this->cacheSet($redis, $code);
}
}
return $received;
}
/**
* @return \Redis|null
*/
protected function connectRedis()
{
if (!class_exists('\Redis')) {
return null;
}
$config = (array)config('cache.redis');
$host = !empty($config['host']) ? $config['host'] : '127.0.0.1';
$port = !empty($config['port']) ? (int)$config['port'] : 6379;
try {
$redis = new \Redis();
$redis->connect($host, $port, 1.5);
if (!empty($config['password'])) {
$redis->auth($config['password']);
}
if (!empty($config['select'])) {
$redis->select((int)$config['select']);
}
return $redis;
} catch (\Exception $e) {
\think\Log::error('[WmsNotify] waybill.getreceive Redis 连接失败: ' . $e->getMessage());
return null;
}
}
protected function cacheHit($redis, $code)
{
try {
return (string)$redis->get(self::CACHE_PREFIX . $code) === '1';
} catch (\Exception $e) {
return false;
}
}
protected function cacheSet($redis, $code)
{
try {
$redis->setex(self::CACHE_PREFIX . $code, self::CACHE_TTL, '1');
} catch (\Exception $e) {
// 缓存失败不影响本次结果
}
}
}