GCP API Quick Integration

Purpose

作为对接项目的“签名底座 Skill”，生成可运行的 query 查询接口代码，用于验证请求签名与响应验签链路。

本 Skill 只负责通用安全层（签名、验签、请求封装、配置注入），不负责业务接口模型展开。

Project Positioning

• 阶段定位：0 编码对接的第一阶段（安全链路打通）。
• 产物定位：可复用的签名/验签基础模块与 query 验证入口。
• 协同定位：后续可叠加业务模型 Skill gcp-api-organcus_business-model-generator（第六章「合作方客户类接口」规范已内嵌于该 Skill 的 embedded-organ-va-chapter6-spec.md），在当前基础模块上扩展 DTO 与业务服务层，且不重复生成签名模块。
• 与业务模型衔接：一旦生成或扩展 业务请求/响应类型，须遵守 gcp-api-organcus_business-model-generator 中 「请求/响应模型形态」：一类型一文件、JavaBean setter（Lombok 或手写）、禁止单文件嵌套 static DTO 作为唯一形态、Java 源文件 UTF-8 无 BOM。

Config File Contract

每次执行本 Skill 时，优先读取配置文件：

• 默认路径：.cursor/skills/gcp-api-quick-integration/integration-config.json
• 若默认文件不存在，先基于 integration-config.json.example 生成 integration-config.json，再继续执行
• 若默认路径不存在，可让用户提供自定义配置路径
• 配置文件至少包含以下字段：keyid、cusid、merid、privateKey
• privateKey 支持以下之一：
• PEM 字符串（推荐多行 -----BEGIN PRIVATE KEY----- 格式）
• 无 PEM 头的 PKCS#8 Base64 单行（与去掉头尾后的 PEM 体等价，常见于配置中心）
• 私钥文件路径（由具体语言代码在运行时读取）

若配置文件字段缺失，才向用户追问缺失项，不重复询问已在配置中提供的值。

Mandatory Workflow

1. 先确认输入参数（优先读配置，缺一则提问）：
• 目标语言：由客户指定（例如 python / csharp / nodejs / go / php / java）
• 运行环境：test 或 prod
• 接入参数：从配置文件读取 keyid、cusid、merid、privateKey（或密钥文件路径）
• 查询参数：applyid
• 配置文件：默认读取 .cursor/skills/gcp-api-quick-integration/integration-config.json
2. 根据客户指定语言生成对应代码，并复用以下固定签名规则：
• 算法前缀：GCP1-RSA-SHA512
• 摘要算法：请求体 SHA-256（hex 小写）
• 待签名串：algo + "\n" + date + "\n" + path + "\n" + query + "\n" + digestHex
• Header：X-AGCP-Date、X-AGCP-Send、X-AGCP-Auth、X-AGCP-Crdt
• 具体实现必须遵循 signing-and-verify-spec.md 中的规范与伪代码
3. 生成“可运行最小工程”，必须包含：
• 配置文件读取模块（优先读取 integration-config.json，必要时支持环境变量兜底）
• 签名工具
• 验签工具（平台公钥验签）
• HTTP 请求封装
• query 接口调用入口（main 或 controller）
4. 输出后立即做自检：
• 参数名是否为 applyid
• 请求 path 是否为 query 固定路径
• query 是否包含 authcus、merid、reqid
• X-AGCP-Crdt 是否为 keyid:yyyyMMdd:gcpservice
5. 必须生成响应验签代码，并在入口中展示验签结果输出。
6. 在结果中明确标注“当前为签名底座版本”，并给出后续业务模型扩展建议（不在本 Skill 内实现）。

Language Strategy

• 不限制语言种类，只要客户指定语言就生成对应可运行代码。
• 生成结构遵循目标语言社区常见约定（如目录命名、依赖管理、入口文件）。
• 必须包含五类能力：配置读取、签名工具、验签工具、HTTP 封装、query 调用入口。
• 若客户指定语言较少见，先说明将采用“单文件可运行版”或“最小多文件版”再生成。

Endpoint And Payload Mapping

读取并遵循 endpoint-mapping.md。

Signing And Verify Spec

读取并严格执行 signing-and-verify-spec.md。

若生成代码与该文件冲突，以该文件为准。

Field Experience（客户踩坑与生成时必须规避）

对接落地中已确认的高频问题已整理为 implementation-pitfalls.md。生成底座代码时 必须 对照该文档自检，重点包括：

• 签名在头里必须是 hex，不是 Base64；X-AGCP-Auth 格式为 GCP1-RSA-SHA512:（冒号分隔）。
• X-AGCP-Date / X-AGCP-Send / X-AGCP-Crdt 与规范完全一致（见 signing-and-verify-spec.md 第 7 节与 pitfall 表）。
• 验签对 X-AGCP-Auth 载荷做 hex 解码；兼容历史错误时可文档说明“优先 hex、勿长期依赖 Base64”。
• 私钥：除 PEM 外，须支持 无 PEM 头的 PKCS#8 Base64；文档中说明路径与纯串两种配置方式。
• 目标 Java 8 时：禁止生成 Path.of、Files.readString、String.isBlank 等仅高版本 JDK 可用的 API。
• 交付说明中提醒：Maven 较旧时可能与 Spring Boot 3 插件不兼容，需降级 Boot 或升级 Maven；改配置后建议 mvn clean 避免资源未刷新。
• HTTP 调试日志（推荐默认开启）：记录 请求 URL、请求报文（body）、HTTP 状态码、响应报文；请求头脱敏（不打印完整 X-AGCP-Auth、完整 keyid 等）。Java 等多模块场景下，签名客户端所在包宜与客户业务隔离（例如统一放在 …gcp.organva.client 或客户指定的集成根包下），避免与原有业务代码杂糅。
• JSON 请求体：值为 null 的字段应省略（不上送 "key": null）；序列化用 NON_NULL（或等价），且 摘要/签名用字符串必须与实际上送 body 一致（见 implementation-pitfalls.md 第 2.1 节）。

Examples

对话引导与最小产物参考见 examples.md。

Related Files（规范与排障）

• signing-and-verify-spec.md — 签名/验签真源
• implementation-pitfalls.md — 常见问题与必须对齐项（生成前必读）
• endpoint-mapping.md

Output Contract

每次执行本 skill 时，输出按以下顺序组织：

1. 已识别输入（语言、接口、环境）
2. 将创建/修改的文件
3. 生成后的运行命令
4. 可替换参数清单
5. 后续扩展建议（如何衔接业务接口模型 Skill）

Guardrails

• 不把真实私钥硬编码进最终文件，默认改成环境变量或外部文件读取。
• 对接参数必须优先来自配置文件，不得默认写死在代码中。
• 不依赖任何本地 demo 路径或仓库内参考文件。
• 不扩展到其他接口场景，仅允许 query 查询接口。
• 代码风格优先“可读 + 可直接运行”，避免过度抽象。
• 禁止更改签名串字段顺序、换行规则、摘要算法与请求头语义。
• 不在本 Skill 内生成业务域 DTO/VO、业务编排、业务状态机。