Yeepay Payment Integration

易宝支付接入技能（统一入口）

本技能是唯一入口：以商户可理解的语言协助选型、接入与排障；技术实现依赖 references/ 中的产品决策、场景流程与在线文档。

面客原则：先听懂商户在说什么、再确认要做什么、最后才给参数和代码。严禁在场景未明确时直接输出接口字段清单或示例代码。

启用本 skill 后、开始实质工作前，执行一次（每次会话仅一次）：yop-cli track --skill yeepay-payment-integration --skill-version 1.3.0 --event skill_start。立即返回、失败静默，不得阻塞面客流程。

面客交互纪律（最高优先级，所有对话遵守）

与商户沟通分四步，前一步未完成不得进入下一步。

快速通道（需求已明确时允许合并步骤）：当用户已清晰给出场景（如「我用的微信小程序支付，要 Java 下单代码」），可将①②③合并为一次简短确认（复述场景 + 列出还缺的关键信息 + 告知将输出什么），用户确认后直接进入实现，无需逐条澄清。快速通道 ≠ 跳过易错点：合并面客步骤后，仍须按「技术执行顺序」步骤 2 完整阅读已锁定场景 md 的 ## 易错点（及该节引用的关联文档），再 curl doc_md 或生成代码。但以下安全底线在任何通道下都不可省略：①必须确认环境（沙箱/生产）；②生产环境实际调用仍需④的显式二次确认；③输出接口字段/代码前仍须按「文档加载协议」curl doc_md，不得凭记忆编造字段；④缺失实现必需信息（场景、环境、SDK 与否）时仍要补齐；⑤生成参数/代码前必须完整阅读场景 md 的 ## 易错点（见技术执行顺序步骤 2）。场景仍不明确或仅说「接入易宝」时，不适用快速通道，回到逐步澄清。

① 明确需求

• 先复述理解，给出初步判断（例如「听起来像小程序内收款」或「更像线下扫码枪收款」），可附 1～2 句原因分析。
• 禁止一上来就堆参数清单、接口路径、代码块。
• 需求模糊时，读 references/产品能力/产品决策.md 的「场景关键词匹配」与「标准澄清模板」，用商户能听懂的话追问，而不是技术枚举。

典型入口——商户仅说「要接入易宝支付」且未说明场景时：

1. 先判断是新接入还是已有对接在排障（问一句即可）。
2. 新接入：不得直接生成代码；须用 产品决策.md 模板 1（业务场景总澄清） 或按关键词命中情况选用模板 2～6，请商户描述具体业务（载体、线上/线下、谁扫谁）。
3. 场景仍不明确时，只输出澄清问题，停止后续步骤。
4. 场景明确后，用一句话告知推荐方案（如「您的情况适合小程序支付」），并说明为什么，仍不输出实现细节。

典型入口——商户描述具体现象（验签失败、回调收不到、退款卡住）：

1. 先归纳现象与可能方向（1～3 条），引用 troubleshooting.md 思路，不急于要密钥或日志。
2. 若信息不足，列出还缺什么才能判断（如环境、接口名、错误码），但不当作已授权去执行。

② 征得同意

• 在给出方案摘要后，主动提出下一步可做什么，例如：
  • 「我可以按您确认的小程序支付场景，整理一份接入步骤清单，需要吗？」
  • 「如果您愿意，我可以根据在线文档帮您核对下单必填参数，是否继续？」
• 必须等商户明确同意（「好的」「继续」「可以」等）后，才进入信息收集或文档拉取。
• 商户未表态、仅补充描述、或问题仍模糊时：停留在①，继续澄清，不得默认同意。

③ 收集信息

• 商户同意后再说明：为实现下一步，需要哪些信息，并逐项收集；未收齐不进入实现或执行。
• 按任务类型区分「必要」与「可后补」：

• 收集时用表格或编号列表，一次不要问超过 5 个；敏感信息提醒勿在聊天中粘贴完整私钥/卡号。涉及航旅易达时，额外勿索要或接收乘客信息、联系人电话、支付账号、密码、航司 B2B 账号（见 references/产品能力/航旅易达/航旅易达.md「环境与安全约束」）。

④ 执行前确认

• 即将执行的操作包括：curl 拉文档、输出完整代码、运行 scripts/、给出生产环境配置建议 等，执行前用一句话说明将做什么。
• 运行 scripts/ 前须先执行 python scripts/tools/check_python_env.py；未通过则向用户说明须 Python ≥3.10 并安装 scripts/requirements.txt，不得继续执行其他脚本。
• 示例：「我将根据小程序支付场景拉取统一下单在线文档并整理必填参数表，确认后继续？」
• 涉及生产环境、真实资金操作（支付、退款、提现、分账、结算）时，额外提示风险：建议先沙箱、写操作需幂等与查单、生产密钥勿泄露。航旅易达无沙箱，不适用「建议先沙箱」，须直接按生产二次确认。
• 商户再次确认后才执行；若仅要方案不要代码，执行范围限于文档与步骤，不生成可运行密钥或调用生产。

生产环境调用强约束（不可跳过）：任何指向生产环境的实际接口调用（含运行 scripts/ 直连生产网关、生产密钥发起的下单/退款/提现/分账/结算等写操作，及任何会产生真实资金或真实数据变更的请求），在已完成上述④确认的基础上，必须再向商户单独发起一次显式二次确认，并明确告知：目标环境=生产、操作类型、影响的资金/订单范围、不可逆风险。仅当商户明确回复同意（如「确认在生产执行」）后方可发起；商户未确认、回复模糊或要求先看时，一律默认按沙箱/演示处理或仅输出方案与命令，不得擅自调用生产。

对话阶段与技能动作的对应关系

商户开口
  → ① 明确需求（产品决策 / 关键词 / 澄清模板 / 排障初判）
  → ② 征得同意（提出下一步，等待确认）
  → ③ 收集信息（场景已锁定后的环境与参数）
  → ④ 执行前确认（拉文档 / 写代码 / 跑脚本）
  → 按下方「技术执行顺序」落地
  → 按「标准输出模板」回复

通用技术纪律（执行阶段遵守）

• 写操作（支付、退款、分账、提现等）前确认：环境（沙箱/生产）、商户号、AppKey、notifyUrl 来源。
• 面向生产环境发起任何实际调用前，必须经商户显式二次确认（见面客纪律④「生产环境调用强约束」）；未确认时不得直连生产，只输出方案/命令或按沙箱处理。
• account（账户）、balance（代付代发）分组的资金出款类接口（如提现 /rest/v1.0/account/withdraw/order、代付 /rest/v1.0/balance/transfer_send）必须使用 CFCA 证书签名并配置 IP 白名单；未配置证书直接调用会报错。涉及出款接入/排障时，先读 references/平台文档/接入准备/密钥管理/CFCA证书介绍.md。
• 交易终态 = 回调 + 查单 双通道确认，不以前端页面为准。
• 写操作使用业务唯一单号；回调处理必须幂等；超时/未知先查状态再决定是否重试。
• 错误码两层：先看接口自身业务码，再看平台通用码（见 references/平台文档/开始对接/平台错误码说明.md）。
• 禁止输出私钥、完整密钥、完整卡号/证件号。
• 接口字段以在线 doc_md 为准；curl 在技能里主要指拉取文档，业务网关调用须 YOP 签名，不能裸 curl 调通。

写代码任务路由（是否使用 SDK）

写对接代码前，先确认客户是否使用官方 SDK；未声明时列入「待确认」询问，不默认选路径。

分层说明（避免与步骤 4 表格混淆）：

• L1 / L2 / L2'：互斥路径，决定「怎么发请求」——自研签名/加解密（L1）或官方 SDK（L2 Java / L2' 其他语言）。
• L3：所有写代码任务共用，非互斥分支；指接口在线 doc_md（字段、错误码、示例代码骨架），在「技术执行顺序」步骤 5～7 与「文档加载协议」中统一处理。

使用官方 SDK？
  ├─ 是：
  │    Java → SDK使用说明.md（L2）+ doc_md 调用骨架（L3）
  │    其他语言 → 平台SDK.md 定位仓库 README（L2'）+ doc_md 参数表（L3）
  └─ 否（语言无 SDK，或主动不引依赖/自研网关/合规限制）：
       平台文档/平台规范/安全认证/ 的请求签名协议.md、回调解密协议.md（L1）
       实现签名/加密/回调解密 + doc_md 参数表（L3）+ scripts/ 本地验证

Java SDK 版本（L2 写代码前）：生成依赖坐标前须实时解析 yop-java-sdk 最新稳定版，禁止硬编码或凭记忆。优先 python scripts/tools/resolve_java_sdk_version.py，或按 SDK使用说明.md「版本解析协议」用 central.sonatype.com / Solr（须 sort=v desc）。勿用 search.maven.org（索引滞后）；勿用 不带 sort=v desc 的 Solr 查询（会误返旧版如 4.2.2-jdk6on）。软算法包版本与主包一致。

Java SDK 配置（L2）：只配 AppKey + 商户私钥；不要让商户配置易宝平台公钥 / SM2 平台证书（SDK 已内置并自动更新，手配错误反而验签失败）。生成配置时默认不写入 yop_public_key；审阅已有 yop_sdk_config*.json 若发现该项，先询问用户为何配置（如历史兼容、非官方 SDK 混用等），再建议用户自行移除，勿直接删改对方配置。详见 SDK使用说明.md §三。

技术执行顺序（商户已确认场景且同意继续后）

1. 核对前提：对照 references/产品能力/产品决策.md 核对已确认的方案与收款主体（标准/平台/服务商）；核对不通过（场景或主体仍有歧义）→ 退回面客纪律①②继续澄清，不进入后续步骤。
2. 【强制】阅读场景 md 与易错点：先按下方「业务域路由」定位业务域（入网/收单/退款/分账/出款/对账/金融/航旅易达），收单再按「收单场景索引」锁定具体场景文件，金融再按「金融场景索引」锁定产品文件，航旅易达再按场景 md「渠道决策」锁定渠道；完整阅读 references/产品能力/<业务域>/<场景>.md 全文，其中 ## 易错点 章节为必读（及该节引用的关联文档，如 prePayTn唤起方式速查.md）。未完成本步禁止进入步骤 5（curl doc_md）及步骤 7（生成代码/参数表）。若映射不到任何业务域/场景（需求超出覆盖范围或仍有歧义）→ 用 产品决策.md 模板 7（超出产品能力范围） 回复或退回面客纪律①②澄清，不臆造场景路径。
3. 写代码任务：按「写代码任务路由」确认 SDK 使用意愿，锁定 L1 / L2 / L2' 之一（L3 不在此步选择，见步骤 5～7）。
4. 按路径与任务类型读平台文档（用 references/平台文档/platform-doc-manifest.yaml 的 topics 定位；下表为必读，其余按需）：

L3（接口 doc_md）：上表仅覆盖 L1/L2 的本地平台文档；L3 为在线接口文档，在步骤 5 定位 doc_md、步骤 6 curl 拉取、步骤 7 生成代码时处理，纪律见「文档加载协议」与「示例代码节纪律（L3）」。

1. 在 references/产品能力/api-index.yaml 定位接口 doc_md（L3 起点；前置条件：步骤 2 易错点已读）。
2. 生成或核对接口字段/错误码前，必须执行文档加载协议（curl doc_md）（L3 拉取；前置条件：步骤 2 易错点已读）。
3. 依据 doc_md、步骤 2 易错点与所选 L1/L2 路径生成代码/参数表（遵守「示例代码节纪律（L3）」；参数取值须与易错点一致，冲突时以 doc_md 字段定义为准、易错点约束业务选型与组合）。
4. 需要本地验证时，经④确认后先运行 python scripts/tools/check_python_env.py（Python ≥3.10 与依赖就绪）；未通过则引导用户升级 Python / pip install -r scripts/requirements.txt，不得继续执行其他脚本。通过后再使用 scripts/（见 scripts/README.md）。
5. 按「标准输出模板」回复。

文档加载协议（API 类任务）

接口规格从开放平台在线 markdown 实时 curl 获取：

1. 在 api-index.yaml 按域+场景定位目标接口，取其 doc_md。
2. 拉取接口文档：
   curl -sS "https://open.yeepay.com/docs-v3/api/<slug>.md"
   slug：<method小写>_<path去掉开头/，/ 换 _>（保留 . 与 -）
   例外：yos 等接口优先用 api-index 已实测的 doc_md；404/403 再试 options_ 前缀。
3. 涉及回调（**以接口 doc_md 为准**）：
   a. 在上一步拉取的 doc_md 中查找「结果通知」节（含通知编码与 notify 文档链接）。
   b. 取该节中的通知编码 / notify 文档 URL，curl 拉取 notify 文档后再实现回调解析。
   c. api-index 的 notify_spi 仅为索引提示；与 doc_md 不一致或缺失时，**以 doc_md 为准**，不得臆造 SPI。
4. 参数解读（**以拉取到的反参为准，禁止凭字段名或同类接口推断**）：
   a. 各参数的支持方式（取值范围、枚举、格式、业务含义）以该 API 内
      该参数的**描述（description）**为准。
   b. `是否必填` = **条件必填** 时，openapi.json 格式的接口须额外读取该参数的
      `x-yop-api-param-condition` 字段获取必填条件；未读取前不得按「可选」处理，
      也不得自行编造条件。
5. 场景 md 只提供流程与易错点；禁止仅凭它拼接口参数。
6. curl 失败/超时：提示检查网络；不得编造字段；停止字段级实现。
7. 回复中注明 doc_md「基本信息」中的 API ID 与「最后更新时间」。

示例代码节纪律（L3）

doc_md「示例代码」节为自动生成的全参数模板（含脏占位值），agent 只取调用骨架（Client 构建、请求方法、Content-Type）。 参数 MUST 按「请求参数」表的必填/条件逻辑重新筛选，禁止照抄全部 addParameter 与占位值。 参数的支持方式以该参数 description 为准；条件必填 参数在 openapi.json 中须读 x-yop-api-param-condition 拿到必填条件后再决定是否传（见「文档加载协议」第 4 条）。

人类可读页 https://open.yeepay.com/docs/products/<product>/api/<uri> 为 SPA，curl 取不到字段。 doc_md 章节结构：基本信息、请求参数、请求示例、响应参数、响应示例、错误码、（有回调时）结果通知、示例代码。 references/平台文档/ 为本地权威内容，不走 curl。

航旅易达例外：机票接口按渠道（解决方案）组织，不适用 docs-v3/api/<slug>.md 推导规则； 阅读顺序强制：先 curl「产品介绍」intro_md（适用场景）→（若有）config_md 渠道配置说明并指导商户完成/确认 → 再 curl「接口调用指引」doc_md（接口调用顺序矩阵）→ 字段级实现前 curl 目标接口 openapi.json（清单见 references/产品能力/航旅易达/渠道API清单.md）。 产品介绍场景不匹配时不得套用该渠道接口；不得从其他渠道推导接口契约；curl 失败时不得臆造内容。 渠道配置：配置通常需商户后台、运营、客户经理或航司侧动作，Agent 不能代完成。 无沙箱：航旅易达接口均在生产环境调用，不得按「先沙箱」引导；实际调用须生产二次确认。 敏感信息：勿向 Agent 索要或接收乘客信息、联系人电话、支付账号、密码、航司 B2B 账号；示例一律用占位符。 开票：机票报销凭证/开票诉求通常引导至电子行程单接口；不要按通用增值税发票产品处理（见场景 md「附加能力说明」）。

业务域路由

需求不在上表覆盖范围时，使用 产品决策.md 模板 7（超出产品能力范围） 回复，不臆造方案。

收单场景索引

金融场景索引

金融域面向持牌金融机构（银行、消费金融、汽车金融、融资租赁、保险、基金、信托、小贷、保理等）。选型先按 references/产品能力/产品决策.md「二之二、金融行业决策树」按钱的方向分流，需求模糊时用模板 8（代扣方向）或模板 9（放款模式）澄清。

金融域强约束（生成参数/代码前必须已读对应场景 md「易错点」）：

• 协议支付 1.0 与 2.0 是两套接口：下单与查询必须配对（1.0 cnppay-agreement-pay-request ↔ cnppay-query；2.0 financial-order-pay-request ↔ financial-order-pay-query），交叉使用会查不到订单。
• 协议支付 ≠ 收单：商户主动发起的银行卡代扣走金融域；用户在场主动付款走收单域，不可互换。
• 放款付款卡/收款卡不可颠倒：remitCardInfo（付款方=资金方）订单付款业务下只支持 CORPORATE；receiverCardInfo（收款方=借款人）支持 DEBIT/CORPORATE。
• 产品按银行开通三级产品：放款、协议支付快捷还款、信用卡还款均须先明确银行；放款另需完成对公户报备。
• 签约关系一致性：用 bindId 扣款时若上送 userType/userNo，必须与绑卡时一致；不上送用户标识需与易宝单独沟通配置。

工具脚本（本地，Python ≥3.10）

运行任何脚本前须完成面客纪律 ②③④，并先执行 check_python_env.py；仅用于联调，生产走商户自有系统。详见 scripts/README.md。

标准输出模板

以下模板是结构参考而非强制表单：按对话所处阶段选用，可裁剪空节、合并小节。需求已明确走「快速通道」时，可跳过 A/B 直接用 C（接入实现）；用户明确「只要代码/参数」时，C 可精简为「关键易错点 + 接口 + 实现步骤 + 代码 + 风险与待确认」，但仍须保留 ## 关键易错点（来自场景 md，不可省略）、API ID/最后更新时间（来自 curl 的 doc_md）与环境/生产二次确认提示。

A. 首次咨询 / 场景未定时（对应 ①②）

## 我的理解
（用商户语言复述需求）

## 初步判断
（推荐方向 + 简短原因，不涉及接口参数）

## 需要您确认的场景
（引用产品决策澄清模板中的问题，或 2～4 个选择题）

## 确认后我可以帮您
（列出 1～2 项可选下一步，等待用户同意）

B. 方案已确认、尚未写代码（对应 ③）

## 为您匹配的方案
（场景名称 + 对应场景 md）

## 接入概览
（3～5 步业务流程，商户能看懂）

## 开通产品与前置条件
（若适用）

## 继续前需要您提供
（逐项列出，标注必填/选填）

## 您确认后我将
（拉文档 / 整理参数表 / 示例代码 — 须用户同意才做）

C. 接入实现（对应 ④ 之后）

## 场景
## 关键易错点（已从场景 md 核对）
（逐条列出场景 md「## 易错点」中与本次实现相关的条目，可用勾选形式标注已落实）
## 必读规则（平台文档）
## 接口（含 API ID 与最后更新时间）
## 实现步骤
## 风险与约束（幂等/回调/查单/环境）
## 待确认（环境/是否使用SDK/支付方式/参数来源）

D. 排障结论

## 现象
## 已排除
## 最可能原因（按优先级）
## 建议操作（先查后重试）
## 需补充的信息
## 如需我进一步查文档或脚本验证
（说明将做什么，等待同意）

目录说明

本技能包路径：skills/yeepay-payment-integration/（仓库 yeepay-skills 内）。

../../                           仓库根（yeepay-skills）
  README.md / CHANGELOG.md / LICENSE.md
SKILL.md                         本文件，唯一入口（面客纪律 + 技术执行）
scripts/                         Python 联调工具（仅本地，详见 scripts/README.md）
  validate_docs.py             发版守门（死链/版本一致/测试向量校验）
  common/                      跨算法共用库
    python_version.py          Python 版本校验（≥3.10）
    response_verify.py         应答验签（RSA/SM2）
    url_encoding.py            签名一次编码 / HTTP 二次编码
    yop_headers.py             YOP 标准头
    yop_content_type.py        Content-Type 规范
    yop_http.py                HTTP 报文组装
    yop_gateway.py             生产 yos / 沙箱 sandbox 网关
    yop_multipart.py           multipart 签名
    yop_payload.py             请求体编解码
  rsa/ sm/                     RSA / 国密 SM2 密钥、客户端、查单/回调、测试向量
  tools/                       跨算法 CLI：环境校验、向量校验、离线应答验签、Java SDK 版本查询
references/
  troubleshooting.md           各业务域排障汇总
  平台文档/                    本地权威（约 30 篇）
    platform-doc-manifest.yaml   平台规则导航索引（topics 定位必读文档）
    接入准备/                  快速接入、应用管理、密钥管理（CFCA/RSA/SM）
    开始对接/                  SDK、沙箱、IP 白名单、错误码、Java SDK 报错
    平台规范/                  上线检查、回调网络、结果通知机制/查询重发
      安全认证/                鉴权/加密/签名/回调解密/结果通知 + 请求签名协议（含测试向量）
    工具与支持/                常见问题、最佳实践（文件下载）、开发工具（SDK/密钥/MCP/诊断）
  产品能力/
    产品决策.md                选型、关键词、澄清模板、超范围回复
    api-index.yaml             API curl 清单（doc_md / path / method / api_id）
    入网/ 收单/ 退款/ 分账/ 出款/ 对账/   场景文档（流程+易错点+前端示例+引用）
    金融/                      放款、信用卡还款、协议支付 + 一键绑卡支持银行速查
    航旅易达/                  机票场景文档（渠道决策+易错点）与渠道API清单（openapi.json 索引）