@alipay/alipay-aipay 1.1.0 → 1.2.2

package/skill/references/integration/flow.md

@@ -4,6 +4,18 @@
 
 ---
 
+## 内容导航
+
+- [文件路由表](#-文件路由表)
+- [强制执行要点](#-强制执行要点)
+- [阻塞确认点索引](#阻塞确认点索引)
+- [完成条件索引](#完成条件索引)
+- [产品文档路由](#-产品文档路由)
+- [集成流程](#集成流程7步--app支付跳过步骤5共6步)
+- [问题排查流程](#问题排查流程功能二)
+- [核心产物](#核心产物)
+- [集成完成确认](#集成完成确认)
+
 ## 📂 文件路由表
 
 > 本文件位于 `references/integration/`。下表中的 `modules/...`、`../normal/...` 路径均相对本文件所在目录；若从技能包根目录定位，请加前缀 `references/integration/`。
@@ -23,12 +35,7 @@
 | ↳ 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/code-examples/** | 五语言、按产品分类的代码示例 | 步骤 4 代码生成 |
 | ↳ modules/sandbox/a2m-sandbox-test.md | 按量付费沙箱测试 | 步骤 5 按量付费测试 |
 | ↳ modules/scripts/local_402_sandbox_pay.py | 402沙箱收银测试脚本 | 步骤 5 按量付费测试 |
 | ↳ modules/checklist.md | 集成校验清单 | 步骤 7 集成校验 |
@@ -44,19 +51,20 @@
 1. **先定计划再动手**：执行任何操作之前，**必须先确定功能分支并打印完整的待办步骤清单**，禁止未确定计划就直接开始执行
 2. **必须获得用户同意**：未经用户同意，禁止启动集成流程
 3. **单一产品原则**：一次只能集成一个产品，完成后再讨论下一个
-4. **禁止假数据**：禁止编造沙箱配置或使用占位符
+4. **禁止假数据与占位符冒充**：沙箱成功返回完整配置时，禁止用占位符代替真实返回值；禁止自行生成示例私钥、示例账号等假数据
 5. **阻塞确认点**：必须等待用户明确回复后才能继续下一步
 6. **禁止合理化跳过确认**：禁止用"用户可能希望快速完成"、"这是一个简单场景"等理由跳过阻塞确认点
-7. **禁止假数据与占位符冒充**：沙箱成功返回完整配置时，禁止用占位符代替真实返回值；禁止自行生成示例私钥、示例账号等假数据
-8. **先阅读文档再执行**：每个步骤必须先阅读相关文档，完成该步骤的**完成条件**自检后，方可进入下一步
-9. **生产密钥替换提醒**：当用户要求直接替换生产环境密钥配置，或声称已替换完成并要求启动生产环境支付测试时，必须先基于项目编程语言和应用私钥格式提醒用户：`appId`、应用公钥、应用私钥必须属于同一套应用密钥；应用私钥格式必须与语言 SDK 匹配，格式不匹配时使用支付宝开放平台密钥工具做私钥格式转换。
-10. **依据不足时不编造**：代码集成、SDK 使用、应用创建、应用发布等问题若没有确定依据，必须说明无法确认，并引导用户前往[支付宝开放平台](https://open.alipay.com/)或[支付宝技术支持](https://opensupport.alipay.com/support/intelligent-services?form=payskill)咨询客服；不得猜测接口能力、审核规则或处理时效。
+7. **先阅读文档再执行**：每个步骤必须先阅读相关文档，完成该步骤的**完成条件**自检后，方可进入下一步
+8. **生产密钥替换提醒**：当用户要求直接替换生产环境密钥配置，或声称已替换完成并要求启动生产环境支付测试时，必须先基于项目编程语言和应用私钥格式提醒用户：`appId`、应用公钥、应用私钥必须属于同一套应用密钥；应用私钥格式必须与语言 SDK 匹配，格式不匹配时使用支付宝开放平台密钥工具做私钥格式转换。
+9. **依据不足时不编造**：代码集成、SDK 使用、应用创建、应用发布等问题若没有确定依据，必须说明无法确认，并引导用户前往[支付宝开放平台](https://open.alipay.com/)或[支付宝技术支持](https://opensupport.alipay.com/support/intelligent-services?form=payskill)咨询客服；不得猜测接口能力、审核规则或处理时效。
+10. **适用接口必须完整实现**：根据目标产品官方产品文档、接口文档和 `modules/interface-guide.md` 确定适用接口集合。网站支付/APP支付必须实现产品下单、交易查询、退款、退款查询、关闭交易和异步通知处理；按量付费实现 402 协议、支付凭证验证和履约确认，不得添加不适用的通用收单接口。本流程实现和校验项目代码，不主动发起真实生产交易。
+11. **异步通知口径分层**：网站支付/APP支付必须实现异步通知处理代码，但“已实现通知处理”与“已完成公网通知联调”是两件事。用户项目尚未上线、暂无可公网访问 HTTPS `notify_url` 时，可进入“本地生产参数验收模式”：网站支付保留本地同步回跳或结果页并结合订单查询链路，APP支付保留订单查询链路，临时关闭异步通知发起配置或不传 `notify_url`，并把公网通知联调标记为人工待验证；正式上线前仍必须恢复 `notify_url` 并完成公网 HTTPS、验签、幂等、关键字段校验和补偿查询。
 
 ### 服务声明
 
 > ⚠️ **服务声明**：使用本 Skill 即表示您同意：
 > （1）使用本服务需遵守法律法规、自行审核测试并承担使用责任，我方不对使用效果、正确性担保。
-> （2）禁止在代码、大模型对话等公网透露敏感信息（密码、API Keys、私钥等）。
+> （2）禁止在代码、大模型对话等公网透露真实账号密码、API Keys、私钥等敏感信息。快速沙箱创建成功且字段校验通过后，为完成沙箱付款，可按 `modules/sandbox/sandbox-setup-guide.md` 在当前对话展示工具实际返回的沙箱测试账号登录密码和支付密码；不得将该例外扩展到真实账号或生产环境。
 
 ### ⚠️ 反面案例（严禁行为）
 
@@ -66,7 +74,7 @@ Agent 出现如下任何一种行为即视为违规：
 - 因用户指令中存在"快速接入"、"快点"、"赶紧"等催促关键词而简化本 Skill 中执行流程，不再输出本 Skill 规定的完整待办步骤清单
 - 跳步、合并步骤
 - 进行"我认为..."、"简化起见..."等自行判断
-- **绕过阻塞确认**：在 `<BLOCKING_CONFIRMATION>` 确认点，禁止以任何理由跳过等待，禁止假设用户已同意或使用"我将继续..."等单方面声明代替用户确认
+- **绕过阻塞确认**：在 `<INTERNAL_BLOCKING_CONFIRMATION>` 确认点，禁止以任何理由跳过等待，禁止假设用户已同意或使用"我将继续..."等单方面声明代替用户确认
 - **合理化跳过确认**：用"用户可能希望快速完成"、"这是一个简单场景"、"用户没说不要"等理由合理化跳过阻塞确认点，实际行动仍继续执行而非等待
 
 ---
@@ -76,8 +84,8 @@ Agent 出现如下任何一种行为即视为违规：
 | 位置 | 触发时机 | 等待内容 |
 |------|----------|----------|
 | 步骤 1 | 产品决策后 | 用户同意服务声明并确认接入特定产品 |
-| 步骤 5 | 按量付费测试前 | 用户确认服务已启动并准备好进行沙箱付款测试 |
-| 步骤 7 | 集成完成后 | 用户确认是否需要进行集成校验 |
+
+> 步骤 5 中，按量付费沙箱测试是前置条件就绪后默认自动执行的完成质量门；网站支付则必须在收尾前向用户提供人工沙箱付款入口和操作说明，但不强制用户当场付款；APP支付跳过步骤 5。步骤 7 的集成校验默认自动执行，不作为可选阻塞确认。自动执行不改变沙箱测试流程或 `modules/checklist.md` 的任何校验内容；无法自动验证的项目必须逐项标记为人工待验证。步骤 2 的沙箱字段完整性校验只证明配置可用，不是沙箱支付测试，三类产品都不得据此输出“沙箱测试通过”或等价结论。
 
 ---
 
@@ -88,8 +96,8 @@ Agent 出现如下任何一种行为即视为违规：
 | 步骤 1 产品决策 | [M-01] | 4 项 |
 | 步骤 2 沙箱初始化 | [M-02] | 5 项 |
 | 步骤 3 集成前置 | [M-03] | 4 项 |
-| 步骤 4 集成代码 | [M-04] | 3 项 |
-| 步骤 5 按量付费沙箱测试 | [M-05] | 6 项（仅按量付费） |
+| 步骤 4 集成代码 | [M-04] | 6 项 |
+| 步骤 5 沙箱测试与体验 | [M-05] | 按量付费 5 项；网站支付 1 项 |
 | 步骤 6 集成后说明 | [M-06] | 2 项 |
 | 步骤 7 集成校验 | [M-07] | 1 项 |
 
@@ -118,14 +126,29 @@ Agent 出现如下任何一种行为即视为违规：
 
 ---
 
-## 集成流程（7步 / 网站支付和APP支付跳过步骤5，共6步）
+## 集成流程（7步 / APP支付跳过步骤5，共6步）
+
+### 目标项目执行上下文
+
+进入步骤 1 前先确定唯一的规范化目标项目根目录，后续所有项目检测、依赖安装、代码与配置写入、服务启动和校验命令都必须以该目录为工作目录。禁止因为 Agent 的原始工作目录更方便而切回原目录，也禁止把临时目录中的产物误报为目标项目产物。
+
+- `full_process`：必须继承 `../../SKILL.md` 统一分流确认中的目标产品、项目选择分类、规范化项目路径、目标产品集成状态、判断依据以及检测到的其他支付产品，不得重新猜测或静默改选项目。
+- `integration_only`：优先从当前可访问业务项目确定根目录；不存在、存在多个候选或用户要求其他/新项目时，先让用户选定并确认规范化路径，不得自行选择。
+- 已有项目：进入任何写操作前确认目标路径可读、在当前 Agent 权限范围内可写且仍对应用户选定的业务项目；需要环境文件权限时按当前权限机制申请，无法取得权限、路径失效或实际项目不符时停止，要求用户提供可访问路径或重新选择项目。完整保留项目结构、已有文件和其他支付能力，只对当前目标产品需要的位置做可审查的局部修改，禁止先删除文件再重建。
+- 新项目：目标路径必须尚不存在或已检查为空，初始化前确认目标路径或其最近已有父目录在当前 Agent 权限范围内可写；需要环境文件权限时按当前权限机制申请。路径非空或无法取得写权限时停止，保留其中全部内容，让用户改选明确的空子目录、空同级目录或其他尚不存在或为空的目录，禁止清空、覆盖或把该目录强行当作新项目。步骤 1 必须确认开发语言、框架和项目创建方式，收到该步骤的阻塞确认后才能按确认方式创建目录和初始化项目。创建命令只能来自用户指定方式、可访问模板/项目中的既有命令或本轮已读取的官方文档，且不得使用 `--force` 等覆盖既有文件的选项；禁止凭记忆编造脚手架、依赖或默认工程结构。
+- 项目准备失败时停留在步骤 1，输出实际错误和待补条件；不得进入沙箱初始化。目标项目准备成功后记录实际根目录，步骤 2 的沙箱配置和后续代码必须落入该项目，只有 `modules/sandbox/sandbox-setup-guide.md` 明确允许的情况才能使用临时目录。
+
+**项目选择保护规则**：当前目录已包含项目时，只能让用户选择“保留并在该项目新增目标支付能力”“保留并在指定的新子目录创建独立项目”或“保留并使用指定的其他路径”，不得展示清空或删除选项。用户只回复“新建”时，正确回应是：“现有项目及文件保持不变。请提供独立新项目的具体路径，或确认在当前目录下使用哪个新子目录。”对 `full_process`，此时必须留在或返回 `../../SKILL.md` 主编排并保持 `PROJECT_UNRESOLVED`，不得进入或继续 integration；对 `integration_only`，只继续澄清具体路径，不使用 `PROJECT_UNRESOLVED` 或创建其他状态。取得并确认尚不存在或为空的精确路径前不得执行文件操作。
+
+**破坏性操作二次确认**：本支付集成流程本身不得删除用户既有文件。用户另行主动要求删除具体文件时，先停止集成，列出每个精确规范化路径和不可逆影响，再在独立轮次等待用户逐项确认该清单；此前的分流确认、步骤 1 确认、服务声明确认及任何含糊回复均无效。未取得二次明确确认时严禁调用删除、清空、强制覆盖或等价命令；即使确认，也禁止删除项目根目录、`.git`、使用通配符或触及清单外文件。
 
 ### 步骤 1：产品决策
 
-**任务**：根据用户场景确定要集成的产品
+**任务**：根据用户场景和目标项目确定开发语言、框架、接入产品、项目创建方式（仅新项目）与执行范围，并通过一次确认启动流程
 
 **完成条件**：
 - [M-01] 已确认用户服务端开发语言（Java / Python / Node.js / C# / PHP 五选一）
+- [M-01] 已确认唯一的规范化目标项目路径；已有项目已验证可访问且保持原有内容，新项目路径已验证为尚不存在或为空并确认框架和项目创建方式
 - [M-01] 已根据用户场景决策出支付产品
 - [M-01] 已征得用户明确同意
 - [M-01] 已输出服务声明并获得用户同意
@@ -137,20 +160,26 @@ Agent 出现如下任何一种行为即视为违规：
 | APP、应用内支付、手机APP、iOS、Android、鸿蒙 | APP支付 |
 | 模糊场景 | 引用 modules/product-decision.md 进行澄清 |
 
-<BLOCKING_CONFIRMATION>
+<INTERNAL_BLOCKING_CONFIRMATION>
 
 **确认点：产品决策**
 
-输出产品选择后，**必须暂停等待用户确认**，按以下顺序执行：
+输出产品选择后，**必须暂停等待用户确认**，按以下顺序执行。复用用户已经明确提供的信息，只集中补问无法可靠识别的字段：
 
-1. **确认开发语言**：询问用户项目使用什么服务端开发语言（Java / Python / Node.js / C# / PHP）
-2. **输出决策结果**：告知用户推荐的支付产品及选择理由
-3. **输出服务声明**（完整打印）
-4. **显式询问确认**：
+1. **确认目标项目**：展示规范化目标项目路径及已有/新项目类型；已有项目验证可访问性并声明保留原有内容，新项目先验证路径尚不存在或为空，再集中询问无法确定的服务端语言、框架和项目创建方式
+2. **识别开发语言**：优先读取已有目标项目判断服务端开发语言与框架；无法可靠判断时，询问用户使用 Java / Python / Node.js / C# / PHP 中的哪一种
+3. **输出决策结果**：告知用户识别或推荐的支付产品、目标项目路径、服务端语言、框架、接入范围及选择理由；新项目同时展示确认的创建方式
+4. **输出完整待办步骤清单**：不得省略当前产品适用的步骤、沙箱测试和自动集成校验
+5. **输出服务声明**（完整打印）
+6. **显式询问确认**：
    > "请问您是否同意上述服务声明并确认接入【{产品名称}】？请回复'同意'或'确认'后，我将继续后续步骤。"
-5. **等待用户回复**：必须收到用户明确同意的回复后，方可进入步骤2。
+7. **等待用户回复**：必须收到用户明确同意的回复后，方可准备目标项目并进入步骤2。用户此前只说明了产品或语言但未同意服务声明时，不得视为已经确认。
+
+如果当前意图为 `full_process`，进入本流程只代表主编排已判定需要先完成集成，不能替代本步骤对产品、语言、服务声明和集成执行范围的确认。此处只展示集成待办，禁止提前展示 MCC、授权范围、签约材料或 onboarding 待办。
+
+</INTERNAL_BLOCKING_CONFIRMATION>
 
-</BLOCKING_CONFIRMATION>
+**确认后的项目准备**：已有项目重新确认实际根目录并保持原有工程结构；新项目在执行初始化前再次检查目标路径仍不存在或为空，再按已确认的创建方式初始化。若路径在确认后变为非空，立即停止并重新选址，不得删除新出现的内容。完成后检查实际生成的项目标识、启动/构建入口和工作目录，确认无误才进入步骤 2。初始化命令、依赖或框架信息没有可靠来源时继续补问或读取官方文档，不得猜测执行。
 
 ---
 
@@ -167,15 +196,15 @@ Agent 出现如下任何一种行为即视为违规：
 - [M-02] 已检测用户操作系统类型
 - [M-02] Unix/macOS/Linux：已调用沙箱工具获取候选沙箱 `data`
 - [M-02] Windows：已引导用户自行获取沙箱信息并提供配置
-- [M-02] 已按 `sandbox-setup-guide.md` 完成字段完整性校验、正式落盘、摘要输出、配置文件路径输出和成功创建后提示
+- [M-02] 已按 `sandbox-setup-guide.md` 完成字段完整性校验和正式落盘；字段无缺失时未输出独立校验结论或字段核对表，只输出一张包含配置文件路径的沙箱环境摘要表及创建后提醒
+
+> 沙箱必含字段、落盘格式、路径输出、重复创建红线和失败处理均以 `modules/sandbox/sandbox-setup-guide.md` 为准。必须保留本步骤输出的实际配置文件路径作为后续唯一可信来源；无论结构化读取还是写入本地测试代码，都必须以该 JSON 中的原值为准，禁止从对话或历史代码复制密钥。
 
 **操作流程**：
 1. 检测用户操作系统（Windows/macOS/Linux）
 2. Windows用户：引导自行获取沙箱信息，参考 `modules/sandbox/sandbox-setup-guide.md` 第 1.2 节
 3. Unix/macOS/Linux用户：参考 `modules/sandbox/alipay-sandbox-tool.md` 调用沙箱工具
-4. 按 `modules/sandbox/sandbox-setup-guide.md` 的顺序处理候选 `data`：字段完整性校验 → 正式落盘 → 输出关键摘要与配置文件路径
-
-> 沙箱必含字段、落盘格式、路径输出、重复创建红线、失败处理和写入项目后的后置校验，均以 `modules/sandbox/sandbox-setup-guide.md` 为准。
+4. 按 `modules/sandbox/sandbox-setup-guide.md` 的顺序处理候选 `data`：内部完成字段完整性校验 → 正式落盘 → 对客输出唯一的沙箱环境摘要表与创建后提醒。字段无缺失时不单独输出校验结果或字段核对表
 
 ---
 
@@ -186,7 +215,7 @@ Agent 出现如下任何一种行为即视为违规：
 **完成条件**：
 - [M-03] 已阅读 `modules/alipay-sdk-reminder.md` 完整内容（私钥格式、页面跳转方法、验签排查等）
 - [M-03] 已理解 SDK 选择和 SDK 防幻觉强制规则
-- [M-03] 已递归读取产品在线文档（快速接入、接口列表、异步通知等）
+- [M-03] 已读取当前产品和任务直接相关的在线文档（快速接入、接口列表、异步通知等），没有进行无边界递归抓取
 - [M-03] 已阅读产品相关接口代码示例
 
 **产品在线文档访问**：
@@ -195,7 +224,7 @@ Agent 出现如下任何一种行为即视为违规：
 ```bash
 curl -sL "https://ideservice.alipay.com/cms/site/{文档ID}"
 ```
-递归阅读产品在线文档中的快速接入、接口列表、异步通知、注意事项等部分，了解产品特有逻辑。
+读取当前产品直接相关的快速接入、接口列表、异步通知和注意事项。只沿当前任务需要的官方链接继续读取，避免无边界抓取；在线文档无法访问时不得猜测，使用已验证的本地参考并把无法确认项标记为待核验。
 
 **必须阅读的文件**：
 - `modules/alipay-sdk-reminder.md` - SDK防坑指南（含私钥格式、页面跳转方法、验签排查等）
@@ -213,62 +242,82 @@ curl -sL "https://ideservice.alipay.com/cms/site/{文档ID}"
 | 3 | 前端禁止用 URL 直接跳转支付表单 | 支付接口返回的是 HTML 表单，必须渲染并自动提交 form，直接用 URL 跳转会导致页面只显示参数而无法跳转支付宝 |
 | 4 | 时间戳格式 | 必须使用 `yyyy-MM-dd HH:mm:ss`，禁止使用 ISO 格式 |
 | 5 | SDK 引入方式 | 必须通过查阅 SDK 文档或类型定义确定正确的引入方式，禁止凭猜测选择 |
-| 6 | 遇到 `invalid-signature` 报错 | 严禁凭猜测归因到私钥格式，最常见原因是请求参数不完整（如 `return_url` 未传入） |
+| 6 | 遇到 `invalid-signature` 报错 | 严禁凭猜测归因到私钥格式；先核对实际发送、参与签名和服务端验签的参数是否完全一致 |
 | 7 | 配置写入后必须后置校验 | 必须确认写入配置来自同一份沙箱返回配置、与沙箱返回配置一致、字段映射正确、SDK 配置匹配；失败时禁止继续联调 |
 
 ---
 
 ### 步骤 4：代码生成
 
-**任务**：根据用户选择的开发语言和产品，生成集成代码
+**任务**：根据用户选择的开发语言和产品，在已确认的目标项目根目录中生成集成代码
 
 **完成条件**：
 - [M-04] 已完成支付宝支付产品集成代码实现
+- [M-04] 已按目标产品文档完成全部适用接口；网站支付/APP支付覆盖下单、交易查询、退款、退款查询、关闭交易和异步通知处理代码，按量付费覆盖 402、`payment.verify` 和 `fulfillment.confirm`
 - [M-04] 已完成代码自检并确认无误
 - [M-04] 已完成支付配置准确性后置校验，确认写入配置来自同一份沙箱返回配置、与沙箱返回配置一致、字段映射正确、SDK 配置匹配
+- [M-04] 网站支付在用户未明确要求不使用同步回跳时，已配置与当前项目一致的 `return_url`，并实现可通过 GET 访问的回跳路由和结果页；页面不直接信任同步回跳参数判定支付成功
+- [M-04] 用户处于“本地生产参数验收模式”时，已明确记录当前暂不联调公网 `notify_url`，支付结果确认依赖异步通知处理代码加主动查询兜底；未把同步回跳参数当作支付成功依据
+- [M-04] 按量付费生产接入中已补齐订单持久化、本地订单匹配、金额一致性、资源防串、幂等履约和履约确认失败可重试逻辑，不存在未实现的关键 TODO
 
-**代码示例位置**：
-```
-modules/code-examples/
-├── python/        # 1-通用接口 2-网站支付 3-APP支付 4-按量付费
-├── java/          # 同上
-├── nodejs/        # 同上
-├── csharp/        # 同上
-└── php/           # 同上
-```
+**实现与自检入口**：按当前语言和产品读取 `modules/interface-guide.md` 路由的专用/通用接口示例，并完整应用 `modules/alipay-sdk-reminder.md` 的生成前自检与配置后置校验。本地缺少示例不等于接口不适用；用户限定本轮范围时，未实现的适用接口必须列为待办，不得宣称完整集成。
+
+**支付配置写入后校验**：写入项目后按 `modules/sandbox/sandbox-setup-guide.md` 第 7 节确认 `appId`、应用私钥和支付宝公钥来自步骤 2 的同一份配置，Java 使用 `appPrivateKey`，其他四种语言使用 `appPrivatePkcsKey`。SDK 配置保留原始私钥值；A2M 的 `seller_signature` 使用原生密码库时，只在调用边界按库要求解析密钥。校验失败时从可信配置重新读取，禁止猜测、转换格式或改写原始值。
+
+**网站支付回跳默认规则**：用户未特别说明时，默认实现支付后同步回跳。`return_url` 必须来自已确认目标项目的实际协议、主机、端口和路由，禁止保留 `your-domain.com`、示例端口或猜测路径。项目没有结果页时，在当前技术栈内新增与既有 UI 一致的 GET 回跳路由和页面，至少能展示订单处理中、支付成功、支付未完成或查询失败状态。回跳处理必须先验证支付宝同步参数签名，或使用服务端保存且与当前用户会话绑定的订单标识定位待查订单；不得信任可任意修改的订单号查看或改写其他订单。页面必须通过服务端交易查询或已验签的异步通知状态展示最终结果，不得因为回跳参数中出现成功字段就直接标记订单已支付。用户明确不需要同步回跳时，才可不配置 `return_url`，但必须保留异步通知和交易查询的结果确认链路。
+
+**本地生产参数验收模式**：用户项目尚未上线、无法提供真实公网地址，或当前自定义域名/TLS 检查失败时，网站支付/APP支付可以进入本模式。要求如下：
 
-**重要规则**：
-- 按量付费：直接使用 `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 头）。
+1. 代码层必须已经实现异步通知处理入口、验签、关键字段校验、幂等和成功响应 `success`，只是当前环境不对外联调。
+2. 运行层可以临时关闭异步通知发起配置或不传 `notify_url`；如项目已有显式开关，也可使用项目内已有的 `notify_enabled=false` 等等价配置，但必须向用户说明这是“本地生产参数验收模式”，不是生产最终配置。
+3. 本地模式下，网站支付保留 `localhost` 或当前可访问开发地址的 `return_url`/结果页，APP支付保留本地订单查询链路，并统一提供服务端交易查询或订单查询页作为结果确认兜底。
+4. 任何本地模式结果都只能表述为“本地正式验收完成”或“本地生产参数验收完成，公网异步通知待补齐”，不得表述为“生产就绪”。
+
+**按量付费沙箱 serviceId**：生成或写入按量付费沙箱运行配置时，`serviceId` 固定使用 `api_mock_service_id`，禁止向用户索要正式 `serviceId` 才继续沙箱联调。该值必须与正式环境配置隔离；正式上线前替换为服务市场注册或复用结果中的真实 `serviceId`。
+
+**按量付费生产边界**：五语言 A2M 文件只是核心协议与 SDK 调用示例。生产实现必须通过 `modules/checklist.md` 的全部按量付费专项校验；任一关键控制仍为 TODO、注释、内存演示或伪代码时，不得满足 [M-04] 或标记生产就绪。
+
+> ⚠️ **按量付费**：代码生成后启动本地服务，后续步骤 5 将默认进行端到端沙箱服务端联调。服务需实现 402 协议（无 Payment-Proof 时返回 HTTP 402 + Payment-Needed 头）。
 
 ---
 
-### 步骤 5：按量付费沙箱测试（仅按量付费）
+### 步骤 5：沙箱测试与体验（按量付费、网站支付）
+
+> APP支付跳过本步骤，直接进入步骤 6。按量付费执行自动服务端联调；网站支付向用户提供人工沙箱付款入口和操作说明后进入步骤 6。只有按量付费满足本步骤全部端到端完成条件时，才能对客输出“沙箱测试通过”或等价结论；网站支付和 APP支付不得输出该结论。
+
+#### 网站支付：提供人工沙箱付款指引
 
-> ⚠️ **仅当产品为「按量付费」时执行此步骤**。网站支付和APP支付直接跳过本步骤，进入步骤 6。
+网站支付步骤 5 是用户可操作的付款体验交付，不是支付接口冒烟测试。启动服务、访问首页、用 `curl` 调用下单接口或取得 HTML 支付表单，只能证明对应本地接口有响应；没有向用户提供可在浏览器打开的真实支付页面和以下两种付款方式时，禁止标记步骤 5 完成：
 
-**任务**：验证按量付费 402 协议端到端支付流程
+- 方式一：在沙箱收银台输入沙箱买家账号和登录密码，再输入支付密码付款。
+- 方式二：仅限 Android，安装沙箱支付宝并登录沙箱买家账号，在沙箱收银台使用客户端扫码，再输入支付密码付款。
+
+两种方式必须同时说明并由用户自行二选一，不要求用户两种都做；用户暂不体验不阻塞后续代码校验，但必须明确记录“沙箱付款待用户体验”，不得输出“支付订单创建成功”来替代该状态。
+
+网站支付代码生成和配置后置校验完成后，按以下顺序执行：
+
+1. 从已确认的目标项目确定真实的服务启动命令和支付页面访问地址，禁止使用占位符、示例端口或猜测地址。
+2. 用户未明确关闭同步回跳时，确认 SDK 实际传入的 `return_url`，且其与项目实现的 GET 回跳路由完全一致。
+3. 默认分支继续启动服务，并对不带支付结果参数的 `return_url` 发起 GET 访问。这一步只验证路由和页面壳：无订单上下文时应展示安全的中性状态，不得因没有签名参数而绕过真实回跳请求的验签和订单归属校验。确认响应成功、无认证或重定向循环；单页应用直接刷新不得返回 404。
+4. 默认分支中，Agent 具备浏览器/UI 验证能力时，实际打开回跳页，确认页面非空白、无可见报错且关键状态内容正常渲染。不具备时，向用户提供精确地址请其打开确认；取得证据前只能标记为“回跳页渲染待验证”。
+5. 用户已明确关闭同步回跳时，不要求或猜测 `return_url`；确认 SDK 请求未传该字段，并改为验证异步通知处理代码、交易查询和商户订单查询页。本地生产参数验收模式下，如暂无公网 HTTPS `notify_url`，将公网异步通知联调标记为人工待验证，不以此阻塞本地正式验收。
+6. 按 `modules/sandbox/sandbox-setup-guide.md` 第 5.4 节输出沙箱付款说明。操作顺序为：启动服务 → 用浏览器访问支付页面 → 发起支付 → 唤起沙箱收银台 → 用户从“收银台账号登录”与“安卓沙箱支付宝扫码”中二选一完成付款 → 返回商户结果页并查询展示订单状态。
+
+回跳地址无法确定、访问失败或页面渲染未取得证据时，必须先修正或保持“回跳页渲染待验证”，不得宣称回跳页已验证或网站支付集成完成。该体验不新增业务写操作确认点，用户暂未付款不阻止后续代码校验。
+
+网站支付本步骤的完成语义是“沙箱付款入口与操作说明已提供，并已按实际证据验证回跳页面或关闭回跳分支”，不是“沙箱支付测试通过”。即使用户随后反馈已完成付款，也只记录“用户已完成一笔沙箱付款”以及能够实际核验的订单、回跳或查询结果，不输出笼统的“沙箱环境测试通过”。
+
+**完成条件（网站支付）**：
+- [M-05] 已向用户明确提供真实服务启动命令、浏览器支付页面访问地址、完整沙箱付款顺序、“沙箱买家账号登录”与“安卓沙箱支付宝扫码”两种二选一体验方式，以及结果判断提醒；未用 `curl` 返回的 HTML 表单替代浏览器付款入口
+
+以下两项按实际分支二选一，不得同时要求：
+
+- [M-05] 默认分支已确认实际 `return_url` 与项目路由一致，启动服务后 GET 访问通过，且已通过 Agent 浏览器/UI 验证或用户明确确认取得页面正常渲染的证据
+- [M-05] 关闭分支已记录用户的明确决定，确认 SDK 请求未传 `return_url`，并完成异步通知处理代码、交易查询和商户订单查询页校验；缺少公网 HTTPS `notify_url` 时，已明确标记公网通知联调为人工待验证
+
+#### 按量付费：自动沙箱联调
+
+**任务**：验证按量付费 402 协议端到端服务端联调流程
 
 > ⚠️ **必须完整阅读** `modules/sandbox/a2m-sandbox-test.md` 后方可执行本步骤
 >
@@ -277,39 +326,27 @@ modules/code-examples/
 **完成条件**：
 - [M-05] 已确认用户本地按量付费服务已启动可访问
 - [M-05] 已执行 Payment-Needed 预检，确认 HTTP 402 和关键字段存在
-- [M-05] 已执行沙箱支付测试脚本 `run`，成功获取 Payment-Needed 并生成付款链接
-- [M-05] 用户已在浏览器使用沙箱买家账号完成付款
-- [M-05] 已携带 Payment-Proof 重试原服务并验证响应成功
-- [M-05] 已确认全链路 402 支付流程通过
+- [M-05] 已执行沙箱支付测试脚本 `run --auto-complete`，成功获取 Payment-Needed、生成付款链接并连续执行服务端联调
+- [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` 的“测试前预检”确认服务返回 HTTP 402，Payment-Needed 包含 `seller_signature` 等关键字段，且 `method.service_id` 等于 `api_mock_service_id`。
 
-**沙箱支付宝提醒**：用户进入付款环节前，必须按 `modules/sandbox/a2m-sandbox-test.md` 提醒沙箱支付宝当前仅支持安卓系统，并提供沙箱版支付宝安装包下载说明。
+**沙箱支付宝体验提醒**：服务端联调结论输出后，按 `modules/sandbox/a2m-sandbox-test.md` 向用户提供付款链接、沙箱买家账号和安卓客户端下载说明作为可选付款体验；该体验不新增阻塞确认点。
 
-<BLOCKING_CONFIRMATION>
-
-**确认点：按量付费沙箱测试**
-
-输出测试说明后，**必须暂停等待用户确认**，按以下顺序执行：
-
-1. **确认服务就绪**：询问用户是否已完成代码集成并启动本地服务
-2. **收集测试参数**：
-   - 服务请求地址（含 GET 参数）
-   - HTTP 方法（GET / POST）
-   - 沙箱买家 2088 账号（从步骤 2 获取的 `userId`）
-3. **显式询问确认**：
-   > "以上信息确认无误后，我将执行沙箱支付测试脚本。是否继续？请回复'确认'或'继续'。"
-4. **等待用户回复**：必须收到用户明确回复后，方可调用测试脚本。
+**默认执行规则**：
+1. 从已确认的目标项目和步骤 2 已校验的沙箱配置中确定服务请求地址、HTTP 方法和沙箱买家 `userId`；仅缺少无法从当前上下文取得的真实参数时才询问对应信息，禁止编造或猜测。
+2. 确认本地服务可访问；项目已有明确启动方式且当前环境可执行时直接启动，否则只要求用户完成必要的服务启动。服务恢复可访问后自动继续，不询问是否执行沙箱测试。
+3. 向用户输出即将联调的服务地址、HTTP 方法和测试内容，使用陈述句说明“开始执行按量付费沙箱服务端联调”，不询问“是否继续”、“是否测试”或等价问题。
+4. 立即执行测试前预检和 `run --auto-complete`，连续输出服务端联调结果，中途不新增确认点。
 
 > 详细测试流程见 `modules/sandbox/a2m-sandbox-test.md`
 
-</BLOCKING_CONFIRMATION>
-
 ---
 
 ### 步骤 6：集成后说明
 
-**任务**：输出安全红线和后续指引
+**任务**：在最终校验前输出安全红线和后续指引，不得提前宣称集成已经完成
 
 **完成条件**：
 - [M-06] 已向用户明文打印安全红线
@@ -330,7 +367,9 @@ modules/code-examples/
 - 🤖 凭证不过期复用：验证 `active` 字段，已过期的支付凭证拒绝服务
 
 **后续指引**：
-> 当前配置为沙箱测试环境，仅用于开发调试（沙箱环境无法测试异步通知，请在生产环境进行检查）。上线前请将 appId、私钥、公钥等配置替换为线上正式环境的配置信息，并认真进行人工代码审查。
+> 当前配置为沙箱测试环境，仅用于开发调试。异步通知只有在 `notify_url` 可被支付宝服务器公网访问时才能联调；`localhost`、局域网地址或其他不可公网访问的地址无法完成该项验证，应将其标记为人工待验证，不得据此宣称沙箱环境整体不支持异步通知。上线前请将 appId、私钥、公钥等配置替换为线上正式环境的配置信息；按量付费还必须将沙箱值 `api_mock_service_id` 替换为服务市场注册或复用服务后实际返回的真实 `serviceId`，并认真进行人工代码审查。
+
+对网站支付和 APP支付：未完成公网 HTTPS `notify_url` 联调时，只能表述为“已完成本地正式验收 / 本地生产参数验收，公网异步通知待补齐”。
 
 **生产密钥配置提醒（生产支付测试前必须输出）**：
 - `appId`、应用公钥、应用私钥必须来自同一套生产应用密钥；不要混用沙箱应用、其他生产应用或重新生成的另一套密钥。
@@ -340,23 +379,18 @@ modules/code-examples/
 
 **签约衔接提醒（必须输出）**：
 - 如果当前意图是 `integration_only`：提醒用户正式上线前还需要完成对应产品的商家签约/入驻。
-- 如果当前意图是 `full_process`：继续引导进入 `references/onboarding/flow.md`，完成对应产品签约/入驻。
+- 如果当前意图是 `full_process`：本步骤只说明仍需完成步骤 7 集成校验，不展示签约待办、MCC、授权范围或材料。只有全部适用集成步骤和校验通过后，才按 `../../SKILL.md` 的“完整接入编排”进入 onboarding。
 
 ---
 
 ### 步骤 7：集成校验
 
 **完成条件**：
-- [M-07] 已获得用户同意并按照集成校验清单逐项校验并输出结果
+- [M-07] 已按照集成校验清单逐项校验并保留判断依据；已按摘要规则输出结论、问题和人工待验证项
 
-<BLOCKING_CONFIRMATION>
+**自动执行规则**：步骤 6 完成后直接读取 `modules/checklist.md`，默认只执行代码阅读、配置后置校验、语法/静态检查，以及无需安装依赖、联网或监听端口的已有定向测试，并复用步骤 4、步骤 5 已取得的校验证据，不增加“是否需要校验”的用户确认。
 
-**确认点：集成校验**
-
-输出步骤 6 的内容后，**必须暂停并询问用户**：
-> "支付能力集成已完成。为确保集成质量，我可按照集成校验清单帮您逐项校验（包括签名验签、异步通知、异常处理等）。请问您是否需要进行集成校验？请回复'需要'或'确认'后，我将开始校验。"
-
-</BLOCKING_CONFIRMATION>
+**执行边界**：默认禁止安装依赖或浏览器、切换运行时版本、启动长期服务、申请网络/端口权限、执行截图或 UI 自动化，也不得重复步骤 5 已完成的端到端测试。遇到 `EPERM`、网络受限、缺少浏览器等环境限制时，将对应项标记为“人工待验证”并停止扩展排查；不得据此推断代码或运行时兼容问题。只有用户明确要求继续扩展验证时，才展示拟执行动作并按原确认规则处理。
 
 校验项包括：
 - 签名验签
@@ -365,6 +399,12 @@ modules/code-examples/
 
 > 详细校验清单见 `modules/checklist.md`
 
+**校验完整性要求**：内部必须覆盖 `modules/checklist.md` 的密钥与安全、异步通知、适用接口覆盖、支付结果处理、按量付费专项、退款和上线前七类校验，不得只检查上方三个摘要项。默认对客输出整体结论、通过类别摘要、失败或部分通过项、人工待验证项和风险；通过项与不适用项无需逐行展开，用户要求明细时再输出完整逐项结果。精简输出不得导致任何适用校验被跳过。
+
+**完成语义**：只有步骤 1-7 的适用完成条件均满足后，才可声明支付能力集成完成。若存在未通过项，输出“实现完成但校验未通过”；若仅剩无法自动验证项，输出“自动校验已完成，仍有人工待验证项”。
+
+**沙箱结论边界**：步骤 7 的代码与配置校验不得把步骤 2 的字段完整性、网站支付的付款指引或 APP支付跳过步骤 5 改写为“沙箱测试通过”。只有按量付费步骤 5 已取得完整端到端成功证据时，最终摘要才可复用该测试结论。
+
 ---
 
 ## 问题排查流程（功能二）
@@ -430,12 +470,12 @@ modules/code-examples/
 
 遇到 `invalid-signature`（验签出错）时，**严禁凭猜测归因到私钥格式或环境兼容性**，必须按以下原则排查：
 
-1. **先验证实际请求内容，再怀疑密钥配置** — 验签失败最常见的原因是请求参数不完整或不匹配（如 `return_url` 未传入），而非私钥格式问题。
+1. **先验证实际请求内容，再怀疑密钥配置** — 先核对实际发送、参与签名和服务端验签的参数集是否完全一致，不得在没有请求证据时归因于私钥格式。
 
 2. **严禁陷入连环误判**：看到 `ERR_OSSL_UNSUPPORTED` 就推断私钥格式有问题 → 给私钥添加 PEM 头尾或其他前后缀 → 转换格式，这是错误排查路径。详见 `modules/alipay-sdk-reminder.md` 中的「验签失败排查原则」。
 
 3. **正确排查顺序**：
-   - 检查请求参数完整性（最常见原因）
+   - 检查实际发送、签名和验签参数的一致性
    - 检查私钥字段是否正确（Java 用 `appPrivateKey`，其他语言用 `appPrivatePkcsKey`）
    - 检查 signType 是否为 RSA2
    - 检查网关地址是否正确
@@ -458,6 +498,8 @@ modules/code-examples/
 
 ## 集成完成确认
 
-集成完成后，询问用户：
+集成校验完成后输出实际状态：
 
-> "支付产品集成已完成。如您需要开通正式支付能力，可以进行签约入驻。请问还有其他需要帮助的吗？"
+- `integration_only`：说明已完成项、未通过项、人工待验证项，并提醒正式上线前还需要完成签约入驻。
+- `full_process`：只有全部适用集成步骤和校验通过后，才保留实际产物并自动进入 `references/onboarding/flow.md`；进入 onboarding 后再首次展示该流程的 MCC、授权范围、签约待办和条件材料。存在未通过项时停留在 integration，禁止提前进入或预告 onboarding。
+- 存在未通过校验时不得宣称集成完成，必须列出整改项和对应风险。

package/skill/references/integration/modules/alipay-sdk-reminder.md

@@ -137,15 +137,17 @@ if (data.paymentHtml) {
 
 | 误判行为 | 为什么错 | 正确做法 |
 |---------|---------|---------|
-| 看到 `ERR_OSSL_UNSUPPORTED` 就推断私钥格式有问题 | 该错误通常是 SDK 配置参数错误（如私钥字段选错、字符编码问题），**不是**私钥格式本身有问题 | 先确认使用了正确的私钥字段（Java 用 `appPrivateKey`，非 Java 用 `appPrivatePkcsKey`），再检查其他配置参数 |
-| 手动添加 PEM 头尾、其他前后缀、包装行或说明文字 | 支付宝 SDK 会按配置自行处理密钥包装，手动添加会导致格式错误 | 直接使用沙箱或生产配置中的原始私钥值，不做任何格式处理 |
+| 看到 `ERR_OSSL_UNSUPPORTED` 就推断私钥格式有问题 | 该错误也可能来自私钥复制污染、字段选错或 SDK 配置参数错误，不能证明私钥格式或运行时不兼容 | 先确认项目实际读取值与可信配置原值一致，再检查字段映射和 SDK 参数 |
+| 向 SDK 配置写入 PEM 头尾、其他前后缀、包装行或说明文字 | 支付宝 SDK 会按配置自行处理密钥包装，手动添加会导致格式错误 | SDK 配置直接使用沙箱或生产配置中的原始私钥值，不做任何格式处理 |
 | 将沙箱返回的 `appPrivatePkcsKey` 转换为 PKCS#8 格式 | 沙箱已同时返回两种格式，转换会引入不必要风险 | 非 Java 语言使用原始 `appPrivatePkcsKey` 值，不做转换 |
 | 将沙箱返回的 `appPrivateKey` 转换为 PKCS#1 格式 | 沙箱已同时返回两种格式，转换会引入不必要风险 | Java 语言使用原始 `appPrivateKey` 值，不做转换 |
-| 对私钥内容做 Base64 解码/重新编码 | 无需任何编码处理 | 直接使用沙箱返回的原始字符串 |
+| 写入 SDK 配置前先对私钥做 Base64 解码/重新编码 | SDK 配置无需这些处理 | SDK 配置直接使用沙箱返回的原始字符串 |
 | 因为字段名含 "Pkcs" 就认为是 PKCS#8 格式 | `appPrivatePkcsKey` 是 **PKCS#1** 格式，"Pkcs" 仅表示这是 PKCS 系列标准之一，不代表 PKCS#8 | 非 Java 语言使用 `appPrivatePkcsKey`（PKCS#1），Java 语言使用 `appPrivateKey`（PKCS#8） |
 
 **核心原则：沙箱配置直接使用沙箱返回的对应私钥字段，不做格式转换；生产配置必须确认应用私钥格式与项目语言匹配。所有写入 SDK 配置的私钥值都使用不带 PEM 头尾或其他前后缀的原始密钥字符串，禁止手动添加 PEM 头尾、添加其他前后缀、编码处理或换行符调整。Java 语言使用 PKCS#8，非 Java 语言（Node.js、Python、PHP、.NET 等）使用 PKCS#1。**
 
+**调用边界说明**：上述禁止加工规则针对持久化配置和 SDK 配置。若 A2M 等业务协议需要直接调用语言原生密码库生成业务签名，而该密码库明确要求 PEM 或密钥对象，可从已经校验一致的原始私钥临时构造调用入参；禁止写回配置、覆盖原始值，或把这种调用适配解释成私钥修复。支付宝 SDK 请求签名仍直接使用原始字段，不得预先包装。
+
 ### 生产密钥替换与生产支付测试提醒
 
 当用户要求 Agent 直接替换生产环境密钥配置，或用户声称已经替换完成并要求启动生产环境支付测试时，必须先提醒并核对以下事项：
@@ -164,8 +166,8 @@ if (data.paymentHtml) {
 
 第 1 步（误判起点）：看到 ERR_OSSL_UNSUPPORTED → 推断"私钥格式有问题"
     ↓
-第 2 步（错误修复）：认为"PKCS#1 私钥应该手动添加 PEM 头尾或其他前后缀"
-    → 手动添加 PEM 头尾或其他前后缀 → 错误仍在
+第 2 步（错误修复）：认为"给 SDK 配置添加 PEM 头尾可以修复私钥"
+    → 改写 SDK 配置或原始私钥 → 错误仍在
     ↓
 第 3 步（错误归因）：认为"Node.js 18+ 用了 OpenSSL 3.0，旧格式不被支持"
     ↓
@@ -173,7 +175,7 @@ if (data.paymentHtml) {
     → 将私钥转换为 PKCS#8 格式 → 错误更严重（注：Java 语言应直接使用沙箱返回的 `appPrivateKey` 字段，而非手动转换格式）
 ```
 
-**正确做法**：看到 `ERR_OSSL_UNSUPPORTED`，**立即停止所有格式操作**，按下方「验签失败排查原则」中的正确排查顺序逐项检查。
+**正确做法**：看到 `ERR_OSSL_UNSUPPORTED`，立即停止改写原始私钥或 SDK 配置，先核对项目读取值与可信配置原值，再按下方「验签失败排查原则」逐项检查。原生密码库所需的临时调用适配仍按上方“调用边界说明”处理，不能用于修复配置。
 
 ---
 
@@ -185,13 +187,11 @@ if (data.paymentHtml) {
 
 **原则：先验证实际请求内容，再怀疑密钥配置。**
 
-1. **检查请求参数完整性**（最常见原因）
-   - 支付宝验签时校验所有请求参数是否匹配。如果 `return_url`、`notify_url` 等参数在配置中定义但未传入支付请求，或传入但未参与签名，将导致验签失败。
-   - **排查方法**：打印或检查实际发送给支付宝的请求参数，确认 `return_url`、`notify_url` 等参数是否正确包含在请求中。
-   ```bash
-   # 检查实际请求中是否包含 return_url
-   # 在服务端日志中打印请求参数，确认 return_url 存在
-   ```
+1. **检查实际发送、签名和验签参数的一致性**
+   - 支付宝验签时要求实际请求参数与签名内容匹配。如果 `return_url`、`notify_url` 等参数已传入支付请求但未正确参与签名，或者在签名后被改写，可能导致验签失败。用户明确关闭同步回跳时，未传 `return_url` 本身不应被当作验签失败原因。
+   - **排查方法**：比较实际发送给支付宝的请求参数、SDK 参与签名的参数和服务端验签时使用的参数，确认参数名、参数值和编码方式一致。
+   - 未关闭同步回跳：确认实际请求、签名内容和验签参数中的 `return_url` 值一致。
+   - 已关闭同步回跳：确认实际请求和签名内容均未包含 `return_url`。
 
 2. **检查私钥来源**
    - 确认使用的是沙箱返回的正确私钥字段：Java 使用 `appPrivateKey`，非 Java 使用 `appPrivatePkcsKey`，而非自行生成或其他来源。
@@ -209,6 +209,22 @@ if (data.paymentHtml) {
 
 ---
 
+## 网站支付同步回跳
+
+用户未明确要求关闭同步回跳时，网站支付默认配置 `return_url`。该值不能只是一个格式正确的 URL，还必须对应目标项目内真实存在的 GET 路由和可正常渲染的结果页。
+
+1. 从项目实际运行配置确定协议、主机、端口和路径，禁止使用示例域名、猜测端口或未实现的路由。
+2. 结果页不存在时，必须在当前项目中实现，不得只填写 SDK 的 `return_url` 参数。
+3. 启动服务后对不带支付参数的精确 `return_url` 发起 GET 请求。该请求只验证路由和页面壳：没有订单上下文时展示安全的中性状态，不得放宽真实回跳请求的验签和订单归属校验。跟随有限次重定向，确认最终响应无 404、500、认证循环或重定向循环。单页应用直接刷新该路由仍必须返回应用页面。
+4. 检查 SDK 实际传入的 `return_url` 与已验证地址完全一致，防止域名、端口、协议或路径在配置映射中被替换。
+5. 回跳处理必须先验证支付宝同步参数签名，或使用服务端保存且与当前用户会话绑定的订单标识定位待查订单；不得信任可任意修改的订单号。
+6. 同步回跳参数不是支付成功的可信依据。页面应先展示“正在确认支付结果”，再通过服务端交易查询或已验签的异步通知状态展示最终结果。
+7. 当前 Agent 有浏览器或 UI 验证能力时，必须实际打开回跳页，确认非空白、无可见报错且关键状态内容已渲染。当前无该能力时，向用户提供精确回跳地址请其打开确认；取得确认前不得宣称页面渲染已验证或网站支付集成完成。
+
+回跳地址无法访问、路由不存在、页面无法渲染，或 SDK 实际值与已验证地址不一致时，必须先修正，不得宣称网站支付集成完成。
+
+---
+
 ## 时间戳格式化
 
 支付宝要求时间戳格式为 `yyyy-MM-dd HH:mm:ss`（空格分隔，非 ISO 格式）。