@alipay/alipay-aipay 0.1.1-beta.1

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

@@ -0,0 +1,465 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+A2M 智能收产品接入示例 - Python 版本
+
+本文件演示完整的智能收产品接入流程：
+1. 返回 402 Payment-Needed Header
+2. 验证 Payment-Proof 支付凭证
+3. 发送履约回执确认
+4. 返回资源内容
+
+依赖安装：
+pip install flask alipay-sdk-python
+
+注意：Python SDK 3.7+ 版本必须使用 Model 类（如 AlipayAipayAgentPaymentVerifyModel），
+不能直接使用 dict 赋值给 biz_model，因为 SDK 会调用 to_alipay_dict() 方法。
+"""
+
+import json
+import time
+import base64
+from datetime import datetime, timedelta, timezone
+from urllib.parse import quote, unquote
+from Crypto.Signature import pkcs1_15
+from Crypto.Hash import SHA256
+from Crypto.PublicKey import RSA
+from flask import Flask, request, Response
+from alipay.aop.api.AlipayClientConfig import AlipayClientConfig
+from alipay.aop.api.DefaultAlipayClient import DefaultAlipayClient
+from alipay.aop.api.request.AlipayAipayAgentPaymentVerifyRequest import AlipayAipayAgentPaymentVerifyRequest
+from alipay.aop.api.request.AlipayAipayAgentFulfillmentConfirmRequest import AlipayAipayAgentFulfillmentConfirmRequest
+from alipay.aop.api.domain.AlipayAipayAgentPaymentVerifyModel import AlipayAipayAgentPaymentVerifyModel
+from alipay.aop.api.domain.AlipayAipayAgentFulfillmentConfirmModel import AlipayAipayAgentFulfillmentConfirmModel
+
+app = Flask(__name__)
+
+# ==================== 配置信息（实际使用时请从配置中心读取）====================
+ALIPAY_CONFIG = {
+    'appId': '<APP_ID>',
+    'privateKey': '<APP_PRIVATE_KEY>',  # 请填写您的应用私钥（PKCS#1 格式）
+    'alipayPublicKey': '<ALIPAY_PUBLIC_KEY>',  # 请填写您的支付宝公钥
+    'gateway': 'https://openapi.alipay.com/gateway.do',
+    'sellerId': '<SELLER_ID_2088>',  # 商户 ID（2088 格式）
+    'serviceId': '<SERVICE_ID>',  # 商户服务 ID
+    'merchantPrivateKey': '<APP_PRIVATE_KEY>'  # 请填写您的应用私钥（用于商家签名）
+}
+
+RESOURCE_CONFIG = {
+    'path': '/demo/a2m/resource',
+    'goodsName': 'AI 生成内容服务'
+}
+
+# 初始化支付宝客户端
+def init_alipay_client():
+    """初始化支付宝 SDK 客户端"""
+    config = AlipayClientConfig()
+    config.server_url = ALIPAY_CONFIG['gateway']
+    config.app_id = ALIPAY_CONFIG['appId']
+    config.app_private_key = ALIPAY_CONFIG['privateKey']
+    config.alipay_public_key = ALIPAY_CONFIG['alipayPublicKey']
+    config.charset = 'utf-8'
+    config.sign_type = 'RSA2'
+    
+    return DefaultAlipayClient(alipay_client_config=config)
+
+
+# ==================== 工具方法 ====================
+
+def format_alipay_timestamp(dt=None):
+    """格式化支付宝时间戳：yyyy-MM-dd HH:mm:ss"""
+    if dt is None:
+        dt = datetime.now()
+    return dt.strftime('%Y-%m-%d %H:%M:%S')
+
+
+def generate_seller_signature(params, private_key):
+    """
+    生成商家签名（seller_signature）
+    
+    Args:
+        params: 待签名参数字典
+        private_key: 商户私钥字符串
+    
+    Returns:
+        Base64 编码的签名
+    """
+    # 1. 按 key 字典序排序
+    sorted_keys = sorted(params.keys())
+    
+    # 2. 拼接签名内容
+    sign_content = []
+    for key in sorted_keys:
+        value = params[key]
+        if value is not None and value != '':
+            sign_content.append(f"{key}={value}")
+    
+    sign_string = '&'.join(sign_content)
+    
+    # 3. RSA2 签名
+    key = RSA.import_key(private_key)
+    h = SHA256.new(sign_string.encode('utf-8'))
+    signature = pkcs1_15.new(key).sign(h)
+    
+    return base64.b64encode(signature).decode('utf-8')
+
+
+def base64url_encode(data):
+    """Base64URL 编码"""
+    if isinstance(data, str):
+        data = data.encode('utf-8')
+    return base64.urlsafe_b64encode(data).rstrip(b'=').decode('utf-8')
+
+
+def base64url_decode(data):
+    """Base64URL 解码"""
+    # 补充 padding
+    padding = 4 - len(data) % 4
+    if padding != 4:
+        data += '=' * padding
+    
+    return base64.urlsafe_b64decode(data).decode('utf-8')
+
+
+def json_response(data, status_code=200, headers=None):
+    """发送 JSON 响应"""
+    response = Response(
+        json.dumps(data, ensure_ascii=False),
+        status=status_code,
+        mimetype='application/json; charset=utf-8'
+    )
+    
+    if headers:
+        for key, value in headers.items():
+            response.headers[key] = value
+    
+    return response
+
+
+# ==================== 智能收产品接入示例接口 ====================
+
+@app.route(RESOURCE_CONFIG['path'], methods=['GET'])
+def handle_resource():
+    """
+    智能收产品统一接口
+    
+    完整流程演示：
+    1. 不带 Payment-Proof Header：返回 HTTP 402 + Payment-Needed Header
+    2. 带 Payment-Proof Header：验证支付 → 自动履约 → 返回资源
+    """
+    # 获取 Payment-Proof Header
+    payment_proof = request.headers.get('Payment-Proof')
+    
+    # 场景 1：用户未支付，返回 402 + Payment-Needed Header
+    if not payment_proof or not payment_proof.strip():
+        return create_payment_required_response()
+    
+    # 场景 2：用户已支付，验证 Payment-Proof 并返回资源
+    return verify_payment_and_deliver_resource(payment_proof)
+
+
+def create_payment_required_response():
+    """创建 402 支付请求响应"""
+    try:
+        # 1. 构造订单信息
+        out_trade_no = f"ORDER_{int(time.time() * 1000)}"
+        amount = '0.01'  # 单位：元
+        currency = 'CNY'
+        resource_id = RESOURCE_CONFIG['path']
+        goods_name = RESOURCE_CONFIG['goodsName']
+        
+        # 2. 计算支付截止时间（30 分钟后），使用带时区的 ISO 8601 格式
+        pay_before = (datetime.now(timezone.utc).astimezone() + timedelta(minutes=30)).isoformat()
+        
+        # 3. 生成商家签名
+        seller_signature = generate_seller_signature({
+            'amount': amount,
+            'currency': currency,
+            'goods_name': goods_name,
+            'out_trade_no': out_trade_no,
+            'pay_before': pay_before,
+            'resource_id': resource_id,
+            'seller_id': ALIPAY_CONFIG['sellerId'],
+            'service_id': ALIPAY_CONFIG['serviceId']
+        }, ALIPAY_CONFIG['merchantPrivateKey'])
+        
+        # 4. 构造 Payment-Needed Header 内容
+        payment_needed = {
+            'protocol': {
+                'out_trade_no': out_trade_no,
+                'amount': amount,
+                'currency': currency,
+                'resource_id': resource_id,
+                'pay_before': pay_before,
+                'seller_signature': seller_signature,
+                'seller_sign_type': 'RSA2',
+                'seller_unique_id': ALIPAY_CONFIG['sellerId']
+            },
+            'method': {
+                'seller_name': '测试商户',
+                'seller_id': ALIPAY_CONFIG['sellerId'],
+                'seller_app_id': ALIPAY_CONFIG['appId'],
+                'goods_name': goods_name,
+                'seller_unique_id_key': 'seller_id',
+                'service_id': ALIPAY_CONFIG['serviceId']
+            }
+        }
+        
+        # 5. Base64URL 编码
+        payment_needed_encoded = base64url_encode(json.dumps(payment_needed, ensure_ascii=False))
+        
+        # 6. 构造 402 响应
+        response_data = {
+            'code': 'Payment-Needed',
+            'message': '需要支付',
+            'out_trade_no': out_trade_no,
+            'amount': amount,
+            'currency': currency,
+            'goods_name': goods_name
+        }
+        
+        print(f"创建支付订单成功：outTradeNo={out_trade_no}, amount={amount}")
+        
+        return json_response(
+            response_data,
+            status_code=402,
+            headers={'Payment-Needed': payment_needed_encoded}
+        )
+        
+    except Exception as e:
+        print(f'创建订单失败：{str(e)}')
+        return json_response({
+            'code': 'CREATE_ORDER_ERROR',
+            'message': f'创建订单失败：{str(e)}'
+        }, status_code=500)
+
+
+def verify_payment_and_deliver_resource(payment_proof):
+    """验证支付凭证并交付资源"""
+    try:
+        # 1. 从 Payment-Proof 中解析订单信息
+        try:
+            decoded_proof = base64url_decode(payment_proof)
+            proof_json = json.loads(decoded_proof)
+            
+            # 从 protocol 层获取 payment_proof 和 trade_no
+            protocol = proof_json.get('protocol', {})
+            payment_proof_value = protocol.get('payment_proof')
+            trade_no = protocol.get('trade_no')
+            
+            # 从 method 层获取 client_session
+            method = proof_json.get('method', {})
+            client_session = method.get('client_session')
+            
+            # 校验必要字段
+            if not payment_proof_value or not payment_proof_value.strip():
+                return json_response({
+                    'code': 'INVALID_PAYMENT_PROOF_FORMAT',
+                    'message': 'Payment-Proof 格式错误：缺少 payment_proof'
+                }, status_code=400)
+            
+            if not trade_no or not trade_no.strip():
+                return json_response({
+                    'code': 'INVALID_PAYMENT_PROOF_FORMAT',
+                    'message': 'Payment-Proof 格式错误：缺少 trade_no'
+                }, status_code=400)
+                
+        except Exception as e:
+            print(f'Payment-Proof 解析失败：{str(e)}')
+            return json_response({
+                'code': 'INVALID_PAYMENT_PROOF_FORMAT',
+                'message': f'Payment-Proof 格式错误：{str(e)}'
+            }, status_code=400)
+        
+        # 2. 调用支付宝 API 验证支付凭证
+        # 注意：必须使用 Model 类，不能使用 dict
+        # SDK 的 get_params() 方法会调用 biz_model.to_alipay_dict()
+        alipay_client = init_alipay_client()
+        verify_request = AlipayAipayAgentPaymentVerifyRequest()
+        
+        # 使用 Model 类（正确方式）
+        model = AlipayAipayAgentPaymentVerifyModel()
+        model.payment_proof = payment_proof_value
+        model.trade_no = trade_no
+        model.client_session = client_session
+        verify_request.biz_model = model
+        
+        # 如果 SDK 版本支持直接使用 dict，也可以用 biz_content（备选方案）
+        # verify_request.biz_content = json.dumps({
+        #     'payment_proof': payment_proof_value,
+        #     'trade_no': trade_no,
+        #     'client_session': client_session
+        # }, ensure_ascii=False)
+        
+        verify_response_content = alipay_client.execute(verify_request)
+        verify_response = json.loads(verify_response_content)
+        
+        # 3. 验证失败，返回错误
+        # 注意：SDK execute() 返回的 JSON 可能是扁平结构（直接包含 code/trade_no 等字段），
+        # 也可能嵌套在 alipay_aipay_agent_payment_verify_response 键下，需兼容两种情况
+        response_data = verify_response.get('alipay_aipay_agent_payment_verify_response', verify_response)
+        if response_data.get('code') != '10000':
+            print(f'支付凭证验证失败：{response_data.get("sub_msg")}')
+            return json_response({
+                'code': response_data.get('sub_code', 'VERIFY_FAILED'),
+                'message': response_data.get('sub_msg', '支付凭证验证失败')
+            }, status_code=400)
+        
+        # 4. 验证成功，获取订单信息
+        verify_trade_no = response_data.get('trade_no')
+        verify_out_trade_no = response_data.get('out_trade_no')
+        resource_id = response_data.get('resource_id')
+        active = response_data.get('active')
+        
+        print(f"支付凭证验证成功：tradeNo={verify_trade_no}, outTradeNo={verify_out_trade_no}")
+        
+        # 5. 校验凭证有效性（active=true 表示凭证有效）
+        if active is not True:
+            print(f"支付凭证无效或已过期：outTradeNo={verify_out_trade_no}")
+            return json_response({
+                'code': 'INVALID_PAYMENT_PROOF',
+                'message': '支付凭证无效或已过期'
+            }, status_code=400)
+        
+        # 6. 【TODO】查询订单是否存在（以数据库为准）
+        # order = order_repository.find_by_out_trade_no(verify_out_trade_no)
+        # if not order:
+        #     return json_response({
+        #         'code': 'ORDER_NOT_FOUND',
+        #         'message': '订单不存在'
+        #     }, status_code=404)
+        
+        # 7. 【TODO】资源防串校验
+        # if resource_id != order.resource_id:
+        #     return json_response({
+        #         'code': 'RESOURCE_ID_MISMATCH',
+        #         'message': '资源 ID 不匹配，可能存在资源串改风险'
+        #     }, status_code=403)
+        
+        # 8. 【TODO】履约防重放校验（数据库幂等控制）
+        # if order.fulfill_status == 'FULFILLED':
+        #     return json_response({
+        #         'code': 'ALREADY_FULFILLED',
+        #         'message': '订单已履约，不重复提供',
+        #         'already_fulfilled': True
+        #     }, status_code=200)
+        
+        # 9. 生成资源内容
+        service_result = generate_service_resource(resource_id)
+        
+        # 10. 【TODO】履约记录落库
+        # fulfillment_record_repository.save({...})
+        
+        # 11. 【TODO】保存待确认履约状态
+        # 实际生产中建议先保存 service_result 和 PENDING_CONFIRM 状态。
+        # fulfillment.confirm 成功后再标记 FULFILLED；如果确认失败，
+        # 允许同一笔 Payment-Proof 重试确认，避免误返回成功。
+        # order_repository.update(verify_out_trade_no, {
+        #     'order_status': 'PAID',
+        #     'fulfill_status': 'PENDING_CONFIRM',
+        #     'trade_no': verify_trade_no,
+        #     'service_result': service_result
+        # })
+
+        print(f"资源已生成，准备发送履约确认：outTradeNo={verify_out_trade_no}, tradeNo={verify_trade_no}")
+
+        # 12. 发送履约确认到支付宝，确认成功后才返回成功交付
+        # 注意：同样需要使用 Model 类
+        if not send_fulfillment_confirm(verify_trade_no):
+            return json_response({
+                'code': 'FULFILLMENT_CONFIRM_FAILED',
+                'message': '资源已生成但履约确认失败，请稍后使用同一 Payment-Proof 重试'
+            }, status_code=502)
+
+        # 12.1 【TODO】履约确认成功后，再标记订单已履约
+        # order_repository.update(verify_out_trade_no, {
+        #     'fulfill_status': 'FULFILLED',
+        #     'fulfilled_at': datetime.now(timezone.utc).astimezone().isoformat()
+        # })
+
+        print(f"履约确认成功：outTradeNo={verify_out_trade_no}, tradeNo={verify_trade_no}")
+        
+        # 13. 构造 Payment-Validation Header
+        payment_validation = {
+            'trade_no': verify_trade_no,
+            'out_trade_no': verify_out_trade_no,
+            'validated': True,
+            'resource_id': resource_id
+        }
+        
+        payment_validation_encoded = base64url_encode(json.dumps(payment_validation, ensure_ascii=False))
+        
+        # 14. 返回资源内容
+        return json_response({
+            'resource_id': resource_id,
+            'content': service_result,
+            'trade_no': verify_trade_no,
+            'out_trade_no': verify_out_trade_no,
+            'already_fulfilled': False,
+            'fulfillment_confirmed': True
+        }, headers={'Payment-Validation': payment_validation_encoded})
+        
+    except Exception as e:
+        print(f'支付凭证验证异常：{str(e)}')
+        return json_response({
+            'code': 'VERIFY_FAILED',
+            'message': f'支付凭证验证失败：{str(e)}'
+        }, status_code=500)
+
+
+def generate_service_resource(resource_id):
+    """生成服务资源内容"""
+    return json.dumps({
+        'status': 'success',
+        'service_type': 'AI_CONTENT_GENERATION',
+        'resource_id': resource_id,
+        'content': '这是 AI 生成的内容示例，可根据实际业务替换为任意数字服务内容',
+        'generated_at': datetime.now(timezone.utc).astimezone().isoformat()
+    }, ensure_ascii=False)
+
+
+def send_fulfillment_confirm(trade_no):
+    """发送履约确认"""
+    try:
+        print(f"开始发送履约确认：tradeNo={trade_no}")
+        
+        alipay_client = init_alipay_client()
+        confirm_request = AlipayAipayAgentFulfillmentConfirmRequest()
+        
+        # 使用 Model 类（正确方式）
+        model = AlipayAipayAgentFulfillmentConfirmModel()
+        model.trade_no = trade_no
+        confirm_request.biz_model = model
+        
+        # 备选方案：使用 biz_content
+        # confirm_request.biz_content = json.dumps({
+        #     'trade_no': trade_no
+        # }, ensure_ascii=False)
+        
+        response_content = alipay_client.execute(confirm_request)
+        response = json.loads(response_content)
+        
+        # 注意：SDK execute() 返回的 JSON 可能是扁平结构，也可能嵌套在响应键下，需兼容两种情况
+        response_data = response.get('alipay_aipay_agent_fulfillment_confirm_response', response)
+        if response_data.get('code') == '10000':
+            print(f"履约确认成功：tradeNo={trade_no}")
+            return True
+        else:
+            print(f"履约确认失败：tradeNo={trade_no}, errorCode={response_data.get('sub_code')}, "
+                  f"errorMsg={response_data.get('sub_msg')}")
+            return False
+            
+    except Exception as e:
+        print(f"履约确认异常：tradeNo={trade_no}, error={str(e)}")
+        return False
+
+
+# ==================== 启动服务 ====================
+
+if __name__ == '__main__':
+    print(f"A2M 智能收服务已启动：http://localhost:5000{RESOURCE_CONFIG['path']}")
+    print('测试步骤：')
+    print(f'1. 无 Payment-Proof Header: curl http://localhost:5000{RESOURCE_CONFIG["path"]}')
+    print(f'2. 有 Payment-Proof Header: curl -H "Payment-Proof: <value>" http://localhost:5000{RESOURCE_CONFIG["path"]}')
+    
+    app.run(host='0.0.0.0', port=5000, debug=True)

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

@@ -0,0 +1,90 @@
+# 接口说明与代码示例索引
+
+本文件汇总了支付宝支付产品的通用接口和产品专用接口的参考文档及代码示例索引，供主 Skill 集成参考。**本 Skill 仅支持按量付费、网站支付、APP支付三种产品**。
+
+---
+
+## 一、通用接口
+
+下表所列接口适用于网站支付和APP支付产品，请结合用户集成诉求按需查阅。**按量付费产品不使用这些通用接口**。
+
+### 通用接口文档索引
+
+| 接口名称 | 文档链接 |
+| --- | --- |
+| 统一收单交易查询接口 | <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# |
+| --- | --- | --- | --- | --- | --- |
+| 统一收单交易查询接口 | [示例](./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) |
+
+---
+
+## 二、产品专用接口
+
+本 Skill 支持的三种产品的专用接口说明。代码示例存放于各语言目录的对应产品子目录下。
+
+### 按量付费 API
+
+> ⚠️ 按量付费使用专属的 A2M（Agent to Machine Payment）接口，不使用统一收单接口。
+
+| 接口名称 | 文档链接 | 说明 |
+| --- | --- | --- |
+| 支付凭证验证 `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) | 确认商家已完成服务交付 |
+
+> **说明**：以上两个接口的在线文档同属按量付费聚合文档（0jaqax），并非两个独立文档，查阅时请在同一文档内定位对应接口。
+
+**按量付费代码示例**（A2M 接口，位于各语言 `4-按量付费/` 子目录）：
+
+| 语言 | 代码示例 |
+| --- | --- |
+| 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
+
+| 接口名称 | 文档链接 | 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`，适用于电脑网页与手机网页场景。
+
+### 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-按量付费/` 目录下的代码示例
+- 按量付费**不需要**参考通用接口
+- 示例中的 `sellerId`、`serviceId`、`appId`、`alipayPublicKey` 只能作为占位说明。正式集成时必须替换为签约入驻产物：`sellerId` 来自商户 PID/2088，`serviceId` 来自服务市场注册或复用结果，`appId/alipayPublicKey` 来自应用发布或复用结果。
+- 生成按量付费代码时必须补齐订单持久化、本地订单匹配、资源防串、幂等履约和履约确认失败可重试逻辑；不要把示例中的内存/占位实现当作生产实现。
+
+### 网站支付 / APP支付
+- 必须同时参考：
+  1. 对应产品的专用接口（如 `2-网站支付/` 或 `3-APP支付/`）
+  2. 通用接口 `1-通用接口/`（交易查询、退款、退款查询、关闭交易等）

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

@@ -0,0 +1,90 @@
+# 产品决策
+
+用于用户集成支付宝支付产品时的产品决策。**本 Skill 仅支持按量付费、网站支付、APP支付三种产品**。
+
+---
+
+## 支持的产品
+
+> 术语说明：本 Skill 中“网站支付”是唯一的网页支付产品概念，覆盖电脑网页和手机浏览器网页/H5 场景；“电脑网站支付”“PC网站支付”“手机网站支付”“H5支付”均路由到网站支付。集成侧网站支付底层接口固定使用 `alipay.trade.page.pay`，即使是手机浏览器/H5 场景，也不得改用或推荐其他网页支付接口。
+
+| 产品 | 定义 | 适用场景 |
+|------|------|----------|
+| **按量付费** | 面向 AI 智能体的机器支付收款产品 | API、数字内容、算力资源、智能体按调用付费、402 协议收款 |
+| **网站支付** | 用户在电脑网页或手机网页发起支付 | PC 官网、电商网站、在线教育、政务缴费网站、手机 H5 页面 |
+| **APP支付** | 原生 App 内调起支付宝支付 | iOS/Android/鸿蒙原生 App 内支付 |
+
+---
+
+## 产品决策树
+
+```
+用户咨询支付宝接入
+        |
+        +-- 面向 AI 智能体收款？402 协议？
+        |       +-- 按量付费
+        |
+        +-- 线上网页支付？
+        |       +-- 电脑浏览器网页 --> 网站支付
+        |       +-- 手机浏览器 H5 --> 网站支付
+        |
+        +-- 原生 APP支付？
+                +-- iOS/Android/鸿蒙 --> APP支付
+```
+
+---
+
+## 场景关键词匹配
+
+根据用户输入的关键词快速路由到对应产品：
+
+| 关键词 | 路由产品 |
+| --- | --- |
+| 402协议、Agent收款、A2A、ACT协议、A2M、AI支付、Agent支付、智能体、API收费、按调用付费、机器支付 | **按量付费** |
+| PC支付、电脑网站、网页支付、电脑端支付、PC网页、电脑浏览器、网站支付、传统网页支付、网页收银台、H5支付、手机网页 | **网站支付** |
+| APP支付、移动应用支付、iOS支付、Android支付、鸿蒙支付、App内支付、原生APP支付、手机APP支付、移动端App、SDK支付、客户端支付 | **APP支付** |
+
+---
+
+## ❌ 不支持的产品
+
+> ⚠️ 以下产品**不在本 Skill 支持范围内**。拒绝引导话术见 `../../normal/rejection-guide.md`
+
+| 不支持的产品 | 处理方式 |
+|-------------|----------|
+| 当面付 | 使用 rejection-guide.md 中的标准引导 |
+| 订单码支付 | 使用 rejection-guide.md 中的标准引导 |
+| JSAPI支付 | 使用 rejection-guide.md 中的标准引导 |
+| 预授权支付 | 使用 rejection-guide.md 中的标准引导 |
+| 商家扣款 | 使用 rejection-guide.md 中的标准引导 |
+
+---
+
+## 澄清话术
+
+当用户描述模糊或关键词匹配不明确时，使用以下模板进行产品决策：
+
+### 标准澄清模板
+
+```
+请确认您的业务场景：
+
+1. 按量付费
+   - 面向 AI 智能体的机器支付，基于 402 protocol 实现
+   - 适用：API、数字内容、算力资源、智能体按调用付费
+
+2. 网站支付
+   - 用户在电脑网页或手机 H5 页面发起支付，跳转支付宝完成付款
+   - 适用：PC 官网、手机 H5 页面、电商网站、在线教育、政务缴费网站
+   - 底层接口：`alipay.trade.page.pay`
+
+3. APP支付
+   - 原生 iOS/Android/鸿蒙 App 内调起支付宝付款
+   - 适用：移动端原生应用内支付
+
+请描述您的具体业务需求？
+```
+
+### 不支持场景回复模板
+
+> 使用标准拒绝引导话术，详见 `../../normal/rejection-guide.md`