@alipay/alipay-aipay 1.2.2 → 1.5.0

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

@@ -46,6 +46,7 @@ SDK 的引入方式取决于对应语言的包管理方式和实际导出方式
 **注意：**
 - package.json 的 `exports` 字段是入口路径配置，不是导出方式
 - 包的导出方式可能随版本更新而改变，务必验证
+- `code-examples/nodejs/` 中的 `require` / `import` 行只用于展示 SDK 调用位置，不作为当前项目可复制依据；生成或修改真实 Node.js 项目前，必须以目标项目实际安装的 `alipay-sdk` 包和项目模块制式为准重新确定导入方式
 
 ---
 
@@ -61,7 +62,7 @@ SDK 的引入方式取决于对应语言的包管理方式和实际导出方式
 | 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` 方法：**
+**此外，APP 支付（`alipay.trade.app.pay`）属于客户端 SDK 调用类 API，需使用 `sdkExecute`/`sdkExec` 方法：**
 
 | 语言 | 客户端 SDK 方法 |
 |------|---------------|
@@ -204,6 +205,7 @@ if (data.paymentHtml) {
 
 5. **检查网关地址**
    - 沙箱环境必须使用沙箱网关 `https://openapi-sandbox.dl.alipaydev.com/gateway.do`，生产环境使用 `https://openapi.alipay.com/gateway.do`。
+   - 五语言 A2M 示例默认读取 `ALIPAY_GATEWAY`，未设置时使用沙箱网关；只有生产部署才把该环境变量显式设置为生产网关。禁止把生产网关硬编码成沙箱联调默认值。
 
 > **核心教训**：验签失败 ≠ 私钥问题。应先通过日志/输出验证实际请求行为（参数是否完整传入），而非基于技术传言做假设。
 
@@ -219,9 +221,9 @@ if (data.paymentHtml) {
 4. 检查 SDK 实际传入的 `return_url` 与已验证地址完全一致，防止域名、端口、协议或路径在配置映射中被替换。
 5. 回跳处理必须先验证支付宝同步参数签名，或使用服务端保存且与当前用户会话绑定的订单标识定位待查订单；不得信任可任意修改的订单号。
 6. 同步回跳参数不是支付成功的可信依据。页面应先展示“正在确认支付结果”，再通过服务端交易查询或已验签的异步通知状态展示最终结果。
-7. 当前 Agent 有浏览器或 UI 验证能力时，必须实际打开回跳页，确认非空白、无可见报错且关键状态内容已渲染。当前无该能力时，向用户提供精确回跳地址请其打开确认；取得确认前不得宣称页面渲染已验证或网站支付集成完成。
+7. 当前 Agent 有浏览器或 UI 验证能力时，必须实际打开回跳页，确认非空白、无可见报错且关键状态内容已渲染。当前无该能力时，不追加用户确认，将回跳页 UI 证据标记为人工待验证；不得宣称页面渲染已验证或网站支付代码开发完成。
 
-回跳地址无法访问、路由不存在、页面无法渲染，或 SDK 实际值与已验证地址不一致时，必须先修正，不得宣称网站支付集成完成。
+回跳地址无法访问、路由不存在、页面无法渲染，或 SDK 实际值与已验证地址不一致时，必须先修正，不得宣称网站支付代码开发完成。
 
 ---
 

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

@@ -1,9 +1,10 @@
-# 支付宝支付集成校验清单
+# 支付宝支付产品代码开发校验清单
 
-本文档整理了支付宝支付集成过程中的通用校验项，仅包含必须校验和高危项目。代码实现后、集成收口前必须逐项核对；逐项核对不等于为每项安装工具或启动运行环境，自动执行边界以 `../flow.md` 步骤 7 为准，无法自动取得证据时标记为“人工待验证”。默认按第八节摘要模板输出，用户要求明细时再展开全部逐项结果。校验结果供参考，开发者务必按照支付宝最新开放平台文档进行检查。
+本文档整理了支付宝支付集成过程中的通用校验项，仅包含必须校验和高危项目。代码实现后、集成收口前必须逐项核对；逐项核对不等于为每项安装工具或启动运行环境，自动执行边界以 `../flow.md` 步骤 8 为准，无法自动取得证据时标记为“人工待验证”。默认按第八节摘要模板输出，用户要求明细时再展开全部逐项结果。校验结果供参考，开发者务必按照支付宝最新开放平台文档进行检查。
 
 ---
 
+<!-- ALIPAY_AIPAY_CHECKLIST_PRODUCTS:aipay,webpay,apppay -->
 ## 一、密钥与安全校验
 
 | 校验项 | 校验要求 | 说明 |
@@ -11,11 +12,13 @@
 | 私钥存储位置 | 私钥不得保存在客户端代码中 | 构造交易数据并签名必须在商家服务端完成，私钥绝对不能保存在商家APP客户端中，也不能从服务端下发。商户需妥善保存私钥，不建议在代码或配置中明文写入私钥，应当通过加密配置文件或密钥管理平台进行管理 |
 | 私钥日志安全 | 私钥不得出现在日志中 | 私钥的保密等级比源码高，出现在日志中将增加私钥泄露的风险 |
 | 私钥仓库安全 | 私钥不得上传公共仓库 | 私钥泄露将导致应用和支付宝交互的安全性完全丧失 |
-| 沙箱配置后置校验 | 沙箱 appId、应用私钥、支付宝公钥写入项目后必须完成配置准确性校验 | 必须确认写入配置来自同一份沙箱返回配置、与沙箱返回配置一致、字段选择正确、SDK 配置匹配，私钥不是占位符、示例值或其他来源的密钥 |
+| 沙箱配置后置校验 | 沙箱 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 暂存区或公共仓库；缺少适用保护时判定不通过 |
 
 ---
 
+<!-- ALIPAY_AIPAY_CHECKLIST_PRODUCTS:webpay,apppay -->
 ## 二、异步通知校验
 
 先区分两种验收层级，再判断是否通过：
@@ -34,36 +37,39 @@
 | 重定向 | notify_url 不能重定向 | 重定向会导致支付宝收不到 success |
 | 外网可访问 | 真实生产上线时，notify_url 必须外网可访问；本地生产参数验收模式下标记为人工待验证 | 需确保支付宝服务器可访问；本地 `localhost`、局域网地址或 TLS 未就绪域名不阻塞本地正式验收 |
 
+<!-- ALIPAY_AIPAY_CHECKLIST_PRODUCTS:aipay,webpay,apppay -->
 ## 三、适用接口覆盖校验
 
 | 校验项 | 校验要求 | 说明 |
 |----------|----------|----------|
-| 网站支付/APP支付 | 已实现产品下单、交易查询、退款、退款查询、关闭交易和异步通知处理代码 | 以产品和接口文档为准；缺少本地示例不得作为省略理由。公网通知联调是否完成单独在上一节判断 |
-| 按量付费 | 已实现 402 协议、`alipay.aipay.agent.payment.verify` 和 `alipay.aipay.agent.fulfillment.confirm` | 不使用网站支付/APP支付的通用收单接口 |
+| AI 网页应用收款/AI 移动应用收款 | 已实现产品下单、交易查询、退款、退款查询、关闭交易和异步通知处理代码 | 以产品和接口文档为准；缺少本地示例不得作为省略理由。公网通知联调是否完成单独在上一节判断 |
+| AI 按量付费 | 已实现 402 协议、`alipay.aipay.agent.payment.verify` 和 `alipay.aipay.agent.fulfillment.confirm` | 不使用 AI 网页应用收款/AI 移动应用收款的通用收单接口 |
 | 限定范围 | 用户明确排除的适用接口已列为待办 | 存在未实现的适用接口时不得判定完整集成 |
 
 ---
 
+<!-- ALIPAY_AIPAY_CHECKLIST_PRODUCTS:webpay,apppay -->
 ## 四、支付结果处理校验
 
 | 校验项 | 校验要求 | 说明 |
 |----------|----------|----------|
 | 前台同步结果防范 | 前台同步跳转结果仅作通知，**不能作为支付成功的依据** | 必须以异步通知或查询接口结果为准 |
-| 网站支付回跳默认行为 | 用户未明确关闭同步回跳时，已配置项目实际 `return_url` | 地址不得包含示例域名、占位符、猜测端口或未实现路由 |
-| 网站支付回跳页可用性 | 启动服务后 GET 访问精确 `return_url`，并通过 Agent 浏览器/UI 验证或用户明确确认证明页面正常渲染 | 不得出现 404、500、空白页、可见报错、认证循环或重定向循环；单页应用直接刷新路由也必须可用 |
-| 网站支付回跳状态展示 | 先验证同步参数签名，或使用与当前用户会话绑定的服务端订单标识；再通过服务端查询或已验签通知状态展示最终支付结果 | 同步回跳参数不得直接改写订单或作为支付成功依据，不得使用可任意修改的订单号访问其他订单 |
-| 网站支付关闭同步回跳 | 仅当用户已明确关闭时适用；SDK 请求未传 `return_url` | 必须保留异步通知、交易查询和商户订单查询页，且沙箱提示不得声称付款后会自动返回商户网站 |
+| 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 按量付费专项校验
 
 | 校验项 | 校验要求 | 说明 |
 |----------|----------|----------|
@@ -74,12 +80,15 @@
 | 金额一致性 | 必须校验本地订单金额与 `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 -->
 ## 六、退款校验
 
 | 校验项 | 校验要求 | 说明 |
@@ -90,16 +99,17 @@
 
 ---
 
+<!-- ALIPAY_AIPAY_CHECKLIST_PRODUCTS:aipay,webpay,apppay -->
 ## 七、上线前校验
 
 | 校验项 | 校验要求 | 说明 |
 |----------|----------|----------|
-| 网关地址切换 | 切换为生产网关 `https://openapi.alipay.com/gateway.do`|  上线前必须修改 |
+| 网关地址切换 | 五语言 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。格式不匹配时使用支付宝开放平台密钥工具转换 |
-| 按量付费 serviceId 替换 | 生产配置中不得保留 `api_mock_service_id` | 上线前替换为服务市场实际返回的真实 `serviceId` |
+| AI 按量付费 serviceId 替换 | 生产配置中不得保留 `api_mock_service_id` | 上线前替换为服务市场实际返回的真实 `serviceId` |
 | 证书切换 | 公钥证书模式需切换为生产环境证书 | 应用公钥证书、支付宝公钥证书、支付宝根证书 |
 | 产品开通状态 | 确认产品已在生产环境开通 | 沙箱无需开通，生产环境需要申请开通 |
 | 私钥安全 | 私钥不在代码、日志、公共仓库中明文存储 | 使用安全的方式管理私钥 |
@@ -108,7 +118,8 @@
 
 ---
 
-## 八、集成结果输出模板
+<!-- ALIPAY_AIPAY_CHECKLIST_PRODUCTS:aipay,webpay,apppay -->
+## 八、代码开发结果输出
 
 > 内部逐项判断使用以下状态：
 > - ✅ 通过：已实现且符合规范
@@ -117,35 +128,46 @@
 > - ➖ 不适用：当前集成场景不涉及此项
 > - 🟡 人工待验证：当前环境无法自动取得充分证据
 
-默认对客输出不重复罗列每个通过或不适用项，但必须保留所有适用项的检查结论和依据。用户要求完整明细时，再输出逐项表格。
+先按当前实际证据完成内部逐项判断。本轮范围内仍可直接修复代码或配置时，先修复并重检，不渲染中间结果；只有已通过、只剩人工待验证，或本轮无法继续修复时，才使用 `../../normal/json/customer-messages.json` 的 `integration.checklist.result` 按产品选择 `AIPAY`、`WEBPAY` 或 `APPPAY`，并传入最终一轮实际整体结论、不通过/部分通过项和人工待验证项。renderer 会按结果自动选择精简的通过或未完成模板。必须从本文档所在目录执行：
 
-集成校验结论必须与沙箱测试结论分开：沙箱配置字段完整、配置后置校验通过、网站支付付款指引已提供或 APP支付不适用步骤 5，都不得表述为“沙箱测试通过”或“沙箱环境测试通过”。只有按量付费步骤 5 已自动完成 402 Payment-Needed、沙箱收银、Payment-Proof 重试和资源交付全链路并取得成功证据时，才可在本摘要中复用“按量付费沙箱测试通过”的结论。
+Unix/macOS/Linux 的 `sandboxConfigState` 必须复用 integration flow 的固定脚本终态。Windows 必须复用步骤 1/3 记录的 `READY|VERIFY_PENDING`。待配置时不在本步骤重跑创建或复核，不读取当前配置，把配置后置校验、摘要和适用沙箱测试列入未完成；若代码实现与其他安全检查均通过，整体结果为“部分通过”，否则按其他缺口判为“未通过”。
 
-涉及网站支付或 APP支付 时，校验结论还必须显式区分：
-- “本地正式验收完成 / 本地生产参数验收完成，公网异步通知待补齐”
-- “真实生产上线条件已满足”
+```bash
+printf '%s' "$CHECKLIST_RESULT_JSON" \
+  | node ../../normal/scripts/integration_message_runner.mjs checklist-result --variant <AIPAY|WEBPAY|APPPAY> --project-path "$PROJECT_PATH" --scope-receipt "$CHECKLIST_SCOPE_RECEIPT"
+```
 
-未完成公网 HTTPS `notify_url` 联调时，禁止把第一种表述写成第二种。
+上方 stdin 命令保持用于 Unix/macOS/Linux。Windows 不使用管道或续行符，按当前产品执行对应 PowerShell 单行命令：
 
-### 一、校验结论
-[校验结果整体结论，输出校验结果和风险情况]
----
+```powershell
+node ../../normal/scripts/integration_message_runner.mjs checklist-result --variant AIPAY --project-path "$PROJECT_PATH" --scope-receipt "$CHECKLIST_SCOPE_RECEIPT" --overall-result "$OVERALL_RESULT" --failed-items "$FAILED_ITEMS" --manual-items "$MANUAL_ITEMS" --sandbox-result "$SANDBOX_RESULT" --sandbox-config-state "$SANDBOX_CONFIG_STATE" --blocking-defect-state "$BLOCKING_DEFECT_STATE" --execution-mode "$EXECUTION_MODE" --next-flow-reminder "$NEXT_FLOW_REMINDER"
+node ../../normal/scripts/integration_message_runner.mjs checklist-result --variant WEBPAY --project-path "$PROJECT_PATH" --scope-receipt "$CHECKLIST_SCOPE_RECEIPT" --overall-result "$OVERALL_RESULT" --failed-items "$FAILED_ITEMS" --manual-items "$MANUAL_ITEMS" --webpay-experience-result "$WEBPAY_EXPERIENCE_RESULT" --sandbox-config-state "$SANDBOX_CONFIG_STATE" --blocking-defect-state "$BLOCKING_DEFECT_STATE" --execution-mode "$EXECUTION_MODE" --next-flow-reminder "$NEXT_FLOW_REMINDER"
+node ../../normal/scripts/integration_message_runner.mjs checklist-result --variant APPPAY --project-path "$PROJECT_PATH" --scope-receipt "$CHECKLIST_SCOPE_RECEIPT" --overall-result "$OVERALL_RESULT" --failed-items "$FAILED_ITEMS" --manual-items "$MANUAL_ITEMS" --sandbox-config-state "$SANDBOX_CONFIG_STATE" --blocking-defect-state "$BLOCKING_DEFECT_STATE" --execution-mode "$EXECUTION_MODE" --next-flow-reminder "$NEXT_FLOW_REMINDER"
+```
 
-### 二、通过摘要
+只有 `AIPAY` 传入独立 `sandboxResult`；`WEBPAY` 必须按步骤 6 的实际证据传入消息目录登记的 `webpayExperienceResult` 枚举。禁止跨产品传入其他产品结论。这些字段只用于校验代码开发总结果与实际沙箱事实一致，不在最终精简消息中重复展示。内部必须保留所有适用项的检查结论和依据；用户要求完整明细时，再从实际证据输出逐项表格，不维护第二份固定模板。
 
-[列出已完成检查的类别及通过情况，不逐行重复通过项。]
+三个产品的内部结论校验差异如下，具体对客文本只在消息目录维护：
 
-### 三、需要处理的项目
+| 产品 | checklist 内部校验事实 | 实际待办来源 |
+|---|---|---|
+| `AIPAY` | 代码开发通过必须绑定本轮 AI 按量付费沙箱服务端联调通过 | checklist 失败/部分通过项、人工待验证项和联调恢复动作 |
+| `WEBPAY` | 未提供浏览器付款入口或完整指引时不得标记代码开发通过 | checklist 失败/部分通过项、人工待验证项和待用户体验事项 |
+| `APPPAY` | 当前没有沙箱付款验证结论，不据此生成通过或失败事实 | checklist 失败/部分通过项和人工待验证项 |
 
-| 校验项 | 状态 | 问题或缺少的证据 | 下一步 |
-|------|------|------|------|
-| 仅列出不通过、部分通过和人工待验证项 | | | |
+`APPPAY` 变体在 `customer-messages.json` 保留不渲染的维护 TODO。后续确定 AI 移动应用收款沙箱测试动作时，只修改该变体仍不够，必须同步 integration flow、本文适用校验项和自动化测试；在此之前 Agent 禁止临场补充沙箱付款步骤。
 
----
+代码开发校验结论必须与沙箱测试结论分开：沙箱配置字段完整、配置后置校验通过、AI 网页应用收款付款指引已提供或 AI 移动应用收款不适用步骤 6，都不得表述为“沙箱测试通过”或“沙箱环境测试通过”。只有 AI 按量付费步骤 6 已自动完成 402 Payment-Needed、沙箱收银、Payment-Proof 重试和资源交付全链路并取得成功证据时，才可在本摘要中复用“AI 按量付费沙箱测试通过”的结论。
+
+涉及 AI 网页应用收款或 AI 移动应用收款时，校验结论还必须显式区分：
+- “本地正式验收完成 / 本地生产参数验收完成，公网异步通知待补齐”
+- “真实生产上线条件已满足”
+
+未完成公网 HTTPS `notify_url` 联调时，禁止把第一种表述写成第二种。
 
-### 四、风险说明
+`failedItems` 与 `manualItems` 必须在各自受控单行值中包含对应的确定下一步；没有对应项目时明确传入“无”。`overallResult=通过` 时两者必须都是“无”、`sandboxConfigState=READY` 且 `blockingDefectState=NONE`；“部分通过”必须至少存在一类缺口；“未通过”必须列出未通过项。`blockingDefectState` 只表示除沙箱配置及其直接依赖动作之外，是否存在代码、安全或必要依据缺口；当前环境无法自动取得 UI、浏览器或公网联调证据但代码与安全依据已完成时，只登记 `manualItems`，不把该人工待验证项自动计为 `PRESENT`。待配置时恢复口令由 renderer 固定生成。`full_process` 在待配置且无其他阻塞缺口，或 `READY` 且仅剩非阻塞人工待验证项时，输出“部分通过”并继续产品开通；其他未通过组合保持停留提醒。
 
-[未通过校验项（❌不通过、⚠️部分通过）的风险说明，需要提醒用户发布前完成整改或确认风险可接受。]
+同一次代码开发只渲染一次最终结果；renderer stdout 是默认收口的唯一对客正文，禁止在前后追加通过摘要、风险说明、产品开通提醒或第二份待办。
 
 ---
 

package/skill/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`。

package/skill/references/integration/modules/code-examples/csharp/2-/347/275/221/347/253/231/346/224/257/344/273/230//347/273/237/344/270/200/346/224/266/345/215/225/344/270/213/345/215/225/345/271/266/346/224/257/344/273/230/351/241/265/351/235/242/346/216/245/345/217/243/344/273/243/347/240/201/347/244/272/344/276/213.md

@@ -12,7 +12,11 @@ using Aop.Api.Domain;
 IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig());
 
 var request = new AlipayTradePagePayRequest();
-request.SetNotifyUrl("https://your-domain.com/notify");  // 真实生产或公网联调时传入；本地生产参数验收模式可临时不传，但仍需实现通知处理代码
+var notifyUrl = Environment.GetEnvironmentVariable("ALIPAY_NOTIFY_URL");
+if (!string.IsNullOrWhiteSpace(notifyUrl))
+{
+    request.SetNotifyUrl(notifyUrl.Trim());  // 真实生产或公网联调时传入；本地没有公网 HTTPS notify_url 时不要传 null、空字符串或占位 URL
+}
 request.SetReturnUrl("https://your-domain.com/return");  // 默认传入并替换为已验证结果页；仅用户明确关闭同步回跳时省略
 
 var model = new AlipayTradePagePayModel
@@ -24,11 +28,11 @@ var model = new AlipayTradePagePayModel
 };
 request.SetBizModel(model);
 
-// ⚠️ 网站支付必须使用 pageExecute()，不能使用 Execute()
+// ⚠️ 网站支付必须使用 PageExecute()，不能使用 Execute()
 // ⚠️ 第二个参数传 null（accessToken），第三个参数 "POST" 表示生成 POST 表单
-AlipayTradePagePayResponse response = alipayClient.pageExecute(request, null, "POST");
+AlipayTradePagePayResponse response = alipayClient.PageExecute(request, null, "POST");
 string formHtml = response.Body;
-// pageExecute 返回的是 HTML 表单字符串，前端需要渲染并自动提交
+// PageExecute 返回的是 HTML 表单字符串，前端需要渲染并自动提交
 
 private static AlipayConfig GetAlipayConfig()
 {

package/skill/references/integration/modules/code-examples/csharp/3-APP/346/224/257/344/273/230/APP/346/224/257/344/273/230/346/216/245/345/217/243/344/273/243/347/240/201/347/244/272/344/276/213.md

@@ -1,4 +1,4 @@
-# APP支付接口 - C# 示例
+# APP 支付接口 - C# 示例
 
 ## 请求示例
 
@@ -20,6 +20,11 @@ namespace SdkDemoTest
             IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig());
             // 构造请求参数以调用接口
             AlipayTradeAppPayRequest request = new AlipayTradeAppPayRequest();
+            var notifyUrl = Environment.GetEnvironmentVariable("ALIPAY_NOTIFY_URL");
+            if (!string.IsNullOrWhiteSpace(notifyUrl))
+            {
+                request.SetNotifyUrl(notifyUrl.Trim());  // 真实生产或公网联调时传入；本地没有公网 HTTPS notify_url 时不要传 null、空字符串或占位 URL
+            }
             AlipayTradeAppPayModel model = new AlipayTradeAppPayModel();
             
             // 设置商户订单号
@@ -125,4 +130,3 @@ namespace SdkDemoTest
 ```
 app_id=20190xxxxxx&biz_content=%7B%22time_expire%22%3A%222016-12-31+10%3A05%3A00%22%2C%22extend_params%22%3A%22%22%2C%22query_options%22%3A%22%5B%5C%22hyb_amount%5C%22%2C%5C%22enterprise_pay_info%5C%22%5D%22%2C%22subject%22%3A%22%E5%A4%A7%E4%B9%90%E9%80%8F%22%2C%22product_code%22%3A%22QUICK_MSECURITY_PAY%22%2C%22body%22%3A%22Iphone6+16G%22%2C%22passback_params%22%3A%22merchantBizType%253d3C%2526merchantBizNo%253dMERCHANT_BIZ_NO_PLACEHOLDER%22%2C%22specified_channel%22%3A%22pcredit%22%2C%22goods_detail%22%3A%22%22%2C%22merchant_order_no%22%3A%22MERCHANT_ORDER_NO_PLACEHOLDER%22%2C%22enable_pay_channels%22%3A%22pcredit%2CmoneyFund%2CdebitCardExpress%22%2C%22out_trade_no%22%3A%22MERCHANT_ORDER_NO_PLACEHOLDER%22%2C%22ext_user_info%22%3A%22%22%2C%22total_amount%22%3A%229.00%22%2C%22timeout_express%22%3A%2290m%22%2C%22disable_pay_channels%22%3A%22pcredit%2CmoneyFund%2CdebitCardExpress%22%2C%22agreement_sign_params%22%3A%22%22%7D&charset=UTF-8&format=json&method=alipay.trade.app.pay&sign=SIGN_PLACEHOLDER&sign_type=RSA2&timestamp=2014-07-24+03%3A07%3A50&version=1.0
 ```
-

package/skill/references/integration/modules/code-examples/csharp/4-/346/214/211/351/207/217/344/273/230/350/264/271/A2MPaymentDemo.cs

@@ -40,7 +40,9 @@ namespace A2MPaymentDemo
         // ==================== 配置信息（实际使用时请从配置中心读取）====================
         private static readonly AlipayConfig AlipayConfig = new AlipayConfig
         {
-            ServerUrl = "https://openapi.alipay.com/gateway.do",
+            // 默认用于本 Skill 的快速沙箱联调；生产部署时设置 ALIPAY_GATEWAY=https://openapi.alipay.com/gateway.do
+            ServerUrl = Environment.GetEnvironmentVariable("ALIPAY_GATEWAY")
+                ?? "https://openapi-sandbox.dl.alipaydev.com/gateway.do",
             AppId = "<APP_ID>",
             PrivateKey = "<APP_PRIVATE_KEY>", // 请填写您的应用私钥（PKCS#1 格式）
             AlipayPublicKey = "<ALIPAY_PUBLIC_KEY>", // 请填写您的支付宝公钥