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

127 lines
8.0 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.
# CI 门禁:色号表与 Showcase 等新页面构建检查(T-109)
> 维护者:GitOps-Engineer(T-109)
> 关联文件:`.github/workflows/deploy.yml`、`perler-lab/nginx.conf`、`perler-lab/src/App.tsx`
> 更新日期:2026-08-14
## 检查结论(TL;DR)
| 检查项 | 结论 |
|---|---|
| 新页面是否影响现有构建? | **不破坏**。新页面均通过 `App.tsx` 顶层静态 import 打包进同一 Vite bundle,`typecheck` + `vite build` 天然覆盖 |
| Vite build 是否自动打包新路由页面? | **是**。路由为 `App.tsx` 内基于 `window.location.pathname` 的客户端分支(非 react-router 动态加载),无按路由分包,全部页面一次性打进 `assets/index-*.js` |
| SPA 路由是否需要 Nginx / fallback 配置? | **已具备,无需新增**。`perler-lab/nginx.conf` 已配置 `try_files $uri $uri/ /index.html;`,新路由直访由 nginx 回退到 `index.html` 后由前端渲染 |
| 是否需要新增 CI 门禁? | **需要小补强**。已新增「Verify SPA dist & route smoke」步骤:校验 dist 产物 + 用 `vite preview` 对每个新路由做直访冒烟,防「路由直访 404」回归 |
| 是否改动 deploy.yml? | **是**。`test` job 的 `Frontend production build` 步骤之后新增一个产物校验 + 路由冒烟步骤(见下文) |
---
## ① 新页面构建验证清单(typecheck / build 覆盖确认)
### 新页面与路由清单
| 路由 | 页面组件 | 源码位置 |
|---|---|---|
| `/chibi`、`/chibi/*` | `ChibiPage` | `perler-lab/src/ChibiPage.tsx` |
| `/color-chart`、`/color-chart/:brand` | `ColorChartPage` | `perler-lab/src/ColorChartPage.tsx`(数据 `src/lib/color-chart-data.ts` + `src/lib/palette-data/*.json`) |
| `/showcase`、`/showcase/*` | `ShowcasePage` | `perler-lab/src/pages/ShowcasePage.tsx` |
| `/library`、`/library/*` | `LibraryPage` | `perler-lab/src/pages/LibraryPage.tsx` |
| 其他任意路径 | `HomePage`(兜底) | `perler-lab/src/App.tsx` |
### 覆盖确认
- **路由实现方式**:`App.tsx`(`src/App.tsx` 第 335–348 行)在顶层**静态 import** 全部页面组件(`import ColorChartPage from './ColorChartPage'` 等),再按 `window.location.pathname` 分支渲染。无 react-router、无 `React.lazy` 动态加载。
- **typecheck 覆盖(G3)**:`npm run typecheck` = `tsc --noEmit`(`tsconfig.json` 开启 `strict`)。新增页面的 `.tsx`/`.ts` 源码全部参与编译,类型错误会直接拦截。CI 矩阵中 `perler-lab` 与 `perler-lab-server` 均执行。
- **build 覆盖(G4)**:`npm run build` = `vite build`。由于所有页面为静态 import,新页面组件 + 色号 JSON 数据 + CSS 必然被 Rollup 打包进 `dist/assets/index-*.js`。构建产物中不存在“漏掉某个路由页面”的空间——只要 App.tsx 引用了它,就会进 bundle;引用缺失则 tsc 直接报错(`Cannot find module`)。
- **产物校验**:CI 新增步骤显式断言 `dist/index.html` 与 `dist/assets/*.js` 存在,确认产物完整性。
> 结论:**无需**为新页面单独新增 build 命令。现有 G3(typecheck)+ G4(vite build)已完整覆盖;T-109 仅在其后增加产物校验与路由冒烟,作为“构建成功”之外的“构建产物可直访”门禁。
### 发现的问题(非阻塞)
- `/help` 路由在 `App.tsx` 中**不存在**(`src/App.tsx` 无 `/help` 分支),且全局无 `HelpPage` 组件。直访 `/help` 会落到 `HomePage` 兜底,不会 404,但展示内容与预期不符。若 `help` 属于已规划页面(如 T-109 上下文提到的 4 个新页面之一),需在后续任务中补充路由与组件;若为误报,可忽略。
---
## ② SPA fallback 部署配置建议
### 现状:已配置,无需改动
`perler-lab/nginx.conf` 已包含 SPA 回退:
```nginx
# ── SPA 路由回退 ──
location / {
try_files $uri $uri/ /index.html;
}
```
行为:直访 `/color-chart/mard` → nginx 找不到对应文件 → 回退 `index.html` → 前端 `App.tsx` 读 `location.pathname` → 渲染 `ColorChartPage`。新路由**无需任何额外 Nginx 配置**。
### 建议(保持现状的三条纪律)
1. **不要把新页面做成 `public/` 下的物理 HTML 文件**。Vite 会将 `public/` 原样拷入 dist,若未来出现同名静态目录(如 `dist/showcase/`),nginx 的 `try_files $uri $uri/` 会优先命中该目录而非 SPA 回退,导致路由与静态资源语义冲突。
2. **保持 `location /` 的 try_files 兜底不被覆盖**。新增 location 时避免写死 `try_files $uri =404` 之类的规则覆盖根 location。
3. **若未来迁移到 Next.js / SSR**,此配置需改为上层反代(`nginx.conf` 顶部注释已说明,参考 `docs/DEPLOY.md`),届时 SPA fallback 职责转移,与本门禁解耦。
### 测试环境等价验证
CI 路由冒烟使用 `vite preview`(自带 history fallback),其行为与生产 nginx 的 `try_files $uri $uri/ /index.html` 等价:直访任意路由返回 `index.html`(HTTP 200)。**注意 `vite preview` 只验证“fallback 语义正确”,无法覆盖 nginx 语法/配置错误**——nginx 配置有效性仍需在 `build` job 的 docker 镜像构建阶段(`COPY nginx.conf` + `nginx:alpine` 启动)保证,或本地 `docker run` 验证。
---
## ③ CI 门禁建议(已落地到 deploy.yml)
### 建议结论
**需要**在 `test` job 增加路由冒烟检查。理由:
- typecheck/build 只能证明“代码可编译、页面已打包”,**不能**证明“直访新路由返回 200”;
- 若未来有人误删 `try_files` 或把路由改坏,冒烟检查会在 CI 期拦截,避免部署后用户直访 404;
- 成本极低(一次 `vite preview` + 7 个 curl),并入现有 test job 矩阵的 perler-lab 分支即可。
### 已新增步骤(deploy.yml → test job)
```yaml
- name: Verify SPA dist & route smoke
if: matrix.project.name == 'perler-lab'
working-directory: perler-lab
run: |
set -e
[ -f dist/index.html ] || { echo "❌ dist/index.html 缺失"; exit 1; }
ls dist/assets/*.js > /dev/null 2>&1 || { echo "❌ dist/assets 无 JS bundle"; exit 1; }
npx vite preview --port 4173 --strictPort > /tmp/vite-preview.log 2>&1 &
PID=$!
trap "kill $PID 2>/dev/null || true" EXIT
for i in $(seq 1 30); do
curl -sf http://localhost:4173/ > /dev/null 2>&1 && break
sleep 0.5
done
curl -sf http://localhost:4173/ > /dev/null 2>&1 || {
echo "❌ vite preview 未能启动"; cat /tmp/vite-preview.log; exit 1; }
for route in / /chibi /color-chart /color-chart/mard /color-chart/artkal-c /showcase /library; do
code=$(curl -s -o /dev/null -w '%{http_code}' "http://localhost:4173$route")
echo "GET $route → $code"
[ "$code" = "200" ] || { echo "❌ 路由 $route 返回 $code(预期 200)"; exit 1; }
done
```
要点说明:
- 冒烟路由集:`/`(首页)、`/chibi`、`/color-chart`(列表)、`/color-chart/mard` 与 `/color-chart/artkal-c`(品牌子路由,覆盖“带段路由直访”)、`/showcase`、`/library`。未加 `/help`(见①,该路由当前不存在)。
- 若未来新增品牌(如 `/color-chart/perler`),建议同步追加到路由集;也可改为读取 `COLOR_CHART_BRANDS` 动态断言,但会增加 CI 脚本复杂度,暂不引入。
- 冒烟失败(任一路由非 200 或产物缺失)→ 步骤退出码非 0 → `test` job 失败 → 阻塞 `build` / `deploy`,符合门禁语义。
---
## 变更记录(T-109)
| 变更 | 文件 |
|---|---|
| 新增「Verify SPA dist & route smoke」步骤:dist 产物校验 + vite preview 对新路由直访冒烟 | `.github/workflows/deploy.yml` |
| 新增本文档(构建验证清单 / SPA fallback 说明 / CI 门禁建议) | `docs/CI-NEWPAGES.md` |
## 验证方式(CI 执行)
推送 `master` 后观察 Actions 流水线:`test` job(perler-lab 分支)应依次出现 `Frontend production build` → `Verify SPA dist & route smoke`,日志中 7 个 `GET <route> → 200` 全部通过后进入 `build` job。