🏗️ 工程规约：SSG 集成协议 (@wroud/vite-plugin-ssg)

目标： 将架构从 SPA（单页应用）升级为 SSG（静态站点生成）。 目的： 实现“反重力”性能（零 JS 首屏渲染）和针对 AI 爬虫（GEO）的完美 SEO 结构。

1. 架构差异分析 (Current vs. Target)

特性	当前架构 (SPA)	目标架构 (SSG)
构建产物	一个通用的 `index.html` + JS 资源包。	为每个路由生成独立的 `index.html` (如 `/blog/intro/index.html`)。
路由模式	`BrowserHistory` (生产) / `HashHistory` (沙箱)。	构建时使用 `MemoryHistory` (模拟跳转)，客户端使用 `BrowserHistory` (水合)。
SEO 机制	依赖 Googlebot 执行 JS 抓取 (CSR)。	爬虫直接读取预渲染的 HTML (Title, Meta, Content)。
数据加载	客户端 `useDocsDB` 在运行时初始化索引。	构建时 Node.js 环境需访问 `registry` 并预填充数据到 HTML。

要在不破坏 AI Studio 沙箱兼容性的前提下集成 SSG，我们需要执行“外科手术式”的入口分离。

目前的 src/main.tsx 既负责路由创建，也负责挂载 DOM。SSG 需要将它们解耦。

src/router.tsx (共享工厂):
- 职责: 仅导出 createRouter 工厂函数。
- 逻辑: 接受 history 作为参数。这允许我们在服务器端传入 MemoryHistory，在客户端传入 BrowserHistory。
src/entry-client.tsx (浏览器端):
- 职责: 仅在浏览器中运行。
- 关键变更: 将 ReactDOM.createRoot 替换为 ReactDOM.hydrateRoot。这是 React 接管静态 HTML 并消除闪烁的关键。
src/entry-server.tsx (服务器端/构建):
- 职责: SSG 插件的渲染引擎。
- 逻辑:
  - 导出一个渲染函数。
  - 使用 MemoryHistory 初始化路由并推入该 url。
  - 等待数据加载 (await router.load())。
  - 使用 ReactDOMServer.renderToString 生成 HTML 字符串。
  - 提取 Helmet (SEO) 上下文并注入 HTML 头部。

SSG 插件需要知道：“我要生成哪些页面？” 我们不需要爬虫，因为我们有注册表。

策略: 在 vite.config.ts 中编写 getRoutes 逻辑。
逻辑: 读取 src/mocks/content/registry-*.ts，提取所有 slug 和 lang，生成一个路径列表：['/', '/en', '/zh', '/en/docs/core/plan', ...]。

挑战: 服务器端渲染了数据，客户端需要相同的数据来完成“水合”。
解决方案: 由于我们的“数据库”是静态的 TypeScript 文件 (src/mocks/content/index.ts)，只要确保客户端和服务器端引用的是同一份代码，数据一致性天然得到保证。

SSG 是一个构建时 (Build-time) 行为。它依赖于 Node.js API，这在 AI Studio 的浏览器环境中是不存在的。

协议:
- vite dev: 必须保持 SPA 模式。index.html 应指向 entry-client.tsx（或保留 main.tsx 作为开发入口）。
- vite build: 激活 SSG 插件。
护栏: 使用 if (typeof window === 'undefined') 守卫代码，防止第三方库在构建过程中因访问 window 而崩溃。

状态：已完成并激活。SSG 流水线已建立。