# 接口文档导入 ESB 系统接口

当用户要求“从接口文档创建系统接口”“接口文档转 Postman 并导入 ESB”时，使用 e10-cli 的原生命令：

```bash
e10-cli interface import "<文档路径>" --out collection.json
e10-cli interface import "<文档路径>" --system-pool-name "<连接器/系统池名称>" --apply --out collection.json
```

支持 `.docx`、`.pdf`、`.md`、`.txt`、`.xlsx`、`.xls`。默认只解析预览；只有用户明确要求创建时才加 `--apply`。PDF 解析依赖当前机器可用的 `pdftotext`（Poppler）。

`.xlsx` 是表格版接口文档（按「接口目录」+ 每接口一个工作表组织）；`.xls` 是旧版二进制格式，客户/厂商的老文档里常见 —— **别把它当不支持、让用户先转格式**。

## 处理规则

1. 一份文档中的全部接口合并为一个 Postman Collection v2.1，统一调用平台的 `createSystemInterfaceByAi`。
2. `--system-pool-name` 优先使用用户明确指定的连接器/系统池名称；未传时从本次文档文件名去扩展名、去尾部 `(1)`/`（1）` 推导。不能复用旧环境名称，也不能臆造名称。
3. Collection 的 `info.name` 与请求体中的 `systemPoolName` 保持一致且不能为空。
4. 每个接口必须有请求定义和至少一个 `response[]` 示例；平台输出参数来自响应示例的 `body`，不能只写到 description。
5. 文档中的密码、token、Authorization、secret、apiKey 等敏感示例值在本地生成 Collection 时脱敏；不要把 Eteamsid 写进文件。
6. 创建成功必须同时满足外层 `code=200` 和 `data.res=true`，并报告 `systemPk`、接口名称和接口 ID；不能只看 HTTP 200。
7. 创建接口是新增语义，不提供更新/去重；格式校验先在本地完成，避免重复调用在线接口留下重复系统。
8. Excel 文档按**不可信输入**对待，解析限额：单文件 ≤ 20 MB、工作表 ≤ 50 个、单表 ≤ 5000 行、单元格总数 ≤ 50 万。超限**直接报错中止**，**不会截断后继续解析** —— 截断会算出一份看不出错的接口清单，比直接失败坏得多。真遇到超限，先跟用户确认是不是拿错了文件（接口文档通常几行到几十行），再谈拆分。

## 文档提取重点

- 按“接口地址”切分接口区块，提取接口名称、请求方式、URL、请求 JSON 和返回 JSON。
- 请求字段取参数表、请求示例和示例代码中的请求体字段并集，避免漏掉只出现在示例代码中的字段。
- 返回字段取“返回结果/返回示例/响应结果”等示例，按原有嵌套结构写入 Postman `response[].body`，不得扁平化或额外编造字段。
- 解析结果有缺失时，在预览输出的 `warnings` 中明确列出；不要静默按猜测补字段。

## 与动作流 HTTP 组件的边界

这里的 `interface import` 是“从文档创建连接器下的系统接口”；动作流里的 `Http` 是“调用当前租户已经存在的连接器 → 连接信息 → 执行接口”。两者可以串联使用，但不能把接口导入命令当成 HTTP 动作节点配置命令。