Jeepay 开源版支付系统对接 Skill

前置说明

本 Skill 主要提供 Jeepay 开源版支付系统的对接指引和问题排查指引。
请开发人员审查 AI 生成的接入代码，自行确认代码逻辑，上线前充分测试确保其适用性与准确性。
Java 项目优先使用 SDK：当用户项目为 Java 时，优先使用 Jeepay SDK 进行对接，而非直接调用 HTTP 接口。SDK 已封装签名、验签、请求等逻辑，可大幅简化集成工作。

集成原则

⛔ 以下原则必须严格遵守：

征得用户同意：严禁在未征得用户同意的情况下，擅自启动支付产品的集成流程，必须先确认用户意图并获得明确同意后，方可继续执行集成步骤。
单一产品集成：在一次指令中，未经用户许可，严禁同时自动启动多个支付产品的集成，必须先确认单一产品，完成该产品的完整集成流程后，方可视情况讨论下一个产品。

权限配置（自动检测并配置）

⚠️ 本技能执行前，会自动检测并提示用户配置所需权限。

执行流程：

读取当前项目下的 .claude/settings.local.json，检查是否已包含所需权限。
如已配置：直接继续。
如未配置：询问用户是否同意自动添加权限，用户确认后自动写入。

所需权限列表：

| 权限 | 用途 | |------|------| | Bash(curl *) | 调用 Jeepay 在线文档 API | | Bash(javap *) | 查看 SDK 类结构和方法签名 | | Bash(mvn *) | Maven 构建、依赖管理 | | Bash(jar *) | 查看和解压 SDK jar 包 | | WebFetch(domain:doc.jeequan.com) | 访问 Jeepay 官方文档站 | | WebFetch(domain:gitee.com) | 访问 Gitee SDK 源码 |

自动配置内容（用户确认后写入 .claude/settings.local.json）：

{
  "permissions": {
    "allow": [
      "Bash(curl *)",
      "Bash(javap *)",
      "Bash(mvn *)",
      "Bash(jar *)",
      "WebFetch(domain:doc.jeequan.com)",
      "WebFetch(domain:gitee.com)"
    ]
  }
}

强制执行要点

⛔ 以下为全局强制规则，严禁以任何理由跳过或简化：

[1] 告知用户本 Skill 主要提供 Jeepay 开源版支付系统的对接指引和问题排查指引
[2] 告知用户服务声明（完整内容见步骤 1.1 确认点）
[3] 先定计划再动手：先确认用户意图并获得明确同意后，必须先确定功能分支并打印完整的待办步骤清单，禁止未确定计划就直接开始执行
[4] 每个步骤完成后对照完成条件自检，有遗漏须补齐后再继续
[5] 遇到 <BLOCKING_CONFIRMATION> 必须暂停等待用户明确回复，确认话术必须包含"请回复'同意'或'确认'"等显式要求
[6] 禁止编造配置、假数据；禁止绕过确认点
[7] 禁止合理化跳过确认（如"用户可能希望快速完成"）
[8] 禁止假数据与占位符冒充

反面案例（严禁行为）

⚠️ 出现如下任何一种行为即视为违规：

在未输出待办步骤清单前开始输出代码
因用户催促而简化执行流程
跳步、合并步骤
进行"我认为..."、"简化起见..."等自行判断
绕过确认点或假设用户已同意

功能路由

| 用户意图 | 功能分支 | 执行流程 | | --- | --- | --- | | 需要对接 Jeepay 支付系统（支付、退款、转账、分账等） | 功能一 | 步骤 1.1 → 1.2 → 1.3 → 1.4 → 1.5 → 1.6 | | 集成过程中遇到报错或问题 | 功能二 | 步骤 2.1 → 2.2/2.3 |

阻塞确认点索引

以下为流程中必须暂停等待用户明确回复的关键节点，严禁跳过：

| 编号 | 所在步骤 | 确认点内容 | |------|---------|-----------| | B-01 | 步骤 1.1 产品决策 | 用户同意服务声明并确认接入产品（回复"同意"或"确认"） | | B-02 | 步骤 1.2 获取对接文档 | 已读取对接说明、技术规范、SDK&Demo（三项全部满足） | | B-03 | 步骤 1.6 集成校验 | 用户确认是否需要进行集成校验（回复"需要"或"确认"） |

完成条件索引

以下为每个步骤的完成条件，必须全部满足后方可继续下一步骤：

| 编号 | 步骤 | 完成条件 | |------|------|---------| | M-01 | 步骤 1.1 支付方式确认 | 已确认支付方式、用户已同意服务声明 | | M-02 | 步骤 1.2 获取对接文档 | 已读取对接说明、技术规范、SDK&Demo | | M-03 | 步骤 1.3 获取接口文档 | 已根据支付方式获取对应的接口文档 | | M-04 | 步骤 1.4 集成代码 | 已完成代码实现、已通过 7 项自检 | | M-05 | 步骤 1.5 集成后说明 | 已输出安全红线和后续指引 | | M-06 | 步骤 1.6 集成校验 | 已输出校验邀请并等待用户回复 |

功能一：支付对接指引

触发条件：用户需要集成 Jeepay 开源版支付系统。

步骤 1.1 支付方式确认

阅读支付方式路由表，根据用户输入匹配关键词，确认支付方式。当用户描述模糊时，使用澄清话术模板进行支付方式确认。

<BLOCKING_CONFIRMATION>

在输出支付产品决策后，必须严格按以下顺序执行并暂停等待用户回复：

输出决策结果：告知用户推荐的支付产品及选择理由
输出服务声明（完整打印）：

⚠️ 服务声明：使用本 Skill 即表示您同意：（1）使用本服务需遵守法律法规、自行审核测试并承担使用责任，我方不对使用效果、正确性担保。（2）禁止在代码、大模型对话等公网透露敏感信息（密码、API Keys、私钥等）。
显式询问确认（必须使用如下话术）：

"请问您是否同意上述服务声明并确认接入【{产品名称}】？请回复'同意'或'确认'后，我将继续后续步骤。"
等待用户回复：必须收到用户明确同意的回复后，方可进入步骤 1.2。若用户未回复、表示犹豫或拒绝，禁止继续任何后续步骤。

</BLOCKING_CONFIRMATION>

步骤 1.2 获取对接文档

接入前必须阅读下列文档（文档获取方式详见文档访问规范）：

接口规则：了解签名方式、参数格式、通用规则。接口规则文档
SDK下载：获取代码示例。SDK下载文档

💡 Java 项目提示：接入前务必先读取 SDK&Demo 文档，优先使用 Jeepay SDK 进行对接。SDK 集成注意事项详见 SDK 集成指引。

⛔ 阻塞检查点：步骤 1.2 完成标准（下列事项必须全部满足才能继续执行后续步骤）

[ ] 已读取对接说明
[ ] 已读取技术规范
[ ] 已读取 SDK&Demo

集成环境说明

测试环境：详见对接说明文档中的测试环境信息
生产环境：网关地址为自行部署的服务器地址（如 https://pay.yourdomain.com）

步骤 1.3 获取接口文档

根据支付方式，查阅 API 路由表获取对应的接口文档。

channelExtra 参数说明：不同支付方式需要传入不同的 channelExtra 参数（如条码支付的 authCode、小程序支付的 openid 等）。具体参数要求请参考统一支付下单文档中对应支付方式的说明。

💡 转账/分账对接：转账和分账功能按需对接。当用户明确需要对接转账或分账功能时，参考 API 路由表中的转账/分账接口文档按流程接入。

步骤 1.4 集成代码

前置条件：已完成步骤 1.3 获取接口文档。

完成条件：

已完成 Jeepay 支付产品集成代码实现
已完成代码自检并确认无误

代码生成前自检

⛔ 输出任何代码之前，必须逐条自检以下 7 项，全部通过方可输出代码，任何一项不通过必须返回对应步骤重读，禁止跳过自检直接输出代码：

apiKey 是否安全存储（不在代码中硬编码，通过配置文件读取）？→ 是 → 继续
签名方式是否为 MD5（Jeepay 固定 MD5 签名）？→ 是 → 继续
异步通知是否使用动态解析（不硬编码字段）？→ 是 → 继续
是否实现了幂等处理？→ 是 → 继续
是否配置了完整的日志输出（请求 URL + 参数 + 响应）？→ 是 → 继续
SDK 导入语句是否正确（依赖版本、类名路径是否与 SDK 一致）？→ 是 → 继续
是否已读取对应接口的代码示例（从代码示例索引获取）？→ 是 → 继续

代码示例

完整索引见代码示例索引，支持 Java 和 Python 两种语言。

必须按业务类别精准读取对应示例，禁止全量扫描。

步骤 1.5 集成后说明

前置条件：已完成步骤 1.4 集成代码，并通过自检。

⛔ 完成支付能力集成任务后，必须向用户输出以下两部分内容，不打印则违规：

第一部分：安全红线

以下为 Jeepay 支付接入的安全红线，违反可能导致资金损失或安全事故，必须严格遵守，产品集成过程中务必提醒开发者注意以下安全事项。

私钥禁止存客户端：构造交易数据并签名必须在商家服务端完成，私钥严禁保存在商家 APP 客户端中。
私钥禁止记日志：私钥不得出现在任何日志中。
私钥禁止传公共仓库：私钥不得上传到 GitHub、GitLab 等公共代码仓库。
前台支付结果不可信：前台同步跳转结果不可信，必须以 Jeepay 异步通知或调用查单接口获取结果为准。
未确认不重付：在未确认支付结果前，不得要求用户再次付款，必须先通过异步通知或查询接口确认支付结果。
异步通知必须先验签：收到异步通知后必须先验签，确保通知来自 Jeepay。

第二部分：后续指引

当前配置为测试环境配置，仅用于开发调试。上线前请将 mchNo、appId、apiKey、网关地址等配置替换为生产环境配置，并认真进行人工代码审查。

步骤 1.6 集成校验

在集成过程中及发布上线前按照集成校验清单进行校验，确保签名验签、异步通知、异常处理等符合规范。校验结果供参考，开发者务必按照 Jeepay 最新文档进行检查。
异步通知参数处理注意事项详见异步通知代码示例。
日志输出规范详见日志输出指引。

<BLOCKING_CONFIRMATION>

输出步骤 1.5 的「安全红线」和「后续指引」后，必须暂停并等待用户确认：

输出校验邀请：

"支付能力集成已完成。为确保集成质量，我可按照集成校验清单帮您逐项校验（包括签名验签、异步通知、异常处理等）。请问您是否需要进行集成校验？请回复'需要'或'确认'后，我将开始校验。"
等待用户回复：
- 若用户回复需要校验：获得明确同意后，方可按照校验清单逐项执行并输出结果。
- 若用户表示不需要或无回复：禁止主动启动校验流程，可解答用户其他疑问。

</BLOCKING_CONFIRMATION>

功能二：问题排查指引

触发条件：用户在集成 Jeepay 开源版支付系统过程中遇到报错或其他问题。

⚠️ 支付方式信息确认（必须遵守）：执行下述问题排查步骤之前，必须明确用户当前集成的支付方式，否则暂停输出并要求用户澄清，严禁在支付方式信息缺失时尝试查阅文档或猜测支付方式。

步骤 2.1 问题识别与分流

根据用户输入判断问题类型，分流到对应排查路径：

用户问题
    |
    +-- 验签失败（通信秘钥错误、验签出错）  ← 优先匹配，走专项排查
    |       |
    |       └───> 步骤 2.3 验签失败专项排查
    |
    +-- 有明确错误码（如 "通信秘钥错误"、"验签失败"）
    |       |
    |       └───> 步骤 2.2 错误码排查
    |
    +-- 无明确错误码（如流程疑问、功能异常等）
            |
            └───> 步骤 2.3 常见问题排查

步骤 2.2 错误码排查

适用：用户提供了明确的错误码。

⚠️ 报错接口信息确认（必须完成）：错误码查询前，必须确认发生报错的接口信息，否则暂停输出并要求用户澄清，严禁在报错接口信息缺失时尝试查阅文档或猜测报错接口。

排查流程

查系统错误码：查阅 Jeepay 错误码文档，根据用户提供的错误码检索相关内容。如有匹配结果，输出排查结论；否则，查业务错误消息。
查业务错误消息：基于确定的支付方式和报错接口信息，查阅 API 路由表中对应的接口文档，进一步找到报错接口对应的接口文档，并在接口文档中根据用户提供的错误消息检索相关内容。
输出排查结论：根据查询到的错误码关联内容，输出排查结论。

步骤 2.3 常见问题排查

适用：无明确错误码的其他类型问题。

排查流程

根据用户输入和确定的支付方式，查阅 常见问题文档，匹配问题解决方案，回答用户问题时，务必以 Jeepay 文档为准。
若根据 常见问题文档 未找到解决方案，引导用户查阅 Jeepay 在线文档或咨询技术支持，严禁编造常见问题文档以外的解决方案。

常见问题文档索引

| 问题类别 | 常见问题文档 | | --- | --- | | API 调用类 | Jeepay 常见问题文档 | | 支付相关 | Jeepay 常见问题文档 |

验签失败（通信秘钥错误）专项排查

遇到"通信秘钥错误"、"验签失败"等签名相关错误时，严禁凭猜测归因，必须按以下顺序排查：

检查 apiKey 是否与 Jeepay 运营平台配置一致
检查签名参数是否包含 sign 字段（签名前需移除 sign）
检查参数排序是否按 ASCII 升序（key1=value1&key2=value2&...）
检查签名拼接末尾是否附加了 key=apiKey
检查 MD5 结果是否转为大写
检查空值参数是否已过滤（空值不参与签名）

严禁的推断：

看到"通信秘钥错误"就认为 apiKey 配错了 → 应先检查签名算法流程
猜测 MD5 算法实现有问题 → Jeepay SDK 已封装签名逻辑，直接使用即可

jeepay-open-integration

Jeepay 开源版支付系统对接 Skill

前置说明

集成原则

权限配置（自动检测并配置）

强制执行要点

反面案例（严禁行为）

功能路由

阻塞确认点索引

完成条件索引

功能一：支付对接指引

步骤 1.1 支付方式确认

步骤 1.2 获取对接文档

集成环境说明

步骤 1.3 获取接口文档

步骤 1.4 集成代码

代码生成前自检

代码示例

步骤 1.5 集成后说明

步骤 1.6 集成校验

功能二：问题排查指引

步骤 2.1 问题识别与分流

步骤 2.2 错误码排查

排查流程

步骤 2.3 常见问题排查

排查流程

常见问题文档索引

验签失败（通信秘钥错误）专项排查

相关文档