@bovinphang/frontend-craft 2.5.0

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

@@ -0,0 +1,112 @@
+# 国际化 (i18n) 规则
+
+凡是涉及用户可见文案、提示信息、表单标签、错误消息或 UI 文本时，都应用本文件。
+
+<!-- 请根据项目实际 i18n 方案修改 locales 路径、库与 key 前缀 -->
+
+## 适用范围
+
+- **现代栈（纯 React / Vue 等）**：以下「核心原则」「文案规范」「实现指导」与通用检查清单优先适用。
+- **遗留 HTML/JS、渐进迁移或新旧并存**：新代码路径仍须满足核心原则；遗留层额外遵守「遗留代码与迁移场景」，避免扩大硬编码与混乱 key。
+
+下文用 **`src/locales/`** 指代项目实际文案资源目录，请按仓库约定替换（如 `public/locales`、`lang/`、`messages/` 等）。
+
+## 核心原则
+
+- 在新应用代码（组件、路由页、hooks、composables）中，用户可见文案须使用 i18n，**禁止**硬编码中文或英文字符串
+- i18n key 按模块组织，使用点分命名：`module.component.label`
+- 相同语义的文案复用同一个 key，避免重复定义
+
+## 文案规范
+
+### 命名约定
+
+```
+common.confirm        → 通用确认
+common.cancel         → 通用取消
+user.login.title      → 用户登录标题
+order.list.empty      → 订单列表空状态
+```
+
+### 分类
+
+- `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` 等声明保持一致。
+
+## 遗留代码与迁移场景
+
+在渐进式迁移、微前端或新旧代码并存时：
+
+- **遗留层**：不在 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>
+```
+
+## 检查清单
+
+### 通用
+
+- [ ] 所有新增用户可见文案使用 i18n key（新代码路径）
+- [ ] 新增 key 已添加到所有**应覆盖**的语言文件，且各语言仍分文件维护（未混写）
+- [ ] 语言资源文件为 UTF-8（无 BOM 或按仓库约定），在 IDE 中打开无乱码
+- [ ] key 命名符合模块.组件.用途 的约定
+- [ ] 包含变量的文案使用插值而非拼接
+- [ ] 复数形式使用 i18n 复数规则而非条件判断
+- [ ] 日期、数字、货币使用 i18n 格式化
+
+### 迁移或混合栈时补充
+
+- [ ] 已检索 `src/locales/`（或项目约定目录）中是否已有可复用文案
+- [ ] 相关语言文件已同步更新
+- [ ] 未在可国际化路径上新增用户可见硬编码（遗留静态例外见「遗留代码与迁移场景」）
+- [ ] 新代码未破坏现有语言策略（命名空间、加载方式、子应用边界）
+
+## 反模式
+
+- 在模板或 JSX 中直接写中文字符串（新代码路径）
+- 使用字符串拼接代替 i18n 插值（`"共" + count + "条"` → `t('common.total', { count })`）
+- 在 JS/TS 逻辑中硬编码提示信息（新代码路径）
+- 不同模块为相同含义的文案创建不同的 key
+- 多种语言混在同一资源文件或同一顶层对象内，导致 diff、评审与按需加载困难
+- 用非 UTF-8 或错误编码保存文案文件，在 IDE / CI / 协作环境下出现乱码
+- 为迁就历史缩写或劣质命名长期保留多套并行 key，而不做治理
+- 在非契约场景下继续沿用无意义旧 key，把混乱结构复制到新模块

package/templates/shared/rules/fec-naming-conventions.md

@@ -0,0 +1,120 @@
+# 命名规范
+
+## 文件与目录命名
+
+| 类型 | 命名风格 | 示例 |
+|------|----------|------|
+| 页面组件 | PascalCase + `Page` 后缀 | `UserDetailPage.tsx` / `UserDetailPage.vue` |
+| 布局组件 | PascalCase + `Layout` 后缀 | `MainLayout.tsx` / `MainLayout.vue` |
+| 通用组件 | PascalCase | `DataTable.tsx` / `AppButton.vue` |
+| Hooks / Composables | camelCase + `use` 前缀 | `useAuth.ts`、`useDebounce.ts` |
+| Store 文件 | camelCase + `Store` 后缀 | `authStore.ts`、`uiStore.ts` |
+| API 文件 | camelCase | `api.ts` 或按领域命名 `userApi.ts` |
+| 工具函数 | camelCase | `format.ts`、`validators.ts` |
+| 类型文件 | camelCase | `types.ts`、`models.ts` |
+| 常量文件 | camelCase | `constants.ts`、`config.ts` |
+| 测试文件 | 与源文件同名 + `.spec` / `.test` | `Button.spec.tsx`、`useAuth.spec.ts` |
+| 样式文件 | 组件名 + `.styles` + 扩展名 | `Button.styles.css`、`DataTable.styles.scss`；使用 styled-components 时为 `ComponentName.styles.ts` |
+| 语言包 | 语言代码（BCP 47） | `zh-CN.json`、`en-US.json` |
+| 目录名 | PascalCase（组件/页面）或 kebab-case（功能模块） | `UserDetail/`、`auth/`、`order/` |
+
+## 组件命名
+
+### React
+
+```tsx
+// 文件名与组件名一致
+// src/components/DataTable/DataTable.tsx
+export function DataTable({ data, columns }: DataTableProps) { ... }
+
+// 页面组件加 Page 后缀
+// src/pages/UserDetail/UserDetailPage.tsx
+export default function UserDetailPage() { ... }
+```
+
+### Vue
+
+```vue
+<!-- 文件名与组件名一致 -->
+<!-- src/components/AppButton/AppButton.vue -->
+<script setup lang="ts">
+// 无需 defineOptions，文件名即组件名
+</script>
+```
+
+- 多词组件名（避免与 HTML 原生标签冲突）
+- Vue 全局组件推荐使用 `App` 前缀（`AppButton`、`AppModal`）
+- 模板中使用 PascalCase 引用：`<AppButton>` 而非 `<app-button>`
+
+## 变量与函数命名
+
+| 类型 | 命名风格 | 示例 |
+|------|----------|------|
+| 普通变量 | camelCase | `userName`、`isLoading`、`pageSize` |
+| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT`、`DEFAULT_PAGE_SIZE` |
+| 布尔值 | `is` / `has` / `should` / `can` 前缀 | `isVisible`、`hasPermission`、`canEdit` |
+| 事件处理（组件内） | `handle` 前缀 | `handleClick`、`handleSubmit` |
+| 回调 Props | `on` 前缀 | `onClick`、`onSubmit`、`onChange` |
+| 数组 | 复数名词 | `users`、`orderItems`、`selectedIds` |
+| Map / Record | `xxxMap` 或 `xxxByYyy` | `userMap`、`permissionsById` |
+| Ref (Vue) | 不加 `Ref` 后缀 | `count`（不用 `countRef`） |
+| 接口 | PascalCase，不加 `I` 前缀 | `UserProfile`（不用 `IUserProfile`） |
+| Props 接口 | 组件名 + `Props` | `DataTableProps`、`UserFormProps` |
+| Emits 接口 | 组件名 + `Emits` | `UserFormEmits` |
+| 枚举 | PascalCase，成员用 PascalCase | `OrderStatus.Pending` |
+| 泛型参数 | 单字母大写或语义化 | `T`、`TData`、`TItem` |
+
+## CSS 类命名
+
+- 与项目约定保持一致（BEM / CSS Modules / Tailwind / Atomic CSS）
+- 如果使用 CSS Modules，类名用 camelCase：`.headerTitle`、`.cardBody`
+- 如果使用 BEM，遵循 `block__element--modifier` 格式
+- CSS 变量使用 kebab-case：`--color-primary`、`--spacing-md`
+
+## 路由命名
+
+| 类型 | 命名风格 | 示例 |
+|------|----------|------|
+| 路由路径 | kebab-case | `/user-detail`、`/order-list` |
+| 路由名称 | PascalCase | `UserDetail`、`OrderList` |
+| 路由参数 | camelCase | `:userId`、`:orderId` |
+| 查询参数 | camelCase | `?pageSize=10&sortBy=name` |
+| 路径常量 | UPPER_SNAKE_CASE | `ROUTE_USER_DETAIL = '/user-detail'` |
+
+## API 命名
+
+| 类型 | 命名风格 | 示例 |
+|------|----------|------|
+| GET 列表 | `getXxxList` | `getUserList(params)` |
+| GET 单条 | `getXxxDetail` / `getXxxById` | `getUserDetail(id)` |
+| POST 创建 | `createXxx` | `createOrder(data)` |
+| PUT 更新 | `updateXxx` | `updateUser(id, data)` |
+| DELETE 删除 | `deleteXxx` | `deleteOrder(id)` |
+| DTO 类型 | 动词 + 名词 + `DTO` | `CreateOrderDTO`、`UpdateUserDTO` |
+| 响应类型 | 名词 | `User`、`Order`、`PageResult<User>` |
+
+## i18n Key 命名
+
+- 使用点分命名空间：`module.section.label`
+- 示例：`user.form.username`、`common.button.submit`、`error.network.timeout`
+- 不使用中文 / 拼音作为 key
+
+## 反模式
+
+- 文件名和组件名不一致（`user-table.tsx` 导出 `DataGrid`）
+- 同一项目混用多种命名风格（有的 kebab-case 有的 PascalCase）
+- 使用缩写或不明确的名称（`btn`、`usr`、`tmp`、`handleA`）
+- 布尔值没有语义前缀（`visible` → 应为 `isVisible`）
+- 常量不用大写（`maxRetry` → 应为 `MAX_RETRY`）
+- CSS 变量硬编码在组件中而非使用统一变量
+
+## 检查清单
+
+- [ ] 文件名与导出的组件/函数名一致
+- [ ] 页面组件有 `Page` 后缀，布局组件有 `Layout` 后缀
+- [ ] 布尔变量使用 `is` / `has` / `can` / `should` 前缀
+- [ ] 事件处理用 `handle` 前缀，回调 Props 用 `on` 前缀
+- [ ] 常量使用 UPPER_SNAKE_CASE
+- [ ] 路由路径使用 kebab-case，路由名使用 PascalCase
+- [ ] API 函数命名与 HTTP 方法语义一致
+- [ ] i18n key 使用点分命名空间，无硬编码文案

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

@@ -0,0 +1,101 @@
+# 前端性能规则
+
+凡是新增页面、组件、资源加载或数据请求时，都应用本文件。
+
+## 核心原则
+
+- 默认懒加载，按需加载
+- 减少首屏关键资源
+- 避免不必要的重渲染
+- 关注 Core Web Vitals
+- 前端构建必须同时验证开发体验和生产产物，不能只看 dev server 正常
+- 在上下文或任务边界不清时，不启动大规模性能重构；先定位瓶颈再改代码
+- 对长时间运行的命令保留可回看日志，必要时使用终端会话、CI artifact 或测试报告
+- 每项性能建议都要绑定证据、影响范围、验证方式和回退风险
+
+## 代码分割与懒加载
+
+### 路由级分割
+
+```tsx
+// React
+const Dashboard = lazy(() => import('./pages/Dashboard'));
+
+// Vue
+const Dashboard = () => import('./pages/Dashboard.vue');
+```
+
+### 组件级分割
+
+仅在以下场景使用组件级懒加载：
+
+- 重型第三方库（图表、编辑器、地图）
+- 条件渲染的大型模块（如设置面板、高级筛选）
+- 不在首屏可视区域的内容
+
+## 渲染性能
+
+### React
+
+- 合理使用 `React.memo` 避免不必要的重渲染
+- `useMemo` / `useCallback` 仅在依赖稳定且子组件使用 memo 时才有意义
+- 列表渲染必须使用稳定的 `key`
+- 避免在渲染函数内创建新对象、数组或函数
+
+### Vue
+
+- 使用 `computed` 而非 `watch` + 手动赋值
+- 大列表使用虚拟滚动
+- 避免在 `v-for` 中使用 `v-if`
+- 使用 `shallowRef` / `shallowReactive` 优化大型对象
+
+## 资源优化
+
+- 图片使用 WebP/AVIF 格式，提供适当尺寸
+- 图标优先使用 SVG sprite 或 icon font，避免大量独立图片请求
+- 字体按需加载，使用 `font-display: swap`
+- 第三方依赖按需导入（如 `import { Button } from 'antd'` 而非 `import antd from 'antd'`）
+
+## Vite 构建与开发性能
+
+使用 Vite 时额外遵守：
+
+- `vite build` 不做类型检查，CI 必须单独执行 `tsc --noEmit` 或接入 `vite-plugin-checker`
+- 慢启动先用 `vite --profile` 定位插件、解析或预构建瓶颈
+- 大项目可使用 `server.warmup.clientFiles` 预热核心入口
+- CJS/UMD 依赖互操作问题优先通过 `optimizeDeps.include` 处理
+- 手动分包优先使用稳定对象形式，不要把每个 `node_modules` 包拆成独立 chunk
+- 组件库模式必须 externalize peer dependencies，并单独产出类型声明
+- `vite preview` 只用于本地构建烟测，不是生产服务器
+
+## 数据请求
+
+- 避免瀑布式请求（串行依赖），尽可能并行
+- 合理使用缓存策略（SWR / React Query / VueQuery）
+- 分页加载或虚拟滚动处理大数据集
+- 防抖/节流处理高频触发的请求（搜索、滚动）
+
+## 检查清单
+
+- [ ] 是否记录核心路由、设备、网络和当前指标
+- [ ] 路由是否按需加载
+- [ ] 重型组件是否懒加载
+- [ ] 大列表是否使用虚拟滚动或分页
+- [ ] 图片是否使用现代格式和合理尺寸
+- [ ] 第三方库是否按需导入
+- [ ] 是否存在不必要的重渲染
+- [ ] Vite 项目是否单独执行 typecheck
+- [ ] Vite 构建产物是否经过 `vite build` 和本地预览烟测
+- [ ] 是否复查 loading、error、empty、disabled 和移动端状态没有被优化破坏
+
+## 反模式
+
+- 将所有路由打包在一个 chunk 中
+- 在首屏加载整个图表库或编辑器
+- 在组件内重复创建相同的 API 请求
+- 大列表不做虚拟化直接渲染数千行 DOM
+- 频繁操作（如输入、滚动）不做防抖/节流
+- 认为 `vite build` 通过就代表 TypeScript 没有错误
+- 设置 `envPrefix: ""` 或把服务端密钥注入客户端 bundle
+- 未先复现卡顿、包体积或 Web Vitals 指标，就做大范围“性能优化”
+- 为追求实验室分数删除状态反馈、降低可访问性或牺牲主路径可维护性

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

@@ -0,0 +1,82 @@
+# React 规则
+
+当仓库或目标模块使用 React 时，应用本文件。
+
+## 技术栈
+
+<!-- 请根据项目实际情况修改 -->
+
+- 框架: React + TypeScript
+- 样式: Tailwind CSS + CSS Modules
+- 状态管理: Zustand / Redux Toolkit / Jotai（按项目实际选择）
+- UI 组件库: 按项目实际选择（如 Ant Design、Material UI 或内部 Design System）
+- 版本与依赖：新建模块、补充 `package.json` 或更新本节前，优先采用彼此兼容的主流稳定版本（对齐官方文档、脚手架默认值或包管理器推荐），避免混用已停止维护或与仓库主线 major 不匹配的依赖。
+
+## React 组件规范
+
+- 使用**函数组件**、Hooks 与 TypeScript；**不要**新增类组件（含手写 Error Boundary，统一用 `react-error-boundary` 等库）
+- 保持组件小而可组合
+- 将可复用逻辑提取到 hooks
+- props 保持明确且类型清晰
+- 保持可访问性与键盘交互
+- 优先使用可推导状态，避免重复维护 state
+- 在创建新基础组件前，先复用现有设计系统
+- 禁止使用 any，优先使用 unknown
+- CSS 命名遵循 BEM（CSS Modules 场景）
+
+## 模式与最佳实践（React）
+
+- **组合**：用小组件 + `children`/props 拼装；避免宽布尔 props 与假「继承」。
+- **复合组件**：根组件用 Context 向子组件暴露状态；子组件在缺少 Context 时明确报错。
+- **Render Props**：仅在需要封装数据态并把渲染交给上层时考虑；多数场景优先自定义 Hook + 普通组件。
+- **Context + useReducer**：中等复杂度的多子树客户端状态；勿把高频变化大对象放在顶层 Context；服务端数据用 React Query / SWR。
+- **表单**：中大型表单优先 React Hook Form + Zod；避免单文件巨型受控 state。
+- **Error Boundary**：关键模块用 **`react-error-boundary`**（或团队统一的同类库）在模块边界兜底；业务组件一律函数式，不手写类组件 Error Boundary。
+- **性能**：`useMemo`/`useCallback`/`React.memo` 按需使用；长列表用虚拟列表（如 TanStack Virtual、react-window）；昂贵计算注意不可变派生（勿原地 `sort` 原数组）。
+- **动效**：Framer Motion 或 CSS transition；尊重 `prefers-reduced-motion`。
+- **无障碍**：复合控件补齐 `role`/`aria-*` 与键盘操作；弹窗管理焦点落入与关闭后恢复。
+- **Next.js**：App Router 与 Server Components 相关约定以项目 Next 规则为准。
+
+## React 实现指导
+
+创建新组件前：
+
+1. 先搜索是否已存在等价组件
+2. 判断逻辑是否应该放入自定义 hook
+3. 与项目当前样式方案保持一致
+
+编辑 React 组件时：
+
+- 避免在同一个文件里混合数据请求、重业务逻辑和展示逻辑
+- 避免设计过宽或语义不清的 props API
+- 对局部问题避免滥用 context
+- 保持条件渲染可读，必要时提取重复分支
+
+## React 文件组织
+
+优先遵循仓库已有约定。
+常见输出可能包括：
+
+- `Component.tsx`
+- `Component.types.ts`
+- `hooks/useComponentLogic.ts`
+- `ComponentName.styles.css`（普通 CSS / CSS Modules；使用 styled-components 时为 `ComponentName.styles.ts`）
+- 如果仓库采用就近测试，则补充测试文件，如：`__tests__/Component.spec.tsx`
+
+## 组件文件规模
+
+- 单个组件文件保持**职责单一**、语义清晰、易于维护。
+- **行数参考**：优先将单文件控制在约 **300 行**以内；超过 **500 行**应视为**强烈拆分信号**。
+- **未到 500 行也应拆分**的情形：同时存在**复杂状态交织**、**过多副作用**、**JSX 嵌套过深**、**密集条件分支**、数据获取与 UI 长期混在同一文件等，使单文件难以一眼把握时，应拆为**子组件**、**自定义 Hooks**、**工具函数**、**常量**与**类型定义**等独立单元（目录与命名仍遵循上文「React 文件组织」）。
+
+## React 反模式
+
+避免：
+
+- 新建**类组件**或手写类式 Error Boundary（应使用函数组件 + `react-error-boundary` 等）
+- 对可推导值使用多余 state
+- 大段 JSX 不拆成子组件
+- 单文件堆叠过多职责与行数，**逾 500 行或复杂度已高**仍拒不拆分（参见上文「组件文件规模」）
+- 使用不稳定 key
+- 在 props 和 hooks 中无理由使用 `any`
+- 没有充分理由时引入第二套样式体系

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

@@ -0,0 +1,43 @@
+# 重构项目规则
+
+当任务涉及从现有项目重构、迁移或重写前端代码时，应用本文件。
+
+## 目标
+
+- **视觉和交互**：与原项目一致，用户无感知差异
+- **代码质量**：更简洁、易维护，符合目标框架规范
+- **业务功能**：与原项目保持一致，**不得缺失功能**；重构前后行为等价
+
+## 图片与图标
+
+- 直接使用原项目的图片资源路径，不重新托管或替换
+- 可使用 SVG 图片（`<img src="*.svg" />` 或 CSS `background-image`），**禁止使用内联 SVG**（`<svg>...</svg>` 直接写在组件中）
+- **若原项目使用了 iconfont 或 IcoMoon 图标，重构时继续使用**，保持图标体系一致；不替换为其他图标方案
+- 图标优先使用原项目已有的图标文件（iconfont / IcoMoon / 已有 SVG），必要时可引入 SVG 文件作为独立资源
+
+## 样式
+
+- 布局样式对齐原项目视觉效果，但**只参考原项目效果，不照搬其 CSS**
+- 优先使用 **flex 弹性布局**，避免 `float`、复杂 `position`、冗余嵌套
+- 避免不合理写法：`!important` 滥用、过深选择器、重复定义
+- **组件中禁止使用内联样式**（`style={{ ... }}` / `style="..."`），样式统一放在 CSS Modules、Tailwind 类或样式文件中，便于维护
+
+## 强约束
+
+- 业务功能与原项目完整等价，不得缺失
+- 图片使用原项目资源，无内联 SVG；若原项目用 iconfont/IcoMoon 则继续使用
+- 样式参考原项目效果但不照搬 CSS，优先 flex 布局，无内联样式
+- 对公共 API、路由、事件、埋点、权限、缓存和错误状态建立行为清单，重构前后逐项核对
+
+## 死代码清理
+
+清理未使用代码、导出、样式或依赖时：
+
+- 先建立验证基线，再做清理。
+- 使用工具或搜索证据证明候选项无引用。
+- 将候选项分为 SAFE、CAUTION、DANGER。
+- 仅自动清理 SAFE 项；路由、配置、运行时模板、动态 import 和公开 API 默认视为高风险。
+- 每批清理后运行受影响验证命令。
+- 若验证失败，先回到最近一批候选项定位，不继续扩大清理范围。
+
+不要把死代码清理与功能重写、视觉调整或依赖升级混在同一个改动里。

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

@@ -0,0 +1,183 @@
+# 渲染模式选型
+
+当项目需要选择渲染策略或评估 SSR / CSR / SSG / ISR 时，参考本文件。
+
+## 渲染模式概览
+
+| 模式    | 全称                            | 生成时机                | 适用框架                 |
+| ------- | ------------------------------- | ----------------------- | ------------------------ |
+| **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       |
+
+## 选型决策矩阵
+
+### 核心决策因素
+
+| 因素                  | 权重 | 推荐模式                           |
+| --------------------- | ---- | ---------------------------------- |
+| **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 状态
+- 服务端组件可嵌套客户端组件，按需选择
+
+## 检查清单
+
+- [ ] 明确哪些页面需要 SEO（公开页 vs 私有页）
+- [ ] 明确哪些页面需要实时数据（SSR），哪些可接受延迟（ISR/SSG）
+- [ ] 评估页面数量（> 10000 时 SSG 构建时间可能不可接受）
+- [ ] 评估服务器成本（SSR 需 Node 服务，SSG 仅需 CDN）
+- [ ] 确认 Hydration 一致性（SSR 页面首屏 HTML 与客户端渲染匹配）
+- [ ] 为 SSR 页面设置合理的缓存策略（CDN 缓存 + revalidate）