Pr Review Provider

注意：src/Functions.php 已不存在，URL/签名等方法已下沉到 src/Traits/*Trait.php。

Phase 2: 代码规范检查

基本规范

命名规范

日志与异常

• 日志格式：[Provider][V{n}][Category][Plugin]，使用中文消息
• 异常常量：PARAMS_{PROVIDER}_*、CONFIG_{PROVIDER}_*
• 异常消息：中文，附带上下文参数

Phase 3: 安全性检查

1. params vs payload 混淆

高危：Artful::artful() 第二参数必须是 params（含 _config），不能是 payload。

// ❌ 错误 — payload 不含 _config，多租户必崩
$result = Artful::artful([...], $confirmPayload);

// ✅ 正确 — params 含 _config 租户标识
$result = Artful::artful([...], $confirmParams);

检查方法：搜索 Artful::artful( 调用，追踪第二参数来源。

2. 空值处理

检查最终发送的 body/query 是否包含不应出现的 null/空字段。

推荐方式：

• 优先使用 filter_params() 函数（artful 库提供）
• 嵌套数组场景补充 array_filter()

// ✅ 优先方式 — filter_params
$body = http_build_query(filter_params($payload)->toArray());

// ✅ 嵌套场景 — array_filter
$rocket->mergePayload(array_filter([
    'application_context' => $payload->get('application_context'),
], static fn ($value) => !is_null($value)));

检查位置：AddRadarPlugin::getBody()、getQueryString()、业务 Plugin 的 mergePayload()。

3. Webhook 签名验证

安全强制：所有 CallbackPlugin 必须验签。

检查点：

• CallbackPlugin 是否调用 Trait 提供或 Plugin 自身实现的签名验证方法
• 签名算法是否与官方文档一致（对照 @see 链接）
• 配置缺失时抛异常
• 签名为空时抛异常
• 使用 hash_equals 防时序攻击

4. 数组回调的处理

仅适用于 Stripe/Wechat/Paypal（构造 ServerRequest 并验签）：

getCallbackParams() 处理逻辑：

结论：数组回调只有提供完整 headers + body 才能通过验签；否则验签阶段抛异常。

Alipay/Douyin/Unipay 不同：

• getCallbackParams() 返回 Collection（从 query/parsedBody 取值）
• 直接 merge 到 params，不构造 ServerRequest
• CallbackPlugin 从 params 中取值验签

5. 加密资源解密（微信）

微信回调的 resource 字段需解密：

$body['resource'] = self::decryptWechatResource($body['resource'] ?? [], $config);

检查 CallbackPlugin 是否调用此方法。

Phase 4: 架构一致性

1. 插件管道骨架

通用骨架：

StartPlugin → [前置插件] → 业务插件 → [后置插件] → ParserPlugin

各 Provider 差异：

注意：不同 Provider 管道差异较大，不要按固定模板审查。

2. mergeCommonPlugins 实现

Provider 类必须实现此方法，返回完整管道：

public function mergeCommonPlugins(array $plugins): array
{
    return array_merge(
        [StartPlugin::class, /* 前置插件 */],
        $plugins,
        [/* 后置插件 */, ParserPlugin::class],
    );
}

3. Trait 方法复用

新增 Provider 应复用 Trait 方法而非重新实现：

4. Provider 常量定义

必须定义 URL 常量：

public const URL = [
    Pay::MODE_NORMAL => 'https://api.xxx.com/',
    Pay::MODE_SANDBOX => 'https://sandbox.api.xxx.com/',
    Pay::MODE_SERVICE => 'https://api.xxx.com/',
];

特殊常量（如微信）：

• AUTH_TAG_LENGTH_BYTE
• MCH_SECRET_KEY_LENGTH_BYTE

5. Event 调用

callback 方法必须触发事件：

// Stripe/Wechat/Paypal（ServerRequestInterface）
Event::dispatch(new CallbackReceived('provider', clone $request, $params, null));

// Alipay/Douyin/Unipay/Jsb（Collection）
Event::dispatch(new CallbackReceived('provider', $request->all(), $params, null));

其他方法触发：

Event::dispatch(new MethodCalled('provider', __METHOD__, $order, null));

6. PHPStan ignore 注释

Trait 静态方法调用需添加注释：

/* @phpstan-ignore-next-line */