湛兮
59 lines
2.2 KiB
Markdown
59 lines
2.2 KiB
Markdown
# 后端 RTK
|
||
|
||
## 架构
|
||
|
||
- 框架：NestJS + TypeScript。
|
||
- 包管理器：pnpm。
|
||
- 数据访问：Prisma Client 和 Prisma migrations。
|
||
- 本地默认行为：未配置 MySQL 时使用种子项目和内存数据保持 API 可运行；生产环境注入凭据后使用真实 Jenkins 和 Gitea 客户端。
|
||
|
||
## 模块地图
|
||
|
||
- `config`：环境变量 schema 和校验。
|
||
- `prisma`：PrismaService 和数据库健康边界。
|
||
- `health`：运行时和依赖健康摘要。
|
||
- `auth`：登录鉴权、密码管理、登录 token 和当前用户上下文。
|
||
- `members`：成员管理和项目权限分配。
|
||
- `messages`：平台消息通知，当前用于普通成员忘记密码请求。
|
||
- `projects`：项目配置 API 和 Repository。
|
||
- `deploy-runs`：发布记录 API、状态模型和 BPMN 步骤摘要。
|
||
- `integrations/jenkins`：Jenkins API 客户端边界。
|
||
- `integrations/gitea`：Gitea API 客户端边界。
|
||
- `notifications/wecom`：企微、飞书和通用 webhook 通知边界。
|
||
- `agent-config`：Agent 系统级配置、密钥加密和连接测试。
|
||
- `agent`：只面向运维工作流的 LLM 代理边界。
|
||
- `audit`：脱敏审计记录边界。
|
||
|
||
## 数据访问规则
|
||
|
||
1. Controller 调用 service。
|
||
2. Service 调用 repository 和集成客户端。
|
||
3. Repository 调用 Prisma。
|
||
4. 原生 SQL 只允许作为例外，并且只能放在 repository。
|
||
5. 启用持久化写入后，发布记录写入必须使用事务。
|
||
|
||
## 环境规则
|
||
|
||
- `.env.example` 只能包含占位值。
|
||
- `.env` 只用于本地并且不能提交。
|
||
- 缺少外部集成配置时，健康检查应降级为 `not_configured`，不能导致本地开发启动失败。
|
||
- 生产环境保存 Agent 密钥必须配置 `SECRET_ENCRYPTION_KEY`。
|
||
|
||
## 验证
|
||
|
||
依赖可用时，交付前运行：
|
||
|
||
```bash
|
||
pnpm install
|
||
pnpm prisma:generate
|
||
pnpm lint
|
||
pnpm test
|
||
pnpm build
|
||
```
|
||
|
||
## 部署迁移
|
||
|
||
- Jenkins API 部署脚本的仓库版本在 `deploy/deploy-devops-platform-api-from-jenkins.sh`。
|
||
- 脚本会在切换 `/srv/www/devops-platform-api` 前运行 `pnpm prisma migrate deploy`，迁移失败时不会替换旧服务目录。
|
||
- 生产库早期通过手工 SQL 初始化，首次启用迁移时脚本会在确认 12 张核心表都存在后把基线迁移标记为 applied。
|