chore: deploy 触发分支改 master,竞品调研/原型/色板/i18n/分享组件/文档等成果入库
This commit is contained in:
1 parent
5a97e6124e
commit
40e2342a02
75 files changed
+6848
-540
No files matched your search
@@ -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` |
|
||||
Reference in new issue
Block a user