@bovinphang/frontend-craft 2.6.0 → 2.8.0

package/localized/zh-CN/templates/shared/rules/fec-design-system.md

@@ -0,0 +1,72 @@
+# 设计系统规则
+
+凡是任务涉及 UI 实现、设计稿转代码、样式、设计 Token 或组件复用时，都应用本文件。本文只保留项目常驻设计约束；产品化设计方向、设计系统生成、页面级 override、UI QA 细节交给 `fec-ui-design`；Tailwind token、variant、dark mode 和 class 治理交给 `fec-tailwind-design-system`；响应式布局交给 `fec-responsive-layout`。
+
+## 核心优先级
+
+1. 复用已有组件。
+2. 在已有组件上扩展。
+3. 创建新的叶子组件。
+4. 只有在理由充分、边界清晰且会被复用时，才创建新的共享基础组件。
+
+## 产品化设计方向
+
+- 工具型页面、SaaS 后台、CRM、运营台：优先安静、密集、可扫描，首屏直接呈现核心工作区。
+- 品牌页、作品集、发布页：可以更有表现力，但 H1 应是品牌、产品、对象或品类，说明文案放在副标题。
+- 可视化、游戏、创作工具：可以使用更强视觉资产和动效，但必须保持交互可控、状态清晰。
+- 每个重要界面都应有贴合业务的视觉锚点，例如真实媒体、数据形态、行业材质、字体性格、空间组织或交互节奏。
+- 大胆设计必须服务场景；高频工具重效率和稳定，展示型页面重主体识别和记忆点。
+
+避免：
+
+- 把日常高频工具做成营销落地页。
+- 默认使用紫色渐变、装饰光斑、堆叠卡片、空泛 hero 或无语境默认字体。
+- 页面区块大面积卡片化，尤其是卡片套卡片。
+- 用可见说明文字解释常见控件本该表达的功能。
+- 让整个界面只由一个色相的深浅变化组成。
+
+## 设计稿转代码规则
+
+- 有设计上下文时，先通过 MCP 或截图/标注读取事实来源，不靠猜测决定布局、间距、字体、颜色或状态。
+- 设计稿中的颜色、间距、圆角、阴影和字体应映射到现有 token、CSS 变量、主题变量或组件 variant。
+- 创建新组件前先检查现有组件库和业务组件，优先复用。
+- 默认验证 mobile(375px)、tablet(768px)、desktop(1440px)。
+- 像素还原要求以项目约定为准；没有约定时，核心结构、间距、字体、状态和交互优先于机械追求截图重合。
+- 复杂设计任务实现前先给出简短实现计划，说明复用组件、新建组件、可能改动文件、响应式策略和 token 映射。
+
+## 设计 Token 与样式
+
+- 优先使用已有 design token、CSS 变量或主题变量；不要硬编码颜色、圆角、间距、阴影和字体取值。
+- 缺少所需 token 时要明确指出，并集中补齐或记录，不在多个组件里散落字面量。
+- Tailwind 项目中，token 应通过语义化 `theme.extend`、CSS 变量或组件 variant 承接；不要把 `blue-600`、`rounded-xl` 等具体值复制成事实标准。
+- 组件 variant 应区分语义 tone、尺寸 size、密度 density 和状态 state；不要让一个字符串参数同时承载多种业务含义。
+- 动态 Tailwind class 必须可被构建扫描识别；复杂映射使用显式对象、variant 工具或 safelist。
+- 优先使用局部、受控的样式，不做大范围全局覆盖；与项目现有 CSS Modules、Tailwind、组件库或样式体系保持一致。
+
+## 界面质感基线
+
+- 嵌套圆角保持光学关系：外层圆角约等于内层圆角 + 间距。
+- 图标按钮、箭头、播放三角等非对称图形按视觉中心微调。
+- 小控件命中区域至少 40x40px，空间允许时优先 44x44px。
+- 标题和短文本可用 `text-wrap: balance`，短中正文可用 `text-wrap: pretty`。
+- 计数器、价格、时间、表格数字使用 `font-variant-numeric: tabular-nums`。
+- 动效只声明实际变化属性，禁止 `transition: all` 和 `will-change: all`，并尊重 `prefers-reduced-motion`。
+
+## 暗色模式
+
+- 项目级暗色模式只选择一种主策略：CSS 变量、根节点 class、`data-theme` 或组件库主题。
+- 支持手动切换主题时，要在首屏绘制前初始化用户偏好，避免主题闪烁；实现细节交给 Tailwind / design-system skill reference。
+- 亮色与暗色都要复核 disabled、focus、selected、invalid、skeleton、chart、表单控件、第三方组件和阴影层级。
+- 不只靠降低透明度表达 disabled，不只补背景色而忽略文本、边框、图表和焦点状态。
+
+## 可访问性基线
+
+- 优先使用语义化 HTML。
+- 表单控件具备标签，纯图标按钮具备可访问名称。
+- 菜单、标签页、对话框和自定义控件支持键盘操作。
+- 焦点样式可见，标题层级正确，真实表格数据使用表格语义。
+- 颜色对比度、触摸目标、reduced-motion 和错误提示不能被视觉 polish 破坏。
+
+## UI 任务输出
+
+实现完成后说明复用了什么、新建了什么、与设计稿或项目 token 的偏差、缺少哪些资源或交互细节。复杂 UI 还应说明状态覆盖、响应式验证和剩余设计风险。

package/localized/zh-CN/templates/shared/rules/fec-error-handling.md

@@ -0,0 +1,56 @@
+# 错误处理规范
+
+本文件约定前端错误处理的常驻边界。React/Vue 组件边界细节交给对应框架 skill，API 错误映射和鉴权刷新交给 `fec-api-integration`，安全敏感错误交给 `fec-security-review`。
+
+## 错误分层
+
+| 层级 | 错误类型 | 默认处理 |
+| ---- | -------- | -------- |
+| 全局 | 未捕获异常、Promise rejection | 捕获、上报、全局降级 UI |
+| 路由 / 页面 | 页面级渲染异常 | Error Boundary / 框架错误边界 + 页面级降级 |
+| 模块 | 功能模块运行时异常 | 模块级边界 + 局部降级 |
+| 组件 / 请求 | 数据请求失败、操作失败 | 用户可理解提示 + 可恢复动作 |
+| 表单 | 校验失败 | 字段级错误提示和修正入口 |
+
+## 全局与模块边界
+
+- 应在应用入口注册未捕获异常和 Promise rejection 监听，并接入项目错误上报平台。
+- React 使用项目统一的 Error Boundary 方案；业务组件保持函数式，不新增手写类组件边界。
+- Vue 使用项目统一的 `app.config.errorHandler`、`onErrorCaptured` 或框架级错误边界。
+- 独立功能模块应有局部降级能力，模块崩溃不应导致整个页面白屏。
+- Error Boundary 处理渲染异常；普通 API 失败应落到 loading/error/empty/data 状态和可恢复操作。
+
+## API 错误处理
+
+- 请求层统一归一错误形状，组件不直接解析后端异常、token refresh 或重试策略。
+- 每类错误都应对应明确下一步：重试、重新登录、修改输入、返回上级、刷新冲突数据、联系支持或稍后再试。
+- `401`、`403`、`404`、`409`、`422`、`429`、`5xx` 和网络错误应有可区分的用户提示和日志语义。
+- UI 可显示 request id / trace id 方便支持排查，但不得暴露内部堆栈、SQL、服务名、密钥或敏感字段。
+
+## 用户体验
+
+- 每个数据展示区域处理 Loading、Error、Empty、Success 四种状态。
+- 全局级错误页提供返回首页、刷新或重试路径；模块级降级只影响该模块；操作级错误给出下一步。
+- 重试策略要克制：用户手动重试优先，自动重试需有上限、退避和停止条件。
+- 错误提示应保留用户已输入内容，避免因失败丢失表单或上下文。
+
+## 错误上报
+
+上报内容应包含错误堆栈、页面 URL、浏览器/设备信息、用户或会话标识、操作上下文、请求标识和版本信息。上报前清理 token、密码、个人敏感字段和大体积 payload。
+
+## 反模式
+
+- 空 `catch` 块吞掉错误。
+- 所有错误统一用 `alert()` 或一个模糊 toast。
+- 接口失败时 UI 无反馈，或把后端原始异常直接展示给用户。
+- Error Boundary 没有重试或返回路径。
+- 在组件中到处写重复 `try/catch`，而不是统一封装请求边界。
+- 用 Error Boundary 承接普通 API 错误，导致用户无法理解或恢复。
+
+## 检查清单
+
+- [ ] 全局未捕获异常和 Promise rejection 已监听。
+- [ ] 关键页面或模块有框架错误边界和局部降级 UI。
+- [ ] API 请求有统一错误归一、分级处理和可恢复动作。
+- [ ] 数据区域覆盖 Loading / Error / Empty / Success。
+- [ ] 错误上报包含足够定位信息且不泄露敏感数据。

package/localized/zh-CN/templates/shared/rules/fec-git-conventions.md

@@ -0,0 +1,73 @@
+# Git 提交规范
+
+凡是创建 commit、编写 commit message 或准备提交代码时，都应用本文件。
+
+## Conventional Commits 格式
+
+```
+<type>(<scope>): <subject>
+
+[body]
+
+[footer]
+```
+
+### type 取值
+
+| type | 用途 |
+|------|------|
+| `feat` | 新功能 |
+| `fix` | 修复 bug |
+| `refactor` | 重构（不改变行为） |
+| `style` | 代码格式调整（不影响逻辑） |
+| `docs` | 文档变更 |
+| `test` | 测试相关 |
+| `chore` | 构建、工具、依赖等杂项 |
+| `perf` | 性能优化 |
+| `ci` | CI/CD 配置变更 |
+
+### scope
+
+可选，标明影响范围，如模块名、组件名或功能域：
+
+- `feat(auth): 新增手机号登录`
+- `fix(table): 修复排序列未高亮`
+- `refactor(api): 统一请求错误处理`
+
+### subject 规范
+
+- 使用祈使句（"增加 xxx" 而非 "增加了 xxx"）
+- 不超过 72 个字符
+- 不以句号结尾
+- 如果影响范围较大，在 body 中详细说明
+
+## 分支命名
+
+- `feature/xxx` — 新功能
+- `fix/xxx` — 修复
+- `refactor/xxx` — 重构
+- `hotfix/xxx` — 紧急修复
+
+## 提交前检查
+
+提交前必须通过：
+
+1. lint
+2. type-check
+3. 与变更相关的测试
+
+未经用户确认不要直接执行 `git commit`。
+
+## 提交粒度
+
+- 一个提交只包含一个清晰目的：功能、修复、测试、文档或清理。
+- 大型计划应拆成可验证的小批次，每批都有说明和命令结果。
+- 清理、格式化和行为变更不要混在同一提交中。
+- 推送或发 PR 前先复查 diff，确认没有本地配置、密钥、临时报告或调试输出。
+
+## 反模式
+
+- 一个 commit 混合不相关的改动
+- commit message 过于笼统（如 "update"、"fix bug"、"wip"）
+- 在 commit 中包含调试代码、console.log 或临时 hack
+- 未说明验证命令或已知剩余风险就提交高风险改动

package/localized/zh-CN/templates/shared/rules/fec-i18n.md

@@ -0,0 +1,64 @@
+# 国际化 (i18n) 规则
+
+凡是涉及用户可见文案、提示信息、表单标签、错误消息或 UI 文本时，都应用本文件。请根据项目实际 i18n 方案修改 locales 路径、库与 key 前缀。
+
+## 适用范围
+
+- **现代栈（React / Vue / Next / Nuxt 等）**：新增或修改的用户可见文案必须走项目 i18n 方案。
+- **遗留 HTML/JS、渐进迁移或新旧并存**：新代码路径仍须满足核心原则；遗留层遵守迁移约束，避免扩大硬编码和混乱 key。
+
+下文用 `src/locales/` 指代项目实际文案资源目录，请按仓库约定替换。
+
+## 核心原则
+
+- 新应用代码中的用户可见文案须使用 i18n，禁止硬编码中文或英文字符串。
+- i18n key 按模块组织，使用点分命名，例如 `order.list.empty`。
+- 相同语义的文案复用同一个 key，避免重复定义。
+- 变量、复数、日期、数字和货币使用 i18n 能力格式化，不用字符串拼接。
+- 修改文案前先检索现有资源，优先复用准确 key。
+
+## 文案与资源规范
+
+- `common.*` 用于跨模块通用文案，例如确认、取消、提交、加载中。
+- `module.component.*` 用于模块级文案。
+- `validation.*` 用于表单校验提示。
+- `error.*` 用于错误信息。
+- 每种自然语言对应独立资源文件，禁止多种语言混写在同一文件或同一顶层多语言对象内。
+- 文案文件须以 UTF-8 保存；团队有约定时优先 UTF-8 无 BOM，避免中文、日文等非 ASCII 文案乱码。
+- 新增 key 时，同步更新当前功能应覆盖的主要语言文件；若某语言暂缺，必须显式记录缺口。
+
+## 遗留代码与迁移场景
+
+- 遗留 HTML 或 JS 中不新增用户可见硬编码，除非该段为纯静态展示且仓库尚无可接入 i18n 路径。
+- React / Vue 等新代码路径新增提示、错误、按钮、表单标签时，必须走 i18n。
+- 新增子应用或模块时，与现有语言文件结构、命名空间和懒加载策略一致。
+- key 按页面、模块和语义组织，避免继续沿用历史缩写或无意义分段。
+- 旧 key 若仅“能用但不准”，优先重命名 key 并重写译文，不长期保留并行兼容。
+- 仅当旧 key 已成为对外契约（后端、埋点、外部文档、第三方集成等固定引用）时，才引入映射层或别名过渡。
+
+## 实现约束
+
+- Vue、React、Next、Nuxt 的具体调用方式以项目现有 i18n 库为准，例如 `vue-i18n`、`react-intl`、`react-i18next` 或框架内置方案。
+- 组件中不要直接写用户可见硬编码；测试可通过 key 或最终文案断言，但应避免与翻译细节过度耦合。
+- 懒加载语言包时，loading、fallback 和缺失 key 行为要可预期。
+- 错误、表单和空状态文案要能表达用户下一步，不只翻译技术错误。
+
+## 检查清单
+
+- [ ] 所有新增用户可见文案使用 i18n key。
+- [ ] 新增 key 已添加到所有应覆盖语言文件，且各语言分文件维护。
+- [ ] 语言资源文件为 UTF-8，打开无乱码。
+- [ ] key 命名符合模块、组件、用途约定，并复用已有语义。
+- [ ] 插值、复数、日期、数字、货币使用 i18n 格式化。
+- [ ] 迁移或混合栈中未扩大用户可见硬编码。
+- [ ] 新代码未破坏现有命名空间、加载方式和子应用边界。
+
+## 反模式
+
+- 在模板或 JSX 中直接写用户可见中文或英文字符串。
+- 使用字符串拼接代替 i18n 插值。
+- 在 JS/TS 逻辑中硬编码 toast、错误或确认文案。
+- 不同模块为相同含义创建不同 key。
+- 多语言混写导致 diff、评审和按需加载困难。
+- 用非 UTF-8 或错误编码保存文案文件。
+- 为迁就历史缩写或劣质命名长期保留多套并行 key。

package/localized/zh-CN/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/localized/zh-CN/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/localized/zh-CN/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/localized/zh-CN/templates/shared/rules/fec-refactoring.md

@@ -0,0 +1,47 @@
+# 重构项目规则
+
+当任务涉及从现有项目重构、迁移或重写前端代码时，应用本文件。
+
+## 目标
+
+- **视觉和交互**：与原项目一致，用户无感知差异
+- **代码质量**：更简洁、易维护，符合目标框架规范
+- **业务功能**：与原项目保持一致，**不得缺失功能**；重构前后行为等价
+
+## 图片与图标
+
+- 直接使用原项目的图片资源路径，不重新托管或替换
+- 可使用 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、路由、事件、埋点、权限、缓存和错误状态建立行为清单，重构前后逐项核对
+- 涉及页面、组件、路由、表单、弹窗、导航或关键用户流程的迁移，必须使用 Playwright 或同等真实浏览器验证方式对关键路径做对比验证
+- 对视觉敏感页面，应补充截图对比或人工截图验收；动态内容、动画、字体和环境差异需明确屏蔽、稳定化或说明
+- 对纯逻辑、类型、构建或无 UI 的迁移，不强制 Playwright，应选择更贴近风险的验证层：type-check、unit test、component test、build 或 lint
+- 验证目标不是像素级完全一致，而是确认业务功能无缺失、关键交互等价、主要视觉布局无非预期偏差，并且代码比旧实现更清晰、可维护
+
+## 死代码清理
+
+清理未使用代码、导出、样式或依赖时：
+
+- 先建立验证基线，再做清理。
+- 使用工具或搜索证据证明候选项无引用。
+- 将候选项分为 SAFE、CAUTION、DANGER。
+- 仅自动清理 SAFE 项；路由、配置、运行时模板、动态 import 和公开 API 默认视为高风险。
+- 每批清理后运行受影响验证命令。
+- 若验证失败，先回到最近一批候选项定位，不继续扩大清理范围。
+
+不要把死代码清理与功能重写、视觉调整或依赖升级混在同一个改动里。

package/localized/zh-CN/templates/shared/rules/fec-rendering-patterns.md

@@ -0,0 +1,40 @@
+# 渲染模式选型
+
+当项目需要选择或评估 CSR / SSR / SSG / ISR / RSC 时，参考本文件。本文只保留跨框架决策约束；Next.js App Router 细节交给 `fec-nextjs-project-standard`，Nuxt 细节交给 `fec-nuxt-project-standard`，性能证据交给 `fec-performance-optimization`。
+
+## 渲染模式概览
+
+| 模式 | 生成时机 | 典型适用 |
+| ---- | -------- | -------- |
+| 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 或路由行为验证最终模式。