@alipay/alipay-aipay 1.2.2 → 1.4.9

package/skill/references/integration/modules/interface-contract/aipay-interface-contract.md

@@ -0,0 +1,53 @@
+# 按量付费本地接口契约
+
+本文是按量付费代码开发的默认本地依据。在线文档只在本地契约或示例缺失、字段不确定、排查官方错误码、用户明确要求或官方能力变化时作为 fallback 读取。
+
+sourceUrl:
+
+- <https://aipay.alipay.com/docs/ai-receive/MACHINE_PAY.md>
+- <https://aipay.alipay.com/docs/ai-receive/api-list/alipay-aipay-agent-payment-verify.md>
+- <https://aipay.alipay.com/docs/ai-receive/api-list/alipay-aipay-agent-fulfillment-confirm.md>
+
+## 默认范围
+
+按量付费只实现 HTTP 402、`Payment-Needed`、`Payment-Proof`、`alipay.aipay.agent.payment.verify` 和 `alipay.aipay.agent.fulfillment.confirm`。不得混入网站支付或 APP 支付的统一收单接口、异步通知或 `notify_url`。
+
+## 402 与账单
+
+无有效 `Payment-Proof` 时，商家服务端返回 HTTP 402，并在 `Payment-Needed` Header 中返回 Base64URL 编码账单。响应体只用于调试，智能体支付依据是 Header。
+
+`Payment-Needed.protocol` 必须包含：`out_trade_no`、`amount`、`currency=CNY`、`resource_id`、`pay_before`、`seller_signature`、`seller_sign_type=RSA2`、`seller_unique_id`。
+
+`Payment-Needed.method` 必须包含：`seller_name`、`seller_id`、`seller_app_id`、`goods_name`、`seller_unique_id_key=seller_id`、`service_id`。
+
+沙箱 `service_id` 固定为 `api_mock_service_id`；生产环境替换为服务市场真实 `serviceId`，不得向用户索要正式 `serviceId` 来完成沙箱联调。
+
+商家账单签名字段按 key 字典序拼接：`amount`、`currency`、`goods_name`、`out_trade_no`、`pay_before`、`resource_id`、`seller_id`、`service_id`。签名只在商家本地完成，不请求支付宝服务端。
+
+## Payment-Proof 验付
+
+`Payment-Proof` 解码后至少读取：
+
+| 字段 | 来源 |
+| --- | --- |
+| `payment_proof` | `protocol.payment_proof` |
+| `trade_no` | `protocol.trade_no` |
+| `client_session` | `method.client_session`，可选 |
+
+调用 `alipay.aipay.agent.payment.verify` 的业务入参为 `trade_no`、`payment_proof` 和可选 `client_session`。
+
+验付成功不能只看 SDK 调用成功，还必须同时校验：
+
+- `active=true`。
+- 返回 `amount` 等于本地订单金额。
+- 返回 `out_trade_no` 等于本地订单号。
+- 返回 `resource_id` 等于当前请求资源。
+- `trade_no` 未被重复履约。
+- 本地订单未过期、未取消、未完成。
+
+任一校验失败时返回 402，让智能体重新支付；不得返回资源。
+
+## 履约确认
+
+资源生成后调用 `alipay.aipay.agent.fulfillment.confirm`，业务入参只有 `trade_no`。必须在履约确认成功后再把订单标记为最终完成。确认失败时允许同一 `Payment-Proof` 重试确认，避免资源已生成但平台未记录履约。
+

package/skill/references/integration/modules/interface-contract/apppay-interface-contract.md

@@ -0,0 +1,45 @@
+# APP 支付本地接口契约
+
+本文是 APP 支付服务端下单接口的默认本地依据。在线文档只在本地契约或示例缺失、字段不确定、排查官方错误码、用户明确要求或官方能力变化时作为 fallback 读取。
+
+sourceUrl:
+
+- <https://aipay.alipay.com/docs/mobile-app-pay/app-pay-integration-guide-new.md>
+- <https://aipay.alipay.com/docs/mobile-app-pay/ai-app-pay/alipay-trade-app-pay.md>
+- <https://aipay.alipay.com/docs/mobile-app-pay/ai-app-pay/sync-result.md>
+
+## 默认范围
+
+APP 支付必须覆盖：`alipay.trade.app.pay`、交易查询、退款、退款查询、关闭交易、异步通知和服务端订单查询链路。
+
+查询、退款、退款查询、关闭交易读取 `common-trade-contract.md`；异步通知读取 `notify-url-contract.md`。
+
+本 Skill 默认只改商家服务端，不替用户实现 APP 客户端 SDK。HarmonyOS APP 支付代码开发仍可覆盖服务端能力；平台侧移动应用创建边界以 onboarding 应用发布模块为准。
+
+官方目录中的 `alipay.data.dataservice.bill.downloadurl.query` 不是当前 Skill 默认交付项。用户明确要求对账时再按在线文档 fallback 处理，不能加入默认 checklist。
+
+## 下单接口
+
+`alipay.trade.app.pay` 用于商家服务端生成 `orderStr`，由商家 APP 客户端接入支付宝客户端 SDK 后调起支付。
+
+公共参数：
+
+| 字段 | 要求 |
+| --- | --- |
+| `method` | 固定 `alipay.trade.app.pay` |
+| `notify_url` | 生产或公网联调时传入；本地生产参数验收模式可临时不传，但通知处理代码必须存在 |
+
+业务参数：
+
+| 字段 | 要求 |
+| --- | --- |
+| `out_trade_no` | 必填，商户订单号，商户侧唯一 |
+| `total_amount` | 必填，单位元，精确到小数点后两位，不能为 0 |
+| `subject` | 必填，订单标题 |
+| `product_code` | 必填，当前默认固定 `QUICK_MSECURITY_PAY` |
+
+## 响应与结果
+
+- 服务端返回 `orderStr` 给 APP 客户端。
+- APP 客户端同步返回的 `resultStatus=9000` 可作为支付结束通知；为简化默认集成，实际支付是否成功仍以服务端异步通知或 `alipay.trade.query` 为准。
+- `resultStatus=8000` 或 `6004` 表示结果未知，必须查询商家订单或调用 `alipay.trade.query`，不能要求用户重复付款。

package/skill/references/integration/modules/interface-contract/common-trade-contract.md

@@ -0,0 +1,42 @@
+# 统一收单通用本地契约
+
+本文适用于网站支付和 APP 支付。按量付费不使用统一收单通用接口。
+
+sourceUrl:
+
+- <https://aipay.alipay.com/docs/ai-web-app-payment-qianyi/api-list/alipay-trade-query.md>
+- <https://aipay.alipay.com/docs/ai-web-app-payment-qianyi/api-list/alipay-trade-refund.md>
+- <https://aipay.alipay.com/docs/ai-web-app-payment-qianyi/api-list/alipay-trade-fastpay-refund-query.md>
+- <https://aipay.alipay.com/docs/ai-web-app-payment-qianyi/api-list/alipay-trade-close.md>
+- <https://aipay.alipay.com/docs/mobile-app-pay/ai-app-pay/alipay-trade-query.md>
+- <https://aipay.alipay.com/docs/mobile-app-pay/ai-app-pay/alipay-trade-refund.md>
+- <https://aipay.alipay.com/docs/mobile-app-pay/ai-app-pay/alipay-trade-fastpay-refund-query.md>
+- <https://aipay.alipay.com/docs/mobile-app-pay/ai-app-pay/alipay-trade-close.md>
+
+网页应用付款和移动应用收款的查询、退款、退款查询、关闭文档当前内容一致，本 Skill 本地维护一份通用契约。
+
+## 交易查询
+
+接口：`alipay.trade.query`
+
+`out_trade_no` 和 `trade_no` 二选一；同时存在时优先 `trade_no`。常见触发时机：未收到异步通知、支付接口返回系统错误或未知状态、用户可能已支付但本地订单状态未知、关闭或重新下单前确认上一笔订单结果。
+
+支付成功只认 `TRADE_SUCCESS` 或 `TRADE_FINISHED`。`WAIT_BUYER_PAY` 不得判定成功；重新下单前应先关闭未支付订单。
+
+## 退款
+
+接口：`alipay.trade.refund`
+
+`refund_amount` 必填；`out_trade_no` 和 `trade_no` 二选一。部分退款或异常重试必须保持同一 `out_request_no`，防止重复退款。接口返回 `code=10000` 只代表退款请求受理成功；只有 `fund_change=Y` 才通常表示发生退款资金变化，`fund_change=N` 或缺失时必须通过退款查询确认。
+
+## 退款查询
+
+接口：`alipay.trade.fastpay.refund.query`
+
+`out_request_no` 必填；`out_trade_no` 和 `trade_no` 二选一。退款查询发起时间不能离退款请求太短，建议至少间隔 10 秒。只有 `refund_status=REFUND_SUCCESS` 表示退款成功。
+
+## 关闭交易
+
+接口：`alipay.trade.close`
+
+用于关闭未付款交易。`out_trade_no` 和 `trade_no` 二选一；两者同时存在时优先 `trade_no`。关闭成功后该交易不可继续支付。不得主动发起真实生产关单，除非用户明确要求并确认目标交易。

package/skill/references/integration/modules/interface-contract/notify-url-contract.md

@@ -0,0 +1,68 @@
+# 异步通知本地契约
+
+本文是网站支付和 APP 支付共用的异步通知实现依据。按量付费不使用本契约。在线文档只在本地契约或示例缺失、字段不确定、排查官方错误码、用户明确要求或官方能力变化时作为 fallback 读取。
+
+sourceUrl:
+
+- <https://aipay.alipay.com/docs/ai-web-app-payment-qianyi/api-list/async-notify-verify.md>
+- <https://aipay.alipay.com/docs/mobile-app-pay/ai-app-pay/async-notify-verify.md>
+
+当前两份官方文档内容一致。运行时默认读取本文和当前语言 `1-通用接口/异步通知处理代码示例.md`；在线文档只在 fallback 条件下读取。
+
+## 适用范围
+
+| 产品 | 是否适用 | 说明 |
+| --- | --- | --- |
+| 网站支付 | 是 | `alipay.trade.page.pay` 下单时通过公共参数 `notify_url` 指定 |
+| APP 支付 | 是 | `alipay.trade.app.pay` 下单时通过公共参数 `notify_url` 指定 |
+| 按量付费 | 否 | 使用 `Payment-Proof` 验付和履约确认，不使用统一收单异步通知 |
+
+`notify_url` 是商家服务端接收支付宝 POST 表单通知的地址，不是前端页面地址，也不是支付宝生成的 URL。
+
+本地正式验收或本地生产参数验收时，若暂时没有公网 HTTPS 通知地址，可以不传 `notify_url`，但仍必须实现通知处理代码并用交易查询兜底。不要向 SDK 传 `undefined`、`null`、空字符串或占位 URL；没有可用地址时应直接省略该字段或不调用对应 setter。真实生产或公网联调时必须传入可公网访问的 HTTPS `notify_url`，地址不能包含多余字符或发生重定向。
+
+## 必须实现的处理链路
+
+1. 接收支付宝 POST 表单参数，不能按 JSON 请求体解析。
+2. 收集完整参数 map，验签前不得丢字段、改字段名或改字段值。
+3. 用通知中的 `app_id` 在本地选择运行时支付配置和验签上下文；这是为了选择本地支付宝公钥或 SDK 实例，不表示信任通知内容。
+4. 使用当前项目已安装的支付宝 SDK 验签能力验证 `sign`；Java 官方示例为 `AlipaySignature.rsaCheckV1`。
+5. 验签失败时记录脱敏异常并返回纯文本 `fail`。
+6. 验签通过后，用 `out_trade_no` 查询商家本地订单，并校验 `app_id`、`out_trade_no`、`total_amount`、`seller_id` 或 `seller_email`。
+7. `app_id`、`seller_id` / `seller_email` 以运行时支付配置为准，不默认从订单对象或通知参数本身取可信预期值。
+8. 只有 `TRADE_SUCCESS` 或 `TRADE_FINISHED`，且不是退款、关单、分账等事件时，才认定买家付款成功；至少排除 `out_biz_no`、`gmt_refund`、`refund_fee` 等事件特征。
+9. 使用持久化订单状态、`notify_id`、`out_trade_no`、`trade_no` 和事件类型做幂等处理，避免重复发货、重复记账或重复变更。内存订单、内存 Map 或进程内锁只能用于非生产 demo。
+10. 业务处理成功后返回纯文本 `success`；不是 `success` 时支付宝会按策略重试。
+11. 未收到通知或支付状态未知时，必须调用 `alipay.trade.query` 补偿查询。
+
+默认至少处理参数：`notify_type`、`notify_id`、`sign_type`、`sign`、`trade_no`、`app_id`、`out_trade_no`、`trade_status`、`total_amount`、`seller_id` 或 `seller_email`。退款或其他事件可能出现 `out_biz_no`、`gmt_refund`、`refund_fee`，不能误判为付款成功。
+
+## 状态处理
+
+| `trade_status` | 默认处理 |
+| --- | --- |
+| `TRADE_SUCCESS` | 买家付款成功；同时确认不是退款、关单、分账等事件后，幂等标记本地订单已支付 |
+| `TRADE_FINISHED` | 交易结束且付款成功；同时确认不是退款、关单、分账等事件后，幂等标记本地订单已支付 |
+| `WAIT_BUYER_PAY` | 不认定付款成功；记录或忽略，必要时等待查询 |
+| `TRADE_CLOSED` | 不认定付款成功；可记录关闭或退款完成事件 |
+
+退款通知、关闭通知、分账通知等不是付款成功通知。通知本身验签和业务归属校验通过后，可以返回 `success` 避免重复推送，但不得把本地订单改成已支付。支付成功通知至少满足付款成功状态且不包含 `out_biz_no`；退款通知通常包含 `gmt_refund`、`refund_fee`、`out_biz_no`。
+
+## 验收分层
+
+- 本地正式验收 / 本地生产参数验收模式：允许暂时没有公网 HTTPS `notify_url`，但通知处理代码、验签、业务字段校验、持久化幂等和主动查询兜底必须存在；公网通知联调标记为人工待验证。没有可用通知地址时省略 `notify_url`，不要向 SDK 传 `undefined`、`null`、空字符串或占位 URL。
+- 真实生产上线：必须配置公网 HTTPS `notify_url`，完成支付宝服务器可访问联调、验签、关键字段校验、幂等处理、返回 `success` 和补偿查询。
+
+没有完成真实生产上线层时，不得表述为生产就绪或正式上线完成。
+
+## 本地示例索引
+
+| 语言 | 示例 |
+| --- | --- |
+| Java | `code-examples/java/1-通用接口/异步通知处理代码示例.md` |
+| Python | `code-examples/python/1-通用接口/异步通知处理代码示例.md` |
+| Node.js | `code-examples/nodejs/1-通用接口/异步通知处理代码示例.md` |
+| PHP | `code-examples/php/1-通用接口/异步通知处理代码示例.md` |
+| C# | `code-examples/csharp/1-通用接口/异步通知处理代码示例.md` |
+
+Java 官方示例明确使用 `AlipaySignature.rsaCheckV1`。Node.js 示例给出 `checkNotifySignV2(params)` 的落地形态，但 Agent 落地前必须先读取目标项目 `alipay-sdk` 的 package.json 和类型定义，确认当前版本确实暴露该 API。Python、PHP、C# 示例使用项目内支付宝 SDK 验签适配器表示验签边界；适配器必须封装当前项目实际 SDK API，禁止临时手写不确定的 RSA 验签实现。

package/skill/references/integration/modules/interface-contract/webpay-interface-contract.md

@@ -0,0 +1,44 @@
+# 网站支付本地接口契约
+
+本文是网站支付专用下单接口的默认本地依据。在线文档只在本地契约或示例缺失、字段不确定、排查官方错误码、用户明确要求或官方能力变化时作为 fallback 读取。
+
+sourceUrl:
+
+- <https://aipay.alipay.com/docs/ai-web-app-payment-qianyi/ai-web-app-payment-integration-guide.md>
+- <https://aipay.alipay.com/docs/ai-web-app-payment-qianyi/api-list/alipay-trade-page-pay.md>
+
+## 默认范围
+
+网站支付必须覆盖：`alipay.trade.page.pay`、交易查询、退款、退款查询、关闭交易、异步通知和默认同步回跳结果页。
+
+查询、退款、退款查询、关闭交易读取 `common-trade-contract.md`；异步通知读取 `notify-url-contract.md`。
+
+官方目录中的 `alipay.data.dataservice.bill.downloadurl.query` 不是当前 Skill 默认交付项。用户明确要求对账时再按在线文档 fallback 处理，不能加入默认 checklist。
+
+## 下单接口
+
+`alipay.trade.page.pay` 是网站支付唯一默认下单接口，电脑网页、手机浏览器网页和 H5 场景均使用该接口，不改用其他网页支付产品接口。
+
+公共参数：
+
+| 字段 | 要求 |
+| --- | --- |
+| `method` | 固定 `alipay.trade.page.pay` |
+| `notify_url` | 生产或公网联调时传入；本地生产参数验收模式可临时不传，但通知处理代码必须存在 |
+| `return_url` | 用户未明确关闭同步回跳时默认传入，且对应当前项目实际 GET 路由 |
+
+业务参数：
+
+| 字段 | 要求 |
+| --- | --- |
+| `out_trade_no` | 必填，商户订单号，商户侧唯一 |
+| `total_amount` | 必填，单位元，精确到小数点后两位，范围 `[0.01,100000000]` |
+| `subject` | 必填，订单标题 |
+| `product_code` | 必填且固定 `FAST_INSTANT_TRADE_PAY` |
+
+## 响应与结果
+
+- 必须使用页面跳转方法：Java `pageExecute`、Python `page_execute`、PHP `pageExecute`、Node.js `pageExec`、C# `PageExecute`。
+- 推荐 POST 方式，响应为 HTML form 或同等页面跳转内容，必须在浏览器渲染并提交。
+- `curl` 获取到 HTML form 只能证明接口有响应，不能替代浏览器付款入口和沙箱付款体验。
+- `return_url` 或前台页面只作支付结束通知，不能作为付款成功依据；付款成功以验签通过的异步通知或交易查询为准。

package/skill/references/integration/modules/interface-guide.md

@@ -1,94 +1,59 @@
 # 接口说明与代码示例索引
 
-本文件汇总了支付宝支付产品的通用接口和产品专用接口的参考文档及代码示例索引，供主 Skill 集成参考。**本 Skill 仅支持按量付费、网站支付、APP支付三种产品**。
+本文件只做本地接口契约和代码示例路由。正常代码开发默认读取本地契约与当前语言示例；在线文档只作为 `sourceUrl` 和 fallback，不作为默认运行时必读材料。
 
----
+本文中的 `./code-examples/...` 路径一律相对本文件所在目录 `references/integration/modules/` 解析。从 `references/integration/flow.md` 所在目录读取示例时，实际路径必须写成 `modules/code-examples/...`；例如 Node.js 按量付费示例是 `modules/code-examples/nodejs/4-按量付费/A2MPaymentDemo.js`。禁止查找不存在的 `references/integration/code-examples/...`。
 
-## 一、通用接口
+## 默认读取路由
 
-下表所列接口适用于网站支付和APP支付产品，请结合用户集成诉求按需查阅。**按量付费产品不使用这些通用接口**。
-
-### 通用接口文档索引
+| 产品 | 必读本地契约 | 必读示例 |
+| --- | --- | --- |
+| 按量付费 | `interface-contract/aipay-interface-contract.md` | 当前语言 `4-按量付费/` 示例 |
+| 网站支付 | `interface-contract/webpay-interface-contract.md`、`interface-contract/common-trade-contract.md`、`interface-contract/notify-url-contract.md` | 当前语言 `2-网站支付/` 和 `1-通用接口/` 示例 |
+| APP 支付 | `interface-contract/apppay-interface-contract.md`、`interface-contract/common-trade-contract.md`、`interface-contract/notify-url-contract.md` | 当前语言 `3-APP支付/` 和 `1-通用接口/` 示例 |
 
-| 接口名称 | 文档链接 |
-| --- | --- |
-| 统一收单交易查询接口 | <https://ideservice.alipay.com/cms/site/0izblf> |
-| 统一收单交易退款接口 | <https://ideservice.alipay.com/cms/site/0izam4> |
-| 统一收单交易退款查询接口 | <https://ideservice.alipay.com/cms/site/0izl48> |
-| 统一收单交易关闭接口 | <https://ideservice.alipay.com/cms/site/0izcu8> |
-| 异步通知说明 | <https://ideservice.alipay.com/cms/site/0izal6> |
+fallback 仅在本地契约或示例缺失、字段不确定、排查官方错误码、用户明确要求或官方能力变化时触发。触发后只读取当前产品和当前接口直接相关页面，不递归抓取无关文档。
 
-### 通用接口代码示例索引
+## 代码示例路径
 
-各接口的代码示例按编程语言拆分，存放于各语言目录的 `1-通用接口/` 子目录下。请根据用户实际使用的编程语言查找所需接口的示例代码，**不要混用不同语言**。
+语言目录固定为：`java`、`python`、`nodejs`、`php`、`csharp`。选择当前项目服务端语言对应目录，禁止混用不同语言。
 
-> **⚠️ 按量付费产品不涉及这些通用接口**，按量付费使用专属的 A2M 接口进行支付。
+### 按量付费
 
-表格中某语言列为空，表示该语言暂无对应接口的示例文档。此时请依据上述通用接口文档中的**公共请求参数**、**业务请求参数**及**响应参数**，获取字段名、类型、是否必填及取值规则，按照当前编程语言规范自行完成实现。
+| 语言 | 示例 |
+| --- | --- |
+| Java | `./code-examples/java/4-按量付费/A2MPaymentDemoController.java` |
+| Python | `./code-examples/python/4-按量付费/A2MPaymentDemo.py` |
+| Node.js | `./code-examples/nodejs/4-按量付费/A2MPaymentDemo.js` |
+| PHP | `./code-examples/php/4-按量付费/A2MPaymentDemo.php` |
+| C# | `./code-examples/csharp/4-按量付费/A2MPaymentDemo.cs` |
 
-| 接口名称 | Java | Python | Node.js | PHP | C# |
-| --- | --- | --- | --- | --- | --- |
-| 统一收单交易查询接口 | [示例](./code-examples/java/1-通用接口/统一收单交易查询接口代码示例.md) | [示例](./code-examples/python/1-通用接口/统一收单交易查询接口代码示例.md) | [示例](./code-examples/nodejs/1-通用接口/统一收单交易查询接口代码示例.md) | [示例](./code-examples/php/1-通用接口/统一收单交易查询接口代码示例.md) | [示例](./code-examples/csharp/1-通用接口/统一收单交易查询接口代码示例.md) |
-| 统一收单交易退款接口 | [示例](./code-examples/java/1-通用接口/统一收单交易退款接口代码示例.md) | [示例](./code-examples/python/1-通用接口/统一收单交易退款接口代码示例.md) | [示例](./code-examples/nodejs/1-通用接口/统一收单交易退款接口代码示例.md) | [示例](./code-examples/php/1-通用接口/统一收单交易退款接口代码示例.md) | [示例](./code-examples/csharp/1-通用接口/统一收单交易退款接口代码示例.md) |
-| 统一收单交易退款查询接口 | [示例](./code-examples/java/1-通用接口/统一收单交易退款查询接口代码示例.md) | [示例](./code-examples/python/1-通用接口/统一收单交易退款查询接口代码示例.md) | [示例](./code-examples/nodejs/1-通用接口/统一收单交易退款查询接口代码示例.md) | [示例](./code-examples/php/1-通用接口/统一收单交易退款查询接口代码示例.md) | [示例](./code-examples/csharp/1-通用接口/统一收单交易退款查询接口代码示例.md) |
-| 统一收单交易关闭接口 | [示例](./code-examples/java/1-通用接口/统一收单交易关闭接口代码示例.md) | [示例](./code-examples/python/1-通用接口/统一收单交易关闭接口代码示例.md) | [示例](./code-examples/nodejs/1-通用接口/统一收单交易关闭接口代码示例.md) | [示例](./code-examples/php/1-通用接口/统一收单交易关闭接口代码示例.md) | [示例](./code-examples/csharp/1-通用接口/统一收单交易关闭接口代码示例.md) |
+按量付费使用 402、`Payment-Needed`、`Payment-Proof`、验付和履约确认；不读取通用收单接口或异步通知示例。示例包含 TODO、内存模拟或占位函数时，必须替换为项目真实订单持久化、本地订单匹配、金额一致性、资源防串、幂等履约和履约确认失败重试逻辑，不得原样宣称生产完成。
 
----
+### 网站支付
 
-## 二、产品专用接口
+- 专用下单示例：`./code-examples/<语言>/2-网站支付/统一收单下单并支付页面接口代码示例.md`
+- 通用接口示例：读取下方“通用收单示例”
 
-本 Skill 支持的三种产品的专用接口说明。代码示例存放于各语言目录的对应产品子目录下。
+网站支付覆盖 PC 网页和手机浏览器网页/H5，底层接口固定 `alipay.trade.page.pay`。用户未明确关闭同步回跳时，还必须按 `alipay-sdk-reminder.md` 实现并验证同步回跳结果页；支付成功仍以验签通过的异步通知或交易查询为准。
 
-### 按量付费 API
+### APP 支付
 
-> ⚠️ 按量付费使用专属的 A2M（Agent to Machine Payment）接口，不使用统一收单接口。
+- 专用下单示例：`./code-examples/<语言>/3-APP支付/APP支付接口代码示例.md`
+- 通用接口示例：读取下方“通用收单示例”
 
-| 接口名称 | 文档链接 | 说明 |
-| --- | --- | --- |
-| 支付凭证验证 `alipay.aipay.agent.payment.verify` | [文档](https://ideservice.alipay.com/cms/site/0jaqax) | 验证 AI 智能体支付凭证 |
-| 商家履约回执确认 `alipay.aipay.agent.fulfillment.confirm` | [文档](https://ideservice.alipay.com/cms/site/0jaqax) | 确认商家已完成服务交付 |
+APP 支付默认完成商家服务端能力，返回 `orderStr` 给 APP 客户端；客户端 SDK 接入不属于本 Skill 默认服务端改造范围。客户端同步结果只作支付结束通知，不能作为付款成功依据。
 
-> **说明**：以上两个接口的在线文档同属按量付费聚合文档（0jaqax），并非两个独立文档，查阅时请在同一文档内定位对应接口。
+### 通用收单示例
 
-**按量付费代码示例**（A2M 接口，位于各语言 `4-按量付费/` 子目录）：
+网站支付和 APP 支付必须读取当前语言目录下的通用示例：
 
-| 语言 | 代码示例 |
+| 接口 | 文件 |
 | --- | --- |
-| Java | [示例](./code-examples/java/4-按量付费/A2MPaymentDemoController.java) |
-| Python | [示例](./code-examples/python/4-按量付费/A2MPaymentDemo.py) |
-| Node.js | [示例](./code-examples/nodejs/4-按量付费/A2MPaymentDemo.js) |
-| PHP | [示例](./code-examples/php/4-按量付费/A2MPaymentDemo.php) |
-| C# | [示例](./code-examples/csharp/4-按量付费/A2MPaymentDemo.cs) |
-
-### 网站支付 API
+| 交易查询 | `./code-examples/<语言>/1-通用接口/统一收单交易查询接口代码示例.md` |
+| 退款 | `./code-examples/<语言>/1-通用接口/统一收单交易退款接口代码示例.md` |
+| 退款查询 | `./code-examples/<语言>/1-通用接口/统一收单交易退款查询接口代码示例.md` |
+| 关闭交易 | `./code-examples/<语言>/1-通用接口/统一收单交易关闭接口代码示例.md` |
+| 异步通知 | `./code-examples/<语言>/1-通用接口/异步通知处理代码示例.md` |
 
-| 接口名称 | 文档链接 | Java | Python | Node.js | PHP | C# |
-| --- | --- | --- | --- | --- | --- | --- |
-| 统一收单下单并支付页面接口 | [文档](https://ideservice.alipay.com/cms/site/0iztfv) | [示例](./code-examples/java/2-网站支付/统一收单下单并支付页面接口代码示例.md) | [示例](./code-examples/python/2-网站支付/统一收单下单并支付页面接口代码示例.md) | [示例](./code-examples/nodejs/2-网站支付/统一收单下单并支付页面接口代码示例.md) | [示例](./code-examples/php/2-网站支付/统一收单下单并支付页面接口代码示例.md) | [示例](./code-examples/csharp/2-网站支付/统一收单下单并支付页面接口代码示例.md) |
-
-> **说明**：网站支付使用统一收单下单并支付页面接口 `alipay.trade.page.pay`，适用于电脑网页与手机网页场景。上表仅是接口调用示例，实际集成不得止于设置 `return_url`；用户未明确关闭同步回跳时，必须继续按 `alipay-sdk-reminder.md` 的“网站支付同步回跳”实现并验证结果页。本地未上线场景的异步通知口径以 `../flow.md` 为准。
-
-### APP支付 API
-
-| 接口名称 | 文档链接 | Java | Python | Node.js | PHP | C# |
-| --- | --- | --- | --- | --- | --- | --- |
-| APP支付接口 | [文档](https://ideservice.alipay.com/cms/site/0izsn4) | [示例](./code-examples/java/3-APP支付/APP支付接口代码示例.md) | [示例](./code-examples/python/3-APP支付/APP支付接口代码示例.md) | [示例](./code-examples/nodejs/3-APP支付/APP支付接口代码示例.md) | [示例](./code-examples/php/3-APP支付/APP支付接口代码示例.md) | [示例](./code-examples/csharp/3-APP支付/APP支付接口代码示例.md) |
-
----
-
-## 三、代码示例使用说明
-
-### 按量付费
-- 使用 `4-按量付费/` 目录下的代码示例
-- 按量付费**不需要**参考通用接口
-- 五语言 A2M 示例用于说明 402、Payment-Needed、Payment-Proof、验付和履约确认的核心协议与 SDK 调用流程；关键生产控制仍可能是 TODO、注释占位、内存模拟或伪代码，因此禁止原样作为生产实现或据此宣称集成完成。
-- 沙箱联调时 `serviceId` 固定使用 `api_mock_service_id`，该值是本 Skill 定义的沙箱开发值，不得改为其他占位符，也不得为继续沙箱测试向用户索要正式 `serviceId`。正式上线前必须替换为服务市场注册或复用结果中的真实 `serviceId`。
-- 示例中的 `sellerId`、`appId`、`alipayPublicKey` 只能作为占位说明。正式集成时必须替换为签约入驻产物：`sellerId` 来自商户 PID/2088，`appId/alipayPublicKey` 来自应用发布或复用结果。
-- 生成按量付费代码时必须补齐订单持久化、本地订单匹配、金额一致性、资源防串、幂等履约和履约确认失败可重试逻辑；不要把示例中的内存/占位实现当作生产实现。
-
-### 网站支付 / APP支付
-- 必须同时参考：
-  1. 对应产品的专用接口（如 `2-网站支付/` 或 `3-APP支付/`）
-  2. 通用接口 `1-通用接口/`（交易查询、退款、退款查询、关闭交易等）
-- 完整集成必须覆盖产品下单、交易查询、退款、退款查询、关闭交易和异步通知处理代码。本地示例缺失时仍须依据上述已核验的官方文档实现，不得因缺少示例而省略适用接口。
-- 若项目尚未上线，可先按 `../flow.md` 的“本地生产参数验收模式”完成本地结果确认链路验证；正式上线前仍必须补齐公网 HTTPS `notify_url`、验签、幂等和补偿查询。
+本地未上线时，可按 `../flow.md` 的“本地生产参数验收模式”先完成本地结果确认链路验证；正式上线前仍必须补齐公网 HTTPS `notify_url`、验签、幂等、关键字段校验、`success` 回写和补偿查询。用户明确要求对账时再读取官方对账单下载文档作为 fallback；当前默认 checklist 不包含对账单下载。

package/skill/references/integration/modules/product-decision.md

@@ -1,6 +1,6 @@
 # 产品决策
 
-用于用户集成支付宝支付产品时的产品决策。**本 Skill 仅支持按量付费、网站支付、APP支付三种产品**。
+用于用户集成支付宝支付产品时的产品决策。**本 Skill 仅支持按量付费、网站支付、APP 支付三种产品**。
 
 ---
 
@@ -12,7 +12,7 @@
 |------|------|----------|
 | **按量付费** | 面向 AI 智能体的机器支付收款产品 | API、数字内容、算力资源、智能体按调用付费、402 协议收款 |
 | **网站支付** | 用户在电脑网页或手机网页发起支付 | PC 官网、电商网站、在线教育、政务缴费网站、手机 H5 页面 |
-| **APP支付** | 原生 App 内调起支付宝支付 | iOS/Android/鸿蒙原生 App 内支付 |
+| **APP 支付** | 原生 App 内调起支付宝支付 | iOS/Android/鸿蒙原生 App 内支付 |
 
 ---
 
@@ -28,8 +28,8 @@
         |       +-- 电脑浏览器网页 --> 网站支付
         |       +-- 手机浏览器 H5 --> 网站支付
         |
-        +-- 原生 APP支付？
-                +-- iOS/Android/鸿蒙 --> APP支付
+        +-- 原生 APP 支付？
+                +-- iOS/Android/鸿蒙 --> APP 支付
 ```
 
 ---
@@ -42,7 +42,7 @@
 | --- | --- |
 | 402协议、Agent收款、A2A、ACT协议、A2M、AI支付、Agent支付、智能体、API收费、按调用付费、机器支付 | **按量付费** |
 | PC支付、电脑网站、网页支付、电脑端支付、PC网页、电脑浏览器、网站支付、传统网页支付、网页收银台、H5支付、手机网页 | **网站支付** |
-| APP支付、移动应用支付、iOS支付、Android支付、鸿蒙支付、App内支付、原生APP支付、手机APP支付、移动端App、SDK支付、客户端支付 | **APP支付** |
+| APP 支付、移动应用支付、iOS支付、Android支付、鸿蒙支付、App内支付、原生 APP 支付、手机 APP 支付、移动端App、SDK支付、客户端支付 | **APP 支付** |
 
 ---
 
@@ -60,31 +60,14 @@
 
 ---
 
-## 澄清话术
+## 产品澄清
 
-当用户描述模糊或关键词匹配不明确时，使用以下模板进行产品决策：
+用户描述模糊或关键词匹配不明确时，执行下列命令固定渲染 `product.clarify`，等待用户以自然语言回复产品名称和业务需求。本模块不维护第二份澄清模板；不得临场增加不支持产品、改写网站支付接口或省略三种支持产品。
 
-### 标准澄清模板
-
-```
-请确认您的业务场景：
-
-1. 按量付费
-   - 面向 AI 智能体的机器支付，基于 402 protocol 实现
-   - 适用：API、数字内容、算力资源、智能体按调用付费
-
-2. 网站支付
-   - 用户在电脑网页或手机 H5 页面发起支付，跳转支付宝完成付款
-   - 适用：PC 官网、手机 H5 页面、电商网站、在线教育、政务缴费网站
-   - 底层接口：`alipay.trade.page.pay`
-
-3. APP支付
-   - 原生 iOS/Android/鸿蒙 App 内调起支付宝付款
-   - 适用：移动端原生应用内支付
-
-请描述您的具体业务需求？
+```bash
+node ../../normal/scripts/integration_message_runner.mjs product-clarify
 ```
 
-### 不支持场景回复模板
+### 不支持场景回复
 
 > 使用标准拒绝引导话术，详见 `../../normal/rejection-guide.md`