@alipay/alipay-aipay 1.0.2 → 1.2.2

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

@@ -1,14 +1,19 @@
 /**
  * A2M 智能收产品接入示例 - Node.js 版本
+ *
+ * 本示例展示 A2M 核心协议与 SDK 调用流程。
+ * 订单持久化、本地订单匹配、金额一致性、资源防串、幂等履约和失败重试
+ * 需要结合商户实际数据库与订单模型实现。在上述控制完成实现并通过 checklist 前，
+ * 禁止将本文件原样用于生产或判定为生产就绪。
  * 
- * 本文件演示完整的智能收产品接入流程：
+ * 本文件演示 A2M 核心协议调用流程：
  * 1. 返回 402 Payment-Needed Header
  * 2. 验证 Payment-Proof 支付凭证
  * 3. 发送履约回执确认
  * 4. 返回资源内容
  * 
  * 依赖安装：
- * npm install express alipay-sdk crypto-js
+ * npm install express alipay-sdk
  */
 
 const express = require('express');
@@ -18,17 +23,17 @@ const crypto = require('crypto');
 const app = express();
 const PORT = 3000;
 
-// ==================== 配置信息（实际使用时请从配置中心读取）====================
+// ==================== 配置信息（实际使用时请从受保护的配置读取）====================
 const CONFIG = {
   // 支付宝配置
   alipay: {
-    appId: '<APP_ID>',
-    privateKey: '<APP_PRIVATE_KEY>', // 请填写您的应用私钥（PKCS#1 格式）
-    alipayPublicKey: '<ALIPAY_PUBLIC_KEY>', // 请填写您的支付宝公钥
+    appId: '<APP_ID>', // 运行时映射沙箱 appId
+    privateKey: '<APP_PRIVATE_KEY>', // 运行时映射 appPrivatePkcsKey（PKCS#1）
+    alipayPublicKey: '<ALIPAY_PUBLIC_KEY>', // 运行时映射 alipayPublicKey
     gateway: 'https://openapi.alipay.com/gateway.do',
     sellerId: '<SELLER_ID_2088>', // 商户 ID（2088 格式）
-    serviceId: '<SERVICE_ID>', // 商户服务 ID
-    merchantPrivateKey: '<APP_PRIVATE_KEY>' // 请填写您的应用私钥（用于商家签名）
+    serviceId: 'api_mock_service_id', // 仅用于沙箱联调；上线前替换为服务市场真实 serviceId
+    merchantPrivateKey: '<APP_PRIVATE_KEY>' // 与 privateKey 使用同一运行时配置，用于商家签名
   },
   // 资源服务配置
   resource: {
@@ -43,6 +48,7 @@ const alipaySdk = new AlipaySdk({
   privateKey: CONFIG.alipay.privateKey,
   alipayPublicKey: CONFIG.alipay.alipayPublicKey,
   gateway: CONFIG.alipay.gateway,
+  timeout: 30000,
 });
 
 // ==================== 工具方法 ====================
@@ -74,11 +80,16 @@ function generateSellerSignature(params, privateKey) {
     })
     .join('&');
   
-  // 3. RSA2 签名
+  // 3. 将裸 PKCS#1 Base64 临时解析为 DER 密钥对象，不修改原始配置。
+  const sellerPrivateKey = crypto.createPrivateKey({
+    key: Buffer.from(privateKey, 'base64'),
+    format: 'der',
+    type: 'pkcs1'
+  });
   const sign = crypto
     .createSign('RSA-SHA256')
     .update(signContent, 'utf8')
-    .sign(privateKey, 'base64');
+    .sign(sellerPrivateKey, 'base64');
   
   return sign;
 }
@@ -132,7 +143,7 @@ function base64UrlDecode(str) {
 /**
  * 智能收产品统一接口
  * 
- * 完整流程演示：
+ * 核心协议流程演示：
  * 1. 不带 Payment-Proof Header：返回 HTTP 402 + Payment-Needed Header
  * 2. 带 Payment-Proof Header：验证支付 → 自动履约 → 返回资源
  * 
@@ -283,24 +294,37 @@ async function verifyPaymentAndDeliverResource(req, res, paymentProof) {
     });
     
     // 3. 验证失败，返回错误
-    // 注意：SDK 返回的响应可能是扁平结构（code/trade_no 在顶层），
-    // 也可能嵌套在 alipay_aipay_agent_payment_verify_response 键下，需兼容两种情况
-    const responseData = verifyResponse.alipay_aipay_agent_payment_verify_response || verifyResponse;
-    if (responseData.code !== '10000') {
-      console.error('支付凭证验证失败:', responseData.sub_msg);
+    // SDK 可能返回嵌套响应，也可能直接返回业务字段。
+    const nestedResponse = verifyResponse.alipay_aipay_agent_payment_verify_response;
+    const responseData = nestedResponse || verifyResponse;
+
+    if (responseData.code !== '10000' && responseData.code !== 10000) {
+      const errorCode = responseData.sub_code || responseData.errorCode;
+      const errorMessage = responseData.sub_msg || responseData.msg || '支付凭证验证失败';
+      console.error('支付凭证验证失败:', errorMessage);
       return res.status(400).json({
-        code: responseData.sub_code,
-        message: responseData.sub_msg
+        code: errorCode,
+        message: errorMessage
       });
     }
     
     // 4. 验证成功，获取订单信息
-    const {
-      trade_no: verifyTradeNo,
-      out_trade_no: verifyOutTradeNo,
-      resource_id: resourceId,
-      active
-    } = responseData;
+    // 同时兼容 SDK 的 snake_case 与 camelCase 业务字段。
+    const verifyTradeNo = responseData.trade_no || responseData.tradeNo || '';
+    const verifyOutTradeNo = responseData.out_trade_no || responseData.outTradeNo || '';
+    // 当前 demo 在沙箱字段为空时回退到固定资源；生产实现必须从本地订单读取并校验资源 ID。
+    const resourceIdVerified = responseData.resource_id || responseData.resourceId || CONFIG.resource.path;
+    const active = responseData.active;
+
+    if (process.env.A2M_DEBUG === 'true') {
+      console.log('验付响应字段:', {
+        code: responseData.code,
+        tradeNo: verifyTradeNo,
+        outTradeNo: verifyOutTradeNo,
+        resourceId: resourceIdVerified,
+        active
+      });
+    }
     
     console.log(`支付凭证验证成功：tradeNo=${verifyTradeNo}, outTradeNo=${verifyOutTradeNo}`);
     
@@ -323,7 +347,7 @@ async function verifyPaymentAndDeliverResource(req, res, paymentProof) {
     // }
     
     // 7. 【TODO】资源防串校验
-    // if (resourceId !== order.resourceId) {
+    // if (resourceIdVerified !== order.resourceId) {
     //   return res.status(403).json({
     //     code: 'RESOURCE_ID_MISMATCH',
     //     message: '资源 ID 不匹配，可能存在资源串改风险'
@@ -340,7 +364,7 @@ async function verifyPaymentAndDeliverResource(req, res, paymentProof) {
     // }
     
     // 9. 执行业务逻辑，生成资源内容
-    const serviceResult = generateServiceResource(resourceId);
+    const serviceResult = generateServiceResource(resourceIdVerified);
     
     // 10. 【TODO】履约记录落库（用于审计/售后/对账）
     // await fulfillmentRecordRepository.save({ ... });
@@ -356,10 +380,11 @@ async function verifyPaymentAndDeliverResource(req, res, paymentProof) {
     //   serviceResult
     // });
     
-    console.log(`资源已生成，准备发送履约确认：outTradeNo=${verifyOutTradeNo}, tradeNo=${verifyTradeNo}`);
-    
     // 12. 发送履约确认到支付宝，确认成功后才返回成功交付
-    const fulfillmentConfirmed = await sendFulfillmentConfirm(verifyTradeNo);
+    const fulfillmentTradeNo = verifyTradeNo || tradeNo;
+    console.log(`资源已生成，准备发送履约确认：outTradeNo=${verifyOutTradeNo}, tradeNo=${fulfillmentTradeNo}`);
+
+    const fulfillmentConfirmed = await sendFulfillmentConfirm(fulfillmentTradeNo);
     if (!fulfillmentConfirmed) {
       return res.status(502).json({
         code: 'FULFILLMENT_CONFIRM_FAILED',
@@ -373,14 +398,14 @@ async function verifyPaymentAndDeliverResource(req, res, paymentProof) {
     //   fulfilledAt: new Date()
     // });
 
-    console.log(`履约确认成功：outTradeNo=${verifyOutTradeNo}, tradeNo=${verifyTradeNo}`);
+    console.log(`履约确认成功：outTradeNo=${verifyOutTradeNo}, tradeNo=${fulfillmentTradeNo}`);
     
     // 13. 构造 Payment-Validation Header
     const paymentValidation = {
-      trade_no: verifyTradeNo,
+      trade_no: fulfillmentTradeNo,
       out_trade_no: verifyOutTradeNo,
       validated: true,
-      resource_id: resourceId
+      resource_id: resourceIdVerified
     };
     
     const paymentValidationEncoded = base64UrlEncode(JSON.stringify(paymentValidation));
@@ -388,9 +413,9 @@ async function verifyPaymentAndDeliverResource(req, res, paymentProof) {
     
     // 14. 返回资源内容
     res.json({
-      resource_id: resourceId,
+      resource_id: resourceIdVerified,
       content: serviceResult,
-      trade_no: verifyTradeNo,
+      trade_no: fulfillmentTradeNo,
       out_trade_no: verifyOutTradeNo,
       already_fulfilled: false,
       fulfillment_confirmed: true
@@ -422,6 +447,11 @@ function generateServiceResource(resourceId) {
  * 发送履约确认
  */
 async function sendFulfillmentConfirm(tradeNo) {
+  if (!tradeNo) {
+    console.error('履约确认失败：tradeNo 为空');
+    return false;
+  }
+
   try {
     console.log(`开始发送履约确认：tradeNo=${tradeNo}`);
     
@@ -433,11 +463,13 @@ async function sendFulfillmentConfirm(tradeNo) {
     
     // 注意：SDK 返回的响应可能是扁平结构，也可能嵌套在响应键下，需兼容两种情况
     const responseData = response.alipay_aipay_agent_fulfillment_confirm_response || response;
-    if (responseData.code === '10000') {
+    if (responseData.code === '10000' || responseData.code === 10000) {
       console.log(`履约确认成功：tradeNo=${tradeNo}`);
       return true;
     } else {
-      console.error(`履约确认失败：tradeNo=${tradeNo}, errorCode=${responseData.sub_code}, errorMsg=${responseData.sub_msg}`);
+      const errorCode = responseData.sub_code || responseData.errorCode;
+      const errorMessage = responseData.sub_msg || responseData.msg || '履约确认失败';
+      console.error(`履约确认失败：tradeNo=${tradeNo}, errorCode=${errorCode}, errorMsg=${errorMessage}`);
       return false;
     }
     
@@ -451,7 +483,7 @@ async function sendFulfillmentConfirm(tradeNo) {
 
 if (require.main === module) {
   app.listen(PORT, () => {
-    console.log(`A2M 智能收服务已启动：http://localhost:${PORT}${CONFIG.resource.path}`);
+    console.log(`A2M 按量付费服务已启动：http://localhost:${PORT}${CONFIG.resource.path}`);
     console.log('测试步骤：');
     console.log('1. 无 Payment-Proof Header: curl http://localhost:3000/demo/a2m/resource');
     console.log('2. 有 Payment-Proof Header: curl -H "Payment-Proof: <value>" http://localhost:3000/demo/a2m/resource');

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

@@ -20,8 +20,8 @@ $aop->signType = 'RSA2';
 
 // 构造请求参数
 $request = new AlipayTradePagePayRequest();
-$request->setNotifyUrl('https://your-domain.com/notify');  // 异步通知地址
-$request->setReturnUrl('https://your-domain.com/return');  // 同步跳转地址
+$request->setNotifyUrl('https://your-domain.com/notify');  // 真实生产或公网联调时传入；本地生产参数验收模式可临时不传，但仍需实现通知处理代码
+$request->setReturnUrl('https://your-domain.com/return');  // 默认传入并替换为已验证结果页；仅用户明确关闭同步回跳时省略
 
 $bizContent = [
     'out_trade_no' => date('YmdHis') . mt_rand(1000, 9999),  // 商户订单号
@@ -53,4 +53,4 @@ echo $response;
 <input type="submit" value="立即支付" style="display:none" >
 </form>
 <script>document.forms[0].submit();</script>
-```
+```

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

@@ -1,8 +1,13 @@
 <?php
 /**
  * A2M 智能收产品接入示例 - PHP 版本
+ *
+ * 本示例展示 A2M 核心协议与 SDK 调用流程。
+ * 订单持久化、本地订单匹配、金额一致性、资源防串、幂等履约和失败重试
+ * 需要结合商户实际数据库与订单模型实现。在上述控制完成实现并通过 checklist 前，
+ * 禁止将本文件原样用于生产或判定为生产就绪。
  * 
- * 本文件演示完整的智能收产品接入流程：
+ * 本文件演示 A2M 核心协议调用流程：
  * 1. 返回 402 Payment-Needed Header
  * 2. 验证 Payment-Proof 支付凭证
  * 3. 发送履约回执确认
@@ -19,7 +24,7 @@ define('ALIPAY_CONFIG', [
     'alipayPublicKey' => '<ALIPAY_PUBLIC_KEY>', // 请填写您的支付宝公钥
     'gateway' => 'https://openapi.alipay.com/gateway.do',
     'sellerId' => '<SELLER_ID_2088>', // 商户 ID（2088 格式）
-    'serviceId' => '<SERVICE_ID>', // 商户服务 ID
+    'serviceId' => 'api_mock_service_id', // 仅用于沙箱联调；上线前替换为服务市场真实 serviceId
     'merchantPrivateKey' => '<APP_PRIVATE_KEY>' // 请填写您的应用私钥（用于商家签名）
 ]);
 
@@ -73,9 +78,17 @@ function generateSellerSignature($params, $privateKey) {
     }
     $signString = implode('&', $signContent);
     
-    // 3. RSA2 签名
-    $privateKeyResource = openssl_pkey_get_private($privateKey);
-    openssl_sign($signString, $signature, $privateKeyResource, OPENSSL_ALGO_SHA256);
+    // 3. OpenSSL 需要 PEM；仅为本次签名临时包装裸 PKCS#1 Base64，不修改原始配置。
+    $privateKeyPem = "-----BEGIN RSA PRIVATE KEY-----\n"
+        . chunk_split($privateKey, 64, "\n")
+        . "-----END RSA PRIVATE KEY-----";
+    $privateKeyResource = openssl_pkey_get_private($privateKeyPem);
+    if ($privateKeyResource === false) {
+        throw new RuntimeException('无法解析 PKCS#1 应用私钥');
+    }
+    if (!openssl_sign($signString, $signature, $privateKeyResource, OPENSSL_ALGO_SHA256)) {
+        throw new RuntimeException('seller_signature 生成失败');
+    }
     
     return base64_encode($signature);
 }
@@ -118,7 +131,7 @@ function jsonResponse($data, $statusCode = 200, $headers = []) {
 /**
  * 智能收产品统一接口
  * 
- * 完整流程演示：
+ * 核心协议流程演示：
  * 1. 不带 Payment-Proof Header：返回 HTTP 402 + Payment-Needed Header
  * 2. 带 Payment-Proof Header：验证支付 → 自动履约 → 返回资源
  */
@@ -279,9 +292,11 @@ function verifyPaymentAndDeliverResource($paymentProof) {
         }
         
         // 4. 验证成功，获取订单信息
-        $verifyTradeNo = $verifyResponse->trade_no ?? null;
-        $verifyOutTradeNo = $verifyResponse->out_trade_no ?? null;
-        $resourceId = $verifyResponse->resource_id ?? null;
+        $verifyTradeNo = $verifyResponse->trade_no ?? $verifyResponse->tradeNo ?? '';
+        $verifyOutTradeNo = $verifyResponse->out_trade_no ?? $verifyResponse->outTradeNo ?? '';
+        $resourceId = $verifyResponse->resource_id ?? $verifyResponse->resourceId ?? '';
+        // 当前 demo 在沙箱字段为空时回退到固定资源；生产实现必须从本地订单读取并校验资源 ID。
+        $resourceIdVerified = !empty($resourceId) ? $resourceId : RESOURCE_CONFIG['path'];
         $active = $verifyResponse->active ?? null;
         
         error_log("支付凭证验证成功：tradeNo={$verifyTradeNo}, outTradeNo={$verifyOutTradeNo}");
@@ -322,7 +337,7 @@ function verifyPaymentAndDeliverResource($paymentProof) {
         // }
         
         // 9. 执行业务逻辑，生成资源内容
-        $serviceResult = generateServiceResource($resourceId);
+        $serviceResult = generateServiceResource($resourceIdVerified);
         
         // 10. 【TODO】履约记录落库（用于审计/售后/对账）
         // $fulfillmentRecordRepository->save([...]);
@@ -338,10 +353,11 @@ function verifyPaymentAndDeliverResource($paymentProof) {
         //     'serviceResult' => $serviceResult
         // ]);
 
-        error_log("资源已生成，准备发送履约确认：outTradeNo={$verifyOutTradeNo}, tradeNo={$verifyTradeNo}");
+        $fulfillmentTradeNo = $verifyTradeNo ?: $tradeNo;
+        error_log("资源已生成，准备发送履约确认：outTradeNo={$verifyOutTradeNo}, tradeNo={$fulfillmentTradeNo}");
 
         // 12. 发送履约确认到支付宝，确认成功后才返回成功交付
-        if (!sendFulfillmentConfirm($verifyTradeNo)) {
+        if (!sendFulfillmentConfirm($fulfillmentTradeNo)) {
             jsonResponse([
                 'code' => 'FULFILLMENT_CONFIRM_FAILED',
                 'message' => '资源已生成但履约确认失败，请稍后使用同一 Payment-Proof 重试'
@@ -354,23 +370,23 @@ function verifyPaymentAndDeliverResource($paymentProof) {
         //     'fulfilledAt' => date('c')
         // ]);
 
-        error_log("履约确认成功：outTradeNo={$verifyOutTradeNo}, tradeNo={$verifyTradeNo}");
+        error_log("履约确认成功：outTradeNo={$verifyOutTradeNo}, tradeNo={$fulfillmentTradeNo}");
         
         // 13. 构造 Payment-Validation Header
         $paymentValidation = [
-            'trade_no' => $verifyTradeNo,
+            'trade_no' => $fulfillmentTradeNo,
             'out_trade_no' => $verifyOutTradeNo,
             'validated' => true,
-            'resource_id' => $resourceId
+            'resource_id' => $resourceIdVerified
         ];
         
         $paymentValidationEncoded = base64UrlEncode(json_encode($paymentValidation, JSON_UNESCAPED_UNICODE));
         
         // 14. 返回资源内容
         jsonResponse([
-            'resource_id' => $resourceId,
+            'resource_id' => $resourceIdVerified,
             'content' => $serviceResult,
-            'trade_no' => $verifyTradeNo,
+            'trade_no' => $fulfillmentTradeNo,
             'out_trade_no' => $verifyOutTradeNo,
             'already_fulfilled' => false,
             'fulfillment_confirmed' => true
@@ -402,6 +418,11 @@ function generateServiceResource($resourceId) {
  * 发送履约确认
  */
 function sendFulfillmentConfirm($tradeNo) {
+    if (empty($tradeNo)) {
+        error_log('履约确认失败：tradeNo 为空');
+        return false;
+    }
+
     try {
         error_log("开始发送履约确认：tradeNo={$tradeNo}");
         

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

@@ -20,8 +20,8 @@ config.sign_type = "RSA2"
 client = DefaultAlipayClient(alipay_client_config=config)
 
 request = AlipayTradePagePayRequest()
-request.notify_url = "https://your-domain.com/notify"  # 异步通知地址，必须传入
-request.return_url = "https://your-domain.com/return"  # 同步跳转地址，必须传入
+request.notify_url = "https://your-domain.com/notify"  # 真实生产或公网联调时传入；本地生产参数验收模式可临时不传，但仍需实现通知处理代码
+request.return_url = "https://your-domain.com/return"  # 默认传入并替换为已验证结果页；仅用户明确关闭同步回跳时省略
 
 model = AlipayTradePagePayModel()
 model.out_trade_no = "MERCHANT_ORDER_NO_PLACEHOLDER"             # 商户订单号，必填
@@ -45,4 +45,4 @@ print(form_html)
 <input type="submit" value="立即支付" style="display:none" >
 </form>
 <script>document.forms[0].submit();</script>
-```
+```

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

@@ -3,14 +3,19 @@
 """
 A2M 智能收产品接入示例 - Python 版本
 
-本文件演示完整的智能收产品接入流程：
+本示例展示 A2M 核心协议与 SDK 调用流程。
+订单持久化、本地订单匹配、金额一致性、资源防串、幂等履约和失败重试
+需要结合商户实际数据库与订单模型实现。在上述控制完成实现并通过 checklist 前，
+禁止将本文件原样用于生产或判定为生产就绪。
+
+本文件演示 A2M 核心协议调用流程：
 1. 返回 402 Payment-Needed Header
 2. 验证 Payment-Proof 支付凭证
 3. 发送履约回执确认
 4. 返回资源内容
 
 依赖安装：
-pip install flask alipay-sdk-python
+pip install flask alipay-sdk-python pycryptodome
 
 注意：Python SDK 3.7+ 版本必须使用 Model 类（如 AlipayAipayAgentPaymentVerifyModel），
 不能直接使用 dict 赋值给 biz_model，因为 SDK 会调用 to_alipay_dict() 方法。
@@ -41,7 +46,7 @@ ALIPAY_CONFIG = {
     'alipayPublicKey': '<ALIPAY_PUBLIC_KEY>',  # 请填写您的支付宝公钥
     'gateway': 'https://openapi.alipay.com/gateway.do',
     'sellerId': '<SELLER_ID_2088>',  # 商户 ID（2088 格式）
-    'serviceId': '<SERVICE_ID>',  # 商户服务 ID
+    'serviceId': 'api_mock_service_id',  # 仅用于沙箱联调；上线前替换为服务市场真实 serviceId
     'merchantPrivateKey': '<APP_PRIVATE_KEY>'  # 请填写您的应用私钥（用于商家签名）
 }
 
@@ -96,8 +101,9 @@ def generate_seller_signature(params, private_key):
     
     sign_string = '&'.join(sign_content)
     
-    # 3. RSA2 签名
-    key = RSA.import_key(private_key)
+    # 3. 将裸 PKCS#1 Base64 临时解码为 DER 密钥对象，不修改原始配置。
+    key_der = base64.b64decode(private_key, validate=True)
+    key = RSA.import_key(key_der)
     h = SHA256.new(sign_string.encode('utf-8'))
     signature = pkcs1_15.new(key).sign(h)
     
@@ -143,7 +149,7 @@ def handle_resource():
     """
     智能收产品统一接口
     
-    完整流程演示：
+    核心协议流程演示：
     1. 不带 Payment-Proof Header：返回 HTTP 402 + Payment-Needed Header
     2. 带 Payment-Proof Header：验证支付 → 自动履约 → 返回资源
     """
@@ -306,9 +312,11 @@ def verify_payment_and_deliver_resource(payment_proof):
             }, 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')
+        verify_trade_no = response_data.get('trade_no') or response_data.get('tradeNo') or ''
+        verify_out_trade_no = response_data.get('out_trade_no') or response_data.get('outTradeNo') or ''
+        resource_id = response_data.get('resource_id') or response_data.get('resourceId') or ''
+        # 当前 demo 在沙箱字段为空时回退到固定资源；生产实现必须从本地订单读取并校验资源 ID。
+        resource_id_verified = resource_id or RESOURCE_CONFIG['path']
         active = response_data.get('active')
         
         print(f"支付凭证验证成功：tradeNo={verify_trade_no}, outTradeNo={verify_out_trade_no}")
@@ -345,7 +353,7 @@ def verify_payment_and_deliver_resource(payment_proof):
         #     }, status_code=200)
         
         # 9. 生成资源内容
-        service_result = generate_service_resource(resource_id)
+        service_result = generate_service_resource(resource_id_verified)
         
         # 10. 【TODO】履约记录落库
         # fulfillment_record_repository.save({...})
@@ -361,11 +369,12 @@ def verify_payment_and_deliver_resource(payment_proof):
         #     'service_result': service_result
         # })
 
-        print(f"资源已生成，准备发送履约确认：outTradeNo={verify_out_trade_no}, tradeNo={verify_trade_no}")
+        fulfillment_trade_no = verify_trade_no or trade_no
+        print(f"资源已生成，准备发送履约确认：outTradeNo={verify_out_trade_no}, tradeNo={fulfillment_trade_no}")
 
         # 12. 发送履约确认到支付宝，确认成功后才返回成功交付
         # 注意：同样需要使用 Model 类
-        if not send_fulfillment_confirm(verify_trade_no):
+        if not send_fulfillment_confirm(fulfillment_trade_no):
             return json_response({
                 'code': 'FULFILLMENT_CONFIRM_FAILED',
                 'message': '资源已生成但履约确认失败，请稍后使用同一 Payment-Proof 重试'
@@ -377,23 +386,23 @@ def verify_payment_and_deliver_resource(payment_proof):
         #     'fulfilled_at': datetime.now(timezone.utc).astimezone().isoformat()
         # })
 
-        print(f"履约确认成功：outTradeNo={verify_out_trade_no}, tradeNo={verify_trade_no}")
+        print(f"履约确认成功：outTradeNo={verify_out_trade_no}, tradeNo={fulfillment_trade_no}")
         
         # 13. 构造 Payment-Validation Header
         payment_validation = {
-            'trade_no': verify_trade_no,
+            'trade_no': fulfillment_trade_no,
             'out_trade_no': verify_out_trade_no,
             'validated': True,
-            'resource_id': resource_id
+            'resource_id': resource_id_verified
         }
         
         payment_validation_encoded = base64url_encode(json.dumps(payment_validation, ensure_ascii=False))
         
         # 14. 返回资源内容
         return json_response({
-            'resource_id': resource_id,
+            'resource_id': resource_id_verified,
             'content': service_result,
-            'trade_no': verify_trade_no,
+            'trade_no': fulfillment_trade_no,
             'out_trade_no': verify_out_trade_no,
             'already_fulfilled': False,
             'fulfillment_confirmed': True
@@ -420,6 +429,10 @@ def generate_service_resource(resource_id):
 
 def send_fulfillment_confirm(trade_no):
     """发送履约确认"""
+    if not trade_no:
+        print("履约确认失败：tradeNo 为空")
+        return False
+
     try:
         print(f"开始发送履约确认：tradeNo={trade_no}")
         
@@ -457,7 +470,7 @@ def send_fulfillment_confirm(trade_no):
 # ==================== 启动服务 ====================
 
 if __name__ == '__main__':
-    print(f"A2M 智能收服务已启动：http://localhost:5000{RESOURCE_CONFIG['path']}")
+    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"]}')

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

@@ -66,7 +66,7 @@
 | --- | --- | --- | --- | --- | --- | --- |
 | 统一收单下单并支付页面接口 | [文档](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`，适用于电脑网页与手机网页场景。
+> **说明**：网站支付使用统一收单下单并支付页面接口 `alipay.trade.page.pay`，适用于电脑网页与手机网页场景。上表仅是接口调用示例，实际集成不得止于设置 `return_url`；用户未明确关闭同步回跳时，必须继续按 `alipay-sdk-reminder.md` 的“网站支付同步回跳”实现并验证结果页。本地未上线场景的异步通知口径以 `../flow.md` 为准。
 
 ### APP支付 API
 
@@ -81,10 +81,14 @@
 ### 按量付费
 - 使用 `4-按量付费/` 目录下的代码示例
 - 按量付费**不需要**参考通用接口
-- 示例中的 `sellerId`、`serviceId`、`appId`、`alipayPublicKey` 只能作为占位说明。正式集成时必须替换为签约入驻产物：`sellerId` 来自商户 PID/2088，`serviceId` 来自服务市场注册或复用结果，`appId/alipayPublicKey` 来自应用发布或复用结果。
-- 生成按量付费代码时必须补齐订单持久化、本地订单匹配、资源防串、幂等履约和履约确认失败可重试逻辑；不要把示例中的内存/占位实现当作生产实现。
+- 五语言 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`、验签、幂等和补偿查询。