@alipay/alipay-aipay 0.1.1-beta.1

package/skill/references/integration/flow.md

@@ -0,0 +1,487 @@
+# 支付产品集成流程
+
+> ⚠️ **前置声明**：本 flow 仅支持**网站支付、APP支付、按量付费**三种产品的集成。**其他产品（当面付、订单码支付、JSAPI支付、预授权支付、商家扣款等）暂不支持**，如需集成请前往[支付宝开放平台](https://open.alipay.com/)查阅相关文档。
+
+---
+
+## 📂 文件路由表
+
+> 本文件位于 `references/integration/`。下表中的 `modules/...`、`../normal/...` 路径均相对本文件所在目录；若从技能包根目录定位，请加前缀 `references/integration/`。
+
+| 文件 | 说明 | 引用位置 |
+|------|------|----------|
+| **flow.md** | ⭐ 主入口 - 集成流程全览（本文档） | - |
+| **../normal/** | 通用模块 | - |
+| ↳ ../normal/alipay-cli-env.md | alipay-cli 检测与安装 | 步骤 2 沙箱初始化 |
+| ↳ ../normal/rejection-guide.md | 拒绝引导话术 | 通用 |
+| ↳ ../normal/scripts/detect_dev_tool.sh | AI编程工具检测 | 步骤 2 沙箱初始化 |
+| ↳ ../normal/scripts/common.sh | shell 公共函数与初始化入口 | 通用 shell 脚本公共依赖 |
+| **modules/** | 子模块目录 | - |
+| ↳ modules/product-decision.md | 产品决策说明 | 步骤 1 产品决策 |
+| **modules/sandbox/** | 沙箱模块 | - |
+| ↳ modules/sandbox/sandbox-setup-guide.md | 沙箱配置指南 | 步骤 2 沙箱初始化 |
+| ↳ modules/sandbox/alipay-sandbox-tool.md | 沙箱工具使用 | 步骤 2 沙箱初始化 |
+| ↳ modules/alipay-sdk-reminder.md | SDK防坑指南 | 步骤 3 集成前置 |
+| ↳ modules/interface-guide.md | 接口说明与代码示例索引 | 步骤 3 集成前置 / 步骤 4 代码生成 |
+| **modules/code-examples/** | 代码示例目录 | 步骤 4 代码生成 |
+| ↳ modules/code-examples/python/ | Python 代码示例 | 步骤 4 |
+| ↳ modules/code-examples/java/ | Java 代码示例 | 步骤 4 |
+| ↳ modules/code-examples/nodejs/ | Node.js 代码示例 | 步骤 4 |
+| ↳ modules/code-examples/csharp/ | C# 代码示例 | 步骤 4 |
+| ↳ modules/code-examples/php/ | PHP 代码示例 | 步骤 4 |
+| ↳ modules/sandbox/a2m-sandbox-test.md | 按量付费沙箱测试 | 步骤 5 按量付费测试 |
+| ↳ modules/scripts/local_402_sandbox_pay.py | 402沙箱收银测试脚本 | 步骤 5 按量付费测试 |
+| ↳ modules/checklist.md | 集成校验清单 | 步骤 7 集成校验 |
+
+> 📌 **使用建议**：从 flow.md 主入口开始，按流程顺序执行各步骤。需要查看详情时，通过上表快速定位对应文件。
+
+---
+
+## ⛔ 强制执行要点
+
+### 强阻塞阅读项，必须遵循，否则违规！
+
+1. **先定计划再动手**：执行任何操作之前，**必须先确定功能分支并打印完整的待办步骤清单**，禁止未确定计划就直接开始执行
+2. **必须获得用户同意**：未经用户同意，禁止启动集成流程
+3. **单一产品原则**：一次只能集成一个产品，完成后再讨论下一个
+4. **禁止假数据**：禁止编造沙箱配置或使用占位符
+5. **阻塞确认点**：必须等待用户明确回复后才能继续下一步
+6. **禁止合理化跳过确认**：禁止用"用户可能希望快速完成"、"这是一个简单场景"等理由跳过阻塞确认点
+7. **禁止假数据与占位符冒充**：沙箱成功返回完整配置时，禁止用占位符代替真实返回值；禁止自行生成示例私钥、示例账号等假数据
+8. **先阅读文档再执行**：每个步骤必须先阅读相关文档，完成该步骤的**完成条件**自检后，方可进入下一步
+9. **生产密钥替换提醒**：当用户要求直接替换生产环境密钥配置，或声称已替换完成并要求启动生产环境支付测试时，必须先基于项目编程语言和应用私钥格式提醒用户：`appId`、应用公钥、应用私钥必须属于同一套应用密钥；应用私钥格式必须与语言 SDK 匹配，格式不匹配时使用支付宝开放平台密钥工具做私钥格式转换。
+10. **依据不足时不编造**：代码集成、SDK 使用、应用创建、应用发布等问题若没有确定依据，必须说明无法确认，并引导用户前往[支付宝开放平台](https://open.alipay.com/)或[支付宝技术支持](https://opensupport.alipay.com/support/intelligent-services?form=payskill)咨询客服；不得猜测接口能力、审核规则或处理时效。
+
+### 服务声明
+
+> ⚠️ **服务声明**：使用本 Skill 即表示您同意：
+> （1）使用本服务需遵守法律法规、自行审核测试并承担使用责任，我方不对使用效果、正确性担保。
+> （2）禁止在代码、大模型对话等公网透露敏感信息（密码、API Keys、私钥等）。
+
+### ⚠️ 反面案例（严禁行为）
+
+Agent 出现如下任何一种行为即视为违规：
+
+- 在未完整输出本 Skill 要求的**待办步骤清单**前，开始输出代码
+- 因用户指令中存在"快速接入"、"快点"、"赶紧"等催促关键词而简化本 Skill 中执行流程，不再输出本 Skill 规定的完整待办步骤清单
+- 跳步、合并步骤
+- 进行"我认为..."、"简化起见..."等自行判断
+- **绕过阻塞确认**：在 `<BLOCKING_CONFIRMATION>` 确认点，禁止以任何理由跳过等待，禁止假设用户已同意或使用"我将继续..."等单方面声明代替用户确认
+- **合理化跳过确认**：用"用户可能希望快速完成"、"这是一个简单场景"、"用户没说不要"等理由合理化跳过阻塞确认点，实际行动仍继续执行而非等待
+
+---
+
+## 阻塞确认点索引
+
+| 位置 | 触发时机 | 等待内容 |
+|------|----------|----------|
+| 步骤 1 | 产品决策后 | 用户同意服务声明并确认接入特定产品 |
+| 步骤 5 | 按量付费测试前 | 用户确认服务已启动并准备好进行沙箱付款测试 |
+| 步骤 7 | 集成完成后 | 用户确认是否需要进行集成校验 |
+
+---
+
+## 完成条件索引
+
+| 步骤 | 标记 | 完成条件数量 |
+|------|------|--------------|
+| 步骤 1 产品决策 | [M-01] | 4 项 |
+| 步骤 2 沙箱初始化 | [M-02] | 5 项 |
+| 步骤 3 集成前置 | [M-03] | 4 项 |
+| 步骤 4 集成代码 | [M-04] | 3 项 |
+| 步骤 5 按量付费沙箱测试 | [M-05] | 6 项（仅按量付费） |
+| 步骤 6 集成后说明 | [M-06] | 2 项 |
+| 步骤 7 集成校验 | [M-07] | 1 项 |
+
+---
+
+## 📖 产品文档路由
+
+根据用户的业务场景，路由到对应的产品文档：
+
+| 支付产品 | 核心 API | 在线文档 |
+|----------|----------|----------|
+| 按量付费 | `alipay.aipay.agent.payment.verify` + `alipay.aipay.agent.fulfillment.confirm` | [按量付费文档](https://ideservice.alipay.com/cms/site/0jaqax) |
+| 网站支付 | `alipay.trade.page.pay` | [网站支付文档](https://ideservice.alipay.com/cms/site/0iztfv) |
+| APP支付 | `alipay.trade.app.pay` | [APP支付文档](https://ideservice.alipay.com/cms/site/0izsn4) |
+
+---
+
+## 功能路由
+
+根据用户意图判断：
+
+| 用户意图 | 处理方式 |
+|----------|----------|
+| 需要集成支付产品 | 进入集成流程 |
+| 集成中遇到报错 | 进入问题排查流程 |
+
+---
+
+## 集成流程（7步 / 网站支付和APP支付跳过步骤5，共6步）
+
+### 步骤 1：产品决策
+
+**任务**：根据用户场景确定要集成的产品
+
+**完成条件**：
+- [M-01] 已确认用户服务端开发语言（Java / Python / Node.js / C# / PHP 五选一）
+- [M-01] 已根据用户场景决策出支付产品
+- [M-01] 已征得用户明确同意
+- [M-01] 已输出服务声明并获得用户同意
+
+| 场景关键词 | 产品 |
+|------------|------|
+| AI、智能体、大模型、Agent、API、算力、402协议 | 按量付费 |
+| 网站、网页、PC、电商、商城、H5、手机网页 | 网站支付 |
+| APP、应用内支付、手机APP、iOS、Android、鸿蒙 | APP支付 |
+| 模糊场景 | 引用 modules/product-decision.md 进行澄清 |
+
+<BLOCKING_CONFIRMATION>
+
+**确认点：产品决策**
+
+输出产品选择后，**必须暂停等待用户确认**，按以下顺序执行：
+
+1. **确认开发语言**：询问用户项目使用什么服务端开发语言（Java / Python / Node.js / C# / PHP）
+2. **输出决策结果**：告知用户推荐的支付产品及选择理由
+3. **输出服务声明**（完整打印）
+4. **显式询问确认**：
+   > "请问您是否同意上述服务声明并确认接入【{产品名称}】？请回复'同意'或'确认'后，我将继续后续步骤。"
+5. **等待用户回复**：必须收到用户明确同意的回复后，方可进入步骤2。
+
+</BLOCKING_CONFIRMATION>
+
+---
+
+### 步骤 2：沙箱初始化
+
+**任务**：创建沙箱测试环境
+
+> ⚠️ **前置要求**：在调用沙箱工具前，必须先按 `../normal/alipay-cli-env.md` 完成 alipay-cli 检测与安装
+>
+> ⚠️ **必须完整阅读** `modules/sandbox/sandbox-setup-guide.md` 后方可执行本步骤
+
+**完成条件**：
+- [M-02] **必须**已完整阅读 `modules/sandbox/sandbox-setup-guide.md`（含强校验规则、输出格式、红线禁止）
+- [M-02] 已检测用户操作系统类型
+- [M-02] Unix/macOS/Linux：已调用沙箱工具成功创建环境
+- [M-02] Windows：已引导用户自行获取沙箱信息
+- [M-02] 已按文档要求完成沙箱信息强校验（**逐项核对必含字段清单**），并完整输出
+
+**操作流程**：
+1. 检测用户操作系统（Windows/macOS/Linux）
+2. Windows用户：引导自行获取沙箱信息，参考 `modules/sandbox/sandbox-setup-guide.md` 第 1.2 节
+3. Unix/macOS/Linux用户：调用沙箱工具创建环境
+
+**⚠️ 沙箱信息输出格式（必须严格遵循）**：
+
+> 详细输出格式见 `modules/sandbox/sandbox-setup-guide.md` 第 3.2 节
+>
+> **必须按表格格式输出**，包含以下全部内容：
+
+| 类别 | 必含字段 |
+|------|---------|
+| 应用配置 | `appId`、`appPrivateKey`、`appPrivatePkcsKey`、`alipayPublicKey`、`appPublicKey`、`pid` |
+| 商家账号 | `accountDesc`、`email`、`merchantId`、`userId`、`acctrans` |
+| 买家账号 | `accountDesc`、`email`、`userName`、`userId`、`logonPassword`、`payPassword` |
+| 沙箱信息 | `sandboxId`、`sandboxName` |
+
+**强校验规则**：
+- 工具返回后，**必须逐项核对**上述必含字段是否存在且非空
+- 如有字段缺失，**阻断流程**，要求重新创建
+- 后续步骤将沙箱配置写入用户项目后，必须做配置准确性后置校验，确认写入值来自同一份沙箱返回配置，且与沙箱返回值一致、字段选择正确、SDK 配置匹配、无占位符或截断。校验失败必须阻断后续联调，先重新复制沙箱字段或修正 SDK 配置。
+
+**绝对禁止**：
+- ❌ 禁止编造字段
+- ❌ 禁止用占位符（xxx）代替真实返回值
+- ❌ 禁止用示例假数据（如 `MIIEvw...`）冒充
+- ❌ 禁止使用 JSON 代码块输出
+- ❌ 禁止省略任何字段
+
+> ⚠️ 详细操作、输出格式、强校验规则、红线禁止请参阅 `modules/sandbox/sandbox-setup-guide.md`
+
+---
+
+### 步骤 3：集成前置
+
+**任务**：阅读SDK使用要点和产品文档
+
+**完成条件**：
+- [M-03] 已阅读 `modules/alipay-sdk-reminder.md` 完整内容（私钥格式、页面跳转方法、验签排查等）
+- [M-03] 已理解 SDK 选择和 SDK 防幻觉强制规则
+- [M-03] 已递归读取产品在线文档（快速接入、接口列表、异步通知等）
+- [M-03] 已阅读产品相关接口代码示例
+
+**产品在线文档访问**：
+
+> ⚠️ **必须参考上方「📖 产品文档路由」章节**，选择用户对应的产品，使用 curl 获取对应在线文档：
+```bash
+curl -sL "https://ideservice.alipay.com/cms/site/{文档ID}"
+```
+递归阅读产品在线文档中的快速接入、接口列表、异步通知、注意事项等部分，了解产品特有逻辑。
+
+**必须阅读的文件**：
+- `modules/alipay-sdk-reminder.md` - SDK防坑指南（含私钥格式、页面跳转方法、验签排查等）
+- `modules/product-decision.md` - 产品决策说明
+- `modules/interface-guide.md` - 接口说明与代码示例索引（在阅读产品在线文档后，按需读取相关接口的代码示例）
+
+**🚫 SDK 防幻觉强制规则**：
+
+> ⚠️ 以下规则来自真实集成踩坑，违反将导致集成失败。详细说明和各语言操作对照见 [SDK 说明文档](modules/alipay-sdk-reminder.md)，**严禁**在未读取该文档的情况下生成代码或给出建议。
+
+| # | 规则 | 禁令 |
+|---|------|------|
+| 1 | 私钥字段按语言选择沙箱返回值 | Java 使用 `appPrivateKey`（PKCS#8），非 Java 使用 `appPrivatePkcsKey`（PKCS#1），禁止自行生成或格式转换 |
+| 2 | 页面跳转类 API 必须使用页面跳转方法 | `alipay.trade.page.pay` 等必须使用 `pageExecute()`/`pageExec()`，使用 `exec()` 将无法获取支付表单 |
+| 3 | 前端禁止用 URL 直接跳转支付表单 | 支付接口返回的是 HTML 表单，必须渲染并自动提交 form，直接用 URL 跳转会导致页面只显示参数而无法跳转支付宝 |
+| 4 | 时间戳格式 | 必须使用 `yyyy-MM-dd HH:mm:ss`，禁止使用 ISO 格式 |
+| 5 | SDK 引入方式 | 必须通过查阅 SDK 文档或类型定义确定正确的引入方式，禁止凭猜测选择 |
+| 6 | 遇到 `invalid-signature` 报错 | 严禁凭猜测归因到私钥格式，最常见原因是请求参数不完整（如 `return_url` 未传入） |
+| 7 | 配置写入后必须后置校验 | 必须确认写入配置来自同一份沙箱返回配置、与沙箱返回配置一致、字段映射正确、SDK 配置匹配；失败时禁止继续联调 |
+
+---
+
+### 步骤 4：代码生成
+
+**任务**：根据用户选择的开发语言和产品，生成集成代码
+
+**完成条件**：
+- [M-04] 已完成支付宝支付产品集成代码实现
+- [M-04] 已完成代码自检并确认无误
+- [M-04] 已完成支付配置准确性后置校验，确认写入配置来自同一份沙箱返回配置、与沙箱返回配置一致、字段映射正确、SDK 配置匹配
+
+**代码示例位置**：
+```
+modules/code-examples/
+├── python/        # 1-通用接口 2-网站支付 3-APP支付 4-按量付费
+├── java/          # 同上
+├── nodejs/        # 同上
+├── csharp/        # 同上
+└── php/           # 同上
+```
+
+**重要规则**：
+- 按量付费：直接使用 `4-按量付费/` 目录下的代码示例
+- 网站支付/APP支付：**必须同时参考**：
+  1. 对应产品的专用接口（`2-网站支付/` 或 `3-APP支付/`）
+  2. 通用接口 `1-通用接口/`（交易查询、退款、退款查询、关闭交易等）
+
+**代码生成前自检**：
+输出代码前必须逐条自检（按量付费请注意标有 ⚠️ 的项目）：
+1. 私钥字段：Java 用 `appPrivateKey`，非 Java 用 `appPrivatePkcsKey`？
+2. SDK 引入方式：已通过查阅 SDK 文档或类型定义确定？
+3. 页面跳转类 API：使用 `pageExec()` 而非 `exec()`？（⚠️ 不适用于按量付费，按量付费使用 `execute()` 调用 Server API）
+4. 时间戳格式：`yyyy-MM-dd HH:mm:ss`？
+5. 前端支付表单：渲染 HTML 并自动提交？（⚠️ 不适用于按量付费，按量付费在服务端返回 HTTP 402 响应头）
+6. 沙箱配置：无编造/假数据？
+7. 代码示例：已查阅当前语言的产品类别 + 通用接口？
+8. 配置后置校验：是否已确认写入配置来自同一份沙箱返回配置、与沙箱返回配置一致、字段映射正确、SDK 配置匹配？
+
+**按量付费生产实现边界**：
+- 返回 `Payment-Needed` 前必须把 `out_trade_no`、`resource_id`、金额、订单状态和过期时间持久化到商户数据库。内存仓储只适合本地临时演示，服务重启后旧付款链接无法继续履约。
+- `alipay.aipay.agent.payment.verify` 成功只代表支付宝支付凭证有效；交付资源前仍必须映射回商户本地订单，并校验订单状态、金额、资源归属和幂等履约状态。
+- 沙箱联调中 `outTradeNo`、`resourceId` 等验付响应字段可能出现空字符串，排查时先判断字段是否非空再定位问题；生产环境不得因字段为空而跳过核心校验，应按异常凭证或异常订单处理。
+- 资源生成后先保存履约结果为可重试状态，再调用 `alipay.aipay.agent.fulfillment.confirm`。确认成功后才标记订单为 `FULFILLED` 并返回成功交付；确认失败时保留结果并允许同一笔 `Payment-Proof` 重试。
+
+> ⚠️ **按量付费**：代码生成后请启动本地服务，后续步骤 5 将进行端到端沙箱支付测试。服务需实现 402 协议（无 Payment-Proof 时返回 HTTP 402 + Payment-Needed 头）。
+
+---
+
+### 步骤 5：按量付费沙箱测试（仅按量付费）
+
+> ⚠️ **仅当产品为「按量付费」时执行此步骤**。网站支付和APP支付直接跳过本步骤，进入步骤 6。
+
+**任务**：验证按量付费 402 协议端到端支付流程
+
+> ⚠️ **必须完整阅读** `modules/sandbox/a2m-sandbox-test.md` 后方可执行本步骤
+>
+> 沙箱联调经验集中维护在 `modules/sandbox/a2m-sandbox-test.md`。遇到收银接口临时失败、`ORDER_NOT_FOUND`、资源防串失败或履约确认失败时，先按该文档排查，不要反复请求用户服务生成新订单。
+
+**完成条件**：
+- [M-05] 已确认用户本地按量付费服务已启动可访问
+- [M-05] 已执行 Payment-Needed 预检，确认 HTTP 402 和关键字段存在
+- [M-05] 已执行沙箱支付测试脚本 `run`，成功获取 Payment-Needed 并生成付款链接
+- [M-05] 用户已在浏览器使用沙箱买家账号完成付款
+- [M-05] 已携带 Payment-Proof 重试原服务并验证响应成功
+- [M-05] 已确认全链路 402 支付流程通过
+
+**测试前预检**：执行沙箱测试脚本前，先按 `modules/sandbox/a2m-sandbox-test.md` 的“测试前预检”确认服务返回 HTTP 402，且 Payment-Needed 包含 `seller_signature` 等关键字段。
+
+**沙箱支付宝提醒**：用户进入付款环节前，必须按 `modules/sandbox/a2m-sandbox-test.md` 提醒沙箱支付宝当前仅支持安卓系统，并提供沙箱版支付宝安装包下载说明。
+
+<BLOCKING_CONFIRMATION>
+
+**确认点：按量付费沙箱测试**
+
+输出测试说明后，**必须暂停等待用户确认**，按以下顺序执行：
+
+1. **确认服务就绪**：询问用户是否已完成代码集成并启动本地服务
+2. **收集测试参数**：
+   - 服务请求地址（含 GET 参数）
+   - HTTP 方法（GET / POST）
+   - 沙箱买家 2088 账号（从步骤 2 获取的 `userId`）
+3. **显式询问确认**：
+   > "以上信息确认无误后，我将执行沙箱支付测试脚本。是否继续？请回复'确认'或'继续'。"
+4. **等待用户回复**：必须收到用户明确回复后，方可调用测试脚本。
+
+> 详细测试流程见 `modules/sandbox/a2m-sandbox-test.md`
+
+</BLOCKING_CONFIRMATION>
+
+---
+
+### 步骤 6：集成后说明
+
+**任务**：输出安全红线和后续指引
+
+**完成条件**：
+- [M-06] 已向用户明文打印安全红线
+- [M-06] 已向用户输出完整的后续指引
+
+**安全红线（必须明文打印给用户）**：
+
+> 以下为通用安全红线，所有产品均需遵守。按量付费产品请额外关注标有 🤖 的项目。
+
+- 私钥禁止存客户端：构造交易数据并签名必须在商家服务端完成，私钥严禁保存在 APP 客户端
+- 私钥禁止记日志：私钥不得出现在任何日志中
+- 私钥禁止传公共仓库：私钥不得上传到 GitHub、GitLab 等公共代码仓库
+- 前台支付结果不可信：前台同步跳转结果不可信，必须以支付宝异步通知或调用交易查询接口获取结果为准（⚠️ 不适用于按量付费，按量付费依赖 `alipay.aipay.agent.payment.verify` 接口验证支付凭证）
+- 未确认不重付：在未确认支付结果前，不得要求用户再次付款
+- 异步通知必须先验签：收到异步通知后必须先验签，确保通知来自支付宝（⚠️ 不适用于按量付费，按量付费不使用异步通知）
+- 🤖 Payment-Proof 必须验证：收到 Payment-Proof 头后必须调用 `alipay.aipay.agent.payment.verify` 验证凭证有效性
+- 🤖 履约必须确认：服务交付后必须调用 `alipay.aipay.agent.fulfillment.confirm` 发送履约确认
+- 🤖 凭证不过期复用：验证 `active` 字段，已过期的支付凭证拒绝服务
+
+**后续指引**：
+> 当前配置为沙箱测试环境，仅用于开发调试（沙箱环境无法测试异步通知，请在生产环境进行检查）。上线前请将 appId、私钥、公钥等配置替换为线上正式环境的配置信息，并认真进行人工代码审查。
+
+**生产密钥配置提醒（生产支付测试前必须输出）**：
+- `appId`、应用公钥、应用私钥必须来自同一套生产应用密钥；不要混用沙箱应用、其他生产应用或重新生成的另一套密钥。
+- 根据项目编程语言确认应用私钥格式：Java 使用 PKCS#8，非 Java（Node.js、Python、PHP、.NET 等）使用 PKCS#1。
+- 如果生产应用私钥格式与当前语言 SDK 要求不一致，请使用支付宝开放平台密钥工具进行私钥格式转换后再写入配置。
+- 写入配置时仍使用不带 PEM 头尾、包装行或说明文字的原始私钥字符串。
+
+**签约衔接提醒（必须输出）**：
+- 如果当前意图是 `integration_only`：提醒用户正式上线前还需要完成对应产品的商家签约/入驻。
+- 如果当前意图是 `full_process`：继续引导进入 `references/onboarding/flow.md`，完成对应产品签约/入驻。
+
+---
+
+### 步骤 7：集成校验
+
+**完成条件**：
+- [M-07] 已获得用户同意并按照集成校验清单逐项校验并输出结果
+
+<BLOCKING_CONFIRMATION>
+
+**确认点：集成校验**
+
+输出步骤 6 的内容后，**必须暂停并询问用户**：
+> "支付能力集成已完成。为确保集成质量，我可按照集成校验清单帮您逐项校验（包括签名验签、异步通知、异常处理等）。请问您是否需要进行集成校验？请回复'需要'或'确认'后，我将开始校验。"
+
+</BLOCKING_CONFIRMATION>
+
+校验项包括：
+- 签名验签
+- 异步通知
+- 异常处理
+
+> 详细校验清单见 `modules/checklist.md`
+
+---
+
+## 问题排查流程（功能二）
+
+**触发条件**：用户在集成支付宝支付产品过程中遇到报错或其他问题。触发关键词："报错"、"错误码"、"问题"、"排查"、"调试"、"异常"等。
+
+执行下述问题排查步骤之前，**必须明确用户当前集成的支付产品**（按量付费/网站支付/APP支付），否则暂停输出并要求用户澄清。
+
+### 问题识别与分流
+
+根据用户输入判断问题类型，分流到对应排查路径：
+
+```
+用户问题
+    |
+    +-- 验签失败（invalid-signature / 验签出错）  ← 优先匹配
+    |       |
+    |       └───> 常见问题排查（验签失败专项）
+    |
+    +-- 有明确错误码（如 "ACQ.TRADE_HAS_SUCCESS"、"INVALID_PARAMETER"）
+    |       |
+    |       └───> 错误码排查
+    |
+    +-- 无明确错误码（如流程疑问、功能异常等）
+            |
+            └───> 常见问题排查
+```
+
+### 错误码排查
+
+**适用**：用户提供了明确的错误码。
+
+错误码查询前，**必须确认发生报错的接口信息**，否则暂停输出并要求用户澄清。
+
+#### 排查流程
+
+1. **查公共错误码**：查阅 [公共错误码说明](https://ideservice.alipay.com/cms/site/02km9f)，根据用户提供的错误码检索相关内容。如有匹配结果，**输出排查结论**；否则，**查业务错误码**。
+
+2. **查业务错误码**：基于确定的支付产品和报错接口信息，查阅对应产品文档，在接口文档中根据错误码检索相关内容。
+
+3. **输出排查结论**：根据查询到的错误码关联内容，输出排查结论。
+
+### 常见问题排查
+
+**适用**：无明确错误码的其他类型问题，或错误码为 `invalid-signature`（验签出错）。
+
+#### 排查流程
+
+1. 根据用户输入和确定的支付产品，查阅对应的产品**常见问题文档**，匹配问题解决方案。
+
+2. 若未找到解决方案，引导用户查阅 [开放平台在线文档](https://open.alipay.com?form=payskill) 或咨询 [支付宝技术支持](https://opensupport.alipay.com/support/intelligent-services?form=payskill)，**严禁**编造解决方案。
+3. 对代码集成、SDK 使用、应用创建、应用发布等没有确定依据的问题，必须明确说明无法确认，并引导用户前往支付宝开放平台或支付宝技术支持咨询客服。
+
+#### 常见问题文档索引
+
+| 产品类别 | 常见问题文档 |
+|----------|-------------|
+| 按量付费 | [按量付费常见问题](https://ideservice.alipay.com/cms/site/0j7uos) |
+| 网站支付 | [网站支付常见问题](https://ideservice.alipay.com/cms/site/0j3kh1) |
+| APP支付 | [APP支付常见问题](https://ideservice.alipay.com/cms/site/0j3pih) |
+
+#### ⛔ 验签失败（invalid-signature）专项排查
+
+遇到 `invalid-signature`（验签出错）时，**严禁凭猜测归因到私钥格式或环境兼容性**，必须按以下原则排查：
+
+1. **先验证实际请求内容，再怀疑密钥配置** — 验签失败最常见的原因是请求参数不完整或不匹配（如 `return_url` 未传入），而非私钥格式问题。
+
+2. **严禁陷入连环误判**：看到 `ERR_OSSL_UNSUPPORTED` 就推断私钥格式有问题 → 给私钥添加 PEM 头尾或其他前后缀 → 转换格式，这是错误排查路径。详见 `modules/alipay-sdk-reminder.md` 中的「验签失败排查原则」。
+
+3. **正确排查顺序**：
+   - 检查请求参数完整性（最常见原因）
+   - 检查私钥字段是否正确（Java 用 `appPrivateKey`，其他语言用 `appPrivatePkcsKey`）
+   - 检查 signType 是否为 RSA2
+   - 检查网关地址是否正确
+
+4. **线上环境公私钥不匹配**：若线上环境报错"公私钥不匹配"，建议用户：
+   - 登录支付宝开放平台**重新上传应用公钥**
+   - 在应用配置中重新配置应用公私钥对
+
+---
+
+## 核心产物
+
+| 产物 | 说明 |
+|------|------|
+| 沙箱配置 | appId + 支付宝公钥 + 商家私钥 |
+| 集成代码 | 各语言支付代码示例 |
+| 校验结果 | checklist核对结果 |
+
+---
+
+## 集成完成确认
+
+集成完成后，询问用户：
+
+> "支付产品集成已完成。如您需要开通正式支付能力，可以进行签约入驻。请问还有其他需要帮助的吗？"