feat: 接入真实登录与成员权限

- auth/members/messages: 新增超级管理员登录、成员权限和密码消息流程 - agent-config/agent: 支持服务端保存 Agent 配置并取消未配置 mock 成功结果 - projects/deploy-runs/settings: 按当前用户权限保护真实接口 - prisma: 新增用户、项目权限和平台消息表结构
2026-06-12 00:38:23 +08:00
parent cf1bebf625
commit bc3aa31289
83 changed files with 3844 additions and 378 deletions
@@ -1,95 +1,113 @@
-# DevOps Platform API
+# 运维平台 API

-NestJS + TypeScript backend for the DevOps operations platform. The current local MVP provides the enterprise project skeleton, Prisma data model, configuration validation, integration client boundaries, Gitea webhook handling, Jenkins queue/build synchronization, notification provider boundaries, audit logs, BPMN process definitions, and runnable seed-backed APIs.
+这是运维平台后端服务，基于 NestJS、TypeScript 和 Prisma 构建。后端负责账号鉴权、成员管理、项目权限、发布记录、Jenkins/Gitea 集成、通知、审计、流程定义和 Agent 运维能力。

-## Scope
+## 范围

- Manage projects, deploy runs, BPMN step state, Jenkins/Gitea integration state, notification delivery, audit records, and agent invocations.
- Keep all external credentials server-side.
- Use Prisma as the default data access layer. Native SQL is allowed only inside Repository methods with a documented reason.
+- 只维护运维平台 API，不包含前端页面代码。
+- 外部系统密钥只保存在服务端，接口不会返回完整密钥。
+- 数据访问默认使用 Prisma；如必须使用原生 SQL，只能放在 Repository 中并说明原因。
+- 本地未配置 MySQL 时，项目、发布记录、账号和配置能力会使用内存降级数据，便于开发调试。

-## Local Setup
+## 本地启动

 ```bash
 pnpm install
-cp .env.example .env
 pnpm prisma:generate
 pnpm start:dev
 ```

-The API listens on `http://localhost:4300` by default and runs without a local MySQL database when `USE_DATABASE_READS=false`. In that mode `/projects` and `/deploy-runs` use seed-backed repository data while keeping the same service and controller contracts intended for Prisma-backed reads.
+默认监听地址为 `http://localhost:4300`。未配置 `DATABASE_URL` 或 `USE_DATABASE_READS=false` 时，不会强制连接 MySQL。

-## Useful Commands
+## 常用命令

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

-## API
+## 内置账号

- `GET /health`: dependency configuration and health summary.
- `GET /settings/integration-config`: Jenkins/Gitea/notification/LLM/Database/Redis/Secret Encryption Key configuration status and variable help text. The response only exposes environment variable names and safe descriptions, never secret values.
- `GET /projects`: configured project list.
- `GET /projects/:key`: one project by key.
- `GET /deploy-runs`: latest deploy runs.
- `POST /deploy-runs`: create a deploy run. Missing Jenkins config uses a local dry-run path; configured Jenkins calls `buildWithParameters` and returns `queued/running`.
- `POST /deploy-runs/:id/sync-jenkins`: synchronize Jenkins queue/build/log status and advance success or failure.
- `POST /deploy-runs/sync-jenkins`: synchronize all queued/running runs that have Jenkins queue/build identifiers.
- `POST /deploy-runs/:id/cancel`: cancel a deploy run.
- `POST /deploy-runs/:id/retry`: create a retry deploy run.
- `POST /webhooks/gitea`: accept Gitea push webhooks and trigger test deploy runs.
- `GET /process-definitions/release`: BPMN release process definition.
- `GET /audit-logs`: latest sanitized audit records.
- `GET /agent/invocations` and `POST /agent/invocations`: DevOps-scoped agent invocation records and mock results.
- `GET /docs`: Swagger UI.
+- 超级管理员账号：`zhanxi`
+- 超级管理员初始密码：生产环境通过 `SUPER_ADMIN_INITIAL_PASSWORD` 注入；本地未配置时使用开发兜底口令。
+- 普通成员初始密码：`111111`

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

- Business modules access data through Repository classes, not direct Prisma calls in controllers.
- Prisma owns connection pooling, transactions, migrations, and typed models.
- Deploy run creation, status transition, step transition, and audit writes must use explicit Prisma transactions once DB writes are enabled.
- Idempotency keys are mandatory for webhook callbacks, Jenkins queue/build tracking, and manual deploy retry paths.
- Raw SQL must be parameterized, isolated in a Repository method, covered by tests, and justified in the method comment.
+## 关键接口

-## Secret Rules
+- `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 接口文档。

- Never commit real `.env`, Jenkins tokens, Gitea tokens, notification webhook URLs, LLM keys, private keys, or cookies.
- Persisted secrets belong in the `secrets` table encrypted with a deployment-provided key or in the deployment secret manager.
- Logs, audit records, integration errors, and LLM prompts must pass through redaction before storage or return.
+## 权限规则

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

-The Agent module is not a generic chat entrypoint. It can only support DevOps workflows:
+## 密钥规则

- release risk summaries,
- Jenkins failure diagnosis,
- runbook Q&A against whitelisted sources,
- release notes drafts,
- incident review drafts.
+- Agent `key` 保存到服务端 `secrets` 表或本地内存配置，接口只返回脱敏值。
+- 生产环境保存 Agent 密钥必须配置 `SECRET_ENCRYPTION_KEY`。
+- 审计、错误、日志和返回体不能包含完整 token、webhook、cookie、私钥或 Agent key。
+- Agent 调用只使用后端保存的系统级配置，不信任前端传入的模型配置。

-Agent calls are read-only. They must not trigger deploys, mutate Jenkins/Gitea, or expose raw secrets. When `LLM_BASE_URL`, `LLM_API_KEY`, and `LLM_MODEL` are configured, the backend proxies DevOps-scoped prompts to `/chat/completions`; otherwise it returns local mock results with the same API shape.
+## 环境变量

-## Notification Providers
+- `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`：启动时是否主动连接数据库。
+- `JENKINS_BASE_URL`、`JENKINS_USERNAME`、`JENKINS_API_TOKEN`：Jenkins 集成配置。
+- `GITEA_BASE_URL`、`GITEA_TOKEN`、`GITEA_WEBHOOK_SECRET`：Gitea 集成配置。
+- `NOTIFICATION_PROVIDER`、`WECOM_WEBHOOK_URL`、`FEISHU_WEBHOOK_URL`、`NOTIFICATION_WEBHOOK_URL`：通知集成配置。
+- `LLM_BASE_URL`、`LLM_API_KEY`、`LLM_MODEL`：Agent 配置的环境变量后备值。

-`DeployNotificationService` supports the first provider boundary for:
+## Agent 边界

- `NOTIFICATION_PROVIDER=wecom` with `WECOM_WEBHOOK_URL`
- `NOTIFICATION_PROVIDER=feishu` with `FEISHU_WEBHOOK_URL`
- `NOTIFICATION_PROVIDER=generic` with `NOTIFICATION_WEBHOOK_URL`
+Agent 不是通用聊天入口，只支持运维工作流：

-Missing provider or webhook configuration returns a skipped notification result and does not block deploy status transitions.
+- 发布风险摘要
+- Jenkins 失败诊断
+- 运维手册问答
+- 发布说明草稿
+- 事故复盘草稿

-## Jenkins Auto Sync
-
-Manual sync is always available through `POST /deploy-runs/sync-jenkins`. To enable a lightweight in-process poller before Redis/BullMQ is introduced:
-
-```env
-JENKINS_AUTO_SYNC_ENABLED=true
-JENKINS_AUTO_SYNC_INTERVAL_MS=30000
-```
-
-The poller only scans queued/running runs that already have a Jenkins queue id or build number.
+普通成员使用 Agent 时必须绑定自己有权限访问的项目。Agent 调用只读，不会触发发布、修改 Jenkins、修改 Gitea 或暴露密钥。