@alipay/alipay-aipay 1.7.0 → 1.7.1

package/skill-pre/references/integration/modules/alipay-sdk-reminder.md

@@ -0,0 +1,281 @@
+# Alipay-SDK Reminder
+
+以下各项为接入支付宝 SDK 的相关规则，**严禁在未阅读全部内容的情况下编写任何 SDK 相关代码**。每条规则均来自真实集成踩坑，请逐条阅读并确认后再继续，编写代码遵守规则。
+
+---
+
+## SDK 引入方式
+
+SDK 的引入方式取决于对应语言的包管理方式和实际导出方式，**绝不能凭猜测选择**，必须通过查阅 SDK 文档或类型定义确定。
+
+**各语言 SDK 引入方式参考：**
+
+| 语言 | 包管理 | 引入方式 | 备注 |
+|------|--------|---------|------|
+| Java | Maven | `import com.alipay.api.*;` | 通过 Maven 依赖引入，包结构固定 |
+| .NET | NuGet | `using Aop.Api;` 等 | 通过 NuGet 安装 `AlipaySDKNet.Standard`，命名空间固定 |
+| PHP | Composer | `require_once '../aop/AopClient.php';` 等 | 通过 GitHub 仓库或 Composer 引入，类文件路径以实际目录为准 |
+| Python | pip | `from alipay.aop.api.AlipayClientConfig import AlipayClientConfig`<br>`from alipay.aop.api.DefaultAlipayClient import DefaultAlipayClient` | 通过 pip 安装 `alipay-sdk-python`，模块路径以实际版本为准 |
+| Node.js | npm | 需查阅类型定义确认 | 导入方式可能随版本变化，**必须验证**，详见下方「Node.js 导入格式判断」 |
+
+### Node.js 导入格式判断
+
+`alipay-sdk`（Node.js）的导入方式取决于包的实际导出方式，**绝不能凭猜测选择**。
+
+**判断流程：**
+
+1. **查看 package.json**：确认模块类型（ESM/CJS）和入口路径
+   ```bash
+   cat node_modules/alipay-sdk/package.json
+   ```
+   重点看 `type`、`exports`、`main`、`types` 字段。
+
+2. **查看类型定义文件**：确认导出方式
+   ```bash
+   cat node_modules/alipay-sdk/dist/types/index.d.ts
+   ```
+   注意：类型定义文件路径以 package.json 中 `types` 字段为准。
+
+3. **选择导入语法**：
+   - 命名导出（`export class AlipaySdk`）→ `import { AlipaySdk } from 'alipay-sdk'`
+   - 默认导出（`export default`）→ `import AlipaySdk from 'alipay-sdk'`
+   - 混合导出 → `import AlipaySdk, { AlipaySdkConfig } from 'alipay-sdk'`
+
+**优先级**：类型定义（.d.ts）> 官方文档 > 源码
+
+**注意：**
+- package.json 的 `exports` 字段是入口路径配置，不是导出方式
+- 包的导出方式可能随版本更新而改变，务必验证
+- `code-examples/nodejs/` 中的 `require` / `import` 行只用于展示 SDK 调用位置，不作为当前项目可复制依据；生成或修改真实 Node.js 项目前，必须以目标项目实际安装的 `alipay-sdk` 包和项目模块制式为准重新确定导入方式
+
+## 运行与配置边界
+
+1. 沙箱与生产共用支付校验控制流，只切换已确认配置；生产路径不得存在 Mock、固定成功或跳过验签旁路。
+2. `alipayPublicKey` 公钥模式只用当前 SDK 的普通执行 API；证书 API 要求项目明确采用证书模式且同时配置应用、支付宝和支付宝根证书。
+3. Unix/macOS/Linux 从 runner 确认的项目根定位 `.alipay-sandbox.json`，禁止依赖 `cwd`、`getcwd()`、`Directory.GetCurrentDirectory()`、`user.dir` 或 Agent 启动目录。
+4. 配置缺失、模式错配或校验失败时明确失败；不得回退示例值、占位密钥、生产网关、非固定沙箱 `serviceId` 或无验签请求。
+
+---
+
+## 页面跳转类 API 方法选择
+
+`alipay.trade.page.pay` 是页面跳转类 API，**严禁使用 `exec()` 方法**，必须使用页面跳转方法。各语言 SDK 的方法名不同，请按下表选择：
+
+| 语言 | 页面跳转方法 | SDK 执行方法 | 页面跳转类 API 举例 |
+|------|-------------|-------------|-------------------|
+| Java | `alipayClient.pageExecute(request, "POST")` | `alipayClient.execute(request)` | `alipay.trade.page.pay` |
+| .NET | `alipayClient.PageExecute(request, null, "POST")` | `alipayClient.Execute(request)` | 同上 |
+| PHP | `$alipayClient->pageExecute($request, "POST")` | `$alipayClient->execute($request)` | 同上 |
+| Node.js | `alipaySdk.pageExec('alipay.trade.page.pay', 'POST', {...})` | `alipaySdk.exec('alipay.trade.query', {...})` | 同上 |
+| Python | `alipay_client.page_execute(request)` | `alipay_client.execute(request)` | 同上 |
+
+**此外，APP 支付（`alipay.trade.app.pay`）属于客户端 SDK 调用类 API，需使用 `sdkExecute`/`sdkExec` 方法：**
+
+| 语言 | 客户端 SDK 方法 |
+|------|---------------|
+| Java | `alipayClient.sdkExecute(request)` |
+| .NET | `alipayClient.SdkExecute(request)` |
+| PHP | `$alipayClient->sdkExecute($request)` |
+| Node.js | `alipaySdk.sdkExecute('alipay.trade.app.pay', {...})` |
+
+**Node.js 对比示例：**
+```javascript
+// ✅ 正确 - 页面跳转类 API 使用 pageExec()
+const htmlForm = alipaySdk.pageExec('alipay.trade.page.pay', 'POST', {
+  bizContent: { out_trade_no: '123', total_amount: '10.00', ... }
+});
+// 返回：<form action="...">...</form> HTML 字符串
+
+// ❌ 错误 - 对页面跳转类 API 使用 exec()
+const result = await alipaySdk.exec('alipay.trade.page.pay', {
+  bizContent: { out_trade_no: '123', total_amount: '10.00', ... }
+});
+// 返回：JSON 对象，无法用于页面跳转，这是最常见的集成错误！
+```
+
+| 方法类型 | 用途 | 返回值 | 示例 |
+| --- | --- | --- | --- |
+| 页面跳转方法（`pageExec()`/`pageExecute()` 等） | 页面跳转类 API（如：支付） | HTML 表单字符串 | 网站支付 |
+| `exec()` | 服务端 API（查询 / 退款） | 结构化数据（JSON 等） | 交易查询、退款 |
+
+**对支付接口调用 exec() 将不会得到可用的支付表单，是最常见的集成错误之一。**
+
+### 前端支付表单处理
+
+页面跳转类 API 返回的是包含自动提交脚本的 HTML `<form>` 字符串，前端**必须将此 HTML 渲染到页面并自动提交表单**，禁止直接用 URL 跳转。
+
+**❌ 错误写法（以浏览器端 JavaScript 为例）**：
+```javascript
+// paymentHtml 是 HTML 表单字符串，不是 URL
+if (data.paymentHtml) {
+  window.location.href = data.paymentHtml; // 页面只显示 ?method=alipay.trade.page.pay... 参数，无法跳转
+}
+```
+
+**✅ 正确写法**：
+```javascript
+if (data.paymentHtml) {
+  const container = document.createElement('div');
+  container.innerHTML = data.paymentHtml;
+  container.style.position = 'fixed';
+  container.style.top = '0';
+  container.style.left = '0';
+  container.style.width = '100%';
+  container.style.height = '100%';
+  container.style.zIndex = '9999';
+  container.style.background = 'white';
+  document.body.appendChild(container);
+  const form = container.querySelector('form');
+  if (form) form.submit();
+}
+```
+
+---
+
+## 私钥格式
+
+**沙箱返回两个私钥字段，必须按语言选对：**
+
+| 字段 | 格式 | 使用场景 |
+|------|------|---------|
+| `appPrivateKey` | PKCS#8 格式 | ✅ Java 语言必须使用 |
+| `appPrivatePkcsKey` | PKCS#1 格式 | ✅ 非 Java 语言（Python、Node.js、PHP、.NET 等）必须使用 |
+
+**严禁以下误判行为：**
+
+| 误判行为 | 为什么错 | 正确做法 |
+|---------|---------|---------|
+| 看到 `ERR_OSSL_UNSUPPORTED` 就推断私钥格式有问题 | 该错误也可能来自私钥复制污染、字段选错或 SDK 配置参数错误，不能证明私钥格式或运行时不兼容 | 先确认项目实际读取值与可信配置原值一致，再检查字段映射和 SDK 参数 |
+| 向 SDK 配置写入 PEM 头尾、其他前后缀、包装行或说明文字 | 支付宝 SDK 会按配置自行处理密钥包装，手动添加会导致格式错误 | SDK 配置直接使用沙箱或生产配置中的原始私钥值，不做任何格式处理 |
+| 将沙箱返回的 `appPrivatePkcsKey` 转换为 PKCS#8 格式 | 沙箱已同时返回两种格式，转换会引入不必要风险 | 非 Java 语言使用原始 `appPrivatePkcsKey` 值，不做转换 |
+| 将沙箱返回的 `appPrivateKey` 转换为 PKCS#1 格式 | 沙箱已同时返回两种格式，转换会引入不必要风险 | Java 语言使用原始 `appPrivateKey` 值，不做转换 |
+| 写入 SDK 配置前先对私钥做 Base64 解码/重新编码 | SDK 配置无需这些处理 | SDK 配置直接使用沙箱返回的原始字符串 |
+| 因为字段名含 "Pkcs" 就认为是 PKCS#8 格式 | `appPrivatePkcsKey` 是 **PKCS#1** 格式，"Pkcs" 仅表示这是 PKCS 系列标准之一，不代表 PKCS#8 | 非 Java 语言使用 `appPrivatePkcsKey`（PKCS#1），Java 语言使用 `appPrivateKey`（PKCS#8） |
+
+**核心原则：沙箱配置直接使用沙箱返回的对应私钥字段，不做格式转换；生产配置必须确认应用私钥格式与项目语言匹配。所有写入 SDK 配置的私钥值都使用不带 PEM 头尾或其他前后缀的原始密钥字符串，禁止手动添加 PEM 头尾、添加其他前后缀、编码处理或换行符调整。Java 语言使用 PKCS#8，非 Java 语言（Node.js、Python、PHP、.NET 等）使用 PKCS#1。**
+
+**调用边界说明**：上述禁止加工规则针对持久化配置和 SDK 配置。若 A2M 等业务协议需要直接调用语言原生密码库生成业务签名，而该密码库明确要求 PEM 或密钥对象，可从已经校验一致的原始私钥临时构造调用入参；禁止写回配置、覆盖原始值，或把这种调用适配解释成私钥修复。支付宝 SDK 请求签名仍直接使用原始字段，不得预先包装。
+
+### 生产密钥替换与生产支付测试提醒
+
+当用户要求 Agent 直接替换生产环境密钥配置，或用户声称已经替换完成并要求启动生产环境支付测试时，必须先提醒并核对以下事项：
+
+1. `appId`、应用公钥、应用私钥必须属于同一套生产应用密钥，不得混用沙箱应用、其他生产应用或另一套重新生成的密钥。
+2. 基于项目编程语言确认应用私钥格式：Java 使用 PKCS#8；非 Java（Node.js、Python、PHP、.NET 等）使用 PKCS#1。
+3. 如果生产应用私钥格式与当前语言 SDK 要求不一致，请使用支付宝开放平台密钥工具进行私钥格式转换，再将转换后的原始私钥字符串写入项目配置。
+4. 不得把私钥输出到日志、对话总结、测试结果或完整支付表单中。
+
+### 连环误判链
+
+遇到 `ERR_OSSL_UNSUPPORTED` 时，agent 容易陷入以下**越错越远**的连环推理，**每一步都是错的**，必须识别并阻断：
+
+```
+❌ 连环误判链（严禁陷入）：
+
+第 1 步（误判起点）：看到 ERR_OSSL_UNSUPPORTED → 推断"私钥格式有问题"
+    ↓
+第 2 步（错误修复）：认为"给 SDK 配置添加 PEM 头尾可以修复私钥"
+    → 改写 SDK 配置或原始私钥 → 错误仍在
+    ↓
+第 3 步（错误归因）：认为"Node.js 18+ 用了 OpenSSL 3.0，旧格式不被支持"
+    ↓
+第 4 步（越错越远）：认为"应该把原始私钥改成另一种格式"
+    → 将私钥转换为 PKCS#8 格式 → 错误更严重（注：Java 语言应直接使用沙箱返回的 `appPrivateKey` 字段，而非手动转换格式）
+```
+
+**正确做法**：看到 `ERR_OSSL_UNSUPPORTED`，立即停止改写原始私钥或 SDK 配置，先核对项目读取值与可信配置原值，再按下方「验签失败排查原则」逐项检查。原生密码库所需的临时调用适配仍按上方“调用边界说明”处理，不能用于修复配置。
+
+---
+
+## 验签失败排查原则
+
+遇到 `invalid-signature`（验签出错）时，**严禁凭猜测归因到私钥格式或环境兼容性**，必须按以下顺序逐项排查：
+
+### 正确排查顺序
+
+**原则：先验证实际请求内容，再怀疑密钥配置。**
+
+1. **检查实际发送、签名和验签参数的一致性**
+   - 支付宝验签时要求实际请求参数与签名内容匹配。如果 `return_url`、`notify_url` 等参数已传入支付请求但未正确参与签名，或者在签名后被改写，可能导致验签失败。用户明确关闭同步回跳时，未传 `return_url` 本身不应被当作验签失败原因。
+   - **排查方法**：比较实际发送给支付宝的请求参数、SDK 参与签名的参数和服务端验签时使用的参数，确认参数名、参数值和编码方式一致。
+   - 未关闭同步回跳：确认实际请求、签名内容和验签参数中的 `return_url` 值一致。
+   - 已关闭同步回跳：确认实际请求和签名内容均未包含 `return_url`。
+
+2. **检查私钥来源**
+   - 确认使用的是沙箱返回的正确私钥字段：Java 使用 `appPrivateKey`，非 Java 使用 `appPrivatePkcsKey`，而非自行生成或其他来源。
+
+3. **检查 signType 是否一致**
+   - 请求中的 `sign_type` 必须为 `RSA2`，与配置保持一致。
+
+4. **检查私钥格式完整性**
+   - 私钥内容无多余空格、换行符。
+
+5. **检查网关地址**
+   - 沙箱环境必须使用沙箱网关 `https://openapi-sandbox.dl.alipaydev.com/gateway.do`，生产环境使用 `https://openapi.alipay.com/gateway.do`。
+   - 五语言 A2M 示例默认读取 `ALIPAY_GATEWAY`，未设置时使用沙箱网关；只有生产部署才把该环境变量显式设置为生产网关。禁止把生产网关硬编码成沙箱联调默认值。
+
+> **核心教训**：验签失败 ≠ 私钥问题。应先通过日志/输出验证实际请求行为（参数是否完整传入），而非基于技术传言做假设。
+
+---
+
+## 网站支付同步回跳
+
+用户未明确要求关闭同步回跳时，网站支付默认配置 `return_url`。该值不能只是一个格式正确的 URL，还必须对应目标项目内真实存在的 GET 路由和可正常渲染的结果页。
+
+1. 从项目实际运行配置确定协议、主机、端口和路径，禁止使用示例域名、猜测端口或未实现的路由。
+2. 结果页不存在时，必须在当前项目中实现，不得只填写 SDK 的 `return_url` 参数。
+3. 启动服务后对不带支付参数的精确 `return_url` 发起 GET 请求。该请求只验证路由和页面壳：没有订单上下文时展示安全的中性状态，不得放宽真实回跳请求的验签和订单归属校验。跟随有限次重定向，确认最终响应无 404、500、认证循环或重定向循环。单页应用直接刷新该路由仍必须返回应用页面。
+4. 检查 SDK 实际传入的 `return_url` 与已验证地址完全一致，防止域名、端口、协议或路径在配置映射中被替换。
+5. 回跳处理必须先验证支付宝同步参数签名，或使用服务端保存且与当前用户会话绑定的订单标识定位待查订单；不得信任可任意修改的订单号。
+6. 同步回跳参数不是支付成功的可信依据。页面应先展示“正在确认支付结果”，再通过服务端交易查询或已验签的异步通知状态展示最终结果。
+7. 当前 Agent 有浏览器或 UI 验证能力时，必须实际打开回跳页，确认非空白、无可见报错且关键状态内容已渲染。当前无该能力时，不追加用户确认，将回跳页 UI 证据标记为人工待验证；不得宣称页面渲染已验证或网站支付代码开发完成。
+
+回跳地址无法访问、路由不存在、页面无法渲染，或 SDK 实际值与已验证地址不一致时，必须先修正，不得宣称网站支付代码开发完成。
+
+---
+
+## 时间戳格式化
+
+支付宝要求时间戳格式为 `yyyy-MM-dd HH:mm:ss`（空格分隔，非 ISO 格式）。
+
+### Java
+```java
+import java.text.SimpleDateFormat;
+// ✅ 正确
+new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(new Date());
+// ❌ 错误：Instant.now().toString() → "2026-04-29T14:30:00.000Z"
+```
+
+### .NET (C#)
+```csharp
+// ✅ 正确
+DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss");
+// ❌ 错误：DateTime.Now.ToString("o") → "2026-04-29T14:30:00.0000000+08:00"
+```
+
+### PHP
+```php
+// ✅ 正确
+date("Y-m-d H:i:s");
+// ❌ 错误：date("c") → "2026-04-29T14:30:00+08:00"
+```
+
+### Node.js
+```javascript
+function formatAlipayTimestamp(date) {
+  const pad = (n) => n.toString().padStart(2, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+
+// ❌ 错误：new Date().toISOString() → "2026-04-29T14:30:00.000Z"
+```
+
+### Python
+```python
+from datetime import datetime
+
+def format_alipay_timestamp(dt: datetime) -> str:
+    return dt.strftime("%Y-%m-%d %H:%M:%S")
+
+# ❌ 错误：datetime.isoformat() → "2026-04-29T14:30:00"
+```

package/skill-pre/references/integration/modules/checklist.md

@@ -0,0 +1,154 @@
+# 支付宝支付产品代码开发校验清单
+
+本文档整理了支付宝支付集成过程中的通用校验项，仅包含必须校验和高危项目。代码实现后、集成收口前必须逐项核对；逐项核对不等于为每项安装工具或启动运行环境，自动执行边界以 `../flow.md` 步骤 8 为准，无法自动取得证据时标记为“人工待验证”。默认按第八节摘要模板输出，用户要求明细时再展开全部逐项结果。校验结果供参考，开发者务必按照支付宝最新开放平台文档进行检查。
+
+---
+
+<!-- ALIPAY_AIPAY_CHECKLIST_PRODUCTS:aipay,webpay,apppay -->
+## 一、密钥与安全校验
+
+| 校验项 | 校验要求 | 说明 |
+|----------|----------|----------|
+| 私钥存储位置 | 私钥不得保存在客户端代码中 | 构造交易数据并签名必须在商家服务端完成，私钥绝对不能保存在商家APP客户端中，也不能从服务端下发。商户需妥善保存私钥，不建议在代码或配置中明文写入私钥，应当通过加密配置文件或密钥管理平台进行管理 |
+| 私钥日志安全 | 私钥不得出现在日志中 | 私钥的保密等级比源码高，出现在日志中将增加私钥泄露的风险 |
+| 私钥仓库安全 | 私钥不得上传公共仓库 | 私钥泄露将导致应用和支付宝交互的安全性完全丧失 |
+| 沙箱配置后置校验 | 沙箱 appId、应用私钥、支付宝公钥接入项目后必须完成配置准确性校验 | `sandboxConfigState=READY` 时，Unix/macOS/Linux 必须确认商家服务端加载器直接读取已验证的 `.alipay-sandbox.json`，从同一 `appIds[0]` 选择当前语言字段且不在源码、普通日志或额外 `.env` 留下密钥副本；Windows 必须确认项目实际读取值属于本次手工申领和密钥配置的同一沙箱应用。待配置时本项直接不通过，代码只能保留会在配置缺失时明确失败的加载边界，禁止占位符、示例值或其他来源密钥 |
+| 用户项目文件保护 | 既有项目结构、文件和无关支付能力均保留；新项目只创建在尚不存在或为空的目录 | 检查本轮变更不存在未经独立二次确认的既有文件删除、既有文件整体覆盖，或与已确认目标产品无关的修改；新建文件不属于既有文件整体覆盖。发现违规立即判定不通过并停止后续流程 |
+| 沙箱配置防提交 | Unix/macOS/Linux 快速沙箱：配置未被 Git 跟踪，项目根目录 `.gitignore` 包含精确规则 `/.alipay-sandbox.json`，配置权限为 `0600`；Windows 手工沙箱：实际敏感配置未被 Git 跟踪并具有对应忽略保护，Windows 文件访问控制能核验时仅当前用户可访问，不能核验时标记人工待验证 | 禁止私钥、沙箱账号或密码随项目进入 Git 暂存区或公共仓库；缺少适用保护时判定不通过 |
+| 沙箱配置稳定定位 | Unix/macOS/Linux 项目代码从已确认的规范化项目根定位 `.alipay-sandbox.json` | 禁止依赖 `cwd`、`getcwd()`、`Directory.GetCurrentDirectory()`、`user.dir` 或 Agent 启动目录 |
+| SDK 公钥/证书模式一致 | 公钥模式使用普通执行 API；证书执行 API 只在应用公钥证书、支付宝公钥证书和支付宝根证书均已配置时使用 | 禁止公钥配置模式误用证书执行 API |
+| 支付校验无旁路 | 生产源码中不存在 Mock、测试或沙箱开关可触达的跳过验签、固定成功或支付校验旁路 | 沙箱与生产必须共用相同验证控制流 |
+
+---
+
+<!-- ALIPAY_AIPAY_CHECKLIST_PRODUCTS:webpay,apppay -->
+## 二、异步通知校验
+
+先区分两种验收层级，再判断是否通过：
+
+- **本地正式验收 / 本地生产参数验收模式**：允许暂时没有可公网访问的 HTTPS `notify_url`。这一层必须检查“通知处理代码是否已实现”和“支付结果是否可通过主动查询兜底确认”；公网可访问性标记为“人工待验证”，不作为阻断本地正式验收的单一条件。
+- **真实生产上线**：必须具备可公网访问的 HTTPS `notify_url`，并完成验签、关键字段校验、幂等、成功响应 `success` 和补偿查询。未满足时不得判定生产就绪。
+
+| 校验项 | 校验要求 | 说明 |
+|----------|----------|----------|
+| 验签必须执行 | 收到异步通知后必须先验签 | 确保通知来自支付宝 |
+| 关键信息校验 | 检验 out_trade_no、total_amount、app_id、seller_id 等商户请求关键参数| 防止伪造订单、金额篡改等 |
+| 交易状态判断 | 仅 `TRADE_SUCCESS` 或 `TRADE_FINISHED` 才算支付成功 | 其他状态不算支付成功 |
+| 幂等处理 | 必须进行幂等处理，过滤重复的通知 | 同一笔订单可能收到多次异步通知 |
+| 响应值 | 商户侧处理成功后需返回字符串 `success` | 否则支付宝会重试通知 |
+| URL 格式 | notify_url 不能包含空格和 HTML 标签 | 否则可能导致通知失败 |
+| 重定向 | notify_url 不能重定向 | 重定向会导致支付宝收不到 success |
+| 外网可访问 | 真实生产上线时，notify_url 必须外网可访问；本地生产参数验收模式下标记为人工待验证 | 需确保支付宝服务器可访问；本地 `localhost`、局域网地址或 TLS 未就绪域名不阻塞本地正式验收 |
+
+<!-- ALIPAY_AIPAY_CHECKLIST_PRODUCTS:aipay,webpay,apppay -->
+## 三、适用接口覆盖校验
+
+| 校验项 | 校验要求 | 说明 |
+|----------|----------|----------|
+| AI 网页应用收款/AI 移动应用收款 | 已实现产品下单、交易查询、退款、退款查询、关闭交易和异步通知处理代码 | 以产品和接口文档为准；缺少本地示例不得作为省略理由。公网通知联调是否完成单独在上一节判断 |
+| AI 按量付费 | 已实现 402 协议、`alipay.aipay.agent.payment.verify` 和 `alipay.aipay.agent.fulfillment.confirm` | 不使用 AI 网页应用收款/AI 移动应用收款的通用收单接口 |
+| 限定范围 | 用户明确排除的适用接口已列为待办 | 存在未实现的适用接口时不得判定完整集成 |
+
+---
+
+<!-- ALIPAY_AIPAY_CHECKLIST_PRODUCTS:webpay,apppay -->
+## 四、支付结果处理校验
+
+| 校验项 | 校验要求 | 说明 |
+|----------|----------|----------|
+| 前台同步结果防范 | 前台同步跳转结果仅作通知，**不能作为支付成功的依据** | 必须以异步通知或查询接口结果为准 |
+| AI 网页应用收款回跳默认行为 | 用户未明确关闭同步回跳时，已配置项目实际 `return_url` | 地址不得包含示例域名、占位符、猜测端口或未实现路由 |
+| AI 网页应用收款回跳页可用性 | 启动服务后 GET 访问精确 `return_url`，并在 Agent 具备浏览器/UI 能力时验证页面正常渲染；当前环境无法取得 UI 证据时标记人工待验证 | 不得出现 404、500、空白页、可见报错、认证循环或重定向循环；单页应用直接刷新路由也必须可用 |
+| AI 网页应用收款回跳状态展示 | 先验证同步参数签名，或使用与当前用户会话绑定的服务端订单标识；再通过服务端查询或已验签通知状态展示最终支付结果 | 同步回跳参数不得直接改写订单或作为支付成功依据，不得使用可任意修改的订单号访问其他订单 |
+| AI 网页应用收款关闭同步回跳 | 仅当用户已明确表示不使用同步回跳时适用；SDK 请求未传 `return_url` | 用户未明确关闭时，缺少 `return_url` 必须修复为默认同步回跳分支；关闭分支必须保留异步通知、交易查询和商户订单查询页，且沙箱提示不得声称付款后会自动返回商户网站 |
+| 支付成功判断 | 仅 `trade_status` 为 `TRADE_SUCCESS` 或 `TRADE_FINISHED` 时才认定付款成功 | 其他状态不算支付成功 |
+| 主动查询兜底 | 主动查询订单状态必须作为支付结果确认的兜底逻辑 | 无论异步通知是否到达，都应具备主动查询订单状态的能力，防止因网络抖动、通知延迟或丢失导致的状态不一致 |
+| 未知异常处理 | 网络超时或未知异常时，必须调用查询接口确认 | 不能简单推断为成功或失败 |
+| 商家资损防范 | 不依赖前台同步结果，以异步通知或查询为准 | 防止用户未付款但商家判定成功 |
+| 用户资损防范 | 未确认支付结果前不要求用户再次付款 | 防止用户已付款但商家判定失败导致重复扣款 |
+
+> AI 按量付费不使用前台同步跳转结果和异步通知作为支付成功依据，需按下一节专项校验。
+
+---
+
+<!-- ALIPAY_AIPAY_CHECKLIST_PRODUCTS:aipay -->
+## 五、AI 按量付费专项校验
+
+| 校验项 | 校验要求 | 说明 |
+|----------|----------|----------|
+| 订单持久化 | 返回 `Payment-Needed` 前必须持久化 `out_trade_no`、`resource_id`、金额、状态、过期时间 | 付款后携带 `Payment-Proof` 回来时必须能映射回商户本地订单 |
+| Payment-Proof 验证 | 收到 `Payment-Proof` 后必须调用 `alipay.aipay.agent.payment.verify` | 验证成功只代表支付宝凭证有效，不代表本地订单已完成校验 |
+| 本地订单匹配 | 验付成功后必须查询本地订单并校验状态 | 防止凭证有效但商户订单不存在、过期或状态异常 |
+| 资源防串 | 必须校验本地订单的 `resource_id` 与验付结果/请求资源一致 | 防止用户通过篡改资源标识获取其他资源 |
+| 金额一致性 | 必须校验本地订单金额与 `Payment-Needed` 账单金额和服务定价一致；若验付接口返回金额字段，再校验实际支付金额 | 防止金额篡改或错误定价 |
+| 幂等履约 | 同一订单重复携带 `Payment-Proof` 时不得重复发放资源 | 应返回历史履约结果或可重试确认结果 |
+| 履约确认 | 资源生成后必须调用 `alipay.aipay.agent.fulfillment.confirm` | 确认成功后再标记订单 `FULFILLED` 并返回成功交付 |
+| 自动联调成功证据 | 必须同时具备 HTTP 200、非空 `resource_id` / `resourceId`、非空 `content`、无明确业务失败，以及当前五语言示例有效的 `Payment-Validation` | 204、空体、空对象、`VERIFY_FAILED`、履约失败或异常响应头均不得判为通过 |
+| 敏感过程产物 | 单次联调的临时目录/文件权限不得宽于 `0700/0600`，命令结束时立即清理 | 禁止打印 Payment-Proof 或 Payment-Validation 原始值；失败后重新执行完整联调 |
+| 沙箱 serviceId | 沙箱联调的 `serviceId` 固定为 `api_mock_service_id` | 不向用户索要正式 `serviceId`，不使用其他占位符 |
+| 沙箱空字段边界 | 沙箱联调中字段为空可用于排查定位，生产环境关键字段为空必须按异常处理 | 不得把沙箱容错逻辑直接迁移成生产跳过校验 |
+| 生产实现完整性 | 订单持久化、本地订单匹配、金额一致性、资源防串、幂等履约、待确认状态和确认失败重试均已实际实现 | 任一关键控制仍为 TODO、注释、内存演示或伪代码时只能判定沙箱演示可测试，不得判定生产就绪 |
+
+---
+
+<!-- ALIPAY_AIPAY_CHECKLIST_PRODUCTS:webpay,apppay -->
+## 六、退款校验
+
+| 校验项 | 校验要求 | 说明 |
+|----------|----------|----------|
+| 退款使用场景 | 所有退款业务都必须调用退款接口 | 撤销接口不能用于退款业务，撤销接口仅用于在不确定支付结果情况下对交易发起撤销 |
+| 退款是否成功判断 | 退款接口返回 `fund_change=Y` 或退款查询返回 `refund_status=REFUND_SUCCESS` 才算退款成功 | 其他状态不算退款成功 |
+| 退款幂等保障 | 接口未退款成功且不明确交易情况时，重试请务必保证退款请求号 out_request_no 以及请求参数一致，避免发生多次退款 | 防止多次退款 |
+| 新退款与重试区分 | 每次新退款使用新的 `out_request_no`；同一次退款的异常重试复用原编号、金额和请求参数 | 新的一次部分退款不能复用其他退款编号，重试也不能临时生成新编号 |
+| 退款金额计算 | 使用十进制定点金额，并在调用前校验累计退款不超过原订单实付金额 | 禁止二进制浮点误差或超额退款 |
+
+---
+
+<!-- ALIPAY_AIPAY_CHECKLIST_PRODUCTS:aipay,webpay,apppay -->
+## 七、上线前校验
+
+| 校验项 | 校验要求 | 说明 |
+|----------|----------|----------|
+| 网关地址切换 | 五语言 A2M 示例默认沙箱网关为 `https://openapi-sandbox.dl.alipaydev.com/gateway.do`；上线时显式切换为 `https://openapi.alipay.com/gateway.do` | 禁止把生产网关复制进沙箱运行配置 |
+| APPID 切换 | 使用生产环境的 APPID | 与沙箱 APPID 不同 |
+| 密钥切换 | 使用生产环境的应用私钥和支付宝公钥 | 与沙箱密钥不同 |
+| 生产密钥对应关系 | `appId`、应用公钥、应用私钥属于同一套生产应用密钥 | 不得混用沙箱应用、其他生产应用或另一套重新生成的密钥 |
+| 生产私钥格式 | 应用私钥格式与项目语言 SDK 匹配 | Java 使用 PKCS#8；非 Java 使用 PKCS#1。格式不匹配时使用支付宝开放平台密钥工具转换 |
+| AI 按量付费 serviceId 替换 | 生产配置中不得保留 `api_mock_service_id` | 上线前替换为服务市场实际返回的真实 `serviceId` |
+| 证书模式 | 只有明确采用证书模式时才切换为同一生产应用的完整证书链并使用证书执行 API | 应用公钥证书、支付宝公钥证书、支付宝根证书必须同时配置；公钥模式不得调用证书执行 API |
+| 产品开通状态 | 确认产品已在生产环境开通 | 沙箱无需开通，生产环境需要申请开通 |
+| 私钥安全 | 私钥不在代码、日志、公共仓库中明文存储 | 使用安全的方式管理私钥 |
+| 日志安全 | 日志中不打印敏感信息（私钥、用户信息等） | 防止信息泄露 |
+| HTTPS 通信 | 生产环境必须使用 HTTPS | 保证传输安全 |
+
+---
+
+<!-- ALIPAY_AIPAY_CHECKLIST_PRODUCTS:aipay,webpay,apppay -->
+## 八、代码开发结果输出
+
+> 内部逐项判断使用以下状态：
+> - ✅ 通过：已实现且符合规范
+> - ❌ 不通过：未实现或不符合规范，需整改
+> - ⚠️ 部分通过：部分实现，需补充完善
+> - ➖ 不适用：当前集成场景不涉及此项
+> - 🟡 人工待验证：当前环境无法自动取得充分证据
+
+先按当前证据逐项判断；本轮可修复时先修复、重检，不渲染中间结果。项目稳定后按 `../flow.md` 执行唯一 `checklist-result`，由 runner 在同一次最终调用中校验 scope 并对同一项目快照执行固定 implementation audit。审计失败是阻断缺口，不能被 Agent 自报结论覆盖；可修复时先返回结构化 findings，项目变化后重新加载 checklist 阶段取得新 scope。
+
+最终 action、完整参数和失败转移只以 `../flow.md` 步骤 8 为准，本模块不复制命令。runner 只接受最终一轮实际证据：Unix/macOS/Linux 的 `sandboxConfigState` 复用脚本终态，Windows 复用步骤 1/3 的 `READY|VERIFY_PENDING`；待配置时不重跑或读取配置，并把配置及依赖动作列为未完成。
+
+各产品结论差异如下，对客正文只在消息目录维护：
+
+| 产品 | checklist 内部校验事实 | 实际待办来源 |
+|---|---|---|
+| `AIPAY` | 通过必须绑定本轮 AI 按量付费服务端联调成功；只有完整 402、沙箱收银、Payment-Proof 重试和资源交付证据才能称沙箱测试通过 | 失败/部分通过项、人工待验证项、联调恢复动作 |
+| `WEBPAY` | 未提供浏览器付款入口和完整指引时不得通过；公网 HTTPS `notify_url` 未联调只能称本地验收完成，不能称生产就绪 | 失败/部分通过项、人工待验证项、待用户体验事项 |
+| `APPPAY` | 当前没有沙箱付款验证结论，不据此生成通过或失败，也不临场补充沙箱付款步骤 | 失败/部分通过项、人工待验证项 |
+
+`failedItems`、`manualItems` 必须包含确定下一步，无对应项时传“无”。`overallResult=通过` 要求两者为“无”、`sandboxConfigState=READY`、`blockingDefectState=NONE`；“部分通过”至少有一类缺口；“未通过”必须列出失败项。`blockingDefectState` 只表示沙箱配置及其直接依赖以外的代码、安全或必要依据缺口；单纯 UI、浏览器或公网联调待验证只进入 `manualItems`。`full_process` 仅在沙箱待配置且无其他阻断，或 `READY` 且只剩非阻塞人工项时继续 Onboarding。
+
+内部保留适用项依据；明细按实际证据输出，不维护第二份模板。同一次代码开发只渲染一次；renderer stdout 是默认收口的唯一对客正文，前后不得追加摘要、风险或待办。
+
+---
+
+> 📖 本文档内容整理自支付宝开放平台官方文档，如有更新请以官方文档为准。

package/skill-pre/references/integration/modules/code-examples/csharp/1-/351/200/232/347/224/250/346/216/245/345/217/243//345/274/202/346/255/245/351/200/232/347/237/245/345/244/204/347/220/206/344/273/243/347/240/201/347/244/272/344/276/213.md

@@ -0,0 +1,199 @@
+# 异步通知处理 - C# 示例
+
+适用产品：AI 网页应用收款、AI 移动应用收款。AI 按量付费不使用异步通知。
+
+```csharp
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.Linq;
+using System.Text.RegularExpressions;
+using System.Threading.Tasks;
+using Microsoft.AspNetCore.Mvc;
+
+[ApiController]
+public class AlipayNotifyController : ControllerBase
+{
+    private readonly IAlipayNotifyVerifier _alipayNotifyVerifier;
+    private readonly IPaymentConfigRepository _paymentConfigRepository;
+    private readonly IOrderRepository _orderRepository;
+    private readonly INotifyEventRepository _notifyEventRepository;
+    private readonly INotifyLogger _notifyLogger;
+
+    public AlipayNotifyController(
+        IAlipayNotifyVerifier alipayNotifyVerifier,
+        IPaymentConfigRepository paymentConfigRepository,
+        IOrderRepository orderRepository,
+        INotifyEventRepository notifyEventRepository,
+        INotifyLogger notifyLogger)
+    {
+        _alipayNotifyVerifier = alipayNotifyVerifier;
+        _paymentConfigRepository = paymentConfigRepository;
+        _orderRepository = orderRepository;
+        _notifyEventRepository = notifyEventRepository;
+        _notifyLogger = notifyLogger;
+    }
+
+    [HttpPost("/alipay/notify")]
+    public async Task<IActionResult> Notify()
+    {
+        var paramsMap = new Dictionary<string, string>();
+        try
+        {
+            paramsMap = Request.Form.ToDictionary(kv => kv.Key, kv => kv.Value.ToString());
+            var config = await _paymentConfigRepository.FindByAppId(paramsMap.GetValueOrDefault("app_id"));
+            if (config == null)
+            {
+                return Fail("alipay notify app config not found", paramsMap);
+            }
+
+            if (!VerifyNotifyWithAlipaySdk(paramsMap, config))
+            {
+                return Fail("alipay notify signature check failed", paramsMap);
+            }
+
+            var order = await _orderRepository.FindByOutTradeNo(paramsMap.GetValueOrDefault("out_trade_no"));
+            if (order == null || !BusinessFieldsMatch(order, paramsMap, config))
+            {
+                return Fail("alipay notify business check failed", paramsMap);
+            }
+
+            var inserted = await _notifyEventRepository.InsertOnce(
+                paramsMap.GetValueOrDefault("notify_id"),
+                paramsMap.GetValueOrDefault("trade_no"),
+                paramsMap.GetValueOrDefault("out_trade_no"),
+                paramsMap.GetValueOrDefault("trade_status"),
+                paramsMap);
+            if (!inserted)
+            {
+                return Content("success", "text/plain");
+            }
+
+            if (IsPaidTradeNotification(paramsMap))
+            {
+                await _orderRepository.MarkPaidIdempotently(order.OutTradeNo, paramsMap.GetValueOrDefault("trade_no"), paramsMap);
+            }
+            else
+            {
+                await _orderRepository.RecordNonPaidTradeEvent(order.OutTradeNo, paramsMap.GetValueOrDefault("trade_status"), paramsMap);
+            }
+
+            return Content("success", "text/plain");
+        }
+        catch (Exception)
+        {
+            SafeLogNotifyError("alipay notify unexpected exception", paramsMap);
+            return Content("fail", "text/plain");
+        }
+    }
+
+    private bool BusinessFieldsMatch(MerchantOrder order, Dictionary<string, string> paramsMap, AlipayNotifyConfig config)
+    {
+        return paramsMap.GetValueOrDefault("app_id") == config.AppId
+            && paramsMap.GetValueOrDefault("out_trade_no") == order.OutTradeNo
+            && AmountEquals(order.TotalAmount, paramsMap.GetValueOrDefault("total_amount"))
+            && ExpectedSellerMatches(config, paramsMap.GetValueOrDefault("seller_id"), paramsMap.GetValueOrDefault("seller_email"));
+    }
+
+    private static bool AmountEquals(decimal expected, string? actual)
+    {
+        var expectedAmount = NormalizeAmountText(expected);
+        var actualAmount = NormalizeAmountText(actual);
+        return expectedAmount != null && expectedAmount == actualAmount;
+    }
+
+    private static string? NormalizeAmountText(decimal value)
+    {
+        if (decimal.Round(value, 2) != value) return null;
+        return value.ToString("0.00", CultureInfo.InvariantCulture);
+    }
+
+    private static string? NormalizeAmountText(string? value)
+    {
+        if (string.IsNullOrWhiteSpace(value)) return null;
+        var match = Regex.Match(value.Trim(), @"^(\d+)(?:\.(\d{1,2}))?$");
+        if (!match.Success) return null;
+        var yuan = match.Groups[1].Value.TrimStart('0');
+        if (yuan.Length == 0) yuan = "0";
+        return $"{yuan}.{match.Groups[2].Value.PadRight(2, '0')}";
+    }
+
+    private static bool IsPaidTradeNotification(Dictionary<string, string> paramsMap)
+    {
+        var paidStatus = paramsMap.GetValueOrDefault("trade_status") == "TRADE_SUCCESS"
+            || paramsMap.GetValueOrDefault("trade_status") == "TRADE_FINISHED";
+        return paidStatus
+            && string.IsNullOrEmpty(paramsMap.GetValueOrDefault("out_biz_no"))
+            && string.IsNullOrEmpty(paramsMap.GetValueOrDefault("gmt_refund"))
+            && string.IsNullOrEmpty(paramsMap.GetValueOrDefault("refund_fee"));
+    }
+
+    private static bool ExpectedSellerMatches(AlipayNotifyConfig config, string? sellerId, string? sellerEmail)
+    {
+        var expectedSellerId = config.SellerId;
+        var expectedSellerEmail = config.SellerEmail;
+        return (!string.IsNullOrEmpty(expectedSellerId) && sellerId == expectedSellerId)
+            || (!string.IsNullOrEmpty(expectedSellerEmail) && sellerEmail == expectedSellerEmail);
+    }
+
+    private bool VerifyNotifyWithAlipaySdk(Dictionary<string, string> paramsMap, AlipayNotifyConfig config)
+    {
+        // 使用当前项目已安装的支付宝 SDK 验签能力校验 paramsMap["sign"]。
+        // _alipayNotifyVerifier.Verify(paramsMap, config) 必须封装目标项目当前 SDK 实际通知验签 API；落地前先查已安装包文档或类型定义，不能手写临时 RSA 验签。
+        return _alipayNotifyVerifier.Verify(paramsMap, config);
+    }
+
+    private IActionResult Fail(string message, Dictionary<string, string> paramsMap)
+    {
+        SafeLogNotifyError(message, paramsMap);
+        return Content("fail", "text/plain");
+    }
+
+    private void SafeLogNotifyError(string message, Dictionary<string, string> paramsMap)
+    {
+        try
+        {
+            _notifyLogger.Warn(message, SanitizeNotifyParams(paramsMap));
+        }
+        catch (Exception)
+        {
+            // 日志失败不能影响支付宝收到纯文本 fail。
+        }
+    }
+
+    private static Dictionary<string, string> SanitizeNotifyParams(Dictionary<string, string> paramsMap)
+    {
+        var safeParams = new Dictionary<string, string>(paramsMap);
+        safeParams.Remove("sign");
+        return safeParams;
+    }
+}
+
+// 以下接口对接商家项目的真实 SDK 验签、支付配置、订单仓储、通知事件表和脱敏日志。
+// 生产环境必须使用持久化订单表和通知事件表；内存 Dictionary 只能用于非生产 demo。
+public interface IAlipayNotifyVerifier { bool Verify(Dictionary<string, string> paramsMap, AlipayNotifyConfig config); }
+public interface IPaymentConfigRepository { Task<AlipayNotifyConfig?> FindByAppId(string? appId); }
+public interface IOrderRepository
+{
+    Task<MerchantOrder?> FindByOutTradeNo(string? outTradeNo);
+    Task MarkPaidIdempotently(string outTradeNo, string? tradeNo, Dictionary<string, string> paramsMap);
+    Task RecordNonPaidTradeEvent(string outTradeNo, string? tradeStatus, Dictionary<string, string> paramsMap);
+}
+public interface INotifyEventRepository
+{
+    Task<bool> InsertOnce(string? notifyId, string? tradeNo, string? outTradeNo, string? tradeStatus, Dictionary<string, string> paramsMap);
+}
+public interface INotifyLogger { void Warn(string message, Dictionary<string, string> paramsMap); }
+public record AlipayNotifyConfig(string AppId, string AlipayPublicKey, string? SellerId, string? SellerEmail);
+public record MerchantOrder(string OutTradeNo, decimal TotalAmount);
+```
+
+要点：
+
+- 支付宝通知是 POST 表单，验签前必须保留完整表单参数。
+- 验签必须调用当前项目支付宝 SDK 的实际验签 API，验签前不得丢字段或改值。
+- `app_id`、`seller_id` / `seller_email` 从运行时支付配置校验，不从订单对象默认取值。
+- 金额校验使用 `decimal` 或项目定点数工具，不要用浮点数直接比较。
+- 只有付款成功状态且不是退款、关单、分账等事件时，才认定付款成功。
+- 内存订单或内存幂等只能用于非生产 demo，生产必须使用持久化订单表和通知事件表。
+- 处理成功后返回纯文本 `success`；异常、验签失败或业务校验失败返回 `fail`。