Wf API Integration

WF API Integration Skill

帮助用户对接万里汇(WorldFirst) API，支持 Java、Golang 和 Python 三种语言，涵盖转账、代发、收款人管理、账户管理（余额/额度/子账号/店铺/通知）、账单查询、交易订单管理等模块。

语言支持说明：Java 和 Golang 覆盖所有模块；Python 目前仅支持公共模块（common/）和账单管理模块（statement-management/），其余模块暂无 Python 模板。

模块索引

快速决策树

用户咨询 WF API 对接
        |
        +-- 在 WF 账户之间划转资金？ --> 万里汇转账
        |       |
        |       +-- 需要提前获取汇率/手续费？ --> 咨询转账（consultTransfer）
        |       +-- 发起转账？ --> 户到户转账（createTransfer）
        |       +-- 查询转账结果？ --> 查询转账结果（inquiryTransfer）
        |       +-- 接收转账结果回调？ --> 转账结果通知（notifyTransfer）
        |
        +-- 付款到第三方银行卡或电子钱包（发工资、供应商付款、支付宝代发）？ --> 全球分发（代发）
        |       |
        |       +-- 需要提前获取汇率/报价？ --> 咨询代发汇率（consultPayout）
        |       +-- 发起代发？ --> 创建代发（createPayout）
        |       +-- 查询代发结果？ --> 查询代发结果（inquiryPayout）
        |       +-- 接收代发结果回调？ --> 代发结果通知（notifyPayout）
        |
        +-- 管理收款人银行卡（增删改查、卡模版）？ --> 收款人管理
        |       |
        |       +-- 查看卡模版字段要求？ --> 查询卡模版（inquiryTemplate）
        |       +-- 绑定收款人？ --> 绑定收款人（bindBeneficiary）
        |       +-- 删除/编辑/查询收款人？ --> 对应接口
        |       +-- 接收绑卡结果回调？ --> 绑定收款人通知（notifyBindBeneficiary）
        |
        +-- 账户相关查询？ --> 账户管理
        |       |
        |       +-- 查看账户有多少钱？ --> 查询余额（inquiryBalance）
        |       +-- 查看账户基本信息？ --> 查询账户信息（inquiryAccount）
        |       +-- 查看可申报结汇额度？ --> 查询结汇额度（inquiryAvailableQuota）
        |       +-- 查看主/子账号信息？ --> 查询子账号（inquirySubuser）
        |       +-- 查看店铺及关联账号？ --> 查询店铺信息（inquiryStore）
        |       +-- 接收充值/垫付回调？ --> 充值通知（notifyVostro）
        |       +-- 接收余额变动回调？ --> 余额变动通知（notifyBalanceChange）
        |
        +-- 查看账户交易流水或对账？ --> 账单管理
        |       |
        |       +-- 查询流水列表？ --> 查询账单流水（inquiryStatementList）
        |       +-- 查询流水详情？ --> 查询账单详情（inquiryStatementDetail）
        |
        +-- 上传交易订单（跨境结汇 / B2B 订单关联）？ --> 交易信息管理
                |
                +-- 上传交易订单？ --> 提交交易订单（submitTradeOrder）
                +-- 查询上传结果？ --> 查询订单结果（inquiryTradeOrder）
                +-- 接收异步通知？ --> 订单回调通知（notifyTradeOrder）

场景关键词匹配

澄清话术

当用户描述模糊时：

请确认您需要对接的万里汇（WorldFirst）业务模块：

1. 万里汇转账
   在 WF 账户之间划转资金，支持转账前汇率咨询、发起转账、查询转账结果、接收转账结果回调通知
   适用：WF 账户间资金划转

2. 全球分发（代发）
   代发资金到第三方银行卡，支持跨币种汇率咨询、发起代发、查询代发结果、接收代发结果回调通知
   适用：发工资、供应商付款、跨境分发等场景

3. 收款人管理
   管理代发目标银行卡，支持卡模版查询、绑定/编辑/删除/查询收款人、接收绑定结果回调通知
   适用：维护代发收款方的银行卡信息

4. 账户管理
   查询 WF 账户信息、余额、结汇额度、子账号、店铺信息，接收充值/余额变动回调通知
   适用：账户信息查询、余额监控、充值垫付通知处理

5. 账单查询
   查询账户交易流水列表及流水详情
   适用：对账、交易记录查询

6. 交易订单管理
   上传交易订单、查询处理结果、处理异步回调通知
   适用：跨境电商 B2C 结汇、B2B 订单关联

请告诉我您需要对接哪个模块？

使用流程

1. 确认模块：确认用户需要对接的模块，读取对应模块的 README.md 了解接口列表
2. 确认接口：确认用户需要对接的具体接口，读取对应接口的 GUIDE.md 了解接口规范
3. 加载公共代码：读取 references/common/ 下的公共代码模板
4. 加载接口代码：读取对应接口目录下的代码模板
5. 生成代码：根据用户项目结构生成代码，替换 {basePackage}（Java/Python）或 {moduleName}（Golang）占位符
6. 代码检查：执行「代码生成后检查清单」中的各项检查
7. 测试验证：运行单元测试，确保代码可正常编译和运行

Pre-Generation Questions (MUST ASK)

在生成代码前，必须通过 AskUserQuestion 工具询问用户以下所有问题。所有问题必须在开始生成任何代码之前全部收集完毕。

基础信息

1. 项目路径：请问你的项目路径是什么？
2. 语言选择：你需要生成 Java、Golang 还是 Python 的代码？
3. Base Package / Module Name：
   • Java：请提供 base package（如 com.example.project）
   • Golang：请提供 Go module name（如 github.com/example/project）
   • Python：请提供 base package（如 wf_integration），用于组织 import 路径

WfConfig 配置属性（用于生成 WfConfig 类，禁止使用占位符）

以下属性必须在生成 WfConfig 前向用户收集真实值，严禁在代码中生成 YOUR_CLIENT_ID 等占位符让用户自行替换。

4. WF Client ID：请提供您的万里汇 Client ID
5. WF User ID：请提供您的万里汇登录 User ID
6. API Base URL：请提供 API 网关地址（默认 https://open-sea.worldfirst.com）
7. 私钥文件路径：请提供 RSA 私钥文件路径（PKCS#8 格式），如 /etc/wf/certs/private_key.pem
8. 公钥文件路径：请提供万里汇 RSA 公钥文件路径，如 /etc/wf/certs/wf_public_key.pem

重要：用户提供的值直接填入生成的 WfConfig 代码中。如果用户表示暂时不确定某个值，应使用 Spring XML property placeholder（如 ${wf.clientId}）、Go 环境变量读取（如 os.Getenv("WF_CLIENT_ID")）或 Python 环境变量读取（如 os.environ.get("WF_CLIENT_ID")）而非硬编码占位符字符串。

模块特定问题（按需询问）

以下问题仅在用户选择对应模块时询问：

收款人管理模块：

• 集成模式：请问您的 Payout 集成场景是使用卡详情模式（每次代发直接传银行卡信息）还是卡 token 模式（先绑定收款人获取 token）？
  • 卡详情模式：仅需集成 inquiry-template/（查询卡模版）
  • 卡 token 模式：需集成全部 6 个接口

交易订单管理模块：

• 业务场景：请问需要支持哪些业务场景？
  • PAY_INTO_CHINA（B2C 结汇）：需集成全部 3 个接口（submitTradeOrder、inquiryTradeOrder、notifyTradeOrder）
  • CREATE_B2B_ORDERS（B2B 订单关联）：仅需 submitTradeOrder
  • 两者都需要：生成完整套件

公共依赖

所有模块共用以下组件，位于 references/common/：

Java (references/common/java/)

Golang (references/common/golang/)

Python (references/common/python/)

公共代码生成规则

• WfConfig：使用 Pre-Generation Questions 中收集到的用户真实值（第 4-8 项）填充字段默认值，禁止使用占位符
• Result.java / result.go / result.py：共享，仅首次生成，已存在则复用
• WfErrorCode：共享，新接口的错误码追加到已有文件，不重复生成
• WfException：共享，已存在则复用

代码规范

Java

• Java 8（禁止使用 Java 9+ 专有语法）
• CamelCase 类名，lowerCamelCase 变量名，UPPER_SNAKE_CASE 常量名
• 同行左花括号，4 空格缩进，每行最多 120 字符
• 所有 public 方法必须有 Javadoc，使用 SLF4J 日志

Golang

• 标准库优先，按包分文件
• 依赖注入模式（构造函数注入）
• {moduleName} 占位符替换为用户实际 go.mod 中的 module path

Python

• Python 3.10+，使用 type hints 标注参数和返回值
• snake_case 模块名、函数名、变量名，PascalCase 类名，UPPER_SNAKE_CASE 常量名
• 4 空格缩进，每行最多 120 字符，遵循 PEP 8 规范
• 使用 dataclass 或普通类定义 Model，属性使用 snake_case
• 依赖管理通过 requirements.txt 声明，核心依赖：requests>=2.28.0、cryptography>=41.0.0
• {basePackage} 占位符替换为用户实际 base package 名称（用于 import 路径）

签名算法

所有 WF API 使用 RSA256 签名，签名内容格式：

POST {apiPath}\n{clientId}.{requestTime}.{requestBody}

详见 references/common/ 下的签名工具代码。

测试代码生成

每个 Client 类生成一个集成测试类，真实调用 WF API。

测试代码规范

1. 仅生成 Client 类的测试：只为 *Client.java 生成对应的 *ClientTest.java
2. 仅保留一个成功测试方法：每个测试类只包含 testXXX_Success() 一个测试方法
3. 真实HTTP调用：不Mock HTTP响应，通过 client.init() 初始化真实调用WF API
4. 配置使用占位符：clientId、密钥路径等使用 ${wf.xxx} 占位符，由用户自行配置

代码生成后检查清单 (POST-GENERATION CHECKLIST)

⚠️ 重要：每次生成代码后，必须执行以下检查，确保代码质量和完整性。

1. Model 类字段一致性检查

目的：确保生成的 Model 类字段与模板文件完全一致，避免字段遗漏。

检查步骤：

1. 遍历生成的所有 Model 类（位于 model/domain/、model/request/、model/response/）
2. 对比每个生成的类与对应模板文件（references/{module}/{interface}/{language}/model/，其中 {language} 为 java、golang 或 python）
3. 检查字段数量、字段名称、字段类型是否一致
4. Java：检查 Getter/Setter 方法是否完整；Python：检查 dataclass 字段或属性定义是否完整

检查命令示例：

# 对比生成的 FundMoveDetail.java 与模板
diff generated/FundMoveDetail.java references/statement-management/inquiry-statement-list/java/model/domain/FundMoveDetail.java

2. 单元测试运行检查

目的：确保生成的代码可以正常编译和运行，没有语法错误。

检查步骤：

1. 进入用户项目目录
2. 运行编译命令，确保无编译错误
3. 运行生成的单元测试，确保测试用例可正常执行

预期结果：

• 编译成功，无错误
• 单元测试可正常运行（即使测试用例失败，也要确保代码能跑起来）

3. 包名和导入检查

目的：确保生成的代码包名正确，导入语句无冲突。

检查要点：

• Java：包名与用户提供的路径一致；Python：模块路径与项目结构一致
• 无缺失的 import 语句（Python 中包括 from ... import ...）
• 无循环依赖

检查清单执行记录

每次生成代码后，在回复中必须包含以下检查记录：

✅ 代码生成后检查完成

1. Model 类字段一致性检查：
   - [x] FundMoveDetail.java - 18个字段，与模板一致
   - [x] StatementRecord.java - 24个字段，与模板一致
   - [x] ForeignExchangeQuote.java - 3个字段，与模板一致
   - [x] OperatorInfo.java - 2个字段，与模板一致
   - [x] Amount.java - 2个字段，与模板一致
   - [x] RelatedStatement.java - 3个字段，与模板一致

2. 单元测试运行检查：
   - [x] 编译成功
   - [x] 单元测试可正常运行

3. 包名和导入检查：
   - [x] 包名正确
   - [x] 导入语句完整

模块接口详情

万里汇转账（transfer）

📄 官方文档

注意事项：

• 转账为异步接口，PROCESSING 状态必须轮询
• transferRequestId 是幂等键，相同 ID + 不同 body → REPEAT_REQ_INCONSISTENT
• businessSceneCode 在主/子账号余额互转时必填 MULTI_ACCOUNT_TRANSFER
• notifyTransfer 是回调通知接口（WF → 集成商），需验签后返回 SUCCESS，业务逻辑异步处理
• 回调通知需返回成功响应，否则万里汇将重试最多 7 次

全球分发（payout）

📄 官方文档

• 支持四种收款模式（互斥）：
  • 卡详情模式（BANK_ACCOUNT_DETAIL）— 直接传银行卡详情
  • 卡 token 模式（BENEFICIARY_TOKEN）— 使用已绑定收款人的 token
  • 支付宝账户详情模式（ALIPAY_CN_DETAIL）— 代发到支付宝账户，paymentMethodMetaData 传空对象
  • 关联支付宝钱包模式（REFERENCE_ALIPAY_CN）— 代发到关联的支付宝钱包，paymentMethodId 传 referenceCustomerId
• 跨币种代发必须先调 consultPayout 获取 quoteId
• notifyPayout 是回调通知接口（WF → 集成商），需验签后返回 SUCCESS，业务逻辑异步处理
• 回调通知需返回成功响应，否则万里汇将重试最多 7 次
• 完整嵌套对象字段定义见 references/payout/field-reference.md

收款人管理（beneficiary）

📄 官方文档

账户管理（account-management）

📄 官方文档

注意事项：

• notifyVostro 和 notifyBalanceChange 是回调通知接口（WF → 集成商），非主动调用接口
• 回调通知需返回成功响应，否则万里汇将重试最多 7 次
• inquirySubuser 仅主账号可调用，子账号调用返回 USER_ACCOUNT_NOT_PRIMARY
• 余额 value 为最小货币单位的整数（如 USD 100.00 → value = 10000）

账单管理（statement-management）

📄 官方文档

注意事项：

• pageSize 固定为 10，不允许调用方修改
• pageNumber 范围 1-50
• inquiryStatementDetail 的 accountingBizNo 必须通过 inquiryStatementList 获取

交易信息管理（trade-order）

📄 官方文档

注意事项：

• sceneCode 决定必填字段集合
• tradeOrders 上限：B2C 最多 100 笔，B2B 最多 10 笔
• 完整嵌套对象字段定义见 references/trade-order/field-reference.md

安全红线

⛔ 以下规则为万里汇 API 对接的安全红线，违反可能导致资金损失或安全事故，必须严格遵守。

• 私钥禁止硬编码：RSA 私钥必须通过文件路径或密钥管理服务加载，严禁将私钥内容硬编码在源代码中。
• 私钥禁止记日志：私钥内容不得出现在任何日志输出中，包括 debug 级别日志。
• 私钥禁止传公共仓库：私钥文件不得上传到 GitHub、GitLab 等公共代码仓库，必须加入 .gitignore。
• clientId / secretKey 禁止明文存储：clientId 和密钥配置必须通过环境变量、配置中心或加密文件管理，禁止明文写入代码或配置文件提交到版本库。
• 响应必须验签：收到 WF API 响应后必须使用 WF 公钥验签，确认响应来自万里汇，防止中间人篡改。
• 异步通知必须验签：收到 notifyTradeOrder、notifyVostro、notifyBalanceChange、notifyTransfer、notifyPayout、notifyBindBeneficiary 等异步回调通知后，必须先验签再处理业务逻辑，防止伪造通知。
• 幂等性保障：转账（createTransfer）和代发（createPayout）等资金类接口必须使用唯一的 transferRequestId / payoutRequestId，防止因重试导致重复扣款。
• HTTPS 强制：所有 API 请求必须通过 HTTPS 发送，禁止使用 HTTP 明文传输。
• 转账/代发结果不可假定：发起转账或代发后，必须通过查询接口（inquiryTransfer / inquiryPayout）或异步通知确认最终状态，禁止仅凭请求响应的 status 判定最终结果。
• 生产密钥与测试密钥隔离：生产环境和测试环境必须使用不同的 clientId 和密钥对，严禁混用。