@alipay/alipay-aipay 1.2.2 → 1.5.0

package/skill/references/integration/modules/code-examples/python/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,128 @@
+# 异步通知处理 - Python 示例
+
+适用产品：AI 网页应用收款、AI 移动应用收款。AI 按量付费不使用异步通知。
+
+```python
+import re
+from flask import Blueprint, Response, request
+
+
+def create_alipay_notify_blueprint(deps):
+    """deps 接入项目真实 SDK 验签适配器、支付配置、订单仓储、通知事件仓储和脱敏日志。"""
+    blueprint = Blueprint("alipay_notify", __name__)
+
+    @blueprint.post("/alipay/notify")
+    def alipay_notify():
+        params = {}
+        try:
+            params = request.form.to_dict(flat=True)
+            config = deps["payment_config_repository"].find_by_app_id(params.get("app_id"))
+            if config is None:
+                return fail(deps, "alipay notify app config not found", params)
+
+            if not verify_notify_with_alipay_sdk(params, deps["alipay_notify_verifier"], config):
+                return fail(deps, "alipay notify signature check failed", params)
+
+            order = deps["order_repository"].find_by_out_trade_no(params.get("out_trade_no"))
+            if order is None or not business_fields_match(order, params, config):
+                return fail(deps, "alipay notify business check failed", params)
+
+            inserted = deps["notify_event_repository"].insert_once(
+                notify_id=params.get("notify_id"),
+                trade_no=params.get("trade_no"),
+                out_trade_no=params.get("out_trade_no"),
+                trade_status=params.get("trade_status"),
+                raw_params=params,
+            )
+            if not inserted:
+                return Response("success", mimetype="text/plain")
+
+            if is_paid_trade_notification(params):
+                deps["order_repository"].mark_paid_idempotently(order["out_trade_no"], params.get("trade_no"), params)
+            else:
+                deps["order_repository"].record_non_paid_trade_event(order["out_trade_no"], params.get("trade_status"), params)
+
+            return Response("success", mimetype="text/plain")
+        except Exception:
+            safe_log_notify_error(deps, "alipay notify unexpected exception", params)
+            return Response("fail", mimetype="text/plain")
+
+    return blueprint
+
+
+def business_fields_match(order, params, config):
+    return (
+        params.get("app_id") == config["app_id"]
+        and params.get("out_trade_no") == order["out_trade_no"]
+        and amount_equals(order["total_amount"], params.get("total_amount"))
+        and expected_seller_matches(config, params.get("seller_id"), params.get("seller_email"))
+    )
+
+
+def is_paid_trade_notification(params):
+    paid_status = params.get("trade_status") in ("TRADE_SUCCESS", "TRADE_FINISHED")
+    return paid_status and not params.get("out_biz_no") and not params.get("gmt_refund") and not params.get("refund_fee")
+
+
+def amount_equals(expected, actual):
+    expected_amount = normalize_amount_text(expected)
+    actual_amount = normalize_amount_text(actual)
+    return expected_amount is not None and expected_amount == actual_amount
+
+
+def normalize_amount_text(value):
+    if value is None:
+        return None
+    match = re.fullmatch(r"(\d+)(?:\.(\d{1,2}))?", str(value).strip())
+    if not match:
+        return None
+    return f"{int(match.group(1))}.{(match.group(2) or '').ljust(2, '0')}"
+
+
+def expected_seller_matches(config, seller_id, seller_email):
+    expected_seller_id = config.get("seller_id")
+    expected_seller_email = config.get("seller_email")
+    return (
+        bool(expected_seller_id and seller_id == expected_seller_id)
+        or bool(expected_seller_email and seller_email == expected_seller_email)
+    )
+
+
+def verify_notify_with_alipay_sdk(params, verifier, config):
+    """
+    使用当前项目已安装的支付宝 SDK 验签能力校验 params["sign"]。
+    verifier.verify(params, config) 必须封装目标项目当前 SDK 实际通知验签 API；落地前先查已安装包文档或类型定义，不能手写临时 RSA 验签。
+    """
+    return verifier.verify(params, config)
+
+
+def fail(deps, message, params):
+    safe_log_notify_error(deps, message, params)
+    return Response("fail", mimetype="text/plain")
+
+
+def safe_log_notify_error(deps, message, params):
+    try:
+        logger = deps.get("logger")
+        if logger is not None:
+            logger.warning(message, extra={"alipay_notify": sanitize_notify_params(params)})
+    except Exception:
+        # 日志失败不能影响支付宝收到纯文本 fail。
+        pass
+
+
+def sanitize_notify_params(params):
+    safe_params = dict(params)
+    safe_params.pop("sign", None)
+    return safe_params
+```
+
+要点：
+
+- 支付宝通知是 POST 表单，不能用 JSON body 解析。
+- 验签必须调用当前项目支付宝 SDK 的实际验签 API，验签前不得丢字段或改值。
+- `app_id`、`seller_id` / `seller_email` 从运行时支付配置校验，不从订单对象默认取值。
+- 金额校验使用字符串规范化、`Decimal` 或项目定点数工具，不要用浮点数直接比较。
+- 只有付款成功状态且不是退款、关单、分账等事件时，才认定付款成功。
+- 内存订单或内存幂等只能用于非生产 demo，生产必须使用持久化订单表和通知事件表。
+- 处理成功后返回纯文本 `success`；异常、验签失败或业务校验失败返回 `fail`。

package/skill/references/integration/modules/code-examples/python/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

@@ -3,6 +3,7 @@
 ## 请求示例
 
 ```python
+import os
 from alipay.aop.api.AlipayClientConfig import AlipayClientConfig
 from alipay.aop.api.DefaultAlipayClient import DefaultAlipayClient
 from alipay.aop.api.request.AlipayTradePagePayRequest import AlipayTradePagePayRequest
@@ -20,7 +21,9 @@ config.sign_type = "RSA2"
 client = DefaultAlipayClient(alipay_client_config=config)
 
 request = AlipayTradePagePayRequest()
-request.notify_url = "https://your-domain.com/notify"  # 真实生产或公网联调时传入；本地生产参数验收模式可临时不传，但仍需实现通知处理代码
+notify_url = os.getenv("ALIPAY_NOTIFY_URL", "").strip()
+if notify_url:
+    request.notify_url = notify_url  # 真实生产或公网联调时传入；本地没有公网 HTTPS notify_url 时不要传 None、空字符串或占位 URL
 request.return_url = "https://your-domain.com/return"  # 默认传入并替换为已验证结果页；仅用户明确关闭同步回跳时省略
 
 model = AlipayTradePagePayModel()

package/skill/references/integration/modules/code-examples/python/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,9 +1,10 @@
-# APP支付接口 - Python 示例
+# APP 支付接口 - Python 示例
 
 ## 请求示例
 
 ```python
 import json
+import os
 from alipay.aop.api.AlipayClientConfig import AlipayClientConfig
 from alipay.aop.api.DefaultAlipayClient import DefaultAlipayClient
 from alipay.aop.api.request.AlipayTradeAppPayRequest import AlipayTradeAppPayRequest
@@ -21,6 +22,9 @@ client = DefaultAlipayClient(alipay_client_config=config)
 
 # 构造请求参数以调用接口
 request = AlipayTradeAppPayRequest()
+notify_url = os.getenv("ALIPAY_NOTIFY_URL", "").strip()
+if notify_url:
+    request.notify_url = notify_url  # 真实生产或公网联调时传入；本地没有公网 HTTPS notify_url 时不要传 None、空字符串或占位 URL
 model = AlipayTradeAppPayModel()
 
 model.out_trade_no = "MERCHANT_ORDER_NO_PLACEHOLDER"

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

@@ -21,9 +21,10 @@ pip install flask alipay-sdk-python pycryptodome
 不能直接使用 dict 赋值给 biz_model，因为 SDK 会调用 to_alipay_dict() 方法。
 """
 
+import base64
 import json
+import os
 import time
-import base64
 from datetime import datetime, timedelta, timezone
 from urllib.parse import quote, unquote
 from Crypto.Signature import pkcs1_15
@@ -44,7 +45,8 @@ ALIPAY_CONFIG = {
     'appId': '<APP_ID>',
     'privateKey': '<APP_PRIVATE_KEY>',  # 请填写您的应用私钥（PKCS#1 格式）
     'alipayPublicKey': '<ALIPAY_PUBLIC_KEY>',  # 请填写您的支付宝公钥
-    'gateway': 'https://openapi.alipay.com/gateway.do',
+    # 默认用于本 Skill 的快速沙箱联调；生产部署时显式设置为 https://openapi.alipay.com/gateway.do
+    'gateway': os.environ.get('ALIPAY_GATEWAY', 'https://openapi-sandbox.dl.alipaydev.com/gateway.do'),
     'sellerId': '<SELLER_ID_2088>',  # 商户 ID（2088 格式）
     'serviceId': 'api_mock_service_id',  # 仅用于沙箱联调；上线前替换为服务市场真实 serviceId
     'merchantPrivateKey': '<APP_PRIVATE_KEY>'  # 请填写您的应用私钥（用于商家签名）

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

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