@bovinphang/frontend-craft 2.7.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,47 +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、路由、事件、埋点、权限、缓存和错误状态建立行为清单，重构前后逐项核对
-- 涉及页面、组件、路由、表单、弹窗、导航或关键用户流程的迁移，必须使用 Playwright 或同等真实浏览器验证方式对关键路径做对比验证
-- 对视觉敏感页面，应补充截图对比或人工截图验收；动态内容、动画、字体和环境差异需明确屏蔽、稳定化或说明
-- 对纯逻辑、类型、构建或无 UI 的迁移，不强制 Playwright，应选择更贴近风险的验证层：type-check、unit test、component test、build 或 lint
-- 验证目标不是像素级完全一致，而是确认业务功能无缺失、关键交互等价、主要视觉布局无非预期偏差，并且代码比旧实现更清晰、可维护
+- 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,40 +1,40 @@
-# 渲染模式选型
+#Rendering mode selection
 
-当项目需要选择或评估 CSR / SSR / SSG / ISR / RSC 时，参考本文件。本文只保留跨框架决策约束；Next.js App Router 细节交给 `fec-nextjs-project-standard`，Nuxt 细节交给 `fec-nuxt-project-standard`，性能证据交给 `fec-performance-optimization`。
+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 | 浏览器运行时 | 登录后后台、内部工具、高交互 SPA |
-| SSR | 请求时服务端 | SEO 关键且内容实时的公开页 |
-| SSG | 构建时 | 文档、博客、营销页、变化慢的公开内容 |
-| ISR | 构建时 + 按需再生成 | 页面数量多、内容更新频繁但允许延迟 |
-| RSC | 服务端组件渲染 | Next.js App Router 中需要减少客户端 JS 的场景 |
-
-## 选型原则
-
-- SEO 必须且内容实时：优先 SSR，并明确缓存、超时和错误降级。
-- SEO 必须且内容稳定：优先 SSG；页面数量巨大或更新频繁时考虑 ISR。
-- 登录后后台、强交互工作区、内部工具：优先 CSR，公开登录/注册页可单独 SSG/SSR。
-- 混合产品：公开页与私有页可以采用不同模式，不为统一架构牺牲体验或成本。
-- 页面数量、更新频率、服务器成本、部署平台、缓存策略和团队运维能力必须一起评估。
-- RSC 只在支持的框架和路由体系中使用；客户端交互、浏览器 API 和高频状态仍放在客户端叶子组件。
-
-## 实施约束
-
-- SSR / RSC 路径不得直接依赖 `window`、`document`、localStorage 或浏览器专属库。
-- Hydration 前后的 HTML、时间、随机数、用户偏好和媒体查询结果要保持一致，避免水合不匹配。
-- 服务端数据获取必须有超时、错误降级和缓存策略。
-- SSG / ISR 需要明确未预渲染路径、revalidate / 失效策略和回滚方式。
-- 客户端大型动效库、图表、编辑器、地图、WebGL/Canvas 等应按需加载，不进入根布局同步 bundle。
-- 不在没有响应头、构建输出、trace、路由行为或线上指标证据时断言某路由“已缓存”或“必须动态”。
-
-## 检查清单
-
-- [ ] 明确公开页与私有页、SEO 需求和实时性需求。
-- [ ] 明确每类页面使用 CSR / SSR / SSG / ISR / RSC 的理由。
-- [ ] 评估页面数量、构建时间、服务器成本和缓存失效策略。
-- [ ] 检查 SSR/RSC 代码没有浏览器 API 依赖和不可序列化 props。
-- [ ] 确认 loading、error、not-found、离线和权限状态不会因渲染模式丢失。
-- [ ] 用构建输出、响应头、trace 或路由行为验证最终模式。
+| 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.

package/templates/shared/rules/fec-responsive-design.md

@@ -1,50 +1,50 @@
-# 响应式设计规则
+# Responsive design rules
 
-凡是任务涉及移动端适配、响应式布局、多端兼容、触摸目标或视口行为时，都应用本文件。本文只保留项目常驻约束；布局模式、container query、响应式表格、媒体和验证细节交给 `fec-responsive-layout`。
+This document should be used whenever the task involves mobile adaptation, responsive layout, multi-device compatibility, touch targets or viewport behavior. This article only retains project-resident constraints; layout mode, container query, responsive tables, media and validation details are left to `fec-responsive-layout`.
 
-## 核心原则
+## Core Principles
 
-- **移动优先**：从小屏幕开始设计，逐步增强到大屏幕。
-- **内容优先**：小屏优先展示核心任务、关键操作和反馈，次要内容折叠、延后或进入详情层。
-- **触摸友好**：所有交互元素必须适配手指操作，关键功能不能只依赖 hover。
-- **性能优先**：移动端网络和设备性能较弱，首屏资源、图表、动效和大列表要克制。
-- **容器感知**：可复用组件优先适配所在容器，而不是假设整页断点。
-- **稳定尺寸**：工具栏、表格列、棋盘、卡片网格和计数器需要稳定约束，避免状态变化导致布局跳动。
+- **Mobile First**: Start designing for small screens and work your way up to large screens.
+- **Content Priority**: Small screens give priority to core tasks, key operations and feedback, and secondary content is folded, postponed or entered into the detail layer.
+- **Touch Friendly**: All interactive elements must adapt to finger operations, and key functions cannot rely solely on hover.
+- **Performance first**: The mobile network and device performance are weak, so first-screen resources, charts, animations, and large lists should be restrained.
+- **Container Aware**: Reusable components will first adapt to the container in which they are located, instead of assuming full page breakpoints.
+- **Stable size**: Toolbars, table columns, checkerboards, card grids and counters need stable constraints to avoid layout jumps caused by state changes.
 
-## 断点与容器策略
+## Breakpoints and container strategies
 
-- 默认验证 375px、768px、1024px、1440px，以及断点中间值。
-- 使用 mobile-first `min-width` 断点；不要先写桌面样式再用 `max-width` 补移动端。
-- Tailwind 前缀从小到大使用：默认 → `sm:` → `md:` → `lg:` → `xl:` → `2xl:`。
-- 页面级结构可以使用断点；会被放进侧栏、弹窗、卡片或主内容区的复用组件优先使用 container query。
-- grid/flex 子项包含长文本、图表、代码、媒体或表格时，必须考虑 `min-width: 0`、`minmax()`、`aspect-ratio` 和明确溢出策略。
+- Default validation for 375px, 768px, 1024px, 1440px, and breakpoint intermediate values.
+- Use mobile-first `min-width` breakpoint; do not write the desktop style first and then use `max-width` to supplement the mobile version.
+- Tailwind prefixes are used from smallest to largest: default → `sm:` → `md:` → `lg:` → `xl:` → `2xl:`.
+- Page-level structures can use breakpoints; reusable components that will be placed into sidebars, pop-ups, cards, or main content areas preferentially use container queries.
+- `min-width: 0`, `minmax()`, `aspect-ratio` and explicit overflow strategies must be taken into account when grid/flex children contain long text, charts, code, media or tables.
 
-## 触摸目标与移动端交互
+## Touch target to interact with mobile terminal
 
-- 空间允许时，按钮、链接、关闭按钮等交互目标至少 44x44px；紧凑工具界面最低也要保证可操作。
-- 输入框字号避免低于 16px，防止 iOS Safari 自动缩放。
-- 固定底部栏、操作条、抽屉和对话框必须考虑 safe area 与虚拟键盘。
-- hover-only 信息必须有点击、焦点或常驻可见替代方案。
-- 横竖屏切换后，主操作、焦点位置、滚动容器和错误提示仍应可达。
+- When space permits, interaction targets such as buttons, links, and close buttons must be at least 44x44px; compact tool interfaces must be at least operable.
+- Avoid input box font size below 16px to prevent iOS Safari from automatically scaling.
+- Fixed bottom bar, action bar, drawer and dialog box must consider safe area and virtual keyboard.
+- Hover-only messages must have click, focus, or permanent visible alternatives.
+- After switching between horizontal and vertical screens, the main operation, focus position, scroll container and error prompts should still be accessible.
 
-## 数据密集区域
+## Data intensive area
 
-- 表格、列表、看板、编辑器和画布可以局部横向滚动，但页面整体不应出现无意水平溢出。
-- 移动端数据密集视图需先定义列优先级：主标识、状态和主操作优先保留；低优先级字段进入详情、展开行或抽屉。
-- 小屏仍要保留排序、筛选、分页和选择能力。
-- 虚拟滚动只解决 DOM 数量问题，不能替代信息层级设计。
+- Tables, lists, boards, editors and canvases can be partially scrolled horizontally, but the page as a whole should not have unintentional horizontal overflow.
+- Data-intensive views on the mobile terminal need to define column priorities first: main identification, status and main operations are retained first; low-priority fields enter details, expand rows or drawers.
+- Small screens must still retain the ability to sort, filter, paging, and select.
+- Virtual scrolling only solves the problem of DOM quantity and cannot replace information hierarchy design.
 
-## 响应式媒体
+## Responsive media
 
-- 图片和视频要有稳定尺寸、`aspect-ratio` 或容器约束，避免加载后推挤布局。
-- 需要多尺寸资源时使用 `srcset`、`sizes`、`picture` 或框架图片组件，避免移动端下载桌面大图。
-- 媒体裁切必须保留主体信息，不为填满卡片裁掉产品、人物、图表或状态关键区域。
+- Images and videos must have stable size, `aspect-ratio` or container constraints to avoid pushing the layout after loading.
+- Use `srcset`, `sizes`, `picture` or frame picture components when multi-size resources are needed to avoid downloading large desktop images on mobile devices.
+- Media cropping must preserve the main information and do not crop out key areas of products, people, graphics or status to fill the card.
 
-## 检查清单
+## Checklist
 
-- [ ] 320-375px 页面级无水平溢出。
-- [ ] 断点切换后阅读顺序合理，主操作不被隐藏。
-- [ ] 触摸目标、输入字号、safe area、虚拟键盘和横竖屏行为已验证。
-- [ ] loading、empty、error、disabled、hover/focus、长翻译文本和大数字不会撑坏固定格式控件。
-- [ ] 数据密集区域有列优先级、局部滚动或移动端摘要策略。
-- [ ] 首屏媒体尺寸稳定，非首屏媒体不会拖慢移动端主路径。
+- [ ] 320-375px No horizontal overflow at page level.
+- [ ] The reading order is reasonable after breakpoint switching, and the main operation is not hidden.
+- [ ] Touch target, input font size, safe area, virtual keyboard and horizontal and vertical screen behaviors have been verified.
+- [ ] loading, empty, error, disabled, hover/focus, long translation text and large numbers will not break the fixed format control.
+- [ ] Column priority, partial scrolling, or mobile summary strategies for data-intensive areas.
+- [ ] The size of first-screen media is stable, and non-first-screen media will not slow down the main path of the mobile terminal.