# PROGRESS — C-05 · 工具页 SEO 预渲染

- 状态：done

> 日期 2026-09-13 · 范围：`chunyu_project_react`（构建层脚本+nginx.conf）+ 校验脚本

## 现状 vs 差距（接手时）
- 已有：Vite SPA（`dist/index.html` 纯空 `#root` + 单一 `<title>chunyu_project`）、nginx SPA 回退、
  `scripts/check_routes.mjs`（C-01 路由回归）。
- 缺口：蜘蛛抓不到任何工具页正文；无 sitemap/robots；无单页 meta。

## 选型
独立 Node 后处理脚本（`scripts/seo_prerender.mjs`，零新依赖），不引入 `vite-plugin-prerender`/puppeteer：
构建命令不变（`build` 链尾追加），失败即中断构建（`&&` 链），产出直接进 `dist/`。

## 改动（`chunyu_project_react/`）
1. `scripts/seo_prerender.mjs`（新建）：工具清单与后端 `seed_tools.py` 同源（16 启用工具，
   url_path/name/description 对齐）；每工具页直出 `dist/<url>/index.html`（独立 title/description/
   keywords/canonical/OG + 静态正文 h1+说明+相关工具链 + `#root` 占位 + `location.replace` 跳转，
   React hydrate 后照常接管）；聚合页 `/`（`dist/index.seo.html`，不覆盖 SPA 外壳）、`/utility`、`/top`；
   `sitemap.xml`（19 URL）+ `robots.txt`（放行蜘蛛、屏蔽 profile/wallet/console/messages/chat、指向 sitemap）。
2. `scripts/check_seo.mjs`（新建，任务卡验收脚本）：工具页存在/唯一 title/非空 description/
   静态正文/OG、聚合页、sitemap 覆盖 19 URL、robots 口径、SPA 外壳完好、清单 16 条对齐。
3. `package.json`：`build` 链尾 `&& node scripts/seo_prerender.mjs`；新增 `seo` / `seo:check` 快捷命令。
4. `nginx.conf`：`location = /` 优先 `index.seo.html`；工具页正则 location 优先 `try_files` 静态 HTML
  （1h 缓存）；登录态页（/post、/profile 等）不命中，落 SPA 回退。

## 边界遵守
- 无 Next.js 迁移；工具页业务零改；登录态页（profile/wallet/console/messages/chat）robots + nginx 双屏蔽。

## 验证
```bash
pnpm build
# ✓ built in ~12s（含 tsc -b）；[seo] prerender done: 19 html + sitemap(19 urls) + robots.txt in 15ms
node scripts/check_seo.mjs
# SEO CHECK ALL GREEN (16 tools + 3 pages) —— 逐页 PASS 明细见终端输出
curl 等价：dist/utility/json-formatter/index.html → <title>JSON格式化 - 免费在线工具 | 可乐开发工具箱</title>，含 <h1> 正文
nginx：本地无二进制/docker 未起，改用 location 自查——预渲染块在 SPA 回退前、
  16 工具+聚合命中 SEO、/post/1 与 /profile 走 SPA、大括号平衡（node 自查脚本全对）
```
构建耗时：C-06 轮 14.99s → 本轮 11.87s（机器波动范围内），SEO 脚本本身仅 +15ms。

## 状态
done。遗留：`--base` 当前为 `https://tools.example.com` 占位符——部署时带真实域名重跑
`node scripts/seo_prerender.mjs --dist dist --base https://真实域名` 刷新 sitemap/OG/canonical；
浏览器“首屏先现+React 接管”需线上 nginx 联调时录屏补证据。