pr-review-provider

PR Review Checklist — Payment Provider

yansongda/pay 新增/修改 Provider 时的 Code Review 专用检查清单。基于 Airwallex PR #1140 review 经验沉淀。

Review 规范（强制）

1. 提交评论前必须征求用户许可

绝对禁止：未经用户明确允许，不得使用 gh pr comment 或其他方式向 PR 提交任何评论。

正确流程：

1. 完成 review 分析
2. 向用户展示 review 报告内容
3. 询问用户："是否需要我将此报告提交为 PR 评论？"
4. 仅在用户明确确认后才执行提交

2. 报告末尾必须注明使用的模型及审核状态

在 review 报告的结论部分之后，必须添加以下信息：

---
*Review by {模型名称} | {YYYY-MM-DD} | 经人工审核确认*

示例：

---
*Review by deepseek-v4-pro | 2026-05-07 | 经人工审核确认*

---

Review 流程

按以下阶段顺序审查，确保覆盖完整：

1. Phase 1: Provider 结构完整性
2. Phase 2: 代码规范检查
3. Phase 3: 安全性检查（签名验证、加密解密）
4. Phase 4: 架构一致性（管道、Trait、Event）
5. Phase 5: 官方文档对照
6. Phase 6: 测试覆盖
7. Phase 7: 文档完整性

---

Phase 1: 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 */
self::verifyWechatSign(...);

这是 PHPStan 对 Trait 静态调用的已知限制，非代码质量问题。

---

Phase 5: 官方文档对照

结合代码中的 @see 链接验证：

---

Phase 6: 测试覆盖

---

Phase 7: 文档完整性

---

常见误报

null-safe 操作符

$payload?->get('a', $payload->get('b'))

PHP 8.0 的 null-safe 实现了 full short-circuiting：当 $payload 为 null 时，右侧参数不会被求值。这不是 bug。

参考：PHP RFC nullsafe_operator

---

避免重复造轮子

检查新增功能是否在 yansongda/supports 或 yansongda/artful 中已有实现：

Review 报告模板

以下为提交 review 时的标准报告格式：

# PR #{number} Code Review — {Provider} Provider

## 一、总览

| 维度 | 内容 |
|------|------|
| PR | #{number} — {title} |
| 涉及文件 | {n} 个 |
| Review 范围 | 全量代码 + 文档 + 测试 |
| 方法 | 逐文件审查 + 官方文档对照 + 跨 Provider 一致性比对 |

## 二、已确认 Bug（含证据链）

### BUG-{n}: {简要描述}

**严重级别**：{高/中高/中/低}

**位置**：`{file_path}` L{line}

**问题**：
{详细描述问题本质}

**证据链**：
1. 代码现状：`{相关代码片段}`
2. 预期行为：{应该怎样}
3. 实际行为：{实际会怎样}
4. 影响范围：{哪些场景会触发}

**修复建议**：
```php
// 修复方案
```

---

（重复以上格式，每个 Bug 单独一节）

## 三、已排除的误报

### {误报描述}

**结论**：非 Bug

**原因**：{详细解释，附 RFC/文档链接}

## 四、风险项

| # | 风险 | 严重级别 | 文件 | 说明 |
|---|------|----------|------|------|
| RISK-{n} | {风险名} | {级别} | `{file}` | {说明} |

## 五、改进建议

| # | 建议 | 优先级 | 文件 | 说明 |
|---|------|--------|------|------|
| SUG-{n} | {建议名} | {级别} | `{file}` | {说明} |

## 六、官方文档对照验证

| 功能 | 代码中的 URL/算法 | 官方文档 | 是否一致 |
|------|-------------------|----------|----------|
| {功能名} | `{代码实现}` | [官方文档]({url}) | ✅/❌ |

## 七、代码规范检查

| 检查项 | 状态 | 备注 |
|--------|------|------|
| `declare(strict_types=1)` | ✅/❌ | |
| `use` 导入（无内联命名空间） | ✅/❌ | |
| 日志格式 `[Provider][V{n}][Category][Plugin]` | ✅/❌ | |
| 异常常量命名 | ✅/❌ | |
| Plugin/Shortcut 命名规范 | ✅/❌ | |
| 测试覆盖 | ✅/❌ | |

## 八、汇总

| 类别 | 数量 | 详情 |
|------|------|------|
| 已确认 Bug | {n} | {简要列举} |
| 已排除误报 | {n} | {简要列举} |
| 风险项 | {n} | {简要列举} |
| 改进建议 | {n} | {简要列举} |

## 九、结论

{总体评价：代码质量、架构一致性、安全性等。明确给出 Approve / Request Changes 建议及原因。}

---
*Review by {模型名称} | {YYYY-MM-DD} | 经人工审核确认*