vipnub/oil
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

第二次更新

Browse Source
This commit is contained in:
vipnub
2026-09-10 20:56:46 +08:00
parent 4d6a7e7aac
commit caeb4d6760
310 changed files with 2427 additions and 382 deletions
Download Patch File Download Diff File Expand all files Collapse all files
server-tp6/app/common/service/QytOil.php
+289 -47
View File
@@ -1,95 +1,310 @@
<?php
// +----------------------------------------------------------------------
// | 企油通 · 上游接口客户端（支付宝企业码通道）
// | 企油通 · 上游接口客户端
// +----------------------------------------------------------------------
// | 本次实际对接仅 3 个接口：
// | 7.7 运单油费下发 createAndSendQuota —— 本类 createAndSendQuota()
// | 7.15 H5 跳转地址 （本地签名生成 URL） —— 本类 h5Url()
// | 7.10 运单加油明细推送（异步回调） —— app\api\controller\QytNotify
// | 通道固定为支付宝企业码（passageway=1），司机手机号 + 姓名必填。
// | 多企业：一个接入方 appId 下可挂多个企业，业务接口靠 business_license 区分。
// | 用法：QytOil::forEnterprise($enterprise)->createAndSendQuota([...])
// | 不带企业的接口（7.22 企业列表）用 new QytOil() 即可。
// |
// | 已实现：
// | 7.2 企业申请创建 openAnAccount
// | 7.5 企业账户查询 accountQuery
// | 7.7 运单油费下发 createAndSendQuota
// | 7.15 H5免登地址 h5Url（本地签名，不发请求）
// | 7.22 企业列表查询 enterpriseList
// | 7.10 消费回调由 app\api\controller\QytNotify 接收
// |
// | 通道：alipay=支付宝企业码(passageway=1) / pingan=平安银行(passageway=2)，
// | 通道开关存在企业信息里。平安通道要求实名，7.7 必传 id_card。
// | 金额：对外「元」入参，7.7 内部换算为「分」。
// |
// | ⚠️ 7.7 是异步接口，返回成功只代表【受理】，真实发放结果需用 7.8
// | waybillBatch 按 batch_no 查询（见文档 §5 第 7 条）。当前状态机仍按
// | 「受理即完成」处理，7.8 轮询尚未接入。
// +----------------------------------------------------------------------
declare (strict_types=1);
namespace app\common\service;
use app\common\crypto\Qyt as QytCrypto;
use app\common\model\qyt\Enterprise as EnterpriseModel;
class QytOil extends BaseService
{
// 支付宝企业码通道
const PASSAGEWAY_ALIPAY = 1;
// 通道标识
const CHANNEL_ALIPAY = 'alipay';
const CHANNEL_PINGAN = 'pingan';
/** @var array config('qyt') */
/** @var array 合并后的配置（接入方级 + 企业级） */
protected $conf;
/** @var QytCrypto */
protected $crypto;
/** @var EnterpriseModel|array|null 当前企业 */
protected $enterprise = null;
protected function initialize()
{
$this->conf = (array) config('qyt');
$this->conf = QytConfig::get();
$this->crypto = new QytCrypto($this->conf);
}
// ================================================================
// 企业上下文
// ================================================================
/**
* 绑定企业后返回实例（业务接口的常规入口）
* @param EnterpriseModel|array $enterprise
*/
public static function forEnterprise($enterprise): self
{
return (new static())->useEnterprise($enterprise);
}
/**
* 切换当前企业：执照号 / 通道 / 机构号 / 编号前缀等随之变化
* @param EnterpriseModel|array $enterprise
*/
public function useEnterprise($enterprise): self
{
$this->enterprise = $enterprise;
$this->conf = QytConfig::forEnterprise($enterprise);
$this->crypto = new QytCrypto($this->conf);
return $this;
}
public function enterpriseId(): int
{
return (int) ($this->conf['enterprise_id'] ?? 0);
}
public function enterpriseName(): string
{
return (string) ($this->conf['enterprise_name'] ?? '');
}
public function businessLicense(): string
{
return (string) ($this->conf['business_license'] ?? '');
}
/** 当前通道标识 alipay / pingan */
public function channelKey(): string
{
return (string) ($this->conf['passageway'] ?? self::CHANNEL_ALIPAY);
}
/** 当前通道中文名 */
public function channelName(): string
{
return (string) ($this->conf['passageway_name'] ?? '');
}
/** 当前通道的企油通 passageway 编码：1 支付宝企业码 / 2 平安银行 */
public function channelCode(): int
{
return (int) ($this->conf['passageway_code'] ?? 1);
}
/** 当前通道是否必须上送司机身份证号（平安银行=是） */
public function requireIdCard(): bool
{
return !empty($this->conf['require_id_card']);
}
/**
* 生成企油通全平台唯一编号（加企业前缀），确定性派生 -> 重试保持一致
* batch_no / waybill_no / waybill_no_code 都是【全平台唯一】而非接入方内唯一，
* 所以各企业建议用不同前缀，避免与其他接入方或兄弟企业撞号。
* @param string $type B=batch / W=waybill / C=waybill_no_code
* @param string $seed 订单号 / order_id 等业务种子
*/
public function no(string $type, string $seed): string
{
return ((string) ($this->conf['no_prefix'] ?: 'HM')) . $type . $seed;
}
// ================================================================
// 7.7 运单油费下发（一张订单 = 1 batch / 1 waybill / 1 employee）
// ================================================================
/**
* @param array $data ['batch_no','waybill_no','waybill_no_code','mobile','name','amount'(元)]
* @param array $data ['batch_no','waybill_no','waybill_no_code','mobile','name','amount'(元),'id_card'(平安通道必填)]
* @return array 归一化 ['code'=>'00'|其它, 'data'=>[], 'message'=>'', 'dup_batch'=>bool]
*/
public function createAndSendQuota(array $data): array
{
if (($err = $this->requireEnterprise()) !== null) {
return $err;
}
// 支付宝企业码通道下 institution_id 必填；缺了就地失败，不把空值发给企油通
if ($this->channelCode() === 1 && $this->conf['institution_id'] === '') {
return $this->fail("企业[{$this->enterpriseName()}]未配置机构号(institution_id)，支付宝企业码通道无法下发");
}
$idCard = trim((string) ($data['id_card'] ?? ''));
if ($this->requireIdCard() && $idCard === '') {
return $this->fail("通道[{$this->channelName()}]要求实名，缺少司机身份证号(idCard)");
}
$employee = [
'mobile' => $data['mobile'],
'name' => $data['name'],
'quota_amount' => self::yuanToFen($data['amount']), // 分
'voucher_name' => $this->conf['voucher_name'],
'effective_start' => '', // 空=当日生效
'effective_end' => '', // 空=长期有效
'waybill_no_code' => $data['waybill_no_code'],
];
// 身份证号仅在要求实名的通道上送，避免向不需要的通道多传敏感信息
if ($this->requireIdCard()) {
$employee['id_card'] = $idCard;
}
$params = [
'batch_no' => $data['batch_no'],
'business_license' => $this->conf['business_license'],
'passageway' => (string) self::PASSAGEWAY_ALIPAY,
'institution_id' => $this->conf['institution_id'],
'business_license' => $this->businessLicense(),
'passageway' => (string) $this->channelCode(),
'institution_id' => (string) $this->conf['institution_id'],
'waybill_list' => [[
'waybill_no' => $data['waybill_no'],
'employee_list' => [[
'mobile' => $data['mobile'],
'name' => $data['name'],
'quota_amount' => self::yuanToFen($data['amount']), // 分
'voucher_name' => $this->conf['voucher_name'],
'effective_start' => '', // 空=当日生效
'effective_end' => '', // 空=长期有效
'waybill_no_code' => $data['waybill_no_code'],
]],
'employee_list' => [$employee],
]],
];
return $this->post('/enterprise/api/zhyk/createAndSendQuota', $params);
}
// ================================================================
// 7.8 运单发放结果查询（7.7 是异步的，真实结果只能从这里拿）
// ================================================================
/**
* @param string $batchNo 7.7 提交时用的批次号
* @return array data: batch_no / status(1待处理 2处理中 3全部成功 4部分成功 5处理失败) / list[]
* list[] 里每条含 waybill_no_code / handle_status(1待处理 2成功 3失败) / error_msg
*/
public function waybillBatch(string $batchNo): array
{
$params = ['batch_no' => $batchNo];
// business_license 可选；传了会校验归属，能更早发现串企业的问题
$this->businessLicense() !== '' && $params['business_license'] = $this->businessLicense();
return $this->post('/enterprise/api/zhyk/waybillBatch', $params);
}
/**
* 从 7.8 的返回里挑出某条运单流水的处理结果
* @return array|null ['handle_status'=>int, 'error_msg'=>string, 'remark'=>string]
*/
public static function pickWaybill(array $data, string $waybillNoCode): ?array
{
foreach ((array) ($data['list'] ?? []) as $row) {
if ((string) ($row['waybill_no_code'] ?? '') === $waybillNoCode) {
return [
'handle_status' => (int) ($row['handle_status'] ?? 0),
'error_msg' => (string) ($row['error_msg'] ?? ''),
'remark' => (string) ($row['remark'] ?? ''),
];
}
}
return null;
}
// ================================================================
// 7.2 企业申请创建
// ================================================================
/**
* @param array $data ['business_license','business_license_url','passageway'(如 "1,2"),'company_name','contact_mobile','contact_name']
*/
public function openAnAccount(array $data): array
{
return $this->post('/enterprise/api/zhyk/openAnAccount', [
'business_license' => $data['business_license'],
'business_license_url' => $data['business_license_url'],
'passageway' => (string) $data['passageway'],
'company_name' => $data['company_name'],
'contact_mobile' => $data['contact_mobile'],
'contact_name' => $data['contact_name'],
]);
}
// ================================================================
// 7.5 企业账户信息查询
// ================================================================
public function accountQuery(): array
{
if (($err = $this->requireEnterprise()) !== null) {
return $err;
}
return $this->post('/enterprise/api/zhyk/accountQuery', [
'business_license' => $this->businessLicense(),
'passageway' => (string) $this->channelCode(),
]);
}
// ================================================================
// 7.22 企业列表查询（枚举本 appId 名下企业，需先开通权限，未开通返回 403）
// ================================================================
public function enterpriseList(array $params = []): array
{
return $this->post('/enterprise/api/enterprise/list', [
'page' => $params['page'] ?? 1,
'page_size' => $params['page_size'] ?? 100,
]);
}
// ================================================================
// 7.15 H5 免登加油地址（本地签名生成 URL，不发起接口请求）
// 文档：本地址与支付通道无关，落地页由系统按企业实际通道自动判定
// ================================================================
public function h5Url(string $mobile): string
{
$creditcode = !empty($this->conf['h5_with_creditcode']) ? (string) $this->conf['business_license'] : '';
// creditcode 传了则本次登录固定到该企业，且必须一并入签
$creditcode = !empty($this->conf['h5_with_creditcode']) ? $this->businessLicense() : '';
return $this->crypto->h5Url($mobile, $creditcode);
}
// ================================================================
// 内部：统一请求
// 内部
// ================================================================
/** 未绑定企业 / 企业没有执照号时的统一拦截 */
protected function requireEnterprise(): ?array
{
if ($this->businessLicense() === '') {
return $this->fail('未指定企业或企业缺少统一社会信用代码(business_license)');
}
return null;
}
/** 构造一个失败返回，并记日志 */
protected function fail(string $message): array
{
$this->saveLog('[配置错误] ' . $message);
return ['code' => 'ERR', 'data' => [], 'message' => $message, 'dup_batch' => false, 'raw' => []];
}
/**
* @return array ['code' => '00'成功 | 其它, 'data' => array, 'message' => string, 'dup_batch' => bool, 'raw' => array]
*/
protected function post(string $path, array $bizParams): array
{
$url = rtrim((string) $this->conf['base_url'], '/') . $path;
$url = rtrim((string) $this->conf['base_url'], '/') . $path;
$body = $this->crypto->envelope($bizParams);
$this->saveLog("[请求] {$path} " . json_encode(['url' => $url, 'params' => $bizParams], JSON_UNESCAPED_UNICODE));
// 日志脱敏：手机号 / 身份证号不落明文
$this->saveLog("[请求] {$path} " . json_encode(
['企业' => $this->enterpriseName(), 'url' => $url, 'params' => self::maskDeep($bizParams)],
JSON_UNESCAPED_UNICODE));
$resp = $this->curlPost($url, json_encode($body, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES));
$this->saveLog("[响应] {$path} " . $resp);
$this->saveLog("[响应] {$path} " . self::maskText($resp));
$json = json_decode($resp, true);
if (!is_array($json)) {
@@ -97,15 +312,13 @@ class QytOil extends BaseService
}
// 通用响应结构：{ status: ok|error, data, message, serialNo, sign }
$ok = ($json['status'] ?? '') === 'ok';
// 【TODO 待对接人确认】是否所有响应都带 sign、验签串如何构造
// if ($ok && !empty($json['sign'])) { $ok = $this->crypto->verify($json['data'] ?? [], $json['sign']); }
$ok = ($json['status'] ?? '') === 'ok';
$message = (string) ($json['message'] ?? '');
// 幂等：batch_no 已存在 —— 视为「已受理」，供 7.7 重试判定
$dupBatch = false;
if (!$ok && $message !== '') {
foreach ((array) (config('qyt.dup_batch_hints') ?: ['已存在', '重复', 'duplicate', 'exist']) as $hint) {
foreach ((array) ($this->conf['dup_batch_hints'] ?: ['已存在', '重复', 'duplicate', 'exist']) as $hint) {
if (mb_stripos($message, $hint) !== false) {
$dupBatch = true;
break;
@@ -145,9 +358,49 @@ class QytOil extends BaseService
return (string) $resp;
}
// ================================================================
// 工具
// ================================================================
// ---------------- 敏感信息脱敏（日志 / 后台展示复用） ----------------
/** 手机号：138****8000 */
public static function maskMobile(string $s): string
{
return strlen($s) === 11 ? substr($s, 0, 3) . '****' . substr($s, -4) : $s;
}
/** 身份证号：4501**********1234 */
public static function maskIdCard(string $s): string
{
$len = strlen($s);
return $len >= 8 ? substr($s, 0, 4) . str_repeat('*', $len - 8) . substr($s, -4) : $s;
}
/** 递归脱敏数组（按键名识别） */
public static function maskDeep($data)
{
if (!is_array($data)) {
return $data;
}
foreach ($data as $k => $v) {
if (is_array($v)) {
$data[$k] = self::maskDeep($v);
} elseif ($k === 'mobile') {
$data[$k] = self::maskMobile((string) $v);
} elseif ($k === 'id_card' || $k === 'idCard') {
$data[$k] = self::maskIdCard((string) $v);
}
}
return $data;
}
/** 脱敏 JSON 文本里的手机号 / 身份证号（用于原始响应报文落日志） */
public static function maskText(string $s): string
{
$s = preg_replace_callback('/"(id_card|idCard)"\s*:\s*"([^"]+)"/i',
function ($m) { return '"' . $m[1] . '":"' . self::maskIdCard($m[2]) . '"'; }, $s);
return (string) preg_replace_callback('/"mobile"\s*:\s*"(\d{11})"/',
function ($m) { return '"mobile":"' . self::maskMobile($m[1]) . '"'; }, $s);
}
// ---------------- 工具 ----------------
/** 元 → 分 */
public static function yuanToFen($yuan): int
@@ -161,17 +414,6 @@ class QytOil extends BaseService
return bcdiv((string) (int) $fen, '100', 2);
}
/**
* 生成企油通全平台唯一编号（加企业前缀），确定性派生 -> 重试保持一致
* @param string $type B=batch / W=waybill / C=waybill_no_code
* @param string $seed 订单号 / order_id 等业务种子
*/
public static function genNo(string $type, string $seed): string
{
$prefix = (string) (config('qyt.no_prefix') ?: 'HM');
return $prefix . $type . $seed;
}
/** 记录日志到 runtime/storelog */
public function saveLog($data): void
{