chore: deploy 触发分支改 master,竞品调研/原型/色板/i18n/分享组件/文档等成果入库

This commit is contained in:
Sisyphus committed 2026-08-14 09:58:52 +08:00
1 parent 5a97e6124e
commit 40e2342a02
75 files changed
+6848 -540

No files matched your search

+140
View File
@@ -0,0 +1,140 @@
# 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` |