feat: PLANNING体系首版（00路线图/02任务总表/03执行协议/I-03/I-04/registry42口径）+M1止血交付

2026-09-12 14:25:25 +08:00
commit 8242e730b4
482 changed files with 37029 additions and 0 deletions
@@ -0,0 +1,59 @@
+# C-05 · 工具页 SEO 预渲染
+
+| 字段 | 值 |
+|---|---|
+| 项目 | 可乐工具 · `chunyu_project_react`（构建层）+ 部署配置 |
+| 优先级 | P1 · M3 |
+| 建议模型 | deepseek-v4.1-flash（主）/ kimi-k3（全页 meta 核查） |
+| 依赖 | C-01（路由先稳定） |
+| 预估 | 2.5 天 |
+
+## 一、背景（为什么做)
+
+工具站的核心获客渠道是搜索引擎（"时间戳转换""JSON 格式化"都是大流量词），菜鸟工具/tool.lu 全部吃 SEO 流量。本项目 Vite SPA 纯客户端渲染，**蜘蛛抓不到任何工具内容**——SEO 基本为零（`docs/产品问题分析与改造路线.md` P0-4）。
+
+## 二、目标（交付物）
+
+1. **构建期预渲染**：全部工具详情页（20+ 工具页路由）在 `npm run build` 时产出含完整正文的静态 HTML（推荐 `vite-plugin-prerender` 或独立 puppeteer 脚本，按项目现状选型；产出直接进 `dist/`）。
+2. **每页独立 meta**：`<title>`、`<meta name="description">`、OG 标签（`og:title/og:description/og:image`），内容从工具的 name/description 字段生成；**不重复不空**。
+3. **sitemap.xml + robots.txt**：sitemap 覆盖全部工具 URL（含首页、工具列表、分类页），robots 放行蜘蛛、指向 sitemap。
+4. **部署接线**：nginx 对预渲染产物优先返回静态 HTML；不破坏 SPA 接管（首屏 HTML 后 React 正常 hydrate 交互）。
+5. 工具页组件支持标题/描述注入（小型 hook 或 helmet 类方案，按项目现状）。
+
+## 三、执行步骤
+
+```text
+1. 盘点全部需预渲染的路由清单（工具页 + 分类页 + 首页）
+2. 选型预渲染方案并接入构建流程（保持现有构建命令不变）
+3. 每页 meta 注入
+4. sitemap/robots 生成脚本（构建后自动产出）
+5. 本地构建 → curl 验证产物 HTML 含正文
+6. nginx 配置片段更新（预渲染优先），写明部署要点
+```
+
+## 四、验收标准
+
+- [ ] `npm run build` 后 `dist/` 内每个工具页 HTML 含完整正文（`curl` 静态文件可见关键内容，非空 `#root`）
+- [ ] 每页 `<title>` 唯一且语义化；description 非空
+- [ ] sitemap.xml 覆盖全部工具 URL（数量与路由清单一致）
+- [ ] robots.txt 正确放行 + 指向 sitemap
+- [ ] 浏览器访问预渲染页：内容先现、React 正常接管交互（无闪烁错乱）
+- [ ] 构建时间增加在可接受范围（记录数据）
+
+## 五、验收命令（参考）
+
+```bash
+cd chunyu_project_react && npm run build
+node scripts/check_seo.mjs   # 本任务交付：扫描 dist 校验 title/description/sitemap 覆盖
+curl -s http://localhost:8080/utility/json-formatter | grep -o "<title>.*</title>"
+```
+
+## 六、边界（不许做）
+
+- 不引入 Next.js 全量迁移（成本不成比例；预渲染即可）
+- 不改工具页业务逻辑
+- 不预渲染登录态页面（profile/wallet 等一律排除，防信息泄露）
+
+## 七、交接
+
+写 `PROGRESS_C-05.md`（含构建产物校验输出、sitemap 覆盖数、构建耗时对照）。