@bovinphang/frontend-craft 2.6.0 → 2.8.0

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

@@ -1,21 +1,21 @@
-# 前端性能规则
+# Front-end performance rules
 
-凡是新增页面、组件、资源加载或数据请求时，都应用本文件。
+This document will be used whenever new pages, components, resource loading or data requests are added.
 
-## 核心原则
+## Core Principles
 
-- 默认懒加载，按需加载
-- 减少首屏关键资源
-- 避免不必要的重渲染
-- 关注 Core Web Vitals
-- 前端构建必须同时验证开发体验和生产产物，不能只看 dev server 正常
-- 在上下文或任务边界不清时，不启动大规模性能重构；先定位瓶颈再改代码
-- 对长时间运行的命令保留可回看日志，必要时使用终端会话、CI artifact 或测试报告
-- 每项性能建议都要绑定证据、影响范围、验证方式和回退风险
+- Lazy loading by default, loading on demand
+- Reduce key resources on the first screen
+- Avoid unnecessary re-rendering
+- Follow Core Web Vitals
+- The front-end build must verify the development experience and production products at the same time. You cannot just check whether the dev server is normal.
+- Do not initiate large-scale performance refactoring when the context or task boundaries are unclear; locate bottlenecks first and then change the code
+- Keep reviewable logs of long-running commands, using terminal sessions, CI artifacts, or test reports when necessary
+- Each performance recommendation must be bound with evidence, scope of impact, verification methods and rollback risks
 
-## 代码分割与懒加载
+## Code splitting and lazy loading
 
-### 路由级分割
+### Routing level segmentation
 
 ```tsx
 // React
@@ -25,77 +25,77 @@ const Dashboard = lazy(() => import('./pages/Dashboard'));
 const Dashboard = () => import('./pages/Dashboard.vue');
 ```
 
-### 组件级分割
+### Component level segmentation
 
-仅在以下场景使用组件级懒加载：
+Only use component-level lazy loading in the following scenarios:
 
-- 重型第三方库（图表、编辑器、地图）
-- 条件渲染的大型模块（如设置面板、高级筛选）
-- 不在首屏可视区域的内容
+- Heavy-duty third-party libraries (charts, editors, maps)
+- Large modules for conditional rendering (such as settings panel, advanced filtering)
+- Content that is not in the visible area of the first screen
 
-## 渲染性能
+## Rendering performance
 
 ### React
 
-- 合理使用 `React.memo` 避免不必要的重渲染
-- `useMemo` / `useCallback` 仅在依赖稳定且子组件使用 memo 时才有意义
-- 列表渲染必须使用稳定的 `key`
-- 避免在渲染函数内创建新对象、数组或函数
+- Use `React.memo` wisely to avoid unnecessary re-rendering
+- `useMemo` / `useCallback` only makes sense if the dependency is stable and the subcomponent uses memo
+- List rendering must use a stable `key`
+- Avoid creating new objects, arrays or functions inside render functions
 
 ### 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 指标，就做大范围“性能优化”
-- 为追求实验室分数删除状态反馈、降低可访问性或牺牲主路径可维护性
+- Use `computed` instead of `watch` + manual assignment
+- Use virtual scrolling for large lists
+- Avoid using `v-if` inside `v-for`
+- Use `shallowRef` / `shallowReactive` to optimize large objects
+
+## Resource optimization
+
+- Images use WebP/AVIF format and provide appropriate sizes
+- For icons, use SVG sprite or icon font first to avoid a large number of independent image requests
+- Fonts are loaded on demand, use `font-display: swap`
+- Third-party dependencies are imported on demand (such as `import { Button } from 'antd'` instead of `import antd from 'antd'`)
+
+## Vite build and development performance
+
+Additional compliance when using Vite:
+
+- `vite build` does not do type checking, CI must execute `tsc --noEmit` separately or access `vite-plugin-checker`
+- Use `vite --profile` to locate plug-in, parsing or pre-built bottlenecks before slow start
+- Large projects can use `server.warmup.clientFiles` to warm up the core entrance
+- CJS/UMD dependency interoperability issues are first handled through `optimizeDeps.include`
+- For manual sub-packaging, use stable object form first, do not split each `node_modules` package into independent chunks
+- Component library mode must externalize peer dependencies and produce type declarations separately
+- `vite preview` is only used for local build smoke tests, not production servers
+
+## Data request
+
+- Avoid waterfall requests (serial dependencies), parallelize as much as possible
+- Proper use of caching strategies (SWR/React Query/VueQuery)
+- Paged loading or virtual scrolling for processing large data sets
+- Anti-shake/throttle processing of high-frequency triggered requests (search, scrolling)
+
+## Checklist
+
+- [ ] Whether to record core routing, device, network and current metrics
+- [ ] Whether the route is loaded on demand
+- [ ] Whether heavy components are lazy loaded
+- [ ] Whether to use virtual scrolling or paging for large lists
+- [ ] Whether the image uses a modern format and reasonable size
+- [ ] Whether third-party libraries are imported on demand
+- [ ] Whether there is unnecessary re-rendering
+- [ ] Whether the Vite project executes typecheck separately
+- [ ] Whether the Vite build product has passed the `vite build` and local preview smoke tests
+- [ ] Whether to review loading, error, empty, disabled and mobile status are not destroyed by optimization
+
+## Anti-pattern
+
+- Pack all routes in one chunk
+- Load the entire chart library or editor on the first screen
+- Create the same API request repeatedly within the component
+- Large lists directly render thousands of lines of DOM without virtualization
+- No anti-shake/throttling for frequent operations (such as input, scrolling)
+- It is considered that passing `vite build` means that TypeScript has no errors
+- Set `envPrefix: ""` or inject the server key into the client bundle
+- Doing extensive “performance optimization” without first reproducing lag, packet size or Web Vitals indicators
+- Remove status feedback, reduce accessibility, or sacrifice main path maintainability in pursuit of lab scores

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

@@ -1,82 +1,82 @@
-# React 规则
+# React rules
 
-当仓库或目标模块使用 React 时，应用本文件。
+This file applies when the repository or target module uses React.
 
-## 技术栈
+## Technology stack
 
-<!-- 请根据项目实际情况修改 -->
+<!-- Please modify according to the actual situation of the project -->
 
-- 框架: React + TypeScript
-- 样式: Tailwind CSS + CSS Modules
-- 状态管理: Zustand / Redux Toolkit / Jotai（按项目实际选择）
-- UI 组件库: 按项目实际选择（如 Ant Design、Material UI 或内部 Design System）
-- 版本与依赖：新建模块、补充 `package.json` 或更新本节前，优先采用彼此兼容的主流稳定版本（对齐官方文档、脚手架默认值或包管理器推荐），避免混用已停止维护或与仓库主线 major 不匹配的依赖。
+- Framework: React + TypeScript
+- Style: Tailwind CSS + CSS Modules
+- Status management: Zustand / Redux Toolkit / Jotai (select according to the actual project)
+- UI component library: actual selection by project (such as Ant Design, Material UI or internal Design System)
+- Versions and dependencies: Before creating a new module, supplementing `package.json` or updating this section, give priority to using mainstream stable versions that are compatible with each other (align with official documents, scaffolding defaults or package manager recommendations) to avoid mixing dependencies that have stopped maintaining or do not match the major of the mainline of the warehouse.
 
-## React 组件规范
+## React component specification
 
-- 使用**函数组件**、Hooks 与 TypeScript；**不要**新增类组件（含手写 Error Boundary，统一用 `react-error-boundary` 等库）
-- 保持组件小而可组合
-- 将可复用逻辑提取到 hooks
-- props 保持明确且类型清晰
-- 保持可访问性与键盘交互
-- 优先使用可推导状态，避免重复维护 state
-- 在创建新基础组件前，先复用现有设计系统
-- 禁止使用 any，优先使用 unknown
-- CSS 命名遵循 BEM（CSS Modules 场景）
+- Use **Function Components**, Hooks and TypeScript; **Do not** add new class components (including handwritten Error Boundary, use `react-error-boundary` and other libraries)
+- Keep components small and composable
+- Extract reusable logic into hooks
+- Keep props explicit and clearly typed
+- Maintain accessibility with keyboard interaction
+- Prioritize the use of deducible state to avoid repeated state maintenance
+- Reuse existing design systems before creating new base components
+- It is forbidden to use any, prefer unknown
+- CSS naming follows BEM (CSS Modules scenario)
 
-## 模式与最佳实践（React）
+## Patterns and Best Practices (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 规则为准。
+- **Composition**: Use widgets + `children`/props to assemble; avoid wide boolean props and fake "inheritance".
+- **Composite component**: The root component uses Context to expose state to sub-components; sub-components explicitly report an error when Context is missing.
+- **Render Props**: Only considered when it is necessary to encapsulate the data state and hand over the rendering to the upper layer; in most scenarios, custom Hook + ordinary components are given priority.
+- **Context + useReducer**: Medium complexity multi-subtree client state; do not put high-frequency changing large objects in the top-level Context; use React Query / SWR for server-side data.
+- **Form**: Prioritize medium and large forms with React Hook Form + Zod; avoid single-file giant controlled state.
+- **Error Boundary**: Key modules use **`react-error-boundary`** (or a similar library unified by the team) to cover the module boundaries; business components must be functional, and no handwritten class components Error Boundary.
+- **Performance**: Use `useMemo`/`useCallback`/`React.memo` on demand; use virtual lists for long lists (such as TanStack Virtual, react-window); pay attention to immutable derivation for expensive calculations (do not `sort` the original array in place).
+- **Motion**: Framer Motion or CSS transition; respect `prefers-reduced-motion`.
+- **Accessibility**: Compound controls complement `role`/`aria-*` and keyboard operations; pop-up window management focus is dropped and restored after closing.
+- **Next.js**: The relevant agreements between App Router and Server Components are subject to the project Next rules.
 
-## React 实现指导
+## React Implementation Guide
 
-创建新组件前：
+Before creating a new component:
 
-1. 先搜索是否已存在等价组件
-2. 判断逻辑是否应该放入自定义 hook
-3. 与项目当前样式方案保持一致
+1. First search whether equivalent components already exist
+2. Determine whether the logic should be put into a custom hook
+3. Be consistent with the current style scheme of the project
 
-编辑 React 组件时：
+When editing a React component:
 
-- 避免在同一个文件里混合数据请求、重业务逻辑和展示逻辑
-- 避免设计过宽或语义不清的 props API
-- 对局部问题避免滥用 context
-- 保持条件渲染可读，必要时提取重复分支
+- Avoid mixing data requests, heavy business logic and presentation logic in the same file
+- Avoid designing props APIs that are too broad or have unclear semantics
+- Avoid abusing context for local problems
+- Keep conditional rendering readable and extract duplicate branches if necessary
 
-## React 文件组织
+## React file organization
 
-优先遵循仓库已有约定。
-常见输出可能包括：
+Priority is given to following existing agreements in the warehouse.
+Common output may include:
 
 - `Component.tsx`
 - `Component.types.ts`
 - `hooks/useComponentLogic.ts`
-- `ComponentName.styles.css`（普通 CSS / CSS Modules；使用 styled-components 时为 `ComponentName.styles.ts`）
-- 如果仓库采用就近测试，则补充测试文件，如：`__tests__/Component.spec.tsx`
+- `ComponentName.styles.css` (plain CSS / CSS Modules; `ComponentName.styles.ts` when using styled-components)
+- If the warehouse uses nearby testing, add test files, such as: `__tests__/Component.spec.tsx`
 
-## 组件文件规模
+## Component file size
 
-- 单个组件文件保持**职责单一**、语义清晰、易于维护。
-- **行数参考**：优先将单文件控制在约 **300 行**以内；超过 **500 行**应视为**强烈拆分信号**。
-- **未到 500 行也应拆分**的情形：同时存在**复杂状态交织**、**过多副作用**、**JSX 嵌套过深**、**密集条件分支**、数据获取与 UI 长期混在同一文件等，使单文件难以一眼把握时，应拆为**子组件**、**自定义 Hooks**、**工具函数**、**常量**与**类型定义**等独立单元（目录与命名仍遵循上文「React 文件组织」）。
+- A single component file maintains a single responsibility, clear semantics, and is easy to maintain.
+- **Line number reference**: Prioritize the single file to be controlled within about **300 lines**; more than **500 lines** should be regarded as a **strong splitting signal**.
+- **Situations that should be split even if it is less than 500 lines**: There are **complex state interleaving**, **too many side effects**, **JSX too deep nesting**, **dense conditional branches**, data acquisition and UI are mixed in the same file for a long time, etc., making it difficult to grasp a single file at a glance. It should be split into independent units such as **subcomponents**, **custom Hooks**, **tool functions**, **constants** and **type definitions** (the directory and naming still follow the "React file organization" above).
 
-## React 反模式
+## React anti-patterns
 
-避免：
+Avoid:
 
-- 新建**类组件**或手写类式 Error Boundary（应使用函数组件 + `react-error-boundary` 等）
-- 对可推导值使用多余 state
-- 大段 JSX 不拆成子组件
-- 单文件堆叠过多职责与行数，**逾 500 行或复杂度已高**仍拒不拆分（参见上文「组件文件规模」）
-- 使用不稳定 key
-- 在 props 和 hooks 中无理由使用 `any`
-- 没有充分理由时引入第二套样式体系
+- Create a new **class component** or handwritten class Error Boundary (function component + `react-error-boundary`, etc. should be used)
+- Use redundant state for derivable values
+- Large sections of JSX are not broken into subcomponents
+- A single file is stacked with too many responsibilities and lines. It exceeds 500 lines or has high complexity and still refuses to be split (see "Component file size" above)
+- Use unstable keys
+- Use `any` in props and hooks without reason
+- Introduce a second style system when there is no good reason

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

@@ -1,43 +1,47 @@
-# 重构项目规则
+# Refactor project rules
 
-当任务涉及从现有项目重构、迁移或重写前端代码时，应用本文件。
+This document applies when the task involves refactoring, migrating, or rewriting front-end code from an existing project.
 
-## 目标
+## Target
 
-- **视觉和交互**：与原项目一致，用户无感知差异
-- **代码质量**：更简洁、易维护，符合目标框架规范
-- **业务功能**：与原项目保持一致，**不得缺失功能**；重构前后行为等价
+- **Visual and interactive**: consistent with the original project, no perceived difference by users
+- **Code Quality**: more concise, easier to maintain, and in line with the target framework specifications
+- **Business functions**: consistent with the original project, **no missing functions**; behaviors before and after reconstruction are equivalent
 
-## 图片与图标
+## Pictures and Icons
 
-- 直接使用原项目的图片资源路径，不重新托管或替换
-- 可使用 SVG 图片（`<img src="*.svg" />` 或 CSS `background-image`），**禁止使用内联 SVG**（`<svg>...</svg>` 直接写在组件中）
-- **若原项目使用了 iconfont 或 IcoMoon 图标，重构时继续使用**，保持图标体系一致；不替换为其他图标方案
-- 图标优先使用原项目已有的图标文件（iconfont / IcoMoon / 已有 SVG），必要时可引入 SVG 文件作为独立资源
+- Directly use the image resource path of the original project without rehosting or replacing it.
+- SVG images (`<img src="*.svg" />` or CSS `background-image`) can be used, **inline SVG is prohibited** (`<svg>...</svg>` written directly in the component)
+- **If the original project uses iconfont or IcoMoon icons, continue to use them** during reconstruction to keep the icon system consistent; do not replace it with other icon schemes
+- For icons, priority is given to using existing icon files in the original project (iconfont / IcoMoon / existing SVG). If necessary, SVG files can be introduced as independent resources
 
-## 样式
+## Style
 
-- 布局样式对齐原项目视觉效果，但**只参考原项目效果，不照搬其 CSS**
-- 优先使用 **flex 弹性布局**，避免 `float`、复杂 `position`、冗余嵌套
-- 避免不合理写法：`!important` 滥用、过深选择器、重复定义
-- **组件中禁止使用内联样式**（`style={{ ... }}` / `style="..."`），样式统一放在 CSS Modules、Tailwind 类或样式文件中，便于维护
+- The layout style aligns with the visual effects of the original project, but **only refers to the original project effects and does not copy its CSS**
+- Prioritize the use of **flex elastic layout** to avoid `float`, complex `position`, and redundant nesting
+- Avoid unreasonable writing methods: `!important` abuse, excessively deep selectors, and repeated definitions
+- **Inline styles are prohibited in components** (`style={{ ... }}` / `style="..."`). Styles are unified in CSS Modules, Tailwind classes or style files for easy maintenance.
 
-## 强约束
+##Strong constraints
 
-- 业务功能与原项目完整等价，不得缺失
-- 图片使用原项目资源，无内联 SVG；若原项目用 iconfont/IcoMoon 则继续使用
-- 样式参考原项目效果但不照搬 CSS，优先 flex 布局，无内联样式
-- 对公共 API、路由、事件、埋点、权限、缓存和错误状态建立行为清单，重构前后逐项核对
+- The business functions are completely equivalent to the original project and must not be missing.
+- Images use original project resources, no inline SVG; if the original project uses iconfont/IcoMoon, continue to use it
+- The style refers to the original project effect but does not copy CSS, giving priority to flex layout, no inline style
+- Establish a behavior list for public APIs, routing, events, hidden points, permissions, caches and error status, and check them one by one before and after reconstruction
+- For migrations involving pages, components, routes, forms, pop-ups, navigation or key user processes, Playwright or equivalent real browser verification methods must be used to compare and verify the critical paths.
+- For visually sensitive pages, screenshot comparison or manual screenshot acceptance should be supplemented; dynamic content, animation, fonts and environmental differences need to be clearly blocked, stabilized or explained
+- For pure logic, type, build or no UI migrations, Playwright is not mandatory and a validation layer closer to the risk should be chosen: type-check, unit test, component test, build or lint
+- The verification goal is not to be completely consistent at the pixel level, but to confirm that there are no missing business functions, key interactions are equivalent, there are no unexpected deviations in the main visual layout, and the code is clearer and maintainable than the old implementation.
 
-## 死代码清理
+## Dead code cleanup
 
-清理未使用代码、导出、样式或依赖时：
+When cleaning unused code, exports, styles or dependencies:
 
-- 先建立验证基线，再做清理。
-- 使用工具或搜索证据证明候选项无引用。
-- 将候选项分为 SAFE、CAUTION、DANGER。
-- 仅自动清理 SAFE 项；路由、配置、运行时模板、动态 import 和公开 API 默认视为高风险。
-- 每批清理后运行受影响验证命令。
-- 若验证失败，先回到最近一批候选项定位，不继续扩大清理范围。
+- Establish a verification baseline first, then clean it up.
+- Use tools or search for evidence that candidates have no citations.
+- Classify candidates into SAFE, CAUTION, and DANGER.
+- Only SAFE items are automatically sanitized; routing, configuration, runtime templates, dynamic imports, and public APIs are considered high risk by default.
+- Run affected verification command after each batch cleanup.
+- If the verification fails, return to the most recent batch of candidates and do not continue to expand the scope of cleaning.
 
-不要把死代码清理与功能重写、视觉调整或依赖升级混在同一个改动里。
+Don’t mix dead code cleanup with feature rewrites, visual tweaks, or dependency upgrades in the same change.

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

@@ -1,183 +1,40 @@
-# 渲染模式选型
-
-当项目需要选择渲染策略或评估 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）
+#Rendering mode selection
+
+Reference this document when a project needs to select or evaluate CSR/SSR/SSG/ISR/RSC. This article only retains cross-framework decision constraints; Next.js App Router details are left to `fec-nextjs-project-standard`, Nuxt details are left to `fec-nuxt-project-standard`, and performance evidence is left to `fec-performance-optimization`.
+
+## Rendering mode overview
+
+| Mode | Generation timing | Typical application |
+| ---- | -------- | -------- |
+| CSR | Browser runtime | Post-login backend, internal tools, high-interaction SPA |
+| SSR | Server-side on request | SEO-critical and real-time content public page |
+| SSG | Build-time | Documentation, blogs, marketing pages, slow-changing public content |
+| ISR | Build time + regenerate on demand | Large number of pages, frequent content updates but allow for delays |
+| RSC | Server-side component rendering | Scenarios where client-side JS needs to be reduced in Next.js App Router |
+
+## Selection principles
+
+- SEO is a must and content is live: Prioritize SSR and be clear about caching, timeouts and error degradation.
+- SEO is required and the content is stable: Prioritize SSG; consider ISR when the number of pages is huge or updates are frequent.
+- Backend after login, strong interaction workspace, internal tools: priority CSR, public login/registration page can be separate SSG/SSR.
+- Hybrid product: Public pages and private pages can adopt different models without sacrificing experience or cost for a unified architecture.
+- Number of pages, update frequency, server cost, deployment platform, caching strategy and team operation and maintenance capabilities must be evaluated together.
+- RSC is only used in supported frameworks and routing architectures; client interactions, browser APIs, and high-frequency states are still placed in client leaf components.
+
+## Implement constraints
+
+- SSR/RSC paths must not directly depend on `window`, `document`, localStorage or browser-specific libraries.
+- HTML, time, random numbers, user preferences and media query results before and after hydration should be consistent to avoid hydration mismatch.
+- Server-side data retrieval must have timeout, error degradation and caching strategies.
+- SSG/ISR needs to clarify the non-prerendered path, revalidate/invalidation strategy and rollback method.
+- Client-side large animation libraries, charts, editors, maps, WebGL/Canvas, etc. should be loaded on demand without entering the root layout synchronization bundle.
+- No longer assert that a route is "cached" or "must be dynamic" without evidence of response headers, build output, traces, route behavior, or online metrics.
+
+## Checklist
+
+- [ ] Clarify public pages and private pages, SEO requirements and real-time requirements.
+- [ ] Clarify the reasons for using CSR / SSR / SSG / ISR / RSC for each type of page.
+- [ ] Evaluate page count, build times, server costs, and cache invalidation strategies.
+- [ ] Check that SSR/RSC code has no browser API dependencies and non-serializable props.
+- [ ] Confirm that loading, error, not-found, offline and permission states are not lost across render modes.
+- [ ] Verify the final schema with build output, response headers, traces, or routing behavior.