# 运维平台 API

这是运维平台后端服务，基于 NestJS、TypeScript 和 Prisma 构建。后端负责账号鉴权、成员管理、项目权限、发布记录、Jenkins/Gitea 集成、通知、审计、流程定义和 Agent 运维能力。

## 范围

- 只维护运维平台 API，不包含前端页面代码。
- 外部系统密钥只保存在服务端，接口不会返回完整密钥。
- 数据访问默认使用 Prisma；如必须使用原生 SQL，只能放在 Repository 中并说明原因。
- 本地未配置 MySQL 时，项目、发布记录、账号和配置能力会使用内存降级数据，便于开发调试。

## 本地启动

```bash
pnpm install
pnpm prisma:generate
pnpm start:dev
```

默认监听地址为 `http://localhost:4300`。未配置 `DATABASE_URL` 或 `USE_DATABASE_READS=false` 时，不会强制连接 MySQL。

## 常用命令

```bash
pnpm prisma:generate
pnpm lint
pnpm test
pnpm build
pnpm check
pnpm prisma:migrate:dev --name init
pnpm prisma:seed
```

## 数据库迁移与 Jenkins 部署

- 迁移历史从 `prisma/migrations/20260611000000_baseline_current_schema` 开始，空库可以直接执行 `pnpm prisma migrate deploy` 初始化当前 schema。
- 生产库在启用 Prisma 迁移历史前已经存在表结构；`deploy/deploy-devops-platform-api-from-jenkins.sh` 会检测完整表结构并自动将基线迁移标记为已应用，再执行 `pnpm prisma migrate deploy`。
- Jenkins 服务器使用 `/usr/local/bin/deploy-devops-platform-api-from-jenkins`，该脚本应与仓库 `deploy/deploy-devops-platform-api-from-jenkins.sh` 保持一致。
- 如需紧急跳过迁移，可在服务器环境中设置 `PRISMA_MIGRATE_DEPLOY_ENABLED=false`，但不能在存在 schema 变更的版本长期使用该开关。
- 新增表或字段时必须提交新的 `prisma/migrations/<timestamp>_<name>/migration.sql`，不要再用手工 SQL 直接改生产库。

## 内置账号

- 超级管理员账号：`zhanxi`
- 超级管理员初始密码：生产环境通过 `SUPER_ADMIN_INITIAL_PASSWORD` 注入；本地未配置时使用开发兜底口令。
- 普通成员初始密码：`111111`

超级管理员初始化配置集中在 `src/auth/auth.constants.ts` 和服务器环境变量。生产环境缺少 `SUPER_ADMIN_INITIAL_PASSWORD` 时 API 会拒绝初始化超级管理员，避免默认口令上线；如果超级管理员已修改密码，后续初始化不会覆盖密码。

## 关键接口

- `POST /auth/login`：登录，返回 token 和当前账号信息。
- `GET /auth/me`：查询当前登录账号。
- `POST /auth/change-password`：修改当前登录账号密码。
- `POST /auth/forgot-password`：普通成员忘记密码，通知超级管理员处理。
- `GET /members`：超级管理员查询成员列表和项目权限。
- `POST /members`：超级管理员创建普通成员，初始密码固定为 `111111`。
- `PATCH /members/:id/permissions`：超级管理员更新普通成员项目权限。
- `POST /members/:id/reset-password`：超级管理员将普通成员密码重置为 `111111`。
- `PATCH /members/:id/status`：超级管理员启用或禁用普通成员。
- `GET /messages`：超级管理员查询消息通知。
- `POST /messages/:id/handled`：超级管理员将消息标记为已处理。
- `GET /agent/config`：超级管理员查询 Agent 配置，密钥只返回脱敏值。
- `PUT /agent/config`：超级管理员保存 Agent 的 `key`、`baseURL` 和 `model`。
- `POST /agent/config/test`：超级管理员测试已保存的 Agent 配置。
- `GET /projects`：查询当前账号有权限访问的项目。
- `GET /projects/:key`：查询项目详情，需要只读或构建权限。
- `GET /projects/:key/refs`：查询项目分支和标签，需要只读或构建权限。
- `GET /deploy-runs`：查询当前账号有权限项目的发布记录。
- `POST /deploy-runs`：创建发布单并触发构建，需要构建权限。
- `POST /deploy-runs/:id/cancel`：取消发布单，需要构建权限。
- `POST /deploy-runs/:id/retry`：重试发布单，需要构建权限。
- `POST /deploy-runs/:id/sync-jenkins`：同步单个发布单 Jenkins 状态，需要构建权限。
- `POST /deploy-runs/sync-jenkins`：同步全部 Jenkins 状态，仅超级管理员可用。
- `GET /audit-logs`：超级管理员查询脱敏审计日志。
- `GET /settings/integration-config`：超级管理员查询集成配置状态。
- `GET /health`：运行健康检查。
- `GET /docs`：Swagger 接口文档。

## 权限规则

- 未登录访问受保护接口会返回 `登录已失效，请重新登录`。
- 普通成员首次登录或被重置密码后，必须先调用 `POST /auth/change-password` 修改密码。
- 超级管理员拥有全部项目的全部权限，不需要单独授权。
- 普通成员默认没有任何项目权限。
- 只读权限可以查看项目和发布记录，不能触发构建。
- 构建权限包含只读能力，可以对授权项目触发构建、取消、重试和同步单个 Jenkins 状态。
- 成员管理、消息通知、系统设置、审计日志和 Agent 配置仅超级管理员可访问。

## 密钥规则

- Agent `key` 保存到服务端 `secrets` 表或本地内存配置，接口只返回脱敏值。
- 生产环境保存 Agent 密钥必须配置 `SECRET_ENCRYPTION_KEY`。
- 审计、错误、日志和返回体不能包含完整 token、webhook、cookie、私钥或 Agent key。
- Agent 调用只使用后端保存的系统级配置，不信任前端传入的模型配置。

## 环境变量

- `AUTH_TOKEN_SECRET`：登录 token 签名密钥。
- `AUTH_TOKEN_TTL_SECONDS`：登录 token 有效期，默认 43200 秒。
- `SUPER_ADMIN_INITIAL_PASSWORD`：生产环境初始化超级管理员时的初始密码。
- `SECRET_ENCRYPTION_KEY`：服务端密钥加密密钥，生产环境保存 Agent 密钥时必须配置。
- `DATABASE_URL`：MySQL 连接地址。
- `USE_DATABASE_READS`：是否启用 Prisma 数据读写。
- `PRISMA_CONNECT_ON_BOOT`：启动时是否主动连接数据库。
- `REDIS_URL`：Redis 连接地址，`/health` 会执行真实 PING，Jenkins 自动同步和通知 outbox 重试会优先使用 BullMQ 调度。
- `JENKINS_BASE_URL`、`JENKINS_USERNAME`、`JENKINS_API_TOKEN`：Jenkins 集成配置。
- `GITEA_BASE_URL`、`GITEA_TOKEN`、`GITEA_WEBHOOK_SECRET`、`GITEA_WEBHOOK_RELAY_BASE_URL`：Gitea 集成与 Jenkins relay 诊断配置。
- `NOTIFICATION_PROVIDER`、`WECOM_WEBHOOK_URL`、`FEISHU_WEBHOOK_URL`、`NOTIFICATION_WEBHOOK_URL`：通知集成配置。
- `NOTIFICATION_OUTBOX_RETRY_ENABLED`、`NOTIFICATION_OUTBOX_RETRY_INTERVAL_MS`、`NOTIFICATION_OUTBOX_RETRY_DELAY_MS`、`NOTIFICATION_OUTBOX_MAX_ATTEMPTS`、`NOTIFICATION_OUTBOX_BATCH_SIZE`：通知 outbox 自动重试配置；配置 `REDIS_URL` 时使用 BullMQ 调度，否则降级为进程内定时器。
- `LLM_BASE_URL`、`LLM_API_KEY`、`LLM_MODEL`：Agent 配置的环境变量后备值。

## Agent 边界

Agent 不是通用聊天入口，只支持运维工作流：

- 发布风险摘要
- Jenkins 失败诊断
- 运维手册问答
- 发布说明草稿
- 事故复盘草稿

普通成员使用 Agent 时必须绑定自己有权限访问的项目。Agent 调用只读，不会触发发布、修改 Jenkins、修改 Gitea 或暴露密钥。