一、功能概述

本模块提供多服务商物流轨迹查询能力，支持以下两种查询方式：
一号通平台查询 - 内部物流跟踪服务
阿里云物流查询 - 第三方高覆盖率查询服务
系统通过后台配置动态切换服务商，核心功能包括：
物流单号有效性校验
实时轨迹数据获取
多服务商兼容适配
查询结果缓存优化

二、核心流程

1. 物流查询接口

@GetMapping("/logisticsInfo")
@PreAuthorize("hasAuthority('admin:order:logistics:info')")
public CommonResult<LogisticsResultVo> getLogisticsInfo(
    @RequestParam String orderNo // 订单号
)

2.. 处理流程图

start
:接收订单号;
:查询订单物流信息;
if (视频号订单?) then (是)
  :获取快递公司编码;
endif
:读取物流服务配置(logistics_type);
if (配置=1?) then (一号通)
  :调用OnePass服务;
else (阿里云)
  :构造授权Header;
  :处理顺丰特殊单号;
  :调用阿里云API;
endif
:数据格式标准化;
:写入缓存;
:返回前端;

3. 服务路由逻辑

// 物流服务选择
String logisticsType = systemConfigService.getValueByKey("logistics_type");
if ("1".equals(logisticsType)) {
    // 一号通查询
    OnePassLogisticsQueryVo vo = onePassService.exprQuery(expressNo, com);
    resultVo = convertToStandard(vo);
} else {
    // 阿里云查询
    JSONObject aliResult = restTemplateUtil.getData(apiUrl, headers);
    resultVo = parseAliResult(aliResult);
}

4. 特殊单号处理

// 顺丰单号需拼接手机尾号
if ("shunfengkuaiyun".equals(com)) {
    expressNo = expressNo + ":" + StrUtil.sub(phone, 7, -1);
}

5. 缓存机制

@Cacheable(value = "logisticsCache", key = "#expressNo")
public LogisticsResultVo getCachedInfo(String expressNo) {
    // 实际查询逻辑
}

三、二开策略

新增物流服务商

实现步骤：

1.扩展配置枚举：

public enum LogisticsProvider {
    ONE_PASS(1), ALIYUN(2), SF_EXPRESS(3);
    private final int code;
}

2.实现查询适配器：

@Component
public class SfLogisticsAdapter implements LogisticsService {
    public LogisticsResultVo query(String expressNo) {
        // 顺丰专属查询逻辑
    }
}

3.修改路由逻辑：

case 3: // 顺丰
    return sfLogisticsAdapter.query(expressNo);