GCP API Organ Cus Business Model Generator

Purpose

在已完成签名底座（gcp-api-quick-integration）的前提下，仅凭内嵌规范生成第二至第六章对接代码：

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

唯一规范来源：embedded-organ-va-chapter2-6-spec.md。

Code Layout, Naming, and Observability（强制）

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

1. 命名（禁止章节名）：类名、包名、文件名 不得 使用 chapter2、chapter3、Chapter2Models 等章节标识；应使用 业务域名称（例如 VA 交易、账务、受益人、文件、子客户等），与内嵌规范中的接口分组语义一致。
2. 调试日志与请求 JSON：在 HTTP 客户端或服务编排层输出 请求 URL、请求报文（body）、HTTP 状态码、响应报文；请求头须脱敏（如不打印完整 X-AGCP-Auth、敏感 keyid 等，可截断或掩码）。若底座已具备同等日志，业务层不得重复刷屏，但须保证联调路径上至少有一处完整可见。上送 JSON 时，字段值为 null 的键不得出现在报文中（禁止 "bnfid": null 等）；序列化使用 NON_NULL（或语言等价物），且 SHA256 摘要与签名必须基于与 HTTP 实体完全一致的 UTF-8 字节（见 ../gcp-api-quick-integration/implementation-pitfalls.md 第 2.1 节）。
3. 包隔离：在客户工程中落在 单一、明确的新 package 根（例如 …gcp.organva 或客户指定的 …integration.gcp.organva），其下再分子包（client、config、security、service、handler、model 及按业务域分的 model 子包）；避免与现有业务包混在同一目录或随意散落在 com.example.* 根下。
4. 请求/响应模型形态（Java 强制，其他语言按 idiomatic 等价）：
   • 禁止以「单文件容器类 + 大量 public static class 嵌套」作为唯一形态（客户难以在 IDE 中导航，且常见诉求是 setXxx 链式/分步赋值）。
   • 每个请求、每个响应各为独立顶层类型，一公开类型对应一个源文件（文件名与类名一致）；业务上需复用时用 extends（如修改类继承注册类）或组合，仍为独立文件。
   • 字段须可通过 标准 JavaBean 方式赋值：优先 @Getter / @Setter（Lombok） 或 手写 getter/setter；禁止仅提供 public 字段却无访问器、却要求客户以「嵌套类名 + 字段」方式拼装（与上述独立类 + setter 目标冲突）。
   • 生成/保存 .java 源文件须为 UTF-8 且无 BOM（避免 javac 报 \ufeff 非法字符）。
5. 请求/响应字段中文注释（强制）：生成 请求模型、响应模型、回调入参模型（含公共响应基类及各接口扩展字段）时，每个属性/字段 均须附带 中文说明，且与 embedded-organ-va-chapter2-6-spec.md 中对应接口表格一致，禁止臆造规范未出现的含义。
   • Java：每个字段声明 上方 使用 /** … */ JavaDoc；正文以规范表 「中文名称」 为主，并酌情并入 「必输」「备注」 要点（可精简，不得丢失必输/条件必输/枚举取值等关键语义）。类级 JavaDoc 可写明对应接口 path 与方向（合作方→通联 / 通联→合作方）。使用 Lombok 时注释仍写在 字段上（IDE 一般在字段与 setter 调用链上可查阅；若团队要求 getter 上可见，可按项目既有 lombok.config 配置处理）。
   • 其他语言：使用惯用的文档注释（如 Python """ / #、C# /// 等），同样须逐字段中文说明，来源仍为内嵌规范。
   • regcus 等 JSON 字符串子结构：若生成独立 Payload 类型（如 OrganVaCusinfoBasePayload），各字段同样须带中文注释；若字段为「整段 JSON 字符串」类型（如 organvacusinfo），注释中说明「内容为 1.1 客户基础信息 JSON 字符串」等，与规范章节一致。

Java / Spring：Outbound 集成测试（强制）

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

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

Mandatory Workflow

1. 先检查项目中是否已有签名底座能力（签名客户端 + 验签能力）。
2. 若缺失：先按 gcp-api-quick-integration 生成底座，且生成后须满足 signing-and-verify-spec.md 与 implementation-pitfalls.md（见该 Skill 目录），再继续本 Skill。
3. 解析 embedded-organ-va-chapter2-6-spec.md 生成第二至第六章代码（DTO/模型/Service/Handler）。
4. 业务接口代码生成完成后，必须同步为每个 出站 接口生成对应的 真实 HTTP 集成测试 方法（@SpringBootTest + 真实 Service/Client，禁止 Mock HTTP 客户端）；至少能跑通 TLS 与签名并收到网关 HTTP 响应；可按接口补充断言或异常场景说明。
5. regcus 必须按规范将 organvacusinfo、organvainfo、uboinfo 作为 JSON 字符串上送。
6. 所有合作方->通联接口的响应模型均需包含“响应公共参数”；若接口还有特定响应字段，则在公共参数基础上追加，不得臆造字段。
7. 默认覆盖全部接口；若用户指定子集，必须列出未生成部分并确认。
8. 交付说明中须写明：出站测试默认为真实 HTTP 集成测试（非 Mock 客户端）；本地/CI 如何通过 application-local.properties（或等价）启用与跳过；若生成 Java 且目标为 Java 8，禁止在测试与公共工具类中使用 String.isBlank、Path.of、Files.readString 等仅高版本 JDK API。
9. 若生成 Java + Maven：在说明中提示客户环境 Maven 3.6.x 可能与 Spring Boot 3 不兼容时的处理（降级 Boot 2.7 或升级 Maven）；修改 application.properties 后建议 mvn clean 避免 target/classes 残留旧配置。

Output Contract

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

Guardrails

• 禁止用「单文件嵌套 static 类」替代独立 DTO 文件；禁止仅暴露 public 字段而无 getter/setter（Java）；禁止带 BOM 的 UTF-8 Java 源文件。
• 禁止请求/响应/回调模型字段 缺少中文注释 或注释与内嵌规范表意明显不符（不得空泛写「字段 xxx」而无业务含义）。
• 禁止用章节编号作为包名/类名/测试方法名的主要语义（须用业务域命名）；禁止引导用户查阅外部接口文档。
• 禁止重复生成签名/验签算法（须复用 gcp-api-quick-integration 约定；算法细节以 signing-and-verify-spec.md 为准）。
• 禁止臆造规范中不存在的 path 或字段。
• 不把私钥、平台公钥写入业务生成代码。
• 不生成 controller 层代码；业务入口仅限 service/handler 及其测试。
• 禁止为验证「合作方 → 通联」出站链路而 Mock 签名 HTTP 客户端；须生成或使用真实 HTTP 集成测试（见「Java / Spring：Outbound 集成测试」）。

Field Experience（与底座联调时已验证）

以下问题多由 签名底座与网关规范不一致 或 运行环境假设过新 引起，生成业务层时须在交付物与说明中一并规避：

| 问题 | 处理 | |------|------| | 网关验签报 Bad signature length | 底座侧 X-AGCP-Auth 须为小写 hex，非 Base64；分隔符为 : | | X-AGCP-Date / Send / Crdt 与文档不一致 | 严格按 signing-and-verify-spec.md：yyyyMMddHHmmss、send=date+"000"、Crdt=keyid:yyyyMMdd:gcpservice | | 回调验签失败 | Handler 侧对 X-AGCP-Auth 做 hex 解码；支持整段 GCP1-RSA-SHA512:hex 截取 | | 私钥无 PEM 头 | 密钥加载须支持 无头 PKCS#8 Base64（见 implementation-pitfalls.md） | | Java 8 编译失败 | 工具类/测试避免 Java 11+ API | | 已改配置仍读旧值 | 提示 mvn clean 或核对 IDE 使用的 classpath | | 客户误以为测试已打网关 | 默认交付真实 HTTP 集成测试；文档写明须配置本地密钥与 application-local.properties（或等价），且无配置时 @EnabledIf 跳过类 | | Java 编译报 非法字符 \ufeff | 源文件以 UTF-8 无 BOM 保存；勿在 package 行前插入 BOM |

底座侧完整排障表：.cursor/skills/gcp-api-quick-integration/implementation-pitfalls.md。

Related Files

• embedded-organ-va-chapter2-6-spec.md
• dependency-contract.md
• output-checklist.md
• examples.md
• 签名底座规范与排障（跨 Skill）：../gcp-api-quick-integration/signing-and-verify-spec.md、../gcp-api-quick-integration/implementation-pitfalls.md