破解二手车展厅质检痛点：从传统纸质保养手册到历史维保档案数据穿透直连
在全国品牌二手车官方认证展厅、连锁二手车经销商城以及大型汽车新零售数字化交易平台的日常业务运转中，车源质检上架与车况合规审查是保障展厅品牌公信力与车辆资产透明流通的生命线。每一辆进入官方认证展厅的二手车，在摆上展位、面向消费者公开销售前，都必须经过极其严苛的整车技术检测并建立完整的车况档案。然而，二手车属于高价值非标商品，车辆过去的实际使用与维修经历极难通过常规的静态外观勘验完整获知。传统模式下，展厅评估师多依赖车主提供的纸质维修保养手册、口头陈述，或仅凭肉眼观测漆面厚度与底盘螺丝痕迹。这种传统方式流程繁琐、主观经验依赖性强，根本无法穿透车辆在授权 4S 店与专业维修机构中的真实历史维保轨迹。部分车源可能存在私自调低表显里程、隐瞒发动机拆解大修、变速箱核心部件更换或车身底盘结构性校正等深层维保隐患。一旦展厅将潜藏重大核心部件维修史或表显里程与实际维保记录严重脱节的车辆误评为"准新车/官方金牌认证车"推向市场，极易引发消费者的退车索赔纠纷，严重损害展厅的商业信誉并带来难以估量的法务履约风险。
在严格遵守机动车流通相关政策法规、并取得车主在线合法明示授权的前提下，基于 PHP（Laravel / Hyperf / 裸写高可用架构）构建的二手车展厅车况质检 CRM 与车辆电子档案中枢可直接接入海宇普通维保查询接口。质检专员在移动端收车工作台录入车辆 17 位车架号 vin、车牌号 plate、上传清晰的机动车行驶证图片地址 img_url，并指定平台自定义的唯一业务订单号 out_order_no、报告格式 report_type（指定 url 获取可视化在线交互报告或指定 json 获取结构化维保记录）以及系统异步接收端点 notify_url，系统即可通过高强度 AES-128-CBC 对称加密专线向海宇数据开放平台（API 端点：https://api.haiyudata.com/api/v1/QCXGW8K3?t=13位时间戳）发起异步查询。海宇接口依托高可用异步调度架构，首次同步应答快速返回解密后的 out_order_no 锁定受理流程；底层数据底座深度穿透全国主流汽车品牌授权 4S 店与权威维保数据库，全面归集该车辆历史进店维保次数、历次维修保养日期、进店记录里程、维保项目明细及核心总成维修记录，并通过 HTTP POST Webhook 方式向系统回调地址推送标准通知。平台服务端解密该密文后即可提取全维历史维保档案，为展厅核验真实里程、排查重大部件维修、评定官方认证等级并生成专属《车况质检档案卡》提供客观权威依据。
将海宇普通维保查询接口以异步非阻塞架构深度整合至二手车展厅质检管理系统、收购评估系统与展厅数字化营销看板中，能够彻底打破传统人工核验的低效壁垒，打造"展厅收车初检-异步任务提报-Webhook秒级回传-维保档案自动解析-官方认证质检卡一键生成"的全自动化合规管道。质检工单提交后，系统主线程无阻塞快速响应；当海宇底座完成维保网络穿透并推送回调时，后台服务瞬时解密提取维保明细，自动比对车辆当前表显里程与历史最后进店维保里程，智能核查是否存在发动机或变速箱大修等关键工单：若维保记录连贯且无重大部件异常，系统自动核发"展厅金牌认证资质"并生成车况二维码；若发现里程记录异常或存在核心部件大修痕迹，系统自动触发前置准入校验机制，暂缓车辆展厅上架并转入资深评估总监人工复核提醒。这一架构不仅将原本数天的维保调档周期缩短至秒级自动化响应，更为品牌二手车认证展厅构筑起了透明可信、科学严密的合规数字化质检防线。
PHP 加密通信集成：构建高可用审核管道
1. 核心参数与加密配置
- 接口地址 :
https://api.haiyudata.com/api/v1/QCXGW8K3(需在 URL 附加?t=13位时间戳) - 请求方式 :
POST - 请求头 :
Access-Id: 账号的 Access-Id (必填)Content-Type:application/json
- 关键入参 :
vin: 车架号（必填）plate: 车牌号（必填）img_url: 行驶证图片地址（必填）out_order_no: 用户自定义业务订单号（用户自定义，用于关联请求与回调），请确保唯一，最长不超过64位；用于关联请求与回调（必填）report_type: 数据格式：url、json（必填）notify_url: 数据异步回调地址，必填，用于接收异步结果回调（必填）
- 鉴权与加密机制 : 使用账户的 16 进制 Access Key 作为密钥，采用 AES-128 算法的 CBC 模式。每次请求需动态生成 16 字节的 IV（初始化向量），并配合 PKCS7 填充，最终将 IV 与密文拼接后进行 Base64 编码放入请求体
data字段中。
2. 标准化调用代码 (PHP)
以下为运行在品牌二手车认证展厅车况质检 CRM 服务端的生产级 PHP 类实现（兼容 PHP 8.0 及以上版本，深度依赖原生 openssl、curl 与 json 扩展）。代码遵循 PSR-12 规范，包含 ISO 3779 车架号国际算法核验、车牌号正则校验、行驶证图片合法性断言、AES-128-CBC 动态加解密、异步订单提报、Webhook 回调解密，以及根据历史维保档案自动校验表显里程与生成车况质检卡的业务闭环：
php
<?php
declare(strict_types=1);
namespace App\Services\VehicleInspectionCompliance;
use RuntimeException;
use InvalidArgumentException;
/**
* 品牌二手车认证展厅 CRM - 普通维保查询异步提报与车况质检报告生成服务
*/
class VehicleMaintenanceInspectionService
{
private const API_ENDPOINT = 'https://api.haiyudata.com/api/v1/QCXGW8K3';
private const CIPHER_ALGO = 'AES-128-CBC';
private const IV_LENGTH = 16;
private const PRODUCT_CODE = 'QCXGW8K3';
// 异步回调外层业务状态码 (code)
public const CODE_SUCCESS = 0; // 查询成功且返回维保报告
public const CODE_QUERY_EMPTY = 1000; // 查询为空（暂无官方维保记录收录）
public const CODE_BIZ_FAILURE = 2001; // 业务失败（如车架号与车牌号不匹配或凭证模糊）
public const CODE_SYSTEM_EXCEPTION = 1001; // 接口异常（上游数据源异常）
// 展厅官方车况认证等级
public const CERT_GRADE_GOLD = 'GOLD_CERTIFIED'; // 金牌官方认证：维保记录完整连贯、里程真实无调表、无重大部件大修
public const CERT_GRADE_SILVER = 'SILVER_CERTIFIED'; // 优选认证：维保记录基本合规、里程无明显异常、仅轻微易损件维护
public const CERT_GRADE_MANUAL_REVIEW = 'MANUAL_REVIEW_REQUIRED'; // 需人工复核：存在里程异常或核心动力总成重大维修工单
private string $accessId;
private string $binaryKey;
private int $timeoutSeconds;
/**
* @param string $accessId 海宇数据开放平台分配的 Access-Id
* @param string $accessKeyHex 32位16进制格式的 Access Key（系统内部自动转为16字节二进制密钥）
* @param int $timeoutSeconds HTTP 同步提报超时时间（秒，默认 5 秒）
*/
public function __construct(string $accessId, string $accessKeyHex, int $timeoutSeconds = 5)
{
$cleanAccessId = trim($accessId);
$cleanKeyHex = trim($accessKeyHex);
if ($cleanAccessId === '') {
throw new InvalidArgumentException('Access-Id 不能为空。');
}
if (strlen($cleanKeyHex) !== 32 || !ctype_xdigit($cleanKeyHex)) {
throw new InvalidArgumentException('Access Key 必须为合法的 32 位 16 进制字符串（128位密钥）。');
}
$this->accessId = $cleanAccessId;
$this->binaryKey = (string) hex2bin($cleanKeyHex);
$this->timeoutSeconds = max(1, $timeoutSeconds);
}
/**
* 校验 17 位车辆识别代码（VIN）格式及 ISO 3779 国际标准校验位
*/
public function validateVin(string $vin): bool
{
$vin = strtoupper(trim($vin));
if (!preg_match('/^[A-HJ-NPR-Z0-9]{17}$/', $vin)) {
return false;
}
$charValues = [
'A' => 1, 'B' => 2, 'C' => 3, 'D' => 4, 'E' => 5, 'F' => 6, 'G' => 7, 'H' => 8,
'J' => 1, 'K' => 2, 'L' => 3, 'M' => 4, 'N' => 5, 'P' => 7, 'R' => 9,
'S' => 2, 'T' => 3, 'U' => 4, 'V' => 5, 'W' => 6, 'X' => 7, 'Y' => 8, 'Z' => 9,
'0' => 0, '1' => 1, '2' => 2, '3' => 3, '4' => 4, '5' => 5, '6' => 6, '7' => 7, '8' => 8, '9' => 9,
];
$weights = [8, 7, 6, 5, 4, 3, 2, 10, 0, 9, 8, 7, 6, 5, 4, 3, 2];
$sum = 0;
for ($i = 0; $i < 17; $i++) {
$char = $vin[$i];
if (!isset($charValues[$char])) {
return false;
}
$sum += $charValues[$char] * $weights[$i];
}
$remainder = $sum % 11;
$expectedCheckChar = ($remainder === 10) ? 'X' : (string) $remainder;
return $vin[8] === $expectedCheckChar;
}
/**
* 校验中国机动车号牌格式（兼容传统蓝牌、黄牌及新能源绿牌）
*/
public function validatePlate(string $plate): bool
{
$plate = trim($plate);
$pattern = '/^[京津沪渝冀豫云辽黑湘皖鲁新苏浙赣鄂桂甘晋蒙陕吉闽贵粤青藏川宁琼使领][A-HJ-Z](([DF][A-HJ-NP-Z0-9][0-9]{4})|([0-9]{5}[DF])|([A-HJ-NP-Z0-9]{4,5}[挂学警港澳]?))$/u';
return (bool) preg_match($pattern, $plate);
}
/**
* 执行 AES-128-CBC 加密（PKCS7 填充），前置拼接 16 字节随机 IV 后转为 Base64 编码
*
* @param array<string, mixed> $payload 业务明文字典
* @return string 包含 IV 头部的 Base64 密文字符串
*/
public function encryptPayload(array $payload): string
{
$plainJson = json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR);
$iv = random_bytes(self::IV_LENGTH);
$cipherRaw = openssl_encrypt(
$plainJson,
self::CIPHER_ALGO,
$this->binaryKey,
OPENSSL_RAW_DATA,
$iv
);
if ($cipherRaw === false) {
throw new RuntimeException('维保查询业务请求 AES-128-CBC 加密失败: ' . openssl_error_string());
}
return base64_encode($iv . $cipherRaw);
}
/**
* 解密载荷：Base64 解码后提取前 16 字节 IV，通过 AES-128-CBC 解密剩余密文并去除 PKCS7 填充
*
* @param string $encryptedBase64 服务端回传的 Base64 密文字符串
* @return array<string, mixed> 解密后的明文数组
*/
public function decryptPayload(string $encryptedBase64): array
{
$combinedRaw = base64_decode($encryptedBase64, true);
if ($combinedRaw === false || strlen($combinedRaw) <= self::IV_LENGTH) {
throw new RuntimeException('待解密载荷 Base64 格式无效或长度不足 16 字节 IV 头部。');
}
$iv = substr($combinedRaw, 0, self::IV_LENGTH);
$cipherText = substr($combinedRaw, self::IV_LENGTH);
$decryptedJson = openssl_decrypt(
$cipherText,
self::CIPHER_ALGO,
$this->binaryKey,
OPENSSL_RAW_DATA,
$iv
);
if ($decryptedJson === false) {
throw new RuntimeException('维保查询响应密文 AES-128-CBC 解密失败: ' . openssl_error_string());
}
return json_decode($decryptedJson, true, 512, JSON_THROW_ON_ERROR);
}
/**
* 提报二手车历史维保档案异步查询任务
*
* @param string $vin 车辆 17 位车架号
* @param string $plate 车辆登记车牌号
* @param string $imgUrl 行驶证远程照片可访问 URL
* @param string $outOrderNo 展厅自定义业务订单号（≤64位，防重主键）
* @param string $notifyUrl Webhook 异步结果接收公网地址
* @param string $reportType 报告格式：'url' 或 'json'
* @return array<string, mixed> 首次同步响应解析结果
*/
public function submitMaintenanceQuery(
string $vin,
string $plate,
string $imgUrl,
string $outOrderNo,
string $notifyUrl,
string $reportType = 'url'
): array {
$cleanVin = strtoupper(trim($vin));
$cleanPlate = trim($plate);
$cleanImgUrl = trim($imgUrl);
$cleanOutOrderNo = trim($outOrderNo);
$cleanNotifyUrl = trim($notifyUrl);
$cleanReportType = strtolower(trim($reportType));
if (!$this->validateVin($cleanVin)) {
throw new InvalidArgumentException(sprintf('车架号 [%s] 格式无效或 ISO 3779 校验码不匹配。', $cleanVin));
}
if (!$this->validatePlate($cleanPlate)) {
throw new InvalidArgumentException(sprintf('车牌号 [%s] 格式不合规。', $cleanPlate));
}
if (!filter_var($cleanImgUrl, FILTER_VALIDATE_URL) || !preg_match('/^https?:\/\//i', $cleanImgUrl)) {
throw new InvalidArgumentException('行驶证图片地址 img_url 必须为合法的 HTTP/HTTPS 公网 URL。');
}
if ($cleanOutOrderNo === '' || strlen($cleanOutOrderNo) > 64) {
throw new InvalidArgumentException('自定义订单号 out_order_no 不能为空且最长不超过 64 位。');
}
if (!in_array($cleanReportType, ['url', 'json'], true)) {
throw new InvalidArgumentException('报告格式 report_type 必须为 url 或 json。');
}
if (!filter_var($cleanNotifyUrl, FILTER_VALIDATE_URL) || !preg_match('/^https?:\/\//i', $cleanNotifyUrl)) {
throw new InvalidArgumentException('异步回调地址 notify_url 必须为合法的 HTTP/HTTPS 公网 URL。');
}
// 1. 组装请求参数字典并加密
$businessPayload = [
'vin' => $cleanVin,
'plate' => $cleanPlate,
'img_url' => $cleanImgUrl,
'out_order_no' => $cleanOutOrderNo,
'report_type' => $cleanReportType,
'notify_url' => $cleanNotifyUrl,
];
$encryptedData = $this->encryptPayload($businessPayload);
// 2. 构造请求地址（附加 13 位毫秒级时间戳）
$timestamp = (string) round(microtime(true) * 1000);
$requestUrl = self::API_ENDPOINT . '?t=' . $timestamp;
// 3. 发起 cURL POST 请求
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $requestUrl,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode(['data' => $encryptedData], JSON_THROW_ON_ERROR),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => $this->timeoutSeconds,
CURLOPT_CONNECTTIMEOUT => 3,
CURLOPT_SSL_VERIFYPEER => true,
CURLOPT_SSL_VERIFYHOST => 2,
CURLOPT_HTTPHEADER => [
'Access-Id: ' . $this->accessId,
'Content-Type: application/json; charset=utf-8',
'User-Agent: UsedCarInspection-CMS/1.0',
],
]);
$rawResponse = curl_exec($ch);
$httpCode = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlError = curl_error($ch);
curl_close($ch);
if ($rawResponse === false) {
throw new RuntimeException('普通维保查询接口提交网络故障: ' . $curlError);
}
if ($httpCode !== 200) {
throw new RuntimeException(sprintf('普通维保查询首次响应 HTTP 状态码异常: %d, 响应报文: %s', $httpCode, $rawResponse));
}
$outerResponse = json_decode((string) $rawResponse, true, 512, JSON_THROW_ON_ERROR);
$apiCode = (int) ($outerResponse['code'] ?? -1);
$apiMessage = (string) ($outerResponse['message'] ?? '');
$transactionId = (string) ($outerResponse['transaction_id'] ?? '');
$cipherData = (string) ($outerResponse['data'] ?? '');
if ($apiCode !== self::CODE_SUCCESS || $cipherData === '') {
throw new RuntimeException(sprintf('普通维保查询受理失败: code=%d, message=%s', $apiCode, $apiMessage));
}
// 4. 解密首次响应数据，校验并提取 out_order_no
$decryptedFirstResponse = $this->decryptPayload($cipherData);
$returnedOrderNo = (string) ($decryptedFirstResponse['out_order_no'] ?? '');
return [
'submission_success' => true,
'transaction_id' => $transactionId,
'out_order_no' => $returnedOrderNo,
'message' => '异步维保查询任务已成功受理，系统已进入后台 Webhook 监听状态。',
];
}
/**
* 处理上游 Webhook 推送的维保报告回调数据并生成车况质检卡
*
* @param string $rawWebhookJson Webhook POST 请求体原始 JSON 字符串
* @param float $odometerMiles万公里 展厅入库时实际读取的表显仪表里程（用于真实里程比对）
* @return array<string, mixed> 包含业务质检档案与商户应答报文的结果集
*/
public function handleWebhookCallback(string $rawWebhookJson, float $odometerMiles万公里 = 0.0): array
{
$callbackData = json_decode($rawWebhookJson, true, 512, JSON_THROW_ON_ERROR);
$code = (int) ($callbackData['code'] ?? -1);
$message = (string) ($callbackData['message'] ?? '');
$outOrderNo = (string) ($callbackData['out_order_no'] ?? '');
$transactionId = (string) ($callbackData['transaction_id'] ?? '');
$productCode = (string) ($callbackData['product_code'] ?? '');
$cipherData = (string) ($callbackData['data'] ?? '');
// 1. 校验产品代码一致性
if ($productCode !== self::PRODUCT_CODE) {
throw new RuntimeException(sprintf('产品代码不匹配，预期 [%s]，实际收到 [%s]', self::PRODUCT_CODE, $productCode));
}
// 2. 根据状态码分类流转
if ($code === self::CODE_QUERY_EMPTY) {
return [
'status' => 'EMPTY',
'out_order_no' => $outOrderNo,
'transaction_id' => $transactionId,
'inspect_card' => [
'cert_grade' => self::CERT_GRADE_MANUAL_REVIEW,
'summary' => '主流4S店系统暂无该车维保建档记录，需展厅高级评估师线下深度复检。',
'report_url' => null,
],
'echo_response' => 'success',
];
}
if ($code !== self::CODE_SUCCESS || $cipherData === '') {
return [
'status' => 'FAILED',
'out_order_no' => $outOrderNo,
'transaction_id' => $transactionId,
'inspect_card' => [
'cert_grade' => self::CERT_GRADE_MANUAL_REVIEW,
'summary' => sprintf('维保数据调阅失败: code=%d, message=%s', $code, $message),
'report_url' => null,
],
'echo_response' => 'success',
];
}
// 3. 解密业务报告明文
$reportContent = $this->decryptPayload($cipherData);
// 提取报告链接（url 模式）或结构化记录（json 模式）
$reportUrl = $reportContent['report_url'] ?? $reportContent['reportUrl'] ?? '';
$totalRecords = (int) ($reportContent['total_records'] ?? count($reportContent['records'] ?? []));
$lastRecordDate = (string) ($reportContent['last_maintenance_date'] ?? '2025-12-18');
$lastRecordMiles = (float) ($reportContent['last_mileage'] ?? 4.8); // 万公里
$majorRepairs = (array) ($reportContent['major_repairs'] ?? []);
// 4. 执行展厅车况质检与真实里程比对决策
$isMileageNormal = ($odometerMiles万公里 <= 0.0) || ($odometerMiles万公里 >= $lastRecordMiles);
$hasMajorEngineOverhaul = in_array('发动机拆解大修', $majorRepairs, true)
|| in_array('变速箱总成更换', $majorRepairs, true);
if (!$isMileageNormal) {
// 表显里程小于历史最后进店维保里程，存在里程异常偏差
$certGrade = self::CERT_GRADE_MANUAL_REVIEW;
$auditResult = '存在表显里程与维保历史记录倒挂偏差，触发前置准入校验限制，转人工复核提醒。';
} elseif ($hasMajorEngineOverhaul) {
// 存在动力总成重大大修
$certGrade = self::CERT_GRADE_MANUAL_REVIEW;
$auditResult = '历史维保存在核心动力部件拆解大修工单，需转入展厅技术总监人工复核。';
} elseif ($totalRecords >= 3) {
// 维保记录规律连贯、里程无异常
$certGrade = self::CERT_GRADE_GOLD;
$auditResult = '全程4S店正规维保记录清晰连贯，里程真实无调表，授予官方金牌认证。';
} else {
$certGrade = self::CERT_GRADE_SILVER;
$auditResult = '维保记录真实有效，无重大总成维修工单，核准展厅优选认证。';
}
// 5. 生成展厅专属可打印车况质检档案卡
$inspectionCard = [
'out_order_no' => $outOrderNo,
'transaction_id' => $transactionId,
'cert_grade' => $certGrade,
'audit_conclusion' => $auditResult,
'current_odometer_miles' => $odometerMiles万公里 > 0.0 ? $odometerMiles万公里 . ' 万公里' : '未采录',
'last_recorded_miles' => $lastRecordMiles . ' 万公里',
'last_maintenance_date' => $lastRecordDate,
'total_maintenance_times' => $totalRecords . ' 次',
'major_repair_items' => empty($majorRepairs) ? '无重大部件大修' : implode('、', $majorRepairs),
'online_report_url' => $reportUrl,
'qr_verification_code' => 'QR_INSPECT_' . md5($outOrderNo),
'inspection_timestamp' => date('Y-m-d H:i:s'),
];
return [
'status' => 'SUCCESS',
'out_order_no' => $outOrderNo,
'transaction_id' => $transactionId,
'inspect_card' => $inspectionCard,
'echo_response' => 'success', // 按照上游规范，必须向 Webhook 回调回传纯文本 success 或 ok
];
}
}
// ============================================================================
// CLI 示例运行：模拟二手车认证展厅维保异步提报、Webhook 回调与质检档案卡生成
// ============================================================================
if (PHP_SAPI === 'cli' && basename(__FILE__) === basename($_SERVER['SCRIPT_FILENAME'])) {
$accessId = getenv('HAIYU_ACCESS_ID') ?: 'HY_SAMPLE_ACCESS_ID_9901';
$accessKeyHex = getenv('HAIYU_ACCESS_KEY_HEX') ?: '0123456789abcdef0123456789abcdef';
$service = new VehicleMaintenanceInspectionService($accessId, $accessKeyHex);
echo "=================================================================" . PHP_EOL;
echo " 品牌二手车认证展厅 - 海宇普通维保查询与车况质检报告生成服务" . PHP_EOL;
echo "=================================================================" . PHP_EOL;
// 1. 模拟展厅入库收车：录入合规 VIN 码、车牌号及行驶证
$mockVin = 'LFV2A1333C3048991'; // 满足 ISO 3779 校验的标准 17 位 VIN
$mockPlate = '冀F88888';
$mockImgUrl = 'https://oss.dealer-group.example.com/certs/xsz_20261021.jpg';
$mockOutOrderNo = 'INSPECT_' . date('YmdHis') . '_' . bin2hex(random_bytes(3));
$mockNotifyUrl = 'https://crm.dealer-group.example.com/api/v1/webhook/maintenance';
echo "步骤 1: 展厅录入待认证车源，发起异步维保查询申请..." . PHP_EOL;
echo " 车辆车架号 (VIN): " . $mockVin . PHP_EOL;
echo " 车辆号牌 (Plate): " . $mockPlate . PHP_EOL;
echo " 行驶证图片地址 : " . $mockImgUrl . PHP_EOL;
echo " 自定义业务单号 : " . $mockOutOrderNo . PHP_EOL;
// 模拟首次请求成功，解密出 out_order_no
$mockFirstPayload = ['out_order_no' => $mockOutOrderNo];
$mockFirstCipher = $service->encryptPayload($mockFirstPayload);
$mockFirstDecrypted = $service->decryptPayload($mockFirstCipher);
echo ">> 首次响应解密成功，锁定订单关联键: " . $mockFirstDecrypted['out_order_no'] . PHP_EOL;
echo " 系统挂起等待，无阻塞监听后台 Webhook 推送..." . PHP_EOL . PHP_EOL;
// 2. 模拟海宇底座穿透维保数据库后，向 notify_url 发送 Webhook 异步回调
echo "步骤 2: 模拟接收海宇普通维保查询 Webhook 异步回调通知..." . PHP_EOL;
$mockMaintenanceReport = [
'report_url' => 'https://report.haiyudata.com/v/view?token=8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d',
'total_records' => 8,
'last_maintenance_date' => '2025-11-20',
'last_mileage' => 4.2, // 历史最后进店里程 4.2 万公里
'major_repairs' => [], // 无重大部件大修
];
$mockCipherData = $service->encryptPayload($mockMaintenanceReport);
$mockWebhookJson = json_encode([
'code' => VehicleMaintenanceInspectionService::CODE_SUCCESS,
'message' => '成功',
'out_order_no' => $mockOutOrderNo,
'transaction_id' => 'HY_NOTIFY_QCXGW8K3_20261021094030',
'product_code' => 'QCXGW8K3',
'data' => $mockCipherData,
], JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES);
// 展厅现场采录表显里程为 4.5 万公里（正常大于 4.2 万公里）
$callbackResult = $service->handleWebhookCallback($mockWebhookJson, 4.5);
echo "-----------------------------------------------------------------" . PHP_EOL;
echo "Webhook 处理状态 : " . $callbackResult['status'] . PHP_EOL;
echo "业务订单单号 : " . $callbackResult['out_order_no'] . PHP_EOL;
echo "回调流水号 : " . $callbackResult['transaction_id'] . PHP_EOL;
echo "-----------------------------------------------------------------" . PHP_EOL;
echo "【展厅官方认证车况质检档案卡】" . PHP_EOL;
$card = $callbackResult['inspect_card'];
echo "官方认证等级 : " . $card['cert_grade'] . PHP_EOL;
echo "质检综合结论 : " . $card['audit_conclusion'] . PHP_EOL;
echo "当前表显里程 : " . $card['current_odometer_miles'] . PHP_EOL;
echo "最后维保里程 : " . $card['last_recorded_miles'] . PHP_EOL;
echo "最后维保日期 : " . $card['last_maintenance_date'] . PHP_EOL;
echo "累计维保记录 : " . $card['total_maintenance_times'] . PHP_EOL;
echo "重大维修排查 : " . $card['major_repair_items'] . PHP_EOL;
echo "在线维保档案 : " . $card['online_report_url'] . PHP_EOL;
echo "防伪验证码 : " . $card['qr_verification_code'] . PHP_EOL;
echo "质检核签时间 : " . $card['inspection_timestamp'] . PHP_EOL;
echo "-----------------------------------------------------------------" . PHP_EOL;
echo ">> Webhook 应答商户回执: '" . $callbackResult['echo_response'] . "' (HTTP 200)" . PHP_EOL;
echo "=================================================================" . PHP_EOL;
}3. 终端快捷验证 (cURL)
在品牌二手车认证展厅车况质检系统联调阶段，开发团队可通过终端使用以下 cURL 命令，直接向海宇普通维保查询接口提交异步查询任务：
bash
# 1. 获取当前 13 位毫秒级 Unix 时间戳
TIMESTAMP=$(php -r 'echo round(microtime(true) * 1000);')
# 2. 向海宇普通维保查询端点发起 POST 提报（data 为包含 16 字节随机 IV 与 AES-128-CBC 密文的 Base64 编码字符串）
curl -X POST "https://api.haiyudata.com/api/v1/QCXGW8K3?t=${TIMESTAMP}" \
-H "Content-Type: application/json" \
-H "Access-Id: YOUR_HAIYU_ACCESS_ID" \
-d '{
"data": "kL8vM2nX9rP4tQ7yU0zW2aB4cD6eE8fG0hI2jK4lM6nO8pQ0rS2tU4vW6xY8zA0bC2dE4fG6hI8jK0lM2nO4p..."
}'接口首次同步受理成功后，立即下发确认报文：
json
{
"code": 0,
"message": "成功",
"transaction_id": "HY_QCXGW8K3_20261021094012_01",
"data": "vM1nL3qR5vT7xP9zB1cD3fG5hJ7kL9nM1oP3rS5tU7vW9xY1zA3bC5dE7fG9hI1jK3lM5nO7pQ9rS1tU3vW5xY7zA..."
}展厅系统解密首次响应中的 data 密文字符串后，得到订单单号锁定确认：
json
{
"out_order_no": "INSPECT_20261021094000_8892A"
}随后，海宇底层数据网络完成全国授权 4S 店维保档案调阅后，以 application/json 格式向商户提供的 notify_url 主动推送 Webhook 异步回调：
json
{
"code": 0,
"message": "成功",
"out_order_no": "INSPECT_20261021094000_8892A",
"transaction_id": "HY_CB_QCXGW8K3_20261021094045_99",
"product_code": "QCXGW8K3",
"data": "aB3cD5eF7gH9iJ1kL3mN5oP7qR9sT1uV3wX5yZ7aB9cD1eF3gH5iJ7kL9mN1oP3qR5sT7uV9wX1yZ3aB5cD7eF9g..."
}展厅服务端接收到回调后，使用本地配置的 Access Key 对 data 进行 AES-128-CBC 解密，即可提取完整的在线维保报告与车况明细：
json
{
"report_url": "https://report.haiyudata.com/v/view?token=8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d",
"total_records": 8,
"last_maintenance_date": "2025-11-20",
"last_mileage": 4.2,
"major_repairs": []
}展厅服务完成本地质检报告生成与状态机落库后，向 Webhook 直接响应纯文本 success（HTTP 200），通知上游终止重推。
核心车辆维保档案数据解析与业务映射
海宇普通维保查询接口采用异步解耦设计，其请求入参、外层响应与 Webhook 回调推送字段定义及业务映射如下：
| 数据字段名 | 字段类型 | 出现阶段与取值范围 | 二手车认证展厅车况质检 CRM 业务流转策略 |
|---|---|---|---|
vin |
String | 请求参数（17位大写） | 车辆数字资产唯一主键：执行 ISO 3779 算法校验，用于穿透主机厂授权 4S 店历史施工档案。 |
plate |
String | 请求参数（标准号牌格式） | 登记号牌：辅助核验车辆属地、牌证一致性与交管备案状态。 |
img_url |
String | 请求参数（HTTP/HTTPS 链接） | 行驶证影像凭证：上游用于合法调档凭证合规审计，确保授权真实有效。 |
out_order_no |
String | 请求/首次响应/回调外层 | 业务防重与关联主键：展厅质检工单号（≤64位），贯穿提报、回调监听与质检卡生成全生命周期。 |
report_type |
String | 请求参数（url 或 json） |
输出格式控制 ：指定 url 获取在线交互报告（适于生成二维码）；指定 json 获取结构化工单明细。 |
notify_url |
String | 请求参数（公网 URL） | 异步回调接收端点：展厅 CRM 接收 Webhook 推送的对外安全接口。 |
product_code |
String | Webhook 回调外层（固定 QCXGW8K3） |
产品代码强校验：核验回调产品归属，防止异构接口消息串包。 |
transaction_id |
String | 首次响应/Webhook 回调外层 | 数据中台流水号：用于第三方数据公信力举证与全链路审计溯源。 |
code |
Integer | Webhook 回调状态码： • 0：成功 • 1000：查询为空 • 2001：业务失败 • 1001：接口异常 |
展厅质检状态机驱动核心 ： • 0：解密维保报告，触发真实里程校验与官方质检卡生成； • 1000：无 4S 店维保记录，转入展厅高级评估师线下深度复检； • 2001：提示参数不匹配或凭证不清晰，触发前置准入校验限制重新采录； • 1001：上游系统异动，触发后台队列重试。 |
data |
String | 请求体 / 响应体 / Webhook | 高强度加密载荷：装载业务明文或维保报告内容，确保公网信道严密防护。 |
report_url |
String | 解密后报告字段（URL） | 官方在线维保交互报告：生成展厅展车玻璃上的二维码，供购车客户扫码查看。 |
total_records |
Integer | 解密后报告字段 | 历史进店保养次数：综合评估前任车主爱车程度与机械工况健康度。 |
last_mileage |
Float | 解密后报告字段（万公里） | 最后一次进店维保里程：与展厅现场表显里程比对，排查里程异常偏差。 |
major_repairs |
Array | 解密后报告字段（数组） | 重大核心部件维修排查：排查发动机大修、变速箱更换与底盘校正，决定认证等级。 |
技术提示 ：车辆车架号（VIN）与车牌号属于车辆财产关键要素。展厅前端销售看板与数字化大屏在公开展示时应进行脱敏处理：车架号脱敏为
LFV2A133********991，车牌号脱敏为冀F8****。针对公网 Webhook 回调，PHP 控制器必须依托 Redis 建立以out_order_no为键的分布式幂等锁；若本地质检档案已完成生成，重复回调直接响应success，杜绝重复处理与状态冲突。
场景化应用：让核验数据赋能合规闭环
在品牌二手车官方认证展厅、大型二手车交易中心以及主机厂品牌"以旧换新"质检车间的生产环境中，海宇普通维保查询接口驱动了以下三大核心业务场景：
1. 品牌官方认证二手车上架前置车况质检与真实里程校验
在二手车展厅车辆入库检验环节，质检技师手持 PDA 采集车辆车架号、行驶证照片及当前表显里程。系统通过海宇普通维保查询接口异步发起调档。Webhook 回调返回并解密后，质检引擎自动比对当前表显里程与维保历史记录中的 last_mileage。如果当前表显为 4.5 万公里，而历史维保记录中一年前进店里程已达 7.2 万公里，系统立即判定存在严重的里程异常偏差，触发前置准入校验限制，直接驳回上架申请并转入人工复核提醒；若历次维保里程规律递增且无核心部件维修记录，系统秒级签发"官方金牌认证证书"，允许车辆入驻核心展区。
2. 展厅车源收购定价评估与核心部件维修隐患排查
在二手车收购洽谈阶段，收车顾问为了精准锁定收购价格、防范存货贬值风险，必须全面查验车辆的历史工单。通过调用海宇普通维保查询接口，收购评估后台可实时调阅目标车辆是否存在发动机拆解大修、变速箱总成更换、转向机大修或气囊弹出维修记录。一旦发现车辆在半年前因严重涉水进行过发动机深度拆解与电路大修，收车评估系统自动下调收购估值基准，或将车源转入特定处理渠道，有效防范因信息不透明造成的收车资产履约隐患。
3. 展厅"一车一码"透明车况档案展示与客户购车扫码查验
在展厅展车零售销售阶段，传统二手车销售中客户对车况的疑虑是导致成交决策缓慢的主要阻力。展厅利用海宇普通维保查询返回的在线交互报告链接 report_url，自动为每台在售车辆生成专属的车况质检二维码，并打印张贴于车辆挡风玻璃右上角。看车客户只需使用手机微信扫码，即可直观查阅该车辆在官方 4S 店的历次正规维保时间轴、进店项目、机油标号及保养间隔。这种"车况全透明、数据有背书"的数字化体验极大增强了消费者的购车信任，显著缩短了展厅销售转化周期。
生产环境接入的安全与合规边界
将海宇普通维保查询接口深度整合至二手车展厅 CRM 与质检系统的生产运行中，必须严格恪守以下三项安全合规治理原则：
- 合法授权与行驶证凭证合规管理 ：调阅车辆历史维保档案必须具备合法的权属关联或委托依据。展厅在收车或代销环节，必须与原车主签署《车辆技术状况信息核验授权声明》，并在请求中规范上传真实的行驶证凭证照片
img_url。该图片地址建议采用企业对象存储（OSS/COS）生成的带有短期访问有效期的预签名链接，既满足上游合规审计需求，又杜绝凭证长期暴露泄露风险。 - Webhook 幂等性控制与防重放机制 ：公网网络环境复杂，上游 Webhook 在未收到商户
success响应时会启动阶梯式重试机制。展厅 PHP Webhook 控制器必须以out_order_no作为唯一业务键，结合 Redis 缓存锁或数据库唯一键实现强幂等控制。当接收到重复回调时，若本地订单已处于完成状态，应立即响应纯文本success，防止重复触发质检评级与业务工单流转。 - 密钥全生命周期隔离与敏感信息防护：生产环境中的 Access Key 严禁提交至 Git 代码仓库或暴露在前端脚本中，必须配置于服务器环境变量或加密配置文件中。展厅展示终端在面向公众或客户展示车况档案时，必须对车主姓名、车牌号及车架号执行严格的脱敏渲染；同时在系统内部建立完备的查询操作审计日志，确保每一笔维保调档记录均可精准追溯至具体操作门店与员工。