仅依据内嵌业务规范,为跨境香港发卡 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(强制)
生成对接代码时须同时满足:
- 命名(禁止文档章节号当包名):类名、包名、文件名 不得 使用
chapter6、section3等纯章节标识;应使用 业务域名称(账户、VA 入金、支付交易、卡申请、卡状态、卡交易、子商户、文件、共享资金等),与内嵌规范中的接口分组语义一致。接口编号(如3000、4000)可用于注释或常量名,但不宜作为包路径主语义。 - 调试日志与请求 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 节)。 - 包隔离:在客户工程中落在 单一、明确的新 package 根(例如
…integration.gcp.hkcard或客户指定根),其下再分子包(client、config、security、service、handler、model及按业务域分的model子包);避免与现有业务包混放。 - 请求/响应模型形态(Java 强制,其他语言按 idiomatic 等价):
- 禁止以「单文件容器类 + 大量
public static class嵌套」作为唯一形态。 - 每个请求、每个响应各为独立顶层类型,一公开类型对应一个源文件;业务上需复用时用
extends或组合,仍为独立文件。 - 字段须可通过 标准 JavaBean 方式赋值:优先
@Getter/@Setter(Lombok) 或 手写 getter/setter;禁止仅提供public字段却无访问器。 - 生成/保存
.java源文件须为 UTF-8 且无 BOM。
- 禁止以「单文件容器类 + 大量
- 请求/响应字段中文注释(强制):生成 请求模型、响应模型、回调入参模型(含公共请求查询参数、公共响应字段及各接口扩展字段)时,每个属性/字段 均须附带 中文说明,且与
embedded-hk-card-api-spec.md中对应接口表格一致,禁止臆造规范未出现的含义。- Java:每个字段声明 上方 使用
/** … */JavaDoc;正文以规范表 「中文名称」 为主,并酌情并入 「必输」「备注」 要点(可精简,不得丢失必输/条件必输/枚举取值等关键语义)。类级 JavaDoc 可写明对应接口 path 与方向(合作方→通联 / 通联→合作方)。 - 其他语言:使用惯用的文档注释,同样须逐字段中文说明。
- Java:每个字段声明 上方 使用
特殊接口行为(须在生成代码与说明中体现)
- 公共查询参数:
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 测试时,须遵守:
- 禁止 Mock HTTP 客户端:不得对签名底座暴露的 HTTP 客户端使用
@Mock、@MockBean、@Spy等绕过真实 TLS/签名/序列化链路。 - 必须
@SpringBootTest(classes = …):测试类所在包往往与@SpringBootApplication不同包,须 显式 指定启动类,避免 Unable to find a @SpringBootConfiguration。 - 配置与密钥:敏感项放在
.gitignore覆盖的本地文件(如项目根目录application-local.properties),主配置可用spring.config.import=optional:file:./application-local.properties;测试侧用@TestPropertySource等与本地联调一致。不得在生成的业务源码中硬编码私钥/平台公钥。 - CI 可选跳过:若无本地配置文件,可使用类级
@EnabledIf(或等价)检测文件存在性后 整类跳过;有文件时 必须 发起真实请求。 - 一接口一测试方法:每个已覆盖出站 path 至少一个
@Test方法,注入真实…Service,调用后断言响应非空或断言rspcode等业务约定。 - 回调(通联 → 合作方):自动化测试若无法取得网关真实签名报文,可不在本 Skill 内生成「假验签」的 Mock 单测;须在交付说明中写明通过网关实调或内嵌 HTTP 服务做联调验证,不得用 Mock HTTP 客户端冒充「已验证出站签名链路」。
Mandatory Workflow
- 先检查项目中是否已有签名底座能力(请求签名 + 响应/回调验签 + 与网关一致的 HTTP 头)。
- 若缺失:先按
gcp-api-quick-integration生成底座,且生成后须满足signing-and-verify-spec.md与implementation-pitfalls.md,再继续本 Skill。 - 解析
embedded-hk-card-api-spec.md,按文档中的 接口 path、方向、请求/响应表 生成模型、Service、Handler(覆盖用户指定范围;默认覆盖内嵌规范中全部合作方发起的 HTTP 接口及文档列出的回调路径)。 - 业务接口代码生成完成后,必须同步为每个 出站 接口生成对应的 真实 HTTP 集成测试 方法。
- 所有合作方→通联且返回 JSON 的接口,响应模型须包含 公共响应字段(
rspcode、rspinfo、authcus、merid、reqid等,见内嵌规范「公共响应字段」);在此之上扩展业务字段。若某接口文档写明「仅公共响应参数」,不得臆造额外字段。 - 默认覆盖全部接口;若用户指定子集,必须列出未生成部分并确认。
- 交付说明中须写明:出站测试为 真实 HTTP 集成测试;本地/CI 如何通过
application-local.properties(或等价)启用与跳过;若目标为 Java 8,禁止使用String.isBlank、Path.of、Files.readString等仅高版本 JDK API。 - 若生成 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.mddependency-contract.mdoutput-checklist.mdexamples.md- 签名底座:
../gcp-api-quick-integration/signing-and-verify-spec.md、../gcp-api-quick-integration/implementation-pitfalls.md
热门AI工具
相关专题
本专题整理Navicat创建数据库相关教程,介绍新建前的准备、基础设置和创建后的检查方法。内容兼顾入门学习及实际使用需求,帮助用户了解不同数据库类型下的操作差异,为后续建表、保存数据和日常管理提供参考。
0
2026.11.20
本专题整理Navicat入门教程,从认识软件界面到开展数据库操作,介绍初次使用需要了解的知识和方法。内容兼顾连接配置、数据管理及日常使用中的疑问,方便用户按学习进度查阅,为后续实践和独立操作打好基础。
0
2026.11.20
从确认数据库信息到建立可用连接,本专题串联Navicat连接数据库的相关知识和操作方法。既有初次配置时需要了解的基础内容,也有连接后的检查思路,方便用户按实际需求查阅教程,逐步熟悉数据库连接的设置流程。
0
2026.11.20
本专题汇总PHP8.6数组与数据处理教程,涵盖CSV读取和导出、引用遍历删除、array_filter回调模式、配置键名冲突、pathinfo文件名校验、GMP大整数进制转换及UTF-8正则筛选,说明升级兼容变化、输入范围和失败处理方法。
0
2026.11.20
本专题汇总PHP8.6升级迁移与弃用接口改造教程,涵盖反射调用、对象属性赋值、标识符更名、构造函数与__debugInfo调整,以及插件类名检查、常量导出、ArrayIterator排序、SPL和DTO查询参数转换,帮助梳理弃用提示并完成代码兼容改造。
0
2026.11.20
本专题汇总PHP8.6正式版安装部署与FPM运维教程,涵盖Linux并存安装、独立ini配置、扩展重新编译、Nginx切换与回滚、FPM状态监控和慢日志排查,以及环境变量、请求超时、OPcache刷新和预加载配置。
0
2026.11.20
Nginx HTTP/2漏洞该怎么修复?本专题围绕CVE-2026-123007,介绍安全版本升级、模块兼容检查和配置恢复方法,以及日志排查、权限设置等后续加固操作,方便你按实际部署情况查找对应教程。
0
2026.11.20
本专题聚焦GoFrame框架的Web开发,拆解路由注册与匹配规则、请求参数获取、参数校验与中间件执行顺序,说明统一响应、JWT鉴权、文件上传与接口文档生成的落地方式,并补充优雅重启与测试实践。
0
2026.11.17
本专题围绕GoFrame框架的安装与工具链配置展开,讲清Go版本要求、gf命令行的安装方式、代理镜像与依赖准备,说明项目初始化、热编译、交叉编译打包的做法,并整理安装阶段的常见报错与验证步骤。
0
2026.11.17
热门下载
相关下载
精品课程