feat: 初始化DevOps平台后端

2026-06-11 20:49:59 +08:00
commit caec5a618d
88 changed files with 11893 additions and 0 deletions
@@ -0,0 +1,73 @@
+# DevOps Platform 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.
+
+## 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.
+
+## 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.
+
+## Useful Commands
+
+```bash
+pnpm lint
+pnpm test
+pnpm build
+pnpm check
+pnpm prisma:migrate:dev --name init
+```
+
+## API
+
+- `GET /health`: dependency configuration and health summary.
+- `GET /settings/integration-config`: Jenkins/Gitea/notification/LLM/Database/Redis/Secret Encryption Key configuration status. The response only exposes environment variable names, 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/: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.
+
+## Data Access Rules
+
+- 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
+
+- 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
+
+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 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.