# ipaas-ai-automation

把 iPaaS 集成平台（RestCloud 兼容系列）上的**人工操作**，变成 **自然语言 → 脚本/工具调用 → 干跑确认 → 落库 → 审计留痕** 的可复用工程链路。

> 面向**开发人员**：批量注册 API、导出/对比契约、生成与校验流程图 JSON、ETL 任务运维、接口回归、授权批处理、巡检日报。
> 三层交付：**CLI（确定性执行）** · **MCP Server（给 IDE/Agent 用）** · **Skill（领域 SOP）**。

[![CI](https://github.com/providcc/ipaas-ai-automation/actions/workflows/ci.yml/badge.svg)](https://github.com/providcc/ipaas-ai-automation/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## 目录

- [核心特性](#核心特性)
- [5 分钟快速开始](#5-分钟快速开始)（可复制执行）
- [完整 Setup（AI 逐条执行）](#完整-setupai-逐条执行)
- [命令速查](#命令速查)
- [MCP 接入](#mcp-接入)
- [流程 JSON 生成契约](#流程-json-生成契约)
- [组件上下文](#组件上下文)
- [权限模型](#权限模型)
- [多部署适配（泛化）](#多部署适配泛化)
- [安全默认值](#安全默认值)
- [目录结构](#目录结构)
- [故障排查](#故障排查)
- [欠账清单](#欠账清单)
- [开发与贡献](#开发与贡献)

---

## 核心特性

| 能力 | 说明 |
|---|---|
| **API 优先** | 平台界面只是 REST 客户端，本工具直接走接口（目录可达 1900+ 端点），不模拟点击 |
| **写操作默认干跑** | 所有写命令默认只打印请求体，`--apply` 才落库；`prod` 需 `RC_ALLOW_PROD_WRITE=1` + `--confirm <工单号>` |
| **流程图 JSON 生成** | 自然语言 → `processModel`（nodeDataArray/linkDataArray）+ 节点属性，附 12 条静态校验规则 |
| **组件上下文注入** | 60 个流程节点（真实面板重建）+ 184 个 ETL 节点 + 1035 个参数字段，Agent 不再"凭空造节点" |
| **契约 diff** | 服务基线导出与对比，识别新增/删除/变更与破坏性变更（删除路由、方法变更） |
| **授权批处理** | 按期望清单生成 grant/revoke/skip 计划，幂等落库，撤销可逆 |
| **可审计** | 每次调用写 jsonl 审计（who/when/traceId/耗时），凭据字段自动脱敏 |
| **零构建依赖** | TypeScript 直接用 Node 内置 type-stripping 运行；仅 MCP/类型检查需要 npm 依赖 |

---

## 5 分钟快速开始

> 复制粘贴即可执行。假设你已有平台地址与账号。

```bash
# 1) 克隆并安装
git clone https://github.com/providcc/ipaas-ai-automation.git
cd ipaas-ai-automation
npm install

# 2) 配置平台地址与账号
cp .env.example .env
$EDITOR .env            # 至少填 RC_BASE_URL / RC_USER / RC_PASS

# 3) 验证连通性（会打印平台返回的用户信息）
set -a && . ./.env && set +a
npm run cli -- auth status

# 4) 看看平台有哪些接口（内置核心样例目录）
npm run cli -- catalog search esb/process

# 5) 干跑一次写操作（不落库，只打印将要发送的请求）
npm run cli -- api import --app <appId> --file ./my-api.yaml
```

---

## 完整 Setup（AI 逐条执行）

> 下列步骤可被 AI 编程代理逐条执行；每步都给出**命令**与**预期结果**。

### 前置条件

| 依赖 | 版本 | 校验命令 |
|---|---|---|
| Node.js | ≥ 20（推荐 22） | `node -v` |
| npm | ≥ 10 | `npm -v` |
| 平台账号 | 有 API/流程查看权限 | — |
| （可选）平台前端源码 | 用于生成完整接口目录 | — |

### Step 1 — 获取代码并安装依赖

```bash
git clone https://github.com/providcc/ipaas-ai-automation.git
cd ipaas-ai-automation
npm install
```

**预期**：`added N packages`；`node_modules/` 存在。

### Step 2 — 配置目标平台

两种方式，二选一。

**方式 A（单目标，最简）** — 编辑 `.env`：

```bash
cp .env.example .env
# 编辑 .env：
#   RC_BASE_URL=https://<你的平台地址>/<应用路径前缀>
#   RC_USER=<账号>
#   RC_PASS=<密码>
```

**方式 B（多目标，用于多系统部署）** — 部分部署由多套系统组成（网关 / 编排 / 低代码 / 数据源），各自独立地址与账号；**只用一套系统时用方式 A 即可**：

```bash
cp rc.targets.example.json rc.targets.json
# 编辑 rc.targets.json，填写各 target 的 baseUrl；把 default 标在常用目标上
```

也可用环境变量覆盖：`export RC_TARGETS='[{"name":"t1","baseUrl":"https://...","role":"编排","default":true}]'`

> 凭据**只走环境变量或 `.env`**，不要写进代码或提交到仓库（`.gitignore` 已排除 `.env`、`rc.targets.json`）。

### Step 3 — 登录并验证

```bash
set -a && . ./.env && set +a
npm run cli -- auth login --target <targetName>   # 省略 --target 则用默认目标
npm run cli -- auth status
```

**预期**：登录输出 `✔ 登录成功：<用户名>（有效期 <秒>）`；`auth status` 返回 200 且含 `userId`。

> 登录密码会按平台前端同样的 **RSA(PKCS1 v1.5)** 加密后提交（公钥取自 `packages/core/src/auth.ts`，可用 `RC_PUBLIC_KEY` 覆盖）。
> 登录成功后会话自动落盘到 `~/.rc/session-<target>.json`（权限 0600），后续命令自动复用；过期时自动重登录一次。

### Step 4 — 生成你自己的接口目录（可选但推荐）

内置目录只是**核心样例**。完整目录有两种生成方式：

```bash
# 方式 A：有平台前端源码 → 解析全部 URI 常量
npm run catalog:extract -- /path/to/platform-frontend-source

# 方式 B：只有运行中的平台 → 合并平台代码内出现的路径
npm run catalog:merge -- /path/to/platform-frontend-source

# 生成组件目录（需要平台可访问；会登录并读取节点面板）
npm run catalog:components
npm run catalog:etl
```

验证：`npm run cli -- catalog search openapi` 能列出目标平台的接口。

### Step 5 — 跑通第一个真实用例

```bash
# 5.1 列出应用与 API
npm run cli -- api list --app <appId> --enrich 5

# 5.2 导出契约基线
npm run cli -- api export --app <appId> -o baseline.json

# 5.3 改动后对比（返回非 0 表示有删除/破坏性变更）
npm run cli -- api diff --from baseline.json --to new.json --breaking

# 5.4 先预览（只解析，不落库）
npm run cli -- api analyze --app <appId> --file spec.yaml

# 5.5 流程图：规格 → JSON → 校验 → 干跑 → 落库
cat > spec.json <<'JSON'
{
  "nodes": [
    { "nodeType": "start", "text": "开始" },
    { "nodeType": "apiNode", "text": "调用上游" },
    { "nodeType": "dataMapNode", "text": "字段映射" },
    { "nodeType": "returnDataNode", "text": "返回结果" },
    { "nodeType": "end", "text": "结束" }
  ],
  "edges": [
    { "from": "E00001", "to": "T00001" },
    { "from": "T00001", "to": "T00002" },
    { "from": "T00002", "to": "T00003" },
    { "from": "T00003", "to": "E00002" }
  ]
}
JSON
npm run cli -- flow build --file spec.json --out model.json
npm run cli -- flow validate --file model.json
npm run cli -- flow save --file model.json --app <appId> --process-id <pid>          # 干跑
npm run cli -- flow save --file model.json --app <appId> --process-id <pid> --apply  # 落库
```

**预期**：`flow build` 打印 `已生成 model.json：节点 5，连线 4`；`flow validate` 打印 `✔ 校验通过`。

### Step 6 — 接给 AI 编程工具（可选）

见 [MCP 接入](#mcp-接入)。Claude Code / Cursor / IDE 插件配置后即可用自然语言驱动平台操作。

### Step 7 — 跑测试确认环境正常

```bash
npm test          # 单元测试
npm run typecheck # 类型检查
npm run templates # 流程模板自检
```

真实平台集成测试（需要账号与可写测试应用）：

```bash
export RC_USER=... RC_PASS=... RC_BASE_URL=... RC_TEST_APP=test
npm run test:authz    # 授权回路（7 轮：授权→校验→幂等→撤销→复原）
npm run test:import   # OpenAPI 导入回路（分析→落库→详情→删除→清理）
npm run test:flow     # 流程落库回路（创建→属性→图→checkerror→回读→幂等→清理→删除）
npm run test:contract # 上述三组串跑
npm run cleanup:test  # 清理测试期间创建的临时流程
```

**预期**：全部通过，0 失败。

---

## 命令速查

```
认证
  rc auth login [--target t] [--token <t>] [--user u --pass p]   登录并存会话
  rc auth status | refresh                                         会话状态 / 刷新令牌

目录
  rc catalog search <keyword> [--module m] [--json]               检索接口目录
  rc catalog sync --source <dir>                                  重新生成目录

资产
  rc api list --app <appId> [--enrich N]                          API 列表（列表接口只给 id/status）
  rc api get <id>                                                 API 详情
  rc api analyze --app <appId> --file spec.yaml                   只解析不落库（预览待导入列表）
  rc api import --app <appId> --file spec.yaml [--apply]          批量注册（OpenAPI 3，两阶段）
  rc api export --app <appId> -o baseline.json                    导出契约基线
  rc api diff --from a.json --to b.json [--breaking]              契约 diff（--breaking 列破坏性变更）
  rc api impact --id <apiId> [--kind esb|etl]                     反查引用该 API 的流程

流程（生命周期 + JSON 生成）
  rc flow create --application <业务应用 id> --name <流程名> [--config-id <编码>]
  rc flow list [--keyword k] | rc flow get <processId> | rc flow versions <processId>
  rc flow clone <processId> [--name 新名] | rc flow delete <processId> | rc flow publish <processId>
  rc flow build --file spec.json [--kind esb|etl] [--out model.json]
  rc flow validate --file model.json [--allow-mock] [--props props.json]
  rc flow check --file model.json --process-id <pid>          调平台 checkerror
  rc flow props get --process-id <pid> --node-id <nodeKey>
  rc flow props save --process-id <pid> --file props.json     幂等 upsert（自动带 id）
  rc flow save --file model.json --process-id <pid> [--props props.json] [--kind etl] [--apply]
      # 完整闭环：属性 upsert → 图保存 → 清理图外旧属性 → 平台 checkerror → 回读校验

ETL / 运营 / 监控
  rc etl list | get <id> | run <pid> [--mode test|full] [--limit 100] | compensate <pid>
  rc ops summary
  rc monitor summary [--hours 24] | monitor logs <serviceId>

授权
  rc authz perms                                                   权限项列表
  rc authz service <serviceId>                                     某服务已有权限
  rc authz grant --service <id> --permission <pid> [--app <app>]  授权（默认干跑）
  rc authz revoke --service <id> --permission <pid>               撤销
  rc authz plan --service <id> --file desired.json                生成 grant/revoke/skip 计划
  rc authz sync --file plan.json [--apply]                        执行计划

工具
  rc snapshot <api|esb|etl> <id>      写前快照
  rc restore <snapshot.json> [--apply] 回滚
  rc upload <path> --file <local>     multipart 上传（WSDL/Excel/证书）
  rc call <path> [-X GET] [-d @file]  调用任意接口（逃生通道）
```

通用参数：`--target <name>` `--profile dev|uat|prod` `--json` `--apply` `--confirm <ticket>`。

---

## MCP 接入

提供 20 个工具（R 只读 / W 受限写 / D 危险三级分级，写工具需 `confirm=true`）。

```json
{
  "mcpServers": {
    "ipaas": {
      "command": "node",
      "args": ["/absolute/path/ipaas-ai-automation/packages/mcp/src/server.ts"],
      "env": {
        "RC_BASE_URL": "https://<your-host>/<app-path>",
        "RC_USER": "<account>",
        "RC_PASS": "<password>",
        "RC_PROFILE": "uat"
      }
    }
  }
}
```

> MCP Server 以源码方式运行（Node 内置 type-stripping，无需编译）。
> `npm run build` 只编译 SDK（`packages/core/dist`）供其他项目引用；CLI 与 MCP 建议直接跑源码。

工具清单：`search_catalog` `list_apps` `list_apis` `get_api_detail` `list_etl_process` `monitor_summary` `ops_summary` `diff_openapi` `list_flow_components` `get_component_schema` `validate_flow` `list_etl_components` `list_service_permissions` `build_flow` `import_openapi` `save_flow` `run_etl_test` `grant_permission` `revoke_permission` `delete_api`

配套领域 SOP：[`skills/ipaas-ops/SKILL.md`](skills/ipaas-ops/SKILL.md) —— 让 Agent 知道"先建什么后建什么、哪些不能做"。

---

## 流程 JSON 生成契约

平台把流程持久化为**字符串化的 JSON**（图与属性分表存储）：

```jsonc
POST /rest/esb/process/model/save
{
  "appId": "<app-id>",
  "processId": "<process-id>",
  "processModel": "{\"nodeDataArray\":[...],\"linkDataArray\":[...],\"transform\":1}"
}
```

**节点 ID 规则**（前缀 + 5 位左补零，取最小空缺）：

| 前缀 | 节点 |
|---|---|
| `E` | `start` `end` `timeNode` `msgNode` `textNode` 等起止/事件类 |
| `G` | `gateWay` |
| `S` | `subProcess` / `subProcessNode` |
| `T` | 其余业务节点 |
| `R` | 连线（`routerId`） |

**属性单独保存**：`POST /rest/esb/process/node/save`，业务参数**全部是字符串**（布尔用 `"0"/"1"`，数组用逗号连接，`inParams`/`inHeaders`/`exportParams`/`tableColumns` 为 JSON 字符串）。

**校验规则（12 条，落地前必过）**：起止节点、ID 前缀与唯一、连线端点存在、网关须有默认分支、无环、nodeType 在白名单、属性与图一致、布尔/JSON 字符串格式、生产禁 mock、子流程引用存在、表达式引用已声明。

完整字段表与真实样例：[`docs/flow-json-spec.md`](docs/flow-json-spec.md)。

---

## 组件上下文

| 目录 | 内容 | 生成方式 |
|---|---|---|
| `catalog/components.json` | 流程设计器节点（7 类，60 项）+ 参数字段 | `npm run catalog:components`（读平台节点面板） |
| `catalog/etl-components.json` | ETL 节点（8 类 78 项 + 106 个源码表单，1035 字段） | `npm run catalog:etl` |
| `catalog/endpoints.json` | 接口目录（仓库内为核心样例） | `npm run catalog:extract` / `catalog:merge` |

Agent 生成流程图前应先取组件上下文，避免"造出平台不存在的节点"或"参数名自造"。

---

## OpenAPI 导入契约（两阶段）

平台导入是**先分析、后落库**两个接口：

```jsonc
// ① 分析（预览）：body = OpenAPI 文档原文，Content-Type: application/json
POST /rest/core/v2/openapi/analysis?appId=<appId>
→ 返回待导入条目数组（含 mapUrl / methodType / summary）

// ② 导入（落库）：body = 条目数组的 JSON 字符串
POST /rest/core/v2/openapi/import
   每项需补：categoryId / authType / authTypeStr / approveAuthType / approveAuthTypeStr
```

CLI 的 `api analyze` 与 `api import` 已封装这两步；MCP 工具 `import_openapi` 同理（`confirm=false` 时只做分析并返回清单）。

---

## 权限模型

三层结构（平台实际存储）：

1. **权限项** `permissionId`（如 `core.consumer`、`core.appdesigner`）
2. **权限 ↔ 组织** `orgResCode` / `orgResType`（部门/公司）
3. **权限 ↔ 服务资源** `resourceId`（服务 id）+ `resourceDesc`（接口路径）+ `serviceMethod`

落库报文：

```jsonc
POST /rest/core/permissions/resources/saveServiceMap
{ "serviceIds": "<service-id>", "permissionId": "<permission-id>",
  "permissionName": "<权限名>", "appId": "<app-id>" }

// 撤销
POST /rest/core/permissions/resources/delete
{ "ids": "<资源映射 id，多个用逗号分隔>" }
```

重复授权**幂等**（不会产生重复映射）。

---

## 多部署适配（泛化）

本仓库**不含任何真实地址与凭据**，所有环境信息来自：

| 变量 | 作用 |
|---|---|
| `RC_BASE_URL` | 单目标模式 |
| `RC_TARGETS` / `rc.targets.json` | 多目标模式（网关/编排/低代码…） |
| `RC_PROFILE` | `dev` / `uat` / `prod` |
| `RC_USER` / `RC_PASS` / `RC_TOKEN` | 认证 |
| `RC_ALLOW_PROD_WRITE` | prod 写开关（配合 `--confirm`） |
| `RC_ACTOR` | 审计操作人 |
| `RC_HOME` | 凭据与会话目录（默认 `~/.rc`） |
| `RC_MONGO_URI` / `RC_MONGO_DB` | 可选：只读诊断直连 Mongo |

若你的平台不是 RestCloud 系列：接口契约集中在 `packages/core/src/api.ts`（`ENDPOINTS` 常量）、`etl.ts`、`authz.ts`、`monitor.ts`，改这些常量即可适配；`catalog/` 下的目录用生成脚本重建。

---

## 安全默认值

- 所有写操作**默认干跑**，只打印将要发送的请求体；
- `prod` 客户端**默认只读**（`RC_ALLOW_PROD_WRITE=1` + `--confirm <工单号>` 才放行）；
- 危险操作（删除 API / 撤销授权）要求二次确认并**先生成回滚快照**；
- 凭据只走环境变量；审计日志自动脱敏（`password`/`token`/`secret` 等）；
- 每次调用写审计：`~/.rc/audit/YYYY-MM.jsonl`（含 traceId，便于与平台日志对账）。

---

## 目录结构

```
packages/core/src/   SDK：client / errors / idempotency / audit / catalog / auth / targets
                     upload / snapshot / api / etl / monitor / authz / operations
                     flow-build / flow-validate / flow-props
packages/cli/src/    rc CLI（零依赖参数解析）
packages/mcp/src/    MCP Server（20 工具）
catalog/             接口与组件目录（可再生成）
scripts/             目录生成、平台数据采集、只读探查、授权回路测试
skills/              领域 SOP（给 Agent 加载）
tests/unit/          单元测试
docs/                方案 / 实施计划 / JSON 契约 / 组件上下文 / 部署拓扑
```

---

## 故障排查

| 现象 | 处理 |
|---|---|
| `未配置目标` | `cp rc.targets.example.json rc.targets.json` 填写地址，或 `export RC_BASE_URL=...` |
| `登录失败` | 确认账号可用；密码含特殊字符时用单引号；平台启用二次验证时改用 `--token` |
| `401 token已失效` | 会话过期会自动重登录一次；仍失败则 `rc auth login` |
| `profile=prod 为只读` | 需要真写入时设置 `RC_ALLOW_PROD_WRITE=1` 并加 `--confirm <工单号>` |
| `未知 nodeType` | 先 `npm run catalog:components` 生成目录，或用 `list_flow_components` 查真实节点名 |
| 流程保存后画布空白 | 检查 `nodeDataArray` 是否含 `start`/`end`，连线 `from`/`to` 是否与节点 `key` 一致 |
| 目录检索结果太少 | 生成完整目录：`npm run catalog:extract -- <前端源码目录>` 或 `rc catalog sync --source <目录>` |
| `网络请求失败：…域名无法解析` | 目标地址写错或该系统未部署；用 `rc auth status --target <name>` 逐个探测 |

---

## 流程落库闭环（P0）

平台的流程落库**不是一次调用**，而是两个接口 + 平台侧校验：

```text
① 节点属性：POST /rest/esb/process/node/save   （带既有 id = 更新；不带 id = 插入 → 重复记录）
② 图模型：  POST /rest/esb/process/model/save  （body.processModel 为字符串）
③ 平台校验：POST /rest/esb/process/model/checkerror
```

平台的三条硬规则（已由后端实现与实测确认）：

1. **每个节点与每条路由都必须有属性记录**，否则 `节点(X)没有设置属性!`；
2. **并行网关（gatewayType=2/3）必须配对聚合网关**：聚合网关本身是 `gateWay` 节点、
   属性 `joinNodeId` 指向被聚合的并行网关，且必须是其**直接后继**（`dataMergeNode` 不算）；
3. 图改了但旧属性没删 → `并行网关和聚合网关没有成对!` / `图形已被删除`。

因此 `rc flow save` 的顺序固定为：**属性 upsert → 图保存 → 清理图外旧属性 → 平台校验 → 回读校验**，
`rc flow save --props props.json` 一次完成（`--apply` 才落库）。

---

## 欠账清单

当前剩余欠账、每项的解除条件与可重复的自检命令见 [`docs/debt-register.md`](docs/debt-register.md)。
摘要：⏳ 需平台/后端信息 4 项（断言表达式 BNF、模型长度上限、保存事务边界、属性唯一索引）· 🔒 需有权限环境 3 项（prod 写路径、ETL 写操作、第三套系统）· 其余已清零并有自检脚本兜底。

---

## 开发与贡献

```bash
npm test && npm run typecheck     # 提交前必过
npm run templates                 # 流程模板自检
```

- 新增平台接口：先更新 `packages/core/src/*.ts` 的端点常量，再补 `tests/unit/`，禁止在调用处硬编码 URL；
- 任何写操作都必须默认 dry-run，并在 `--apply` 时才落库；
- 提交前确认没有把地址、账号、业务数据写进仓库（CI 里有敏感信息扫描）。

许可：MIT，见 [LICENSE](LICENSE)。