Files
perler-lab/docs/CI-GATES.md
T

141 lines
5.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# PERLER LAB CI 质量门禁清单(CI-GATES)
> 维护者:DevOps-Engineer(T-081)
> 关联文件:`.github/workflows/deploy.yml`
> 更新日期:2026-08-14
本清单定义 PERLER LAB 的 CI/CD 质量门禁。**任一门禁失败即阻塞构建与部署**。
本地开发可执行同样的命令提前自检,确保推送到 `main` 后流水线绿。
---
## 流水线结构
```
push main / workflow_dispatch
│
▼
┌─── test(矩阵并行)───┐
│ perler-lab │
│ perler-lab-server │
└──────────┬─────────────┘
▼
build(Docker 镜像构建)
▼
deploy(SSH 部署,需配置 Secrets)
```
门禁依赖关系:`build` 依赖 `test`,`deploy` 依赖 `build`。测试不通过则不会构建/部署。
---
## 质量门禁清单
### G1 前端单元测试
| 项目 | 值 |
|---|---|
| 命令 | `npm test`(perler-lab 工作目录,即 `npx vitest run`) |
| 通过标准 | 所有测试文件通过,退出码 0;当前基线:11 个文件 / 147 个用例 |
| 流水线步骤 | `test` job → `Install & Test` |
| 失败后果 | 流水线终止,不进入 build |
### G2 后端单元测试
| 项目 | 值 |
|---|---|
| 命令 | `npm test`(perler-lab-server 工作目录,即 `npx vitest run`) |
| 通过标准 | 所有测试文件通过,退出码 0;当前基线:9 个文件 / 121 个用例 |
| 流水线步骤 | `test` job → `Install & Test`(矩阵分支) |
| 失败后果 | 流水线终止,不进入 build |
### G3 TypeScript 严格模式类型检查(前后端)
| 项目 | 值 |
|---|---|
| 命令 | `npm run typecheck`(前后端各自执行,即 `npx tsc --noEmit`) |
| 通过标准 | 无任何 TS 错误,退出码 0 |
| 严格性 | 两端 `tsconfig.json` 均开启 `"strict": true` |
| 流水线步骤 | `test` job → `Typecheck`(矩阵两项目均执行) |
| 失败后果 | 流水线终止;`vite build` 前本地自检必须通过 |
| 备注 | `perler-lab-server` 的 `typecheck` 脚本由 T-081 补齐;`src/i18n/index.tsx` 必须保持 `.tsx` 后缀(含 JSX) |
### G4 前端生产构建
| 项目 | 值 |
|---|---|
| 命令 | `npm run build`(perler-lab 工作目录,即 `npx vite build`) |
| 通过标准 | 构建成功,产出 `dist/`,退出码 0 |
| 流水线步骤 | `test` job → `Frontend production build`(仅 perler-lab) |
| 失败后果 | 流水线终止 |
| 备注 | `build` job 中的 `docker build` 亦会编译前端,但 G4 在前一阶段显式验证 |
### G5 依赖安装策略(矩阵)
| 项目 | 值 |
|---|---|
| 规则 | 存在 `package-lock.json` 用 `npm ci`;不存在则 `npm install` |
| 当前状态 | perler-lab ✅ 有锁文件 → `npm ci`;perler-lab-server ✅ 有锁文件 → `npm ci` |
| 命令 | `npm ci --no-audit --no-fund` |
| 流水线步骤 | `test` job → `Install & Test` |
| 备注 | 若新增子项目无锁文件,需在矩阵中改为 `npm install` |
### G6 密钥安全(无硬编码)
| 项目 | 值 |
|---|---|
| 规则 | 所有敏感信息必须通过 `${{ secrets.X }}` 引用,禁止硬编码 |
| 当前引用 | `DEPLOY_HOST`、`DEPLOY_USER`、`DEPLOY_SSH_KEY`(部署);`DEPLOY_PATH`(带默认值 `/opt/perler-lab`) |
| 仓库配置 | 需在 GitHub → Settings → Secrets 中配置,未配置时 deploy 自动跳过(`if: ${{ secrets.DEPLOY_HOST != '' }}`) |
### G7 并发保护(防并行部署)
| 项目 | 值 |
|---|---|
| 配置 | 工作流级 `concurrency.group: ${{ github.workflow }}-${{ github.ref }}` |
| 行为 | 同一分支同时触发多次时串行执行;`cancel-in-progress: false`(排队等待,不中断进行中的部署) |
| 目的 | 防止两次部署同时 `git pull` + `docker compose up` 造成生产冲突 |
| 备注 | 由 T-081 新增 |
### G8 超时保护
| 项目 | 值 |
|---|---|
| test | `timeout-minutes: 15` |
| build | `timeout-minutes: 20` |
| deploy | `timeout-minutes: 30` |
| 目的 | 防止挂起的 job 无限占用 Actions 时长配额 |
| 备注 | 由 T-081 新增 |
### G9 YAML 结构有效性
| 项目 | 值 |
|---|---|
| 验证命令 | `python -c "import yaml; yaml.safe_load(open('.github/workflows/deploy.yml'))"` |
| 通过标准 | 无解析异常 |
| 备注 | T-081 已通过 pyyaml 实际解析验证 |
---
## 本地自检命令速查
```bash
# 前端(perler-lab/)
npm ci
npm test # G1
npm run typecheck # G3
npm run build # G4
# 后端(perler-lab-server/)
npm ci
npm test # G2
npm run typecheck # G3
```
> 注意:不要直接改 `src/i18n/index.tsx` 的后缀或把含 JSX 的代码放回 `.ts` —— 会同时击穿 G3 与 G4。
## 修改记录(T-081)
| 变更 | 文件 |
|---|---|
| 修复矩阵安装命令:perler-lab 改用 `npm ci`(有锁文件)并更新过期注释 | `.github/workflows/deploy.yml` |
| 新增工作流级 `concurrency` 并发保护 | `.github/workflows/deploy.yml` |
| 新增 `timeout-minutes`:test 15 / build 20 / deploy 30 | `.github/workflows/deploy.yml` |
| 类型检查扩展到前后端两项目(移除 perler-lab 专属条件) | `.github/workflows/deploy.yml` |
| 新增前端生产构建步骤(`npm run build`) | `.github/workflows/deploy.yml` |
| 新增 `typecheck` 脚本 | `perler-lab-server/package.json` |
| 修复含 JSX 的 i18n 运行时文件后缀(`.ts` → `.tsx`) | `perler-lab/src/i18n/index.tsx` |
| 放宽 `Messages` 类型为值类型 `string`(保留键全等约束) | `perler-lab/src/i18n/messages/zh-CN.ts` |
| 修复 `DEFAULT_PLAN` 与新版 `Plan` 接口字段不一致 | `perler-lab/src/App.tsx` |