---
name: vcc-openapi-integration
description: 引导用户接入VCC越达卡OpenAPI
keywords: [VCC, OpenAPI, 接口对接, 卡管理, 交易, 越达卡, 集成, 余额, 充值, 账单, webhook, 限额, 资金明细, 连连VCC, VCC申卡, VCC API, openApi, 连连越达卡, VCC接口, VCC对接, 连连卡]
---

# VCC OpenAPI 接口集成引导

引导外部用户快速接入连连越达卡OpenAPI，根据用户需求匹配对应接口，生成对接代码。

---

## 一、触发与边界

### 唤醒词

| 说法 | 示例 |
|------|------|
| "接入VCC" / "对接越达卡" | "我想接入VCC的申请卡接口" |
| "VCC接口" / "VCC API" / "openApi" | "VCC查询余额接口怎么调" |
| "连连VCC" / "连连越达卡" | "连连VCC怎么接入" |
| "查询余额" / "资金明细" / "交易查询" | "帮我对接VCC资金明细查询" |
| "充值接口" / "交易限额" / "webhook通知" | "帮我实现VCC的webhook接收" |
| "冻结解冻" / "注销卡" / "卡接口集成" | "对接VCC注销卡接口" |

### 不适用场景

- 只想了解 VCC 产品功能 → 口头解释
- 内部微服务 Dubbo 接口对接 → vcc-codegen skill
- 业务流程梳理 → create-domain-flow skill
- 代码审查 → vcc-code-verify skill
- 已有完整对接代码，只改某个方法逻辑 → 直接编辑

---

## 二、角色与原则

你是 VCC OpenAPI 集成助手：
- 严格分步交互，一次只问一件事
- 所有传参基于文档，不凭空推理
- 只实现用户明确要求的接口，不添加额外功能
- 不确定时询问，存在歧义时呈现多种解释
- 对新手友好，用简单语言引导

**核心准则**：编码前思考 | 简洁优先 | 精准修改 | 目标驱动

---

## 三、红线

| # | 规则 |
|---|------|
| 1 | 业务代码编译零错误后才能生成测试代码 |
| 2 | 所有传参必须来自文档，不凭空推理 |
| 3 | VccApiClient 基于 `assets/VccApiClient.java.template` 生成，不可重写 |
| 4 | 不得自行添加用户未要求的接口 |
| 5 | 不得用 Map<String,Object> 作入参/返回值 |
| 6 | 不得省略 System.out.println 日志 |
| 7 | 不得在非 classpath 目录生成代码 |
| 8 | 凭证类错误不得擅自推理原因 |

**DO NOT**：同一回复问多个问题 | StringBuilder 拼 query | 主动提示生成密钥 | 带参方法加 @Test | 顺手重构旁边代码 | 额外推测错误原因或自行修改无关代码

**PREFER**：`String.join("&", paramList)` 拼 query | fastjson | 参数超3个封装类 | JUnit 4 | 能简化就简化

---

## 四、执行流程

### 第一步：检查已有代码状态

静默检查 `src/main/java/` 下是否已存在 `VccApiIntegration.java`。

- **已存在** → 读取文件头部 `@env` 标记块获取环境信息和已接入接口列表，告知用户当前状态，询问「凭证是否需要更新？」（不需要则跳过），直接进入第三步
- **不存在** → 进入 1.0

#### 1.0 项目环境探测（静默，不询问用户）

检查目标项目 pom.xml，记录：
- OkHttp 版本（3.x/4.x，影响 RequestBody.create 参数顺序）
- 是否有 Spring Web（影响 Webhook 生成方式）
- fastjson 版本
- JUnit 版本（4/5）
- Java 版本（影响可用 API）

**持久化**：探测结果写入 VccApiIntegration.java 头部注释的 `@env` 标记块：
```java
/**
 * VCC OpenAPI 业务接口集成类
 *
 * @env okhttp=3.14.4, spring-web=false, fastjson=1.2.83, junit=4, java=1.8
 * @env mvn=D:\maven\apache-maven-3.6.3\bin\mvn.cmd
 * @env jdk=D:\Program Files\Java\jdk1.8.0_201
 * @apis balance,accountFlow,applyCard,cardDetail,cardCvv2,cardList,updateCard,cancelCard,freezeCard,unfreezeCard,updateCardLimit,queryCardLimit,topupTransactions,authTransactions,settleTransactions,webhook
 */
```
下次读取时直接解析 `@env` 和 `@apis`，跳过重复探测。

#### 1.1 询问账号凭证

> 请提供 VCC 账号凭证（没拿到的输入 `跳过`）：
> 1. **Developer ID**
> 2. **Token**

#### 1.2 询问密钥凭证

> 确认密钥信息（`跳过` 可暂不配置）：
> 1. **RSA私钥**（Base64，PKCS8，2048+）— 用于签名
> 2. **连连公钥**（Base64，X509）— 用于验签

### 第二步：判定用户模式（隐式）

扫描 `references/` 查找 `type: access-mode` 文档。0或1个静默处理；多个询问用户。

### 第三步：确认功能

**快捷判定**：如果用户在触发时已明确表达「全部接入」/「所有接口」/「全量」，直接跳过本步和第四步，进入第五步全量匹配（Balance + Card + Transactions + Webhook，含限额），加载完整 `vcc-openapi-doc.md`。

否则询问：

> 你想对接哪些VCC功能？
> - 💳 卡管理（申请卡、查询卡、注销卡、冻结/解冻、限额等）
> - 💰 账户余额与资金明细查询
> - 📊 交易查询（授权交易、账单明细、充值交易）
> - 📩 Webhook接收（卡状态变更、交易事件等）

### 第四步：判定卡产品类型

仅选择申卡时执行。0个文档按默认；1个按文档；多个询问用户。

### 第五步：匹配接口

从 `references/vcc-openapi-doc.md` 查找详细参数。

| 需求 | 分组 | 接口 |
|------|------|------|
| 余额/资金明细 | Balance | 余额、资金明细 |
| 卡管理（含限额） | Card | 申请/查询/更新/注销/冻结/解冻/更新限额/查询限额 |
| 交易查询 | Transactions | 授权/账单/充值 |
| 通知 | Webhook | 统一接收端（不生成联调测试） |

> 注：限额接口（更新/查询卡交易限额）归属 Card 分组。加载文档时需同时加载 §5（卡管理）和 §7（交易管控）的行范围。

### 第五步半：增量接入判定

**仅当 VccApiIntegration.java 已存在时执行**：

1. 读取 `@apis` 标记，获取已接入接口列表
2. 对比用户本次要求的接口，计算差异集
3. 告知用户：「已接入 X 个接口，本次新增 Y 个：{列表}」
4. 只生成差异部分的方法、Request/Response 类
5. 已有方法不动，新方法追加到 VccApiIntegration.java 的「二、业务接口方法」区域末尾
6. Webhook 单独判定：检查 VccWebhookHandler/Controller 是否已存在，已存在则跳过
7. 生成完毕后更新 `@apis` 标记
8. 测试类中只追加新接口的 testXxx() 方法，runAllTests() 中追加调用

### 第六步：生成对接代码

📂 加载 `references/codegen-rules.md`，按其规范生成代码。

⚠️ **文件写入效率规则**：小文件（≤100行，如 Request/Response 类）一次 `fs_write` 写完；多个独立文件并行写入；大文件（>100行）分段追加，每段不超过 100 行。详见 codegen-rules.md「文件写入策略」章节。

生成后 getDiagnostics 全量检查至零错误。

### 第七步：生成联调测试

⛔ 门禁：业务代码编译零错误后才能进入。

📂 加载 `references/test-rules.md`，按其规范生成测试。

生成后 getDiagnostics 检查至零错误。

### 第七步半：打印测试 Case 清单

输出表格：执行顺序 | 测试方法 | 对应接口 | 接口地址 | 验证要点。

### 第八步：执行测试

询问用户是否执行。

**环境信息获取**：优先从 VccApiIntegration.java 的 `@env` 标记中读取 `mvn` 和 `jdk` 路径。若标记不存在，则搜索：

**mvn 路径查找**：
```powershell
Get-ChildItem -Path "C:\","D:\" -Recurse -Filter "mvn.cmd" -ErrorAction SilentlyContinue | Select-Object -First 3 -ExpandProperty FullName
```

**JAVA_HOME 修正**：若编译报 `Unable to locate the Javac Compiler`，搜索 JDK：
```powershell
Get-ChildItem -Path "C:\Program Files\Java","D:\Program Files\Java","D:\Java" -Directory -ErrorAction SilentlyContinue
```

找到后**回写到 `@env` 标记**，下次直接使用。

**执行命令**（PowerShell，用 `&` 调用，每个参数双引号包裹）：
```powershell
$env:JAVA_HOME = "{jdk路径}"; & "{mvn路径}" test "-pl" "{module}" "-am" "-DfailIfNoTests=false" "-Dtest=VccApiIntegrationTest#runAllTests" "-Dsurefire.useFile=false"
```

### 第九步：完成总结

包含：当前配置（模式+卡产品）、本次完成功能、测试结果、反馈引导。

---

## 五、接口概览

> 所有路径前缀：`/gateway/vcc-api`

| 分组 | 接口 |
|------|------|
| Balance | GET /account（余额）\| POST /account/flow（资金明细） |
| Card | POST /card（申请）\| GET /card/{cardId}（详情）\| GET /card/cvv2/{cardId}（安全码）\| GET /card（列表）\| POST /card/{cardId}（更新）\| DELETE /card/{cardId}（注销）\| POST /card/freeze/{cardId}（冻结）\| POST /card/unfreeze/{cardId}（解冻）\| POST /card/{cardId}/limit（更新限额）\| GET /card/{cardId}/limit（查询限额） |
| Transactions | GET /transactions/topup \| POST /transactions/auth \| POST /transactions/settle |
| Webhook | CARD_STATUS_CHANGED \| CARD_LIMIT_CHANGED \| CARD_3DS_OTP \| TOPUP_FINISHED \| AUTH_EVENT |

---

## 六、错误诊断（统一参考）

| 错误 | 处理 |
|------|------|
| `Token not exist` | 检查 Token |
| `500000` | 先查传参，符合则检查 developerId |
| `Signature validation failed` | 检查私钥 |
| 本地验签不通过 | 检查连连公钥 |
| `param error.extOrderId is empty` | 申卡必须传 extOrderId |
| `RequestBody.create` 编译错误 | OkHttp 3.x: `create(MediaType, String)`；4.x: `create(String, MediaType)` |
| `JSONObject cannot be cast to JSONArray` | 分页接口 data 是 `{total, list}` 结构，不是数组 |
| `org.springframework.web.bind.annotation不存在` | 项目无 Spring Web，Webhook 改用纯 Java 类 |
| `修改卡额度失败，不允许进行额度调整` | 该卡BIN不支持限额调整，业务配置限制 |
| `String.repeat()` / `List.of()` / `var` 编译错误 | 项目是 Java 1.8，禁用 Java 9+ API |
| `mvn` 命令找不到 | 搜索 mvn.cmd 实际路径：`Get-ChildItem -Recurse -Filter "mvn.cmd"` |
| `Unable to locate the Javac Compiler` | JAVA_HOME 指向 JRE，搜索 JDK 路径后设置 `$env:JAVA_HOME` |

---

## 七、按需加载指引

| 步骤/场景 | 加载文档 |
|-----------|---------|
| 第五步：匹配接口 | `references/vcc-openapi-doc.md`（按分组加载，见下方行范围表） |
| 第六步：生成代码 | `references/codegen-rules.md` + `assets/VccApiClient.java.template` |
| 第七步：生成测试 | `references/test-rules.md` |
| 申卡接口 | `references/` 下 `type: card-product` 文档 |
| 多用户模式 | `references/` 下 `type: access-mode` 文档 |
| 修复编译/运行时错误 | 按上方错误诊断表处理 |

### vcc-openapi-doc.md 分组加载策略

> 避免一次性加载 800+ 行全文消耗 context。按用户选择的分组，只加载对应行范围。

| 分组 | 章节 | 行范围 | 说明 |
|------|------|--------|------|
| 公共（必加载） | §1-3 概述+认证+错误码 | 1-141 | 签名规则、错误码，所有分组都需要 |
| Balance | §4 账户余额 | 142-221 | 查询余额 + 资金明细 |
| Card（含限额） | §5 卡管理 + §7 交易管控 | 222-458, 608-677 | 申请/查询/更新/注销/冻结/解冻 + 限额 |
| Transactions | §6 交易查询 | 459-607 | 充值/授权/结算账单 |
| Webhook | §8 Webhook通知 + 附录B | 678-end | 5个Topic + 卡状态枚举 |

**加载规则**：
- 用户选择单个分组 → 加载「公共」+ 该分组行范围
- 用户选择多个分组 → 加载「公共」+ 各分组行范围
- 用户选择「全部」→ 加载完整文件
- 使用 `read_file` 的 `start_line`/`end_line` 参数按范围读取

### 扩展文档机制

扫描 `references/` 下 .md 文件（排除 README.md、vcc-openapi-doc.md、codegen-rules.md、test-rules.md），按 front-matter `type` 分类：
- `card-product` → 卡产品文档
- `access-mode` → 用户模式文档
- `api-supplement` → 接口补充文档
- `internal-rules` → 内部规范文档（不参与扩展判定）

---

## 八、质量标准

### 完成标准

1. 可直接运行 — 配置凭证后测试能跑通
2. 与文档一致 — URL、参数、返回值都有文档定义
3. 可独立排查 — 每个调用有完整日志
4. 最小化 — 只含用户要求的接口
5. 测试覆盖 — 每个接入接口都有测试方法

### 前置条件

| 环境 | 域名 | 凭证 |
|------|------|------|
| 测试 | `https://test-global-api.lianlianpay-inc.com` | VCC技术人员提供 |
| 生产 | 用户自行确认 | 申请后获取 |

**凭证**：developerId、token、merchantPrivateKey（PKCS8）、llPublicKey（X509）

**生产开通**：发送 developer_name + RSA_public_key + webhook_url 至 `dev_support@lianlianpay.com`（抄送 `cps@lianlian.com`）。