通联支付跨境系统香港发卡VCC项目 API接口对接SKILL

Polar Sponsor
爱发电 赞助
.NET 9.0

仅依据内嵌业务规范,为跨境香港发卡 GCP 接口自动生成:带逐字段中文注释的 DTO、请求 / 响应模型、业务服务、通知处理器,以及真实 HTTP 集成测试(不使用 Mock HTTP 客户端);签名与验签逻辑统一复用 gcp-api-quick-integration 组件。

GCP API 跨境香港发卡业务模型生成器

功能概述

GCP API 跨境香港发卡业务模型生成器是一项面向实际任务的技能,主要用于Purpose;在已完成签名与验签底座( gcp-api-quick-integration )的前提下,仅凭 本 Skill 内嵌规范 生成发卡平台业务对接代码:;

核心要点

  • DTO / 请求响应模型( 字段须带中文注释 ,释义来自内嵌规范表头「中文名称」及「备注」等);
  • 合作方 → 通联的主动调用业务服务;
  • 通联 → 合作方的回调处理骨架( 先验签,再解析。

使用与执行

它将相关步骤、工具调用和结果整理方式集中到统一流程中,帮助使用者更快完成目标并减少重复操作。从功能定位来看,该技能强调把分散的操作要求整理成清晰、可复用的处理流程,使用户能够围绕既定目标快速准备输入、选择执行方式并获得结构化结果。实际使用前应先确认任务范围、数据来源、运行环境、必要权限和关键参数,再依据技能说明逐步执行;

结果检查与注意事项

若输入条件不完整,应先补齐信息或采用保守配置,避免因错误假设导致结果偏离需求。执行过程中需要关注工具调用是否成功、接口或依赖是否可用、输出格式是否符合预期,并对异常提示、缺失字段和边界情况进行处理;涉及批量任务时,还应保存进度,避免中断后重复操作。

GCP API 跨境香港发卡业务模型生成器

Purpose

在已完成签名与验签底座(gcp-api-quick-integration)的前提下,仅凭 本 Skill 内嵌规范 生成发卡平台业务对接代码:

  • DTO / 请求响应模型(字段须带中文注释,释义来自内嵌规范表头「中文名称」及「备注」等)
  • 合作方 → 通联的主动调用业务服务
  • 通联 → 合作方的回调处理骨架(先验签,再解析)
  • 每个 出站 业务接口对应的 真实 HTTP 集成测试(见下文「Java/Spring:Outbound 集成测试」);禁止用 Mockito 等对签名 HTTP 客户端做桩替代联调。

唯一规范来源:embedded-hk-card-api-spec.md(与对外文件名《跨境香港发卡API文档(脱敏)》内容一致)。

不在本 Skill 内重复生成:公共 HTTP 头、StringToSign、RSA 签名/验签、敏感数据 AES 解密规则等;一律以 gcp-api-quick-integration 的 signing-and-verify-spec.md、implementation-pitfalls.md 为准。内嵌规范中「安全签名」「响应报文的验签过程」「敏感数据解密」等章节仅作业务侧理解参考,实现须回到底座。

Code Layout, Naming, and Observability(强制)

生成对接代码时须同时满足:

  1. 命名(禁止文档章节号当包名):类名、包名、文件名 不得 使用 chapter6、section3 等纯章节标识;应使用 业务域名称(账户、VA 入金、支付交易、卡申请、卡状态、卡交易、子商户、文件、共享资金等),与内嵌规范中的接口分组语义一致。接口编号(如 3000、4000)可用于注释或常量名,但不宜作为包路径主语义。
  2. 调试日志与请求 JSON:在 HTTP 客户端或服务编排层输出 请求 URL、请求报文(body)、HTTP 状态码、响应报文;请求头须脱敏(如不打印完整 X-AGCP-Auth、敏感 keyid 等)。若底座已具备同等日志,业务层不得重复刷屏,但须保证联调路径上至少有一处完整可见。上送 JSON 时,字段值为 null 的键不得出现在报文中(禁止 "field": null 等);序列化使用 NON_NULL(或语言等价物),且 SHA256 摘要与签名必须基于与 HTTP 实体完全一致的 UTF-8 字节(见 ../gcp-api-quick-integration/implementation-pitfalls.md 第 2.1 节)。
  3. 包隔离:在客户工程中落在 单一、明确的新 package 根(例如 …integration.gcp.hkcard 或客户指定根),其下再分子包(client、config、security、service、handler、model 及按业务域分的 model 子包);避免与现有业务包混放。
  4. 请求/响应模型形态(Java 强制,其他语言按 idiomatic 等价):
    • 禁止以「单文件容器类 + 大量 public static class 嵌套」作为唯一形态。
    • 每个请求、每个响应各为独立顶层类型,一公开类型对应一个源文件;业务上需复用时用 extends 或组合,仍为独立文件。
    • 字段须可通过 标准 JavaBean 方式赋值:优先 @Getter / @Setter(Lombok) 或 手写 getter/setter;禁止仅提供 public 字段却无访问器。
    • 生成/保存 .java 源文件须为 UTF-8 且无 BOM。
  5. 请求/响应字段中文注释(强制):生成 请求模型、响应模型、回调入参模型(含公共请求查询参数、公共响应字段及各接口扩展字段)时,每个属性/字段 均须附带 中文说明,且与 embedded-hk-card-api-spec.md 中对应接口表格一致,禁止臆造规范未出现的含义。
    • Java:每个字段声明 上方 使用 /** … */ JavaDoc;正文以规范表 「中文名称」 为主,并酌情并入 「必输」「备注」 要点(可精简,不得丢失必输/条件必输/枚举取值等关键语义)。类级 JavaDoc 可写明对应接口 path 与方向(合作方→通联 / 通联→合作方)。
    • 其他语言:使用惯用的文档注释,同样须逐字段中文说明。

特殊接口行为(须在生成代码与说明中体现)

  • 公共查询参数:authcus、merid、reqid 须放在 URL query,不得放入 JSON body(见内嵌规范「公共请求参数」)。
  • 文件上传 7000:Content-Type: application/octet-stream;body 为 Base64(URL Safe)编码后的内容;签名用 RequestPayload 为未 Base64 的原始文件字节(与内嵌规范一致;底座须已按 implementation-pitfalls.md 处理)。
  • 7005 等文件流 / 加密 CSV:响应为二进制或加密流时,业务客户端须按规范处理 AES 解密与落盘,不在本 Skill 内重复密码学细节,须调用底座或项目内已有解密工具。
  • 卡号脱敏:内嵌规范 4.4 起多接口返回脱敏卡号;模型注释中保留规范描述,不得改为「完整卡号」语义。

Java / Spring:Outbound 集成测试(强制)

当目标栈为 Java + Spring Boot 且生成 合作方 → 通联 的出站 JUnit 测试时,须遵守:

  1. 禁止 Mock HTTP 客户端:不得对签名底座暴露的 HTTP 客户端使用 @Mock、@MockBean、@Spy 等绕过真实 TLS/签名/序列化链路。
  2. 必须 @SpringBootTest(classes = …):测试类所在包往往与 @SpringBootApplication 不同包,须 显式 指定启动类,避免 Unable to find a @SpringBootConfiguration。
  3. 配置与密钥:敏感项放在 .gitignore 覆盖的本地文件(如项目根目录 application-local.properties),主配置可用 spring.config.import=optional:file:./application-local.properties;测试侧用 @TestPropertySource 等与本地联调一致。不得在生成的业务源码中硬编码私钥/平台公钥。
  4. CI 可选跳过:若无本地配置文件,可使用类级 @EnabledIf(或等价)检测文件存在性后 整类跳过;有文件时 必须 发起真实请求。
  5. 一接口一测试方法:每个已覆盖出站 path 至少一个 @Test 方法,注入真实 …Service,调用后断言响应非空或断言 rspcode 等业务约定。
  6. 回调(通联 → 合作方):自动化测试若无法取得网关真实签名报文,可不在本 Skill 内生成「假验签」的 Mock 单测;须在交付说明中写明通过网关实调或内嵌 HTTP 服务做联调验证,不得用 Mock HTTP 客户端冒充「已验证出站签名链路」。

Mandatory Workflow

  1. 先检查项目中是否已有签名底座能力(请求签名 + 响应/回调验签 + 与网关一致的 HTTP 头)。
  2. 若缺失:先按 gcp-api-quick-integration 生成底座,且生成后须满足 signing-and-verify-spec.md 与 implementation-pitfalls.md,再继续本 Skill。
  3. 解析 embedded-hk-card-api-spec.md,按文档中的 接口 path、方向、请求/响应表 生成模型、Service、Handler(覆盖用户指定范围;默认覆盖内嵌规范中全部合作方发起的 HTTP 接口及文档列出的回调路径)。
  4. 业务接口代码生成完成后,必须同步为每个 出站 接口生成对应的 真实 HTTP 集成测试 方法。
  5. 所有合作方→通联且返回 JSON 的接口,响应模型须包含 公共响应字段(rspcode、rspinfo、authcus、merid、reqid 等,见内嵌规范「公共响应字段」);在此之上扩展业务字段。若某接口文档写明「仅公共响应参数」,不得臆造额外字段。
  6. 默认覆盖全部接口;若用户指定子集,必须列出未生成部分并确认。
  7. 交付说明中须写明:出站测试为 真实 HTTP 集成测试;本地/CI 如何通过 application-local.properties(或等价)启用与跳过;若目标为 Java 8,禁止使用 String.isBlank、Path.of、Files.readString 等仅高版本 JDK API。
  8. 若生成 Java + Maven:提示 Maven 3.6.x 与 Spring Boot 3 可能不兼容时的处理;修改 application.properties 后建议 mvn clean。

Output Contract

  • 已识别输入
  • 签名底座检查结果(已存在 / 自动补齐)
  • 已覆盖接口列表(含 path 与文档编号)
  • 将创建/修改的文件
  • JUnit 测试生成清单(按接口映射到测试方法)
  • 与签名底座的依赖清单
  • 运行或编译命令
  • 自检清单(output-checklist.md)

Guardrails

  • 禁止用「单文件嵌套 static 类」替代独立 DTO 文件;禁止仅暴露 public 字段而无 getter/setter(Java);禁止带 BOM 的 UTF-8 Java 源文件。
  • 禁止请求/响应/回调模型字段 缺少中文注释 或注释与内嵌规范表意明显不符。
  • 禁止将钉钉/外链附件或未内嵌的 Excel 当作代码生成真源;path 与字段以 embedded-hk-card-api-spec.md 正文表格为准(外链仅供人工查阅)。
  • 禁止在本 Skill 内 重写 签名/验签算法;须复用 gcp-api-quick-integration 约定。
  • 禁止臆造规范中不存在的 path 或字段。
  • 不把私钥、平台公钥写入业务生成代码。
  • 不生成 controller 层代码;业务入口仅限 service/handler 及其测试。
  • 禁止为验证「合作方 → 通联」出站链路而 Mock 签名 HTTP 客户端。

Field Experience(与底座联调时已验证)

与机构 VA 等业务线相同,常见问题参见 ../gcp-api-quick-integration/implementation-pitfalls.md(X-AGCP-Auth 小写 hex、X-AGCP-Date / Send / Crdt 格式、回调验签 hex 解码、Java 8 API、UTF-8 BOM 等)。

Related Files

  • embedded-hk-card-api-spec.md
  • dependency-contract.md
  • output-checklist.md
  • examples.md
  • 签名底座:../gcp-api-quick-integration/signing-and-verify-spec.md、../gcp-api-quick-integration/implementation-pitfalls.md

相关专题

更多
Navicat创建数据库教程
Navicat创建数据库教程

本专题整理Navicat创建数据库相关教程,介绍新建前的准备、基础设置和创建后的检查方法。内容兼顾入门学习及实际使用需求,帮助用户了解不同数据库类型下的操作差异,为后续建表、保存数据和日常管理提供参考。

2026.11.20

0

7

Navicat入门教程大全
Navicat入门教程大全

本专题整理Navicat入门教程,从认识软件界面到开展数据库操作,介绍初次使用需要了解的知识和方法。内容兼顾连接配置、数据管理及日常使用中的疑问,方便用户按学习进度查阅,为后续实践和独立操作打好基础。

2026.11.20

0

17

Navicat数据库连接配置指南
Navicat数据库连接配置指南

从确认数据库信息到建立可用连接,本专题串联Navicat连接数据库的相关知识和操作方法。既有初次配置时需要了解的基础内容,也有连接后的检查思路,方便用户按实际需求查阅教程,逐步熟悉数据库连接的设置流程。

2026.11.20

0

10

PHP8.6数组与数据处理教程
PHP8.6数组与数据处理教程

本专题汇总PHP8.6数组与数据处理教程,涵盖CSV读取和导出、引用遍历删除、array_filter回调模式、配置键名冲突、pathinfo文件名校验、GMP大整数进制转换及UTF-8正则筛选,说明升级兼容变化、输入范围和失败处理方法。

2026.11.20

0

8

PHP8.6升级迁移教程
PHP8.6升级迁移教程

本专题汇总PHP8.6升级迁移与弃用接口改造教程,涵盖反射调用、对象属性赋值、标识符更名、构造函数与__debugInfo调整,以及插件类名检查、常量导出、ArrayIterator排序、SPL和DTO查询参数转换,帮助梳理弃用提示并完成代码兼容改造。

2026.11.20

0

10

PHP8.6安装配置与FPM运维教程
PHP8.6安装配置与FPM运维教程

本专题汇总PHP8.6正式版安装部署与FPM运维教程,涵盖Linux并存安装、独立ini配置、扩展重新编译、Nginx切换与回滚、FPM状态监控和慢日志排查,以及环境变量、请求超时、OPcache刷新和预加载配置。

2026.11.20

0

10

Nginx CVE-2026-123007排查与防护指南
Nginx CVE-2026-123007排查与防护指南

Nginx HTTP/2漏洞该怎么修复?本专题围绕CVE-2026-123007,介绍安全版本升级、模块兼容检查和配置恢复方法,以及日志排查、权限设置等后续加固操作,方便你按实际部署情况查找对应教程。

2026.11.20

0

8

GoFrame框架Web开发与路由中间件
GoFrame框架Web开发与路由中间件

本专题聚焦GoFrame框架的Web开发,拆解路由注册与匹配规则、请求参数获取、参数校验与中间件执行顺序,说明统一响应、JWT鉴权、文件上传与接口文档生成的落地方式,并补充优雅重启与测试实践。

2026.11.17

0

15

GoFrame框架安装与gf命令行工具
GoFrame框架安装与gf命令行工具

本专题围绕GoFrame框架的安装与工具链配置展开,讲清Go版本要求、gf命令行的安装方式、代理镜像与依赖准备,说明项目初始化、热编译、交叉编译打包的做法,并整理安装阶段的常见报错与验证步骤。

2026.11.17

0

15

热门下载

更多
网站特效
/
网站源码
/
网站素材
/
前端模板

精品课程

更多
热门推荐
/
最新课程
phpStudy极速入门视频教程
phpStudy极速入门视频教程

共6课时 | 54.7万人学习

独孤九贱(4)_PHP视频教程
独孤九贱(4)_PHP视频教程

共89课时 | 134.3万人学习