@bovinphang/frontend-craft 2.5.0 → 2.7.0

package/templates/shared/rules/fec-error-handling.md

@@ -1,200 +1,56 @@
 # 错误处理规范
 
-## 错误分层
-
-| 层级 | 错误类型 | 处理方式 |
-|------|----------|----------|
-| 全局 | 未捕获异常、Promise rejection | 全局捕获 + 上报 + 降级 UI |
-| 路由/页面 | 页面级组件渲染错误 | Error Boundary + 页面级降级 |
-| 模块 | 功能模块内的运行时错误 | Error Boundary + 模块级降级 |
-| 组件 | 数据请求失败、操作失败 | 用户提示 + 重试机制 |
-| 表单 | 校验失败 | 字段级错误提示 |
-
-## 全局错误捕获
-
-### React
-
-```tsx
-// main.tsx — 未捕获的 Promise
-window.addEventListener("unhandledrejection", (event) => {
-  reportError(event.reason);
-});
-
-// 推荐：react-error-boundary，业务侧保持函数组件 + FallbackComponent
-import { ErrorBoundary } from "react-error-boundary";
-
-function GlobalErrorFallback({
-  error,
-  resetErrorBoundary,
-}: {
-  error: Error;
-  resetErrorBoundary: () => void;
-}) {
-  return (
-    <div role="alert">
-      <p>页面出现异常</p>
-      <button type="button" onClick={resetErrorBoundary}>
-        重试
-      </button>
-    </div>
-  );
-}
-
-// 根节点包裹示例（root 来自 createRoot(document.getElementById("root")!) 等）
-root.render(
-  <ErrorBoundary
-    FallbackComponent={GlobalErrorFallback}
-    onError={(error, info) => {
-      reportError(error, { componentStack: info.componentStack });
-    }}
-  >
-    <App />
-  </ErrorBoundary>,
-);
-```
+本文件约定前端错误处理的常驻边界。React/Vue 组件边界细节交给对应框架 skill，API 错误映射和鉴权刷新交给 `fec-api-integration`，安全敏感错误交给 `fec-security-review`。
 
-### Vue
-
-```typescript
-// main.ts
-app.config.errorHandler = (err, instance, info) => {
-    reportError(err, {
-        component: instance?.$options.name,
-        lifecycleHook: info,
-    });
-};
-
-window.addEventListener('unhandledrejection', (event) => {
-    reportError(event.reason);
-});
-```
+## 错误分层
 
-## Error Boundary 策略
+| 层级 | 错误类型 | 默认处理 |
+| ---- | -------- | -------- |
+| 全局 | 未捕获异常、Promise rejection | 捕获、上报、全局降级 UI |
+| 路由 / 页面 | 页面级渲染异常 | Error Boundary / 框架错误边界 + 页面级降级 |
+| 模块 | 功能模块运行时异常 | 模块级边界 + 局部降级 |
+| 组件 / 请求 | 数据请求失败、操作失败 | 用户可理解提示 + 可恢复动作 |
+| 表单 | 校验失败 | 字段级错误提示和修正入口 |
 
-```
-App (GlobalErrorBoundary)
-├── Header
-├── Main
-│   ├── Sidebar (ErrorBoundary)
-│   └── Content
-│       ├── Dashboard (ErrorBoundary)
-│       └── UserList (ErrorBoundary)
-└── Footer
-```
+## 全局与模块边界
 
-- 每个独立功能模块用 Error Boundary 包裹
-- 模块崩溃不应导致整个页面白屏
-- 降级 UI 应提供"重试"操作
+- 应在应用入口注册未捕获异常和 Promise rejection 监听，并接入项目错误上报平台。
+- React 使用项目统一的 Error Boundary 方案；业务组件保持函数式，不新增手写类组件边界。
+- Vue 使用项目统一的 `app.config.errorHandler`、`onErrorCaptured` 或框架级错误边界。
+- 独立功能模块应有局部降级能力，模块崩溃不应导致整个页面白屏。
+- Error Boundary 处理渲染异常；普通 API 失败应落到 loading/error/empty/data 状态和可恢复操作。
 
 ## API 错误处理
 
-### 统一错误格式
-
-```typescript
-interface ApiError {
-    code: string;
-    message: string;
-    details?: Record<string, string[]>;
-}
-```
-
-### 错误分级处理
-
-```typescript
-function handleApiError(error: ApiError) {
-    switch (error.code) {
-        case 'UNAUTHORIZED':
-            redirectToLogin();
-            break;
-        case 'FORBIDDEN':
-            showToast('无权限执行此操作');
-            break;
-        case 'VALIDATION_ERROR':
-            return error.details; // 返回给表单显示字段级错误
-        case 'NETWORK_ERROR':
-            showToast('网络异常，请检查网络连接');
-            break;
-        default:
-            showToast(error.message || '操作失败，请稍后重试');
-            reportError(error);
-    }
-}
-```
-
-### 请求拦截器
-
-在 axios / fetch 封装层统一处理：
-
-- 401 → 跳转登录（或刷新 token）
-- 403 → 权限不足提示
-- 500 → 通用错误提示 + 上报
-- 网络超时 → 超时提示 + 可选重试
-
-### 用户可恢复动作
-
-每类错误都应对应明确下一步：
-
-- `401`：重新登录或静默刷新失败后跳转登录
-- `403`：说明无权限并提供返回或申请权限路径
-- `404`：返回列表、重新搜索或创建入口
-- `409`：展示冲突对象和刷新/覆盖/取消选择
-- `422`：字段级错误回填表单
-- `429`：告知等待时间或稍后重试
-- `5xx` / 网络错误：重试、离线提示或联系支持
-
-UI 可显示 request id / trace id 方便支持排查，但不得暴露内部堆栈、SQL、服务名或敏感字段。
+- 请求层统一归一错误形状，组件不直接解析后端异常、token refresh 或重试策略。
+- 每类错误都应对应明确下一步：重试、重新登录、修改输入、返回上级、刷新冲突数据、联系支持或稍后再试。
+- `401`、`403`、`404`、`409`、`422`、`429`、`5xx` 和网络错误应有可区分的用户提示和日志语义。
+- UI 可显示 request id / trace id 方便支持排查，但不得暴露内部堆栈、SQL、服务名、密钥或敏感字段。
 
 ## 用户体验
 
-### 错误状态 UI
-
-每个数据展示区域应处理四种状态：
-
-1. **Loading** — 骨架屏或 spinner
-2. **Error** — 错误描述 + 重试按钮
-3. **Empty** — 空状态引导
-4. **Success** — 正常数据展示
-
-### 降级 UI 设计
-
-- 全局级：显示友好的错误页面，提供"返回首页"和"重试"
-- 模块级：显示该模块的占位错误卡片，页面其他部分正常
-- 操作级：Toast 提示 + 具体的下一步指引
-
-### 重试策略
-
-- 用户手动重试（按钮）
-- 自动重试（指数退避，最多 3 次）
-- 数据请求库的内置重试（React Query retries 等）
+- 每个数据展示区域处理 Loading、Error、Empty、Success 四种状态。
+- 全局级错误页提供返回首页、刷新或重试路径；模块级降级只影响该模块；操作级错误给出下一步。
+- 重试策略要克制：用户手动重试优先，自动重试需有上限、退避和停止条件。
+- 错误提示应保留用户已输入内容，避免因失败丢失表单或上下文。
 
 ## 错误上报
 
-<!-- 请根据项目实际的错误监控平台调整：Sentry / 自建 / 其他 -->
-
-上报内容应包含：
-
-- 错误堆栈
-- 用户 ID / 会话 ID
-- 当前页面 URL
-- 浏览器/设备信息
-- 复现上下文（操作步骤、请求参数）
+上报内容应包含错误堆栈、页面 URL、浏览器/设备信息、用户或会话标识、操作上下文、请求标识和版本信息。上报前清理 token、密码、个人敏感字段和大体积 payload。
 
 ## 反模式
 
-- 空 catch 块吞掉错误
-- 所有错误统一用 `alert()` 提示
-- 接口失败时 UI 无任何反馈
-- Error Boundary 没有重试机制，用户只能刷新页面
-- 在组件中到处写重复的 try/catch 而不是统一封装
-- 不上报错误，依赖用户反馈来发现问题
-- 用 Error Boundary 承接普通 API 错误，导致用户无法理解或恢复
-- 把后端原始异常、内部错误码或敏感字段直接展示给用户
+- 空 `catch` 块吞掉错误。
+- 所有错误统一用 `alert()` 或一个模糊 toast。
+- 接口失败时 UI 无反馈，或把后端原始异常直接展示给用户。
+- Error Boundary 没有重试或返回路径。
+- 在组件中到处写重复 `try/catch`，而不是统一封装请求边界。
+- 用 Error Boundary 承接普通 API 错误，导致用户无法理解或恢复。
 
 ## 检查清单
 
-- [ ] 全局有未捕获异常和 Promise rejection 的监听
-- [ ] 关键功能模块有 Error Boundary（React）或 onErrorCaptured（Vue）包裹
-- [ ] API 请求有统一的错误拦截和分级处理
-- [ ] 所有数据展示区域处理了 Loading / Error / Empty / Success 四种状态
-- [ ] 降级 UI 提供了"重试"操作
-- [ ] 错误信息上报到监控平台
+- [ ] 全局未捕获异常和 Promise rejection 已监听。
+- [ ] 关键页面或模块有框架错误边界和局部降级 UI。
+- [ ] API 请求有统一错误归一、分级处理和可恢复动作。
+- [ ] 数据区域覆盖 Loading / Error / Empty / Success。
+- [ ] 错误上报包含足够定位信息且不泄露敏感数据。

package/templates/shared/rules/fec-i18n.md

@@ -1,112 +1,64 @@
 # 国际化 (i18n) 规则
 
-凡是涉及用户可见文案、提示信息、表单标签、错误消息或 UI 文本时，都应用本文件。
-
-<!-- 请根据项目实际 i18n 方案修改 locales 路径、库与 key 前缀 -->
+凡是涉及用户可见文案、提示信息、表单标签、错误消息或 UI 文本时，都应用本文件。请根据项目实际 i18n 方案修改 locales 路径、库与 key 前缀。
 
 ## 适用范围
 
-- **现代栈（纯 React / Vue 等）**：以下「核心原则」「文案规范」「实现指导」与通用检查清单优先适用。
-- **遗留 HTML/JS、渐进迁移或新旧并存**：新代码路径仍须满足核心原则；遗留层额外遵守「遗留代码与迁移场景」，避免扩大硬编码与混乱 key。
+- **现代栈（React / Vue / Next / Nuxt 等）**：新增或修改的用户可见文案必须走项目 i18n 方案。
+- **遗留 HTML/JS、渐进迁移或新旧并存**：新代码路径仍须满足核心原则；遗留层遵守迁移约束，避免扩大硬编码和混乱 key。
 
-下文用 **`src/locales/`** 指代项目实际文案资源目录，请按仓库约定替换（如 `public/locales`、`lang/`、`messages/` 等）。
+下文用 `src/locales/` 指代项目实际文案资源目录，请按仓库约定替换。
 
 ## 核心原则
 
-- 在新应用代码（组件、路由页、hooks、composables）中，用户可见文案须使用 i18n，**禁止**硬编码中文或英文字符串
-- i18n key 按模块组织，使用点分命名：`module.component.label`
-- 相同语义的文案复用同一个 key，避免重复定义
-
-## 文案规范
-
-### 命名约定
-
-```
-common.confirm        → 通用确认
-common.cancel         → 通用取消
-user.login.title      → 用户登录标题
-order.list.empty      → 订单列表空状态
-```
-
-### 分类
+- 新应用代码中的用户可见文案须使用 i18n，禁止硬编码中文或英文字符串。
+- i18n key 按模块组织，使用点分命名，例如 `order.list.empty`。
+- 相同语义的文案复用同一个 key，避免重复定义。
+- 变量、复数、日期、数字和货币使用 i18n 能力格式化，不用字符串拼接。
+- 修改文案前先检索现有资源，优先复用准确 key。
 
-- `common.*` — 跨模块通用文案（确认、取消、提交、加载中等）
-- `module.component.*` — 模块级文案
-- `validation.*` — 表单校验提示
-- `error.*` — 错误信息
+## 文案与资源规范
 
-### 语言文件
-
-- **每种自然语言对应独立资源文件**（命名依项目约定，如 `en.json` 与 `zh-CN.json`，或 `en.ts` / `zh-CN.ts`），置于 `src/locales/`（或项目约定目录）下；**禁止**将多种语言的译文混写在同一文件或同一顶层多语言对象内，以免难以 diff、评审与按需加载。若仓库历史结构暂为混排，新增语言或新模块仍应优先采用分文件约定。
-- **编码**：文案文件须以 **UTF-8** 保存（团队有约定时优先 **UTF-8 无 BOM**），确保在 IDE 中打开时中文、日文等非 ASCII 字符**不出现乱码**；禁止用系统默认 ANSI、GBK 等与 UTF-8 混用导致编码误判。若仓库已有 `.editorconfig`，与其中 `charset = utf-8` 等声明保持一致。
+- `common.*` 用于跨模块通用文案，例如确认、取消、提交、加载中。
+- `module.component.*` 用于模块级文案。
+- `validation.*` 用于表单校验提示。
+- `error.*` 用于错误信息。
+- 每种自然语言对应独立资源文件，禁止多种语言混写在同一文件或同一顶层多语言对象内。
+- 文案文件须以 UTF-8 保存；团队有约定时优先 UTF-8 无 BOM，避免中文、日文等非 ASCII 文案乱码。
+- 新增 key 时，同步更新当前功能应覆盖的主要语言文件；若某语言暂缺，必须显式记录缺口。
 
 ## 遗留代码与迁移场景
 
-在渐进式迁移、微前端或新旧代码并存时：
-
-- **遗留层**：不在 legacy HTML 或 JS 中**新写**用户可见的中/英文硬编码，除非该段为纯静态展示且仓库**尚未**建立可接入的国际化路径（避免扩大技术债）。
-- **新代码路径**：React / Vue 等侧新增、修改的提示、错误、按钮、表单标签等，须走 i18n；新增子应用或模块时，须与现有语言文件结构、命名空间、懒加载策略一致，**不破坏**既有语言策略。
-- **复用优先**：同一语义优先复用已有 key 或已有资源项，避免同一含义多份翻译。
-- **多语言同步**：新增或修改条目后，至少核对当前功能已覆盖的**主要语言文件**是否一并更新。
-- **改动前检索**：改提示、错误、按钮、表单标签前，先在 `src/locales/`（或项目约定目录）中搜索是否已有对应文案。
-- **Key 与文案治理**：
-  - key 按**页面 / 模块 / 语义**组织，避免继续沿用历史缩写或无意义分段。
-  - 先按当前界面真实含义定 key，再写各语言译文。
-  - 旧文案若仅「能用但不准」，优先**重命名 key 并重写译文**，不为劣质命名长期保留并行兼容。
-  - 仅当某旧 key 已成为**对外契约**（后端、埋点、外部文档、第三方集成等固定引用）时，才引入映射层或别名过渡；否则不把历史包袱复制进新结构。
-
-## 实现指导
-
-### Vue（vue-i18n）
-
-```vue
-<template>
-  <!-- 正确 -->
-  <span>{{ $t('order.status.pending') }}</span>
-  <!-- 错误：硬编码 -->
-  <span>待处理</span>
-</template>
-```
-
-### React（react-intl / react-i18next）
-
-```tsx
-// 正确
-<FormattedMessage id="order.status.pending" />
-// 或
-const { t } = useTranslation();
-<span>{t('order.status.pending')}</span>
-
-// 错误：硬编码
-<span>待处理</span>
-```
-
-## 检查清单
+- 遗留 HTML 或 JS 中不新增用户可见硬编码，除非该段为纯静态展示且仓库尚无可接入 i18n 路径。
+- React / Vue 等新代码路径新增提示、错误、按钮、表单标签时，必须走 i18n。
+- 新增子应用或模块时，与现有语言文件结构、命名空间和懒加载策略一致。
+- key 按页面、模块和语义组织，避免继续沿用历史缩写或无意义分段。
+- 旧 key 若仅“能用但不准”，优先重命名 key 并重写译文，不长期保留并行兼容。
+- 仅当旧 key 已成为对外契约（后端、埋点、外部文档、第三方集成等固定引用）时，才引入映射层或别名过渡。
 
-### 通用
+## 实现约束
 
-- [ ] 所有新增用户可见文案使用 i18n key（新代码路径）
-- [ ] 新增 key 已添加到所有**应覆盖**的语言文件，且各语言仍分文件维护（未混写）
-- [ ] 语言资源文件为 UTF-8（无 BOM 或按仓库约定），在 IDE 中打开无乱码
-- [ ] key 命名符合模块.组件.用途 的约定
-- [ ] 包含变量的文案使用插值而非拼接
-- [ ] 复数形式使用 i18n 复数规则而非条件判断
-- [ ] 日期、数字、货币使用 i18n 格式化
+- Vue、React、Next、Nuxt 的具体调用方式以项目现有 i18n 库为准，例如 `vue-i18n`、`react-intl`、`react-i18next` 或框架内置方案。
+- 组件中不要直接写用户可见硬编码；测试可通过 key 或最终文案断言，但应避免与翻译细节过度耦合。
+- 懒加载语言包时，loading、fallback 和缺失 key 行为要可预期。
+- 错误、表单和空状态文案要能表达用户下一步，不只翻译技术错误。
 
-### 迁移或混合栈时补充
+## 检查清单
 
-- [ ] 已检索 `src/locales/`（或项目约定目录）中是否已有可复用文案
-- [ ] 相关语言文件已同步更新
-- [ ] 未在可国际化路径上新增用户可见硬编码（遗留静态例外见「遗留代码与迁移场景」）
-- [ ] 新代码未破坏现有语言策略（命名空间、加载方式、子应用边界）
+- [ ] 所有新增用户可见文案使用 i18n key。
+- [ ] 新增 key 已添加到所有应覆盖语言文件，且各语言分文件维护。
+- [ ] 语言资源文件为 UTF-8，打开无乱码。
+- [ ] key 命名符合模块、组件、用途约定，并复用已有语义。
+- [ ] 插值、复数、日期、数字、货币使用 i18n 格式化。
+- [ ] 迁移或混合栈中未扩大用户可见硬编码。
+- [ ] 新代码未破坏现有命名空间、加载方式和子应用边界。
 
 ## 反模式
 
-- 在模板或 JSX 中直接写中文字符串（新代码路径）
-- 使用字符串拼接代替 i18n 插值（`"共" + count + "条"` → `t('common.total', { count })`）
-- 在 JS/TS 逻辑中硬编码提示信息（新代码路径）
-- 不同模块为相同含义的文案创建不同的 key
-- 多种语言混在同一资源文件或同一顶层对象内，导致 diff、评审与按需加载困难
-- 用非 UTF-8 或错误编码保存文案文件，在 IDE / CI / 协作环境下出现乱码
-- 为迁就历史缩写或劣质命名长期保留多套并行 key，而不做治理
-- 在非契约场景下继续沿用无意义旧 key，把混乱结构复制到新模块
+- 在模板或 JSX 中直接写用户可见中文或英文字符串。
+- 使用字符串拼接代替 i18n 插值。
+- 在 JS/TS 逻辑中硬编码 toast、错误或确认文案。
+- 不同模块为相同含义创建不同 key。
+- 多语言混写导致 diff、评审和按需加载困难。
+- 用非 UTF-8 或错误编码保存文案文件。
+- 为迁就历史缩写或劣质命名长期保留多套并行 key。

package/templates/shared/rules/fec-refactoring.md

@@ -28,6 +28,10 @@
 - 图片使用原项目资源，无内联 SVG；若原项目用 iconfont/IcoMoon 则继续使用
 - 样式参考原项目效果但不照搬 CSS，优先 flex 布局，无内联样式
 - 对公共 API、路由、事件、埋点、权限、缓存和错误状态建立行为清单，重构前后逐项核对
+- 涉及页面、组件、路由、表单、弹窗、导航或关键用户流程的迁移，必须使用 Playwright 或同等真实浏览器验证方式对关键路径做对比验证
+- 对视觉敏感页面，应补充截图对比或人工截图验收；动态内容、动画、字体和环境差异需明确屏蔽、稳定化或说明
+- 对纯逻辑、类型、构建或无 UI 的迁移，不强制 Playwright，应选择更贴近风险的验证层：type-check、unit test、component test、build 或 lint
+- 验证目标不是像素级完全一致，而是确认业务功能无缺失、关键交互等价、主要视觉布局无非预期偏差，并且代码比旧实现更清晰、可维护
 
 ## 死代码清理
 

package/templates/shared/rules/fec-rendering-patterns.md

@@ -1,183 +1,40 @@
 # 渲染模式选型
 
-当项目需要选择渲染策略或评估 SSR / CSR / SSG / ISR 时，参考本文件。
+当项目需要选择或评估 CSR / SSR / SSG / ISR / RSC 时，参考本文件。本文只保留跨框架决策约束；Next.js App Router 细节交给 `fec-nextjs-project-standard`，Nuxt 细节交给 `fec-nuxt-project-standard`，性能证据交给 `fec-performance-optimization`。
 
 ## 渲染模式概览
 
-| 模式    | 全称                            | 生成时机                | 适用框架                 |
-| ------- | ------------------------------- | ----------------------- | ------------------------ |
-| **CSR** | Client-Side Rendering           | 运行时（浏览器）        | React SPA, Vue SPA, Vite |
-| **SSR** | Server-Side Rendering           | 请求时（服务端）        | Next.js, Nuxt, Remix     |
-| **SSG** | Static Site Generation          | 构建时                  | Next.js, Astro, Hugo     |
-| **ISR** | Incremental Static Regeneration | 构建时 + 运行时按需更新 | Next.js, Nuxt            |
-| **RSC** | React Server Components         | 请求时（服务端组件）    | Next.js App Router       |
+| 模式 | 生成时机 | 典型适用 |
+| ---- | -------- | -------- |
+| CSR | 浏览器运行时 | 登录后后台、内部工具、高交互 SPA |
+| SSR | 请求时服务端 | SEO 关键且内容实时的公开页 |
+| SSG | 构建时 | 文档、博客、营销页、变化慢的公开内容 |
+| ISR | 构建时 + 按需再生成 | 页面数量多、内容更新频繁但允许延迟 |
+| RSC | 服务端组件渲染 | Next.js App Router 中需要减少客户端 JS 的场景 |
 
-## 选型决策矩阵
+## 选型原则
 
-### 核心决策因素
+- SEO 必须且内容实时：优先 SSR，并明确缓存、超时和错误降级。
+- SEO 必须且内容稳定：优先 SSG；页面数量巨大或更新频繁时考虑 ISR。
+- 登录后后台、强交互工作区、内部工具：优先 CSR，公开登录/注册页可单独 SSG/SSR。
+- 混合产品：公开页与私有页可以采用不同模式，不为统一架构牺牲体验或成本。
+- 页面数量、更新频率、服务器成本、部署平台、缓存策略和团队运维能力必须一起评估。
+- RSC 只在支持的框架和路由体系中使用；客户端交互、浏览器 API 和高频状态仍放在客户端叶子组件。
 
-| 因素                  | 权重 | 推荐模式                           |
-| --------------------- | ---- | ---------------------------------- |
-| **SEO 必须**          | 高   | SSR / SSG / ISR                    |
-| **首屏速度必须 < 1s** | 高   | SSG / ISR                          |
-| **内容实时性**        | 中   | SSR（实时）/ ISR（秒级延迟可接受） |
-| **服务器成本敏感**    | 中   | SSG / CSR（无需 Node 服务）        |
-| **交互复杂度**        | 中   | CSR / RSC                          |
-| **页面数量 > 10000**  | 中   | SSR / ISR（SSG 构建时间过长）      |
-| **纯后台管理系统**    | 低   | CSR                                |
+## 实施约束
 
-### 场景推荐
-
-```
-目标场景是什么？
-├── 营销官网 / 博客 / 文档站
-│   ├── 内容更新频率低（天级）→ SSG
-│   └── 内容更新频率高（小时级）→ ISR
-│
-├── 电商 / 社交网络 / 新闻门户
-│   ├── 商品页（SEO + 可缓存）→ SSR + CDN 缓存
-│   ├── 搜索结果（实时）→ SSR
-│   └── 分类页（变化慢）→ ISR
-│
-├── SaaS Dashboard / 后台管理系统
-│   ├── 登录后页面 → CSR
-│   └── 登录/注册页（SEO）→ SSG
-│
-├── 混合场景（公开页 + 私有页）
-│   └── 混合模式：公开页 SSR/SSG，私有页 CSR
-│
-└── 内容密集型（博客 + 商品 + Dashboard）
-    └── RSC（Next.js App Router）
-```
-
-### 详细对比
-
-| 维度           | CSR                      | SSR                   | SSG                   | ISR                     |
-| -------------- | ------------------------ | --------------------- | --------------------- | ----------------------- |
-| **SEO**        | ❌ 搜索引擎看到空壳 HTML | ✅ 完整 HTML          | ✅ 完整 HTML          | ✅ 完整 HTML            |
-| **FCP**        | ⚠️ 慢（需下载执行 JS）   | ✅ 快（服务端已渲染） | ✅ 最快（纯静态文件） | ✅ 最快（同 SSG）       |
-| **TTI**        | ⚠️ 慢（hydrate 后交互）  | ⚠️ 中（hydrate 开销） | ✅ 快                 | ✅ 快                   |
-| **内容实时性** | ✅ 实时                  | ✅ 实时               | ❌ 构建时固定         | ⚠️ 可配置（秒/分钟级）  |
-| **服务器成本** | ✅ 无需 Node 服务        | ❌ 需 Node 服务       | ✅ 仅需 CDN           | ⚠️ 需 Node 服务（按需） |
-| **构建时间**   | ✅ 快                    | —                     | ⚠️ 页面多时慢         | ✅ 增量构建             |
-| **缓存友好**   | ⚠️ API 级缓存            | ⚠️ 页面级缓存         | ✅ CDN 全量缓存       | ✅ CDN + 按需失效       |
-| **复杂度**     | ✅ 低                    | ⚠️ 中                 | ✅ 低                 | ⚠️ 中                   |
-
-## 各模式实施要点
-
-### CSR（客户端渲染）
-
-适用：后台管理系统、内部工具、登录后页面。
-
-```tsx
-// 纯 SPA 入口
-import { createRoot } from "react-dom/client";
-import { App } from "./App";
-
-createRoot(document.getElementById("root")!).render(<App />);
-```
-
-**SEO 补救**：对需要 SEO 的页面使用动态 import 加载预渲染版本，或使用 Prerender SPA Plugin。
-
-### SSR（服务端渲染）
-
-适用：电商、新闻、社交等 SEO 关键场景。
-
-```tsx
-// Next.js Pages Router
-export async function getServerSideProps() {
-  const data = await fetchProductData();
-  return { props: { data } };
-}
-
-// Next.js App Router (RSC)
-async function ProductPage() {
-  const data = await fetchProductData(); // 服务端直接 await
-  return <ProductLayout data={data} />;
-}
-```
-
-**注意**：
-
-- SSR 页面必须考虑服务端兼容性（无 window/document）
-- Hydration 不匹配会导致客户端重新渲染（SSR 水合失败）
-- 服务端数据获取必须有超时和错误降级
-
-### SSG（静态站点生成）
-
-适用：博客、文档、营销落地页。
-
-```tsx
-// Next.js 构建时生成
-export async function getStaticProps() {
-  const posts = await fetchPosts();
-  return { props: { posts } };
-}
-
-export async function getStaticPaths() {
-  const posts = await fetchPosts();
-  return {
-    paths: posts.map((p) => `/blog/${p.slug}`),
-    fallback: false, // 未预渲染的 404
-  };
-}
-```
-
-### ISR（增量静态再生）
-
-适用：页面数量多、内容更新频繁但非实时。
-
-```tsx
-export async function getStaticProps() {
-  const product = await fetchProduct();
-  return {
-    props: { product },
-    revalidate: 60, // 60 秒内返回缓存版本，后台异步更新
-  };
-}
-```
-
-## React Server Components（RSC）
-
-Next.js App Router 的默认模式，服务端组件不发送 JS 到客户端：
-
-```tsx
-// 服务端组件（默认）— 可直接 await 数据库查询
-async function ProductList() {
-  const products = await db.products.findMany();
-  return (
-    <div>
-      {products.map((p) => (
-        <ProductCard key={p.id} product={p} />
-      ))}
-    </div>
-  );
-}
-
-// 客户端组件 — 需要交互/状态时显式标记
-("use client");
-
-function AddToCartButton({ productId }: { productId: string }) {
-  const [loading, setLoading] = useState(false);
-  return (
-    <button onClick={() => addToCart(productId)}>
-      {loading ? "..." : "加入购物车"}
-    </button>
-  );
-}
-```
-
-**RSC 优势**：
-
-- 服务端组件的 JS 不发送到客户端，减小 bundle
-- 直接 await 数据库/API 调用，无需 useEffect + loading 状态
-- 服务端组件可嵌套客户端组件，按需选择
+- SSR / RSC 路径不得直接依赖 `window`、`document`、localStorage 或浏览器专属库。
+- Hydration 前后的 HTML、时间、随机数、用户偏好和媒体查询结果要保持一致，避免水合不匹配。
+- 服务端数据获取必须有超时、错误降级和缓存策略。
+- SSG / ISR 需要明确未预渲染路径、revalidate / 失效策略和回滚方式。
+- 客户端大型动效库、图表、编辑器、地图、WebGL/Canvas 等应按需加载，不进入根布局同步 bundle。
+- 不在没有响应头、构建输出、trace、路由行为或线上指标证据时断言某路由“已缓存”或“必须动态”。
 
 ## 检查清单
 
-- [ ] 明确哪些页面需要 SEO（公开页 vs 私有页）
-- [ ] 明确哪些页面需要实时数据（SSR），哪些可接受延迟（ISR/SSG）
-- [ ] 评估页面数量（> 10000 时 SSG 构建时间可能不可接受）
-- [ ] 评估服务器成本（SSR 需 Node 服务，SSG 仅需 CDN）
-- [ ] 确认 Hydration 一致性（SSR 页面首屏 HTML 与客户端渲染匹配）
-- [ ] 为 SSR 页面设置合理的缓存策略（CDN 缓存 + revalidate）
+- [ ] 明确公开页与私有页、SEO 需求和实时性需求。
+- [ ] 明确每类页面使用 CSR / SSR / SSG / ISR / RSC 的理由。
+- [ ] 评估页面数量、构建时间、服务器成本和缓存失效策略。
+- [ ] 检查 SSR/RSC 代码没有浏览器 API 依赖和不可序列化 props。
+- [ ] 确认 loading、error、not-found、离线和权限状态不会因渲染模式丢失。
+- [ ] 用构建输出、响应头、trace 或路由行为验证最终模式。