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