FlowStack/backend/docs/API.md

# FlowStack 接口文档

> 与当前后端代码对齐；所有 `/api/*` 需携带登录 Token，敏感字段只写不回显。

| | |
|---|---|
| 文档版本 | v0.4 |
| Base URL | `http://<host>:9527` |
| 鉴权 | `Authorization: Bearer <token>`（`POST /api/auth/login` 获取，7 天有效） |
| 技术栈 | Go gin + SQLite（GORM） |

**典型接入流程**：登录拿 token → 管理流水线/节点/凭证 → 触发运行 → SSE 看日志 → 查发布记录。

## 通用约定

- **鉴权**：除登录、健康检查（`/health`）、入站 Webhook（`/api/hooks/*`）、SSE 日志流外，所有接口需 Bearer Token；用户管理类接口需 admin 角色
- **错误格式**：`{"error": "中文错误信息"}`，HTTP 状态码语义化（400 参数错 / 401 未登录 / 403 权限 / 404 不存在 / 409 冲突）
- **敏感字段只写不回显**：凭证内容、API Key、Token、Bind 密码等提交后永不返回，响应以 `xxxSet` 布尔表示已配置；**编辑时留空 = 保持原值**
- **时间**：ISO 8601 带时区

## 认证

| 接口 | 方法 | 说明 |
|---|---|---|
| `/api/auth/login` | POST | 登录（本地 argon2id 或 LDAP 直连验证），返回签名 token |

```bash
curl -X POST http://localhost:9527/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"xxx"}'
# → {"success":true,"token":"...","username":"admin","role":"admin","expiresAt":"..."}
```

LDAP 用户名在目录验证通过后自动建号/同步（JIT）；错误统一返回 401「用户名或密码错误」。

## 流水线

| 接口 | 方法 | 说明 |
|---|---|---|
| `/api/pipelines` | GET | 列表（每条附 `lastRun` 与 `accessLevel`；普通用户仅返回被授权的） |
| `/api/pipelines` | POST | 创建（**管理员**） |
| `/api/pipelines/:id` | GET | 详情（pipeline + nodes + edges + lastRun + `accessLevel`；需「查看」） |
| `/api/pipelines/:id` | PUT | 更新（需「管理」） |
| `/api/pipelines/:id` | DELETE | 删除（**管理员**；级联删节点连线） |
| `/api/pipelines/:id/nodes` | PUT | 全量保存画布节点（需「管理」） |
| `/api/pipelines/:id/edges` | PUT | 全量保存画布连线（需「管理」） |
| `/api/pipelines/:id/runs` | POST | 触发运行（需「发布」；body 可带 branch/env/triggerType） |

`type=jenkins` 且已关联服务器的流水线触发时走真实 Jenkins 引擎（队列→构建→增量日志回传）。

## 流水线权限

三级等级：`viewer` 查看 / `operator` 发布 / `owner` 管理；管理员全局豁免。未被授权的普通用户默认不可见任何流水线。

| 接口 | 方法 | 说明 |
|---|---|---|
| `/api/me` | GET | 当前会话（username/role/isAdmin） |
| `/api/pipeline-roles` | GET | 权限组列表（**管理员**；附 matchedPipelines 匹配数） |
| `/api/pipeline-roles` | POST | 创建（name/scopeMode=manual|pattern/pattern/pipelineIds/level/members；pattern 仅支持 `*` 通配符） |
| `/api/pipeline-roles/:id` | PUT/DELETE | 更新 / 删除（**管理员**） |
| `/api/pipelines/:id/members` | GET | 单流水线直接成员 + 命中的权限组（需「查看」） |
| `/api/pipelines/:id/members` | POST | 添加/更新成员等级（需「管理」；body: username/level） |
| `/api/pipelines/:id/members/:mid` | DELETE | 移除直接授权（需「管理」） |

资源（主机/集群/凭证/构建节点/工具/Webhook）、Jenkins 服务器、GitOps、插件与系统设置接口均要求**管理员**。

## 运行记录

| 接口 | 方法 | 说明 |
|---|---|---|
| `/api/runs` | GET | 运行列表（`?pipelineId=&status=`；普通用户仅返回被授权流水线的，每条附 `canRetry`） |
| `/api/runs/:runId` | GET | 详情（run + stages + logs；失败含 AI `analysis`；需「查看」） |
| `/api/runs/:runId/logs/stream` | GET | SSE 实时日志（需登录：`?token=` 传会话 token 且需「查看」；事件 connected/log） |
| `/api/runs/:runId/retry` | POST | 以同分支重新触发（需「发布」） |

## AI 与批量发布

| 接口 | 方法 | 说明 |
|---|---|---|
| `/api/ai/chat` | POST | AI 对话（JSON 返回；未配 LLM 降级规则匹配） |
| `/api/ai/chat/stream` | POST | 同上，SSE 流式（delta/done 事件） |
| `/api/ai/release` | POST | 按服务名批量触发（未导入的 Jenkins Job 自动建流水线） |
| `/api/batch/parse` | POST | 粘贴清单解析预览（纯规则） |

```bash
curl -X POST http://localhost:9527/api/ai/release \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"jobs":["aiops-backend","aiops-web"],"branch":"test"}'
# → {"triggered":[{"job":"aiops-backend","runId":"pr-..."}],"failed":[]}
```

## 资源管理

| 接口 | 方法 | 说明 |
|---|---|---|
| `/api/hosts` / `/api/clusters` | CRUD | 主机 / Kubernetes 集群 |
| `/api/hosts/:id/test` / `/api/clusters/:id/test` | POST | 真实 TCP 拨号连通测试 |
| `/api/credentials` | CRUD | 凭证（内容 AES 加密只写；响应含 `contentSet`） |
| `/api/build-nodes` | CRUD | 构建节点 |
| `/api/build-nodes/:id/test` | POST | 连通测试（TCP 拨号 22 端口） |
| `/api/build-nodes/:id/disk-test` | POST | dd 磁盘性能实测（256MB，本机 exec 或 SSH 远程；返回读写 MB/s） |
| `/api/tools` | GET/PUT | 工具清单与安装策略 |
| `/api/tools/:id/check` | POST | 真实执行版本探测命令 |
| `/api/webhooks` | CRUD + `/:id/test` | 出站 Webhook（HMAC-SHA256 签名发送，配置入口：系统设置→消息通知） |
| `/api/hooks/pipeline/:id?token=` | POST | 入站触发流水线（免鉴权，token 校验） |

## Jenkins

| 接口 | 方法 | 说明 |
|---|---|---|
| `/api/jenkins-servers` | CRUD | 服务器管理（Token 加密只写） |
| `/api/jenkins-servers/:id/test` | POST | 真实连通测试（crumb + BasicAuth） |
| `/api/jenkins-servers/:id/jobs` | GET | 拉取 Job 树（folder 压平） |
| `/api/jenkins-servers/:id/import` | POST | 导入 Job 为 jenkins 类型流水线 |

## GitOps

| 接口 | 方法 | 说明 |
|---|---|---|
| `/api/gitops/apps` | GET | 应用列表（含同步/健康状态） |
| `/api/gitops/argo/apps` | GET | Argo 风格状态视图 |
| `/api/gitops/argo/sync` | POST | 触发同步（状态真实推进） |
| `/api/gitops/argo/:app/tree` / `/diff` | GET | 资源树 / 差异对比 |

## 用户与 LDAP

| 接口 | 方法 | 说明 |
|---|---|---|
| `/api/users` | GET/POST | 用户列表 / 创建本地用户（密码留空随机生成并一次性回显） |
| `/api/users/:id` | PUT/DELETE | 角色/信息更新 / 删除（不可删最后一个 admin） |
| `/api/users/:id/reset-password` | POST | 重置密码（LDAP 用户拒绝） |
| `/api/users/ldap-import` | POST | 批量导入（已 LDAP 跳过 / 本地同名转换 / 新建） |
| `/api/ldap/users` | POST | LDAP 用户预览（未启用返回 400） |

## 设置

| 接口 | 方法 | 说明 |
|---|---|---|
| `/api/settings` | GET/PUT | 单行设置：主题/通知/工具模式/AI/飞书/LDAP（敏感字段只写） |
| `/api/settings/test-llm` | POST | AI 连通测试（支持草稿值，apiKey 留空回退已存） |
| `/api/settings/test-lark` | POST | 飞书测试卡片 |
| `/api/settings/ldap/test` | POST | LDAP 测试（支持草稿 + 可选测试账号） |
| `/api/summary` | GET | 概览统计（侧边栏徽标） |
| `/api/docs` | GET | 本文档与使用指南 Markdown |

## 状态码速查

| 状态 | 含义 |
|---|---|
| 400 | 参数错误 / 未启用对应功能 |
| 401 | 未登录 / token 过期 / 用户名或密码错误 |
| 403 | 需要 admin 角色 / 无该流水线的对应权限等级 |
| 404 | 资源不存在 |
| 409 | 名称重复等冲突 |

运行状态枚举：`pending → running → success | failed | cancelled`（Jenkins 队列阶段为 `queued`）。