127 lines
8.0 KiB
Markdown
127 lines
8.0 KiB
Markdown
# 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。
|