@bovinphang/frontend-craft 2.6.0 → 2.7.0

package/skills/fec-legacy-to-modern-migration/references/migration-execution-checklist.md

@@ -0,0 +1,110 @@
+# 迁移执行与检查清单
+
+## 迁移前分析
+
+在动手迁移前，必须完成以下分析并输出**迁移分析报告**：
+
+1. **存量盘点**
+   - 页面数量、功能模块数量
+   - 依赖的 jQuery 插件及替代方案（如 DataTables → TanStack Table）
+   - 现有 API 调用方式、是否有统一封装
+   - 是否有服务端模板（JSP/Thymeleaf/EJS 等）需要保留、局部替换或改为纯前端渲染
+   - 目标栈是 React/Vue/Next/Nuxt、现代 MPA，还是只做局部 TypeScript/构建/测试现代化
+
+2. **依赖关系**
+   - 页面间共享的 JS/CSS 模块
+   - 跨页面复用的业务逻辑
+   - 与后端的接口契约（是否需调整）
+
+3. **迁移优先级**
+   - 按业务价值、复杂度、耦合度排序
+   - 优先迁移独立模块、低耦合页面
+   - 识别可复用的工具函数、常量、类型定义
+
+## 分阶段迁移流程
+
+### 阶段 0：准备
+
+- 搭建或识别目标项目骨架：React/Vue/Next/Nuxt、现代 MPA，或现有项目内的渐进式 TypeScript/构建入口
+- 配置 ESLint、Prettier、测试框架
+- 建立 `services/request.ts` 统一请求层，与现有 API 兼容
+- 将遗留项目中的 `utils`、`constants` 逐步迁移并补充类型
+
+### 阶段 1：基础层
+
+- 迁移并类型化 API 调用（`$.ajax` → `axios`/`fetch`）
+- 迁移工具函数（日期、格式化、校验等）
+- 迁移常量、枚举、类型定义
+- 建立目标导航/页面入口骨架；未迁移页面可继续走旧路由、重定向、iframe 或微前端嵌入
+
+### 阶段 2：按模块/页面迁移
+
+- 每次迁移一个完整功能或页面
+- 从简单到复杂：静态页 → 列表页 → 表单页 → 复杂交互页
+- 迁移时提取可复用组件，遵循目标 React 或 Vue 项目的目录结构
+- 每完成一个模块，补充单元测试和 E2E 关键路径
+
+### 阶段 3：收尾
+
+- 按迁移策略移除或冻结旧代码入口；若保留 MPA，则收敛旧入口并完成现代化边界
+- 配置 404、错误边界、全局错误处理
+- 性能优化（懒加载、代码分割、缓存策略）
+- 文档更新、部署流程调整
+
+## 重构实施要求
+
+迁移时需遵循以下实施约束，确保视觉与交互一致、代码更简洁易维护。
+
+### 图片与图标
+
+- 直接使用原项目的图片资源路径，不重新托管或替换
+- 可使用 SVG 图片（`<img src="*.svg" />` 或 CSS `background-image`）；图标组件或可访问交互确需内联 SVG 时，应遵循目标项目图标规范并说明理由。
+- 若原项目使用了 iconfont 或 IcoMoon 图标，重构时优先继续使用，保持图标体系一致；替换为其他图标方案前需评估视觉一致性、包体和维护成本。
+- 图标优先使用原项目已有的图标文件（iconfont / IcoMoon / 已有 SVG），必要时可引入 SVG 文件作为独立资源
+
+### 国际化（i18n）
+
+- 新栈代码（React / Vue 等）中的用户可见文案须走项目 i18n，不在新代码里硬编码中/英文案
+- 遗留 HTML/JS 中**不要新增**用户可见硬编码文案，除非纯静态且仓库尚无可用 i18n 接入点；改动文案前先查 locales 是否已有条目，并同步主要语言文件
+- key 按页面/模块/语义组织，复用既有 key；仅当旧 key 为对外契约时才做映射过渡，详见项目规则中的 **国际化 (i18n)**（`templates/shared/rules/fec-i18n.md` 内「遗留代码与迁移场景」）
+
+### 样式
+
+- 布局样式对齐原项目视觉效果，但**只参考原项目效果，不照搬其 CSS**
+- 优先使用 **flex 弹性布局**，避免 `float`、复杂 `position`、冗余嵌套
+- 避免不合理写法：如 `!important` 滥用、过深选择器、重复定义
+- 组件中优先避免内联样式（`style={{ ... }}` / `style="..."`）；确需使用运行时动态值、第三方组件 API 或 CSS 变量桥接时，应保持局部、可解释，并优先放入目标项目样式体系。
+
+### 目标
+
+- **视觉和交互**：与原项目一致，用户无感知差异
+- **代码质量**：更简洁、易维护，符合目标框架规范
+- **业务功能**：与原项目保持一致，**不得缺失功能**；迁移前后行为等价
+
+### 验证分层
+
+- 涉及页面、组件、路由、表单、弹窗、导航或关键用户流程的迁移，先建立重构前后的行为清单，再使用 Playwright 或同等真实浏览器验证方式对关键路径做对比验证。
+- 对视觉敏感页面，补充截图对比或人工截图验收；动态内容、动画、字体和环境差异需明确屏蔽、稳定化或说明。
+- 对纯逻辑、类型、构建或无 UI 的迁移，不强制 Playwright，应选择更贴近风险的验证层：type-check、unit test、component test、build 或 lint。
+- 验证目标不是像素级完全一致，而是确认业务功能无缺失、关键交互等价、主要视觉布局无非预期偏差，并且代码比旧实现更清晰、可维护。
+
+## 迁移检查清单
+
+每个迁移单元完成后，确认：
+
+- [ ] 已建立重构前后的行为清单，覆盖公共 API、路由、表单、权限、错误状态、缓存、埋点和关键交互
+- [ ] 业务逻辑与旧实现一致，无功能遗漏，功能完整等价
+- [ ] 涉及 UI、交互或关键流程的迁移已使用 Playwright 或同等真实浏览器验证方式完成关键路径对比
+- [ ] 视觉敏感页面已完成截图对比或人工截图验收，并说明动态内容、动画、字体和环境差异处理方式
+- [ ] 纯逻辑、类型、构建或无 UI 迁移已选择更贴近风险的验证层，不强制套用 Playwright
+- [ ] 类型定义完整，无 `any` 滥用
+- [ ] API 调用使用统一 request 层，错误处理完整
+- [ ] 表单校验、loading、空状态、错误状态已实现
+- [ ] 可访问性：表单有 label、交互可键盘操作
+- [ ] 无 XSS 风险（用户输入已转义或使用安全 API）
+- [ ] 关键路径有测试覆盖
+- [ ] 符合目标栈的项目规范（React / Vue / Next / Nuxt / MPA 现代化等）
+- [ ] 图片使用原项目资源；图标体系优先沿用原项目或目标项目规范，例外已说明
+- [ ] 样式参考原项目效果但不照搬 CSS，优先使用目标项目样式体系，内联样式例外已说明
+- [ ] 视觉与交互与原项目一致，代码更简洁易维护
+- [ ] 新代码路径文案已 i18n；遗留层未扩大硬编码；locales 检索与多语言同步已完成（参见 i18n 规则迁移补充清单）

package/skills/fec-legacy-to-modern-migration/references/migration-strategy-and-mapping.md

@@ -0,0 +1,48 @@
+# 迁移策略与概念映射
+
+## 迁移策略选择
+
+| 策略                        | 适用情况                             | 优点                         | 风险                         |
+| --------------------------- | ------------------------------------ | ---------------------------- | ---------------------------- |
+| **渐进式（Strangler Fig）** | 大型项目、需持续交付、团队熟悉度不足 | 风险可控、可分批上线、可回滚 | 新旧并存期长、需维护两套代码 |
+| **一次性重写**              | 中小型项目、业务稳定、有充足时间窗口 | 目标架构清晰、无历史包袱     | 周期长、上线压力大、回滚困难 |
+
+**推荐**：优先考虑渐进式，除非项目规模小且业务简单。
+
+## 概念映射
+
+### jQuery → React
+
+| 遗留模式                                   | React 对应                             |
+| ------------------------------------------ | -------------------------------------- |
+| `$(selector).html(content)`                | 声明式 JSX + state 驱动渲染            |
+| `$(document).on('click', '.btn', handler)` | `onClick` + 事件委托由 React 处理      |
+| `$.ajax()` / `$.get()`                     | 项目请求层、`fetch` / `axios`，可按需接 TanStack Query 或 SWR |
+| 全局变量 / 命名空间存储状态                | 局部 state、Context 或项目既有 store，可按需使用 Zustand/Redux |
+| `$(el).show()` / `$(el).hide()`            | 条件渲染 `{visible && <Component />}`  |
+| 手动 DOM 操作 `append` / `remove`          | 数据驱动，通过 setState 触发重渲染     |
+| 模板字符串拼接 HTML                        | JSX 组件 + props                       |
+| 多页面 + 服务端路由                        | React Router 客户端路由                |
+
+### jQuery → Vue 3
+
+| 遗留模式                                   | Vue 3 对应                                         |
+| ------------------------------------------ | -------------------------------------------------- |
+| `$(selector).html(content)`                | 模板 + `ref` / `reactive` 驱动渲染                 |
+| `$(document).on('click', '.btn', handler)` | `@click` + 事件修饰符                              |
+| `$.ajax()` / `$.get()`                     | 项目请求层、`fetch` / `axios`，可按需接 VueUse、Nuxt `useFetch` 或 TanStack Query Vue adapter |
+| 全局变量 / 命名空间存储状态                | `ref` / `reactive` / Pinia                         |
+| `$(el).show()` / `$(el).hide()`            | `v-show` / `v-if`                                  |
+| 手动 DOM 操作                              | 数据驱动，通过响应式更新视图                       |
+| 模板字符串拼接 HTML                        | 单文件组件 `<template>` + props                    |
+| 多页面 + 服务端路由                        | Vue Router 客户端路由                              |
+
+### 通用映射
+
+| 遗留概念                          | 现代对应                                   |
+| --------------------------------- | ------------------------------------------ |
+| 页面级 JS 入口（每页一个 script） | 路由/页面入口 + 懒加载模块，或保留 MPA 入口并现代化打包 |
+| 公共 JS 模块（utils、ajax 封装）  | `services/`、`utils/`、类型化 API 层       |
+| 内联样式 / 页面级 CSS             | 目标项目样式体系，如 CSS Modules、Tailwind、全局样式分层或组件库样式 |
+| 服务端模板变量                    | 通过 API 获取、SSR/loader 注入，或保留服务端模板边界并类型化数据 |
+| 表单提交 + 整页刷新               | 表单库 + 客户端校验 + API 调用             |

package/skills/fec-motion-interaction/SKILL.md

@@ -31,12 +31,16 @@ description: Use when designing, implementing, or reviewing frontend interaction
    - Level 3-4：加入短 stagger、局部 spring 和轻量 reveal，适合仪表盘、设置页和管理台。
    - Level 5-6：加入视差、布局 morph、指针响应，适合产品展示和交互式首页。
    - Level 7+：使用滚动叙事、固定段落或 3D/WebGL 配合，必须单独做移动端和 reduced-motion 降级。
+   - 场景默认值：公共服务、医疗、金融和强可访问性产品从 Level 1-2 起步；SaaS 工具和数据后台从 Level 2-3 起步；营销页、品牌页和作品集可从 Level 4-6 起步；实验性活动页或沉浸式叙事才考虑 Level 7+。
+   - 如果 UI 设计流程已经设定了动效强度拨盘，沿用该拨盘；不要因为引入了某个动效库就自动提高强度。
 
 4. 建立性能边界
    - 只高频动画 `transform`、`opacity`，谨慎使用 `filter` 和 `clip-path`。
    - GSAP、Lottie、Three.js、重型动画组件必须动态导入或隔离在叶子组件。
    - 持续动画需要暂停条件：不可见、标签页隐藏、用户关闭、低电量或 reduced motion。
    - 不在滚动事件中同步读写布局；使用 IntersectionObserver、ScrollTimeline 或节流后的 rAF。
+   - 滚动叙事、stagger、spring、磁吸指针和视差效果必须各自有明确职责；同一屏不要同时堆叠多种高强度运动语言。
+   - 长页面中重复 reveal 动画要控制节奏，避免每个区块都以同一种延迟、方向和 easing 进入，造成模板感和滚动疲劳。
 
 5. 设计可访问降级
    - 所有非必要动效读取 `prefers-reduced-motion`，降级为静态、淡入或即时状态。
@@ -50,12 +54,15 @@ description: Use when designing, implementing, or reviewing frontend interaction
    - 检查首次加载 bundle 是否因动效库显著膨胀。
    - 手动开启 reduced motion，确认动画被禁用或弱化。
    - 用性能面板或实际设备确认滚动和关键交互没有明显掉帧。
+   - 检查动效强度是否匹配页面类型：工作台不应出现营销式滚动剧场，作品集也不应只有默认 hover 淡入。
+   - 对滚动触发序列确认用户可以快速到达内容，不因 pinned 区块、过长时间轴或不可中断过渡丢失上下文。
 
 ## Constraints
 
 - 不在同一个组件内混用 Framer Motion 和 GSAP 控制同一元素。
 - 不用动效掩盖 loading、empty、error、disabled 等状态缺失。
 - 不为普通后台表格、配置页和高频工作台默认加入大幅视差或滚动劫持。
+- 不让所有区块使用相同 reveal 模板；动效节奏应随信息层级和用户任务变化。
 - 不动画 `width`、`height`、`top`、`left`、`margin`、`padding` 等会频繁触发布局的属性。
 - 不把大型 Lottie JSON、GSAP 插件或 3D 场景放入首屏同步包。
 - 不让动画改变阅读顺序、焦点顺序或键盘可达性。

package/skills/fec-nextjs-project-standard/SKILL.md

@@ -18,7 +18,8 @@ description: Use when creating or reviewing Next.js 14+ App Router projects, fil
 3. 明确 SSR / SSG / ISR / CSR 渲染模式和 Next fetch/cache 策略。
 4. 为路由补齐 `loading.tsx`、`error.tsx`、`not-found.tsx`、metadata 和敏感逻辑的服务端边界。
 5. 引入第三方库前检查是否支持 Server Component；浏览器专属、动效、图表、编辑器和 WebGL 库必须放进客户端叶子组件并按需加载。
-6. 客户端组件架构问题分流到 React 项目 workflow。
+6. 对动态渲染、缓存失效、RSC 序列化、route handler、middleware 和首屏 bundle 做证据优先审查；不确定时先收集构建、trace、headers 或路由行为证据。
+7. 客户端组件架构问题分流到 React 项目 workflow。
 
 ## 项目结构
 
@@ -73,6 +74,8 @@ src/
 - 客户端组件：`useEffect` + `useState`，或 SWR / React Query
 - 优先在服务端获取数据，减少客户端水合
 - 使用 `loading.tsx` 和 Suspense 包裹异步区块，提供流式体验
+- 缓存策略要写清 `force-cache`、`no-store`、`revalidate`、tag/path revalidation 或用户私有数据约束
+- 任何会让路由从静态变动态的读取（cookies、headers、searchParams、未缓存 fetch）都要说明原因和验证方式
 
 ## 路由与布局
 
@@ -102,6 +105,8 @@ src/
 - 不把密钥、内部 API 地址或服务端 token 放入 `NEXT_PUBLIC_` 环境变量。
 - 不让大型动效库、3D 场景、富文本编辑器或地图 SDK 进入根布局同步 bundle。
 - 首屏媒体必须有确定尺寸、真实资源和合理 priority；不要用远程占位图撑布局。
+- 不在没有指标、响应头、构建输出或路由行为证据时断言某路由“已缓存”或“必须动态”。
+- Middleware 只处理路由级轻量决策，不承载重型鉴权查询、日志批处理或可放到 route handler 的业务逻辑。
 
 ## 与客户端 UI 模式的分工
 
@@ -115,3 +120,4 @@ src/
 - 渲染模式选择正确（SSR/SSG/ISR/CSR），数据获取路径清晰
 - 元数据和 SEO 配置完整（title、description、openGraph）
 - 敏感逻辑在服务端，客户端组件仅处理交互
+- 缓存、动态渲染和首屏 bundle 决策有可复查证据，性能风险可分流到专项性能 workflow

package/skills/fec-performance-optimization/SKILL.md

@@ -21,6 +21,7 @@ description: Use when diagnosing or improving frontend performance, Core Web Vit
    - 对页面体验优先使用 Lighthouse、Performance trace、React Profiler、Vue Devtools、Memory snapshot 或 RUM 数据。
    - 对包体优先看构建产物、source map、依赖重复、首屏 chunk 和动态 import 边界。
    - 对运行时卡顿优先看长任务、重复渲染、昂贵计算、同步循环、布局抖动和大列表。
+   - 如果已有线上监控、平台指标或 CI 产物，先用它们确认受影响路由、设备、时间窗和用户主路径，再决定读哪些源码。
 
 3. 分层定位
    - 加载层：关键 CSS、字体、图片、脚本阻塞、预加载和缓存。
@@ -34,6 +35,7 @@ description: Use when diagnosing or improving frontend performance, Core Web Vit
    - 优先处理高频主路径和 P95 体验；低频后台任务不抢占首屏预算。
    - 先做低风险高收益改动，如懒加载、去重、缓存、尺寸预留、虚拟列表、稳定引用和释放资源。
    - 对会牺牲可维护性的技巧，必须说明收益证据和替代方案。
+   - 建议进入实现前先过候选门禁：是否有指标支撑、能否定位到路由/组件/chunk/请求、是否可由前端验证、是否存在更小改动。
 
 5. 验证回归
    - 重新运行受影响构建、测试和性能采集命令。
@@ -66,11 +68,13 @@ description: Use when diagnosing or improving frontend performance, Core Web Vit
 - 不为一次 Lighthouse 分数牺牲真实用户主路径。
 - 不引入大型新依赖解决小问题；先利用项目已有工具和浏览器能力。
 - 不把后端、网络和浏览器侧问题混为一谈；前端能验证的部分要单独列证据。
+- 不从 repo-wide grep 直接跳到优化结论；先用指标或复现路径收窄候选，再读相关源码。
 
 ## 详细参考
 
 撰写性能分析报告时，加载 [references/report-template.md](references/report-template.md)。
+需要按 React、Vue、Next.js 或 Nuxt 分类定位框架专项性能风险时，加载 [references/framework-performance-patterns.md](references/framework-performance-patterns.md)。
 
 ## Expected Output
 
-输出有证据链的性能分析报告，说明基线、瓶颈、优化建议、验证方式和剩余风险。报告保存为 `reports/performance-review-YYYY-MM-DD-HHmmss.md`。
+输出有证据链的性能分析报告，说明基线、候选门禁、瓶颈、优化建议、验证方式和剩余风险。报告保存为 `reports/performance-review-YYYY-MM-DD-HHmmss.md`。

package/skills/fec-performance-optimization/references/framework-performance-patterns.md

@@ -0,0 +1,38 @@
+# 框架专项性能诊断模式
+
+本参考用于已经进入性能优化流程后的专项定位。先建立目标、基线和候选门禁，再按框架读取对应分类；不要从这些清单直接跳到结论。
+
+## React / Client React
+
+- **Waterfall**：独立请求、权限检查、feature flag 或子组件数据是否被串行等待。用 Network waterfall、React Profiler 或用户路径日志确认依赖关系。
+- **Bundle**：首屏是否同步引入图表、编辑器、地图、3D、全量图标、重型日期库或 barrel export。用构建产物、source map 或 bundle analyzer 定位 chunk。
+- **Rerender**：Context 是否过宽，selector 是否过粗，默认对象/数组 props 是否每次新建，昂贵派生是否在热路径重复执行。用 React Profiler 或可复现交互证明。
+- **Effect**：是否用 effect 保存可直接推导的数据，是否把交互逻辑放进 effect，是否缺少取消、清理或稳定依赖。用渲染次数、请求次数或内存/订阅证据确认。
+- **Lazy boundary**：Suspense、动态 import、错误 fallback、loading/empty/error 状态是否成对出现，懒加载是否破坏焦点或首屏布局稳定性。
+
+## Vue 3 / Nuxt Client
+
+- **Reactive payload size**：大型对象、表格数据或第三方实例是否被深层响应式代理。用组件更新、内存快照或长任务证据判断是否需要浅响应式或不可变边界。
+- **Computed/watch**：本该 computed 的派生值是否用大范围 watcher 手动同步，watch 是否监听过宽对象，异步 watch 是否缺少取消和竞态处理。
+- **Template hot path**：`v-for` 中是否混用 `v-if`、内联重计算、缺少稳定 `:key`，或在大列表中渲染非视区节点。
+- **Async component boundary**：重型组件是否使用异步组件或路由级动态导入，加载状态是否稳定，错误态是否可恢复。
+- **Store fan-out**：Pinia store 是否把高频 UI 临时状态扩散到大范围订阅者，或把服务端缓存复制到全局 store。
+
+## Next.js
+
+- **Dynamic route drift**：cookies、headers、searchParams 或未缓存 fetch 是否让静态路由变动态。用构建输出、响应头或路由行为确认。
+- **RSC serialization**：Server Component 是否向 Client Component 传递过大 props、重复数据或不可序列化结构。
+- **Fetch/cache policy**：`force-cache`、`no-store`、`revalidate`、tag/path revalidation 是否与数据私有性和更新频率匹配。
+- **Client boundary leakage**：根布局或高层客户端边界是否同步带入重型浏览器库、Provider 或不必要状态。
+- **Middleware cost**：middleware 是否承载重型查询、日志批处理或可放到 route handler 的业务逻辑。
+
+## Nuxt 3
+
+- **Rendering mode mismatch**：页面是否应为 SSR、SSG、ISR/route rules 或 SPA，实际行为是否和部署目标一致。
+- **Data duplication**：`useFetch` / `useAsyncData` 是否重复请求，key 是否稳定，客户端 hydration 是否重复拉取同一数据。
+- **Route middleware cost**：路由中间件是否做重型异步工作、重复鉴权请求或不可缓存的全局阻塞逻辑。
+- **Client-only islands**：只在浏览器运行的图表、编辑器、地图或 WebGL 是否被隔离到 client-only 或异步边界。
+
+## 输出要求
+
+每个框架专项建议都要写清楚：证据来源、受影响路由/组件/chunk/请求、建议改法、验证命令和可能影响的 loading、error、empty、offline、reduced-motion 或移动端状态。

package/skills/fec-performance-optimization/references/report-template.md

@@ -25,6 +25,12 @@
 - 关联文件、路由、chunk、组件或请求
 - 支持该判断的 trace、bundle、日志或截图证据
 
+## 候选门禁
+
+| 候选问题 | 指标支撑 | 定位范围 | 前端可验证性 | 结论 |
+| --- | --- | --- | --- | --- |
+| ... | RUM / trace / bundle / network | route / component / chunk / request | 是 / 否 / 需协作 | investigate / defer / reject |
+
 ## 优先级
 
 | 优先级 | 问题 | 用户影响 | 风险 |

package/skills/fec-react-project-standard/SKILL.md

@@ -36,7 +36,7 @@ description: Use when designing or reviewing React + TypeScript project structur
    - 哪些逻辑应下沉为通用能力
    - 哪些状态应本地管理，哪些应交给 store / query / URL
    - 状态归属复杂时使用状态管理流程先做状态清单
-   - DTO、公共 props 或泛型组件复杂时使用 TypeScript 类型安全流程先收敛类型契约
+   - DTO、公共 props、泛型组件或 `tsconfig` 边界复杂时，先使用 TypeScript 项目规范流程收敛跨框架类型契约
 
 4. 输出时补齐关键质量项
    - loading / error / empty / data 状态
@@ -49,10 +49,16 @@ description: Use when designing or reviewing React + TypeScript project structur
    - 图片、视频、字体等资源是否本地化、可缓存，并避免占位 URL 进入交付
    - 页面级 Error Boundary、模块级 fallback、API 错误映射和用户可恢复动作是否一致
    - Tailwind token/variant 或响应式布局需求是否应分流到对应专项 skill
+   - 对明显架构性能风险做轻量筛查，如重型依赖边界、过宽 Context、高频派生值和懒加载 fallback；需要指标证据时进入性能优化 workflow
 
 ## 详细参考
 
-需要具体 React 项目结构、组件模式、Hooks、路由、状态归属、API 层形状、错误处理、样式默认值、TypeScript 约定或审查清单时，加载 [references/react-project-details.md](references/react-project-details.md)。
+按需要加载更细的参考文件：
+
+- 项目目录、组件分层、组件边界和组件目录建议：加载 [references/react-project-structure.md](references/react-project-structure.md)。
+- 组件模式、Hooks、路由、状态归属、API 层、错误处理和 Suspense/懒加载：加载 [references/react-runtime-patterns.md](references/react-runtime-patterns.md)。
+- 样式、注释、TypeScript、测试、反模式和输出检查清单：加载 [references/react-quality-patterns.md](references/react-quality-patterns.md)。
+- React 项目规范层面的轻量性能约定：加载 [references/react-performance-patterns.md](references/react-performance-patterns.md)。
 
 ## Constraints
 
@@ -66,11 +72,12 @@ description: Use when designing or reviewing React + TypeScript project structur
 - 不在通用页面组件里同步引入 GSAP、Three.js、Lottie、富文本编辑器或地图 SDK；需要时用动态导入、路由级分包或叶子组件隔离。
 - 不在 React 组件中散落裸 `fetch`、API URL、token refresh 或上传流程；跨边界请求应收敛到 API 集成层。
 - 不用 Error Boundary 处理普通 API 失败；请求错误应优先落到 loading/error/empty/data 状态和可恢复操作。
+- 不把 React 性能建议写成无证据的全局 memo 化；先定位请求瀑布、bundle 边界、重复渲染或 effect 误用。
 
 ## Expected Output
 
 - 组件边界清晰，pages/features/components 分层明确
-- Props 类型完整且明确，无 `any` 滥用
+- Props 类型完整且明确；复杂公共类型或外部数据收窄已分流到 TypeScript 项目规范流程
 - 可复用逻辑已提取为 hooks，loading/error/empty/data 状态齐全
 - API 层具备类型约束和统一错误处理，状态管理符合就近原则
 - URL 状态、服务端状态、表单状态和全局客户端状态边界明确
@@ -81,3 +88,4 @@ description: Use when designing or reviewing React + TypeScript project structur
 - 必要时说明为什么这样分层
 - 对新增模块，优先输出最小可落地结构，而不是一次性过度设计
 - 对重构任务，优先保证可迁移性和风险可控
+- 对性能相关 React 变更，说明触发的风险类别、证据来源和验证命令

package/skills/fec-react-project-standard/references/react-performance-patterns.md

@@ -0,0 +1,35 @@
+# React performance patterns
+
+This file keeps lightweight React project-standard performance guidance. Use the frontend performance workflow when the task needs metrics, traces, profiles, bundle analysis, network evidence, or a formal performance report.
+
+### 性能（与「性能优化」一节配合）
+
+- **useMemo**：昂贵派生、大列表排序/过滤；注意不可变数据，例如 `useMemo(() => [...list].sort(...), [list])`，避免直接 `sort` 可变原数组。
+- **useCallback**：传给 **`React.memo`** 子组件或作为其他 Hook 依赖的回调，在确有稳定引用需求时使用。
+- **React.memo**：纯展示、props 浅比较可接受的组件；不要全局套 memo。
+- **虚拟列表**：超长列表用 **TanStack Virtual**、**react-window** 等，只渲染视区内节点（路由级与组件级懒加载仍见「Suspense 与懒加载」）。
+
+## 性能优化
+
+在以下场景考虑性能优化：
+
+- 大列表 / 大表格
+- 高频重渲染组件
+- 大量 props 传递的复杂树
+- 重型第三方组件
+- 高频变化 context
+
+### 推荐手段
+
+- 合理使用 `React.memo`
+- 只在必要时使用 `useMemo` / `useCallback`
+- 列表使用稳定 `key`
+- 大列表使用虚拟滚动
+- 路由级做 code splitting
+- 避免将高频变化值放进顶层 context
+- 避免在 render 中无意义创建大量新对象 / 新函数 / 新数组
+- 重型图表、编辑器、地图、3D 和媒体处理能力放到叶子组件或路由级懒加载边界
+- 懒加载组件必须配套 loading、error、empty 或降级 UI，避免只优化包体却破坏用户状态
+
+---
+

package/skills/fec-react-project-standard/references/react-project-structure.md

@@ -0,0 +1,197 @@
+# React project structure and component boundaries
+
+## 项目结构（推荐参考）
+
+以下为中大型 React 项目的业界最佳实践结构，按项目实际情况裁剪：
+
+```text
+src/
+├── app/                        # 应用入口与全局配置
+│   ├── App.tsx                 # 根组件（Provider 组合）
+│   ├── routes.tsx              # 路由配置
+│   └── providers.tsx           # 全局 Provider 组装
+│
+├── pages/                      # 页面组件（与路由一一对应）
+│   ├── Dashboard/
+│   │   ├── DashboardPage.tsx
+│   │   ├── components/         # 页面私有组件
+│   │   └── hooks/              # 页面私有 hooks
+│   ├── UserList/
+│   └── Settings/
+│
+├── layouts/                    # 布局组件
+│   ├── MainLayout.tsx          # 主布局（侧边栏 + 顶栏 + 内容区）
+│   ├── AuthLayout.tsx          # 登录/注册页布局
+│   └── BlankLayout.tsx         # 空白布局（错误页等）
+│
+├── features/                   # 功能模块（按业务领域划分）
+│   ├── auth/
+│   │   ├── components/         # 模块组件
+│   │   ├── hooks/              # 模块 hooks
+│   │   ├── api.ts              # 模块 API 调用
+│   │   ├── types.ts            # 模块类型定义
+│   │   ├── constants.ts        # 模块常量
+│   │   └── index.ts            # 模块公开导出
+│   └── order/
+│
+├── components/                 # 全局共享 UI 组件
+│   ├── Button/
+│   │   ├── Button.tsx
+│   │   ├── Button.styles.css
+│   │   └── __tests__/
+│   ├── Modal/
+│   ├── Form/
+│   └── ErrorBoundary/          # 对 react-error-boundary 等的薄封装（函数组件）
+│
+├── hooks/                      # 全局共享 hooks
+│   ├── useAuth.ts
+│   ├── useDebounce.ts
+│   └── useMediaQuery.ts
+│
+├── services/                   # API 基础层
+│   ├── request.ts              # Axios/fetch 实例与拦截器
+│   └── endpoints/              # API 端点定义（如按领域拆分）
+│
+├── stores/                     # 全局状态管理
+│   ├── authStore.ts
+│   └── uiStore.ts
+│
+├── locales/                    # 国际化语言包
+│   ├── zh-CN.json              # 中文
+│   ├── en-US.json              # 英文
+│   └── index.ts                # i18n 实例初始化（i18next / react-intl）
+│
+├── assets/                     # 静态资源
+│   ├── images/                 # 图片（PNG、JPG、WebP）
+│   ├── icons/                  # SVG 图标
+│   └── fonts/                  # 自定义字体
+│
+├── config/                     # 应用配置
+│   ├── env.ts                  # 环境变量类型化封装
+│   └── features.ts             # Feature Flags 管理
+│
+├── types/                      # 全局共享类型
+│   ├── api.ts                  # API 响应/请求通用类型
+│   ├── models.ts               # 业务实体类型
+│   └── global.d.ts             # 全局类型扩展（图片模块声明等）
+│
+├── utils/                      # 纯工具函数
+│   ├── format.ts               # 日期、数字、货币格式化
+│   ├── validators.ts           # 表单校验规则
+│   └── storage.ts              # LocalStorage / SessionStorage 封装
+│
+├── styles/                     # 全局样式与主题
+│   ├── global.css              # 全局基础样式（reset / normalize）
+│   ├── variables.css           # CSS 变量（颜色、间距、字号）
+│   ├── breakpoints.ts          # 响应式断点常量
+│   └── themes/                 # 主题定义
+│       ├── light.css           # 亮色主题变量
+│       ├── dark.css            # 暗色主题变量
+│       └── index.ts            # 主题切换逻辑
+│
+└── constants/                  # 全局常量
+    ├── routes.ts               # 路由路径常量
+    └── config.ts               # 业务常量（分页大小、超时时间等）
+```
+
+### 关键原则
+
+- `pages/` 做路由映射和页面编排，不承载大块可复用业务逻辑
+- `layouts/` 负责页面骨架和布局容器，由路由配置引用
+- `features/` 按业务领域划分，模块内尽量自包含
+- `components/` 仅放跨页面、跨模块复用的通用组件
+- `hooks/` 仅放全局通用 hooks；业务 hooks 优先放回对应 feature 或 page
+- `locales/` 存放语言包 JSON 文件，组件中使用 `t('key')` 而非硬编码文案
+- `assets/` 存放静态资源，图标优先使用 SVG，图片优先使用 WebP/AVIF
+- `services/` 负责请求基础设施，不堆叠业务细节
+- `config/` 统一封装环境变量和特性开关，禁止组件中直接读取 `import.meta.env`
+- `styles/` 和主题变量统一管理，避免颜色和尺寸散落在业务代码中
+- 每个模块通过 `index.ts` 管控对外公开 API，避免深层路径导入
+
+---
+
+## 组件与模块分层
+
+推荐分层：
+
+```text
+页面组件 (Pages)        → 路由映射、布局组合、页面编排
+  └── 容器/编排层        → 数据获取、状态组织、事件编排
+       └── 业务组件      → 领域逻辑展示
+            └── 通用组件 → 无业务耦合、可跨模块复用
+```
+
+### 什么时候放到 `pages/`
+
+适合放：
+
+- 路由入口组件
+- 页面级布局组合
+- 页面私有的轻量编排逻辑
+
+不适合放：
+
+- 大量领域逻辑
+- 可复用于多个页面的复杂业务块
+- 与某个业务域强绑定的 API / hooks / types
+
+### 什么时候放到 `features/`
+
+适合放：
+
+- 某个业务域的组件、hooks、api、types
+- 可被多个页面共享但带业务语义的逻辑
+- 一个完整业务单元的自包含实现
+
+### 什么时候放到 `components/`
+
+适合放：
+
+- 按钮、弹窗、表单项、表格壳子、空态、错误态等通用 UI
+- 与具体业务无关、可跨模块复用的组件
+
+---
+
+## 组件设计规范
+
+- 使用**函数组件**、Hooks 与 TypeScript；**不要**新增类组件（Error Boundary 用 `react-error-boundary` 等库，见下文）
+- **单文件规模**与拆分原则见 `templates/shared/rules/fec-react.md`「**组件文件规模**」（约 300 行内为佳，逾 500 行或复杂度过高拆子组件、Hooks、utils、类型）
+- 保持组件职责单一、可组合
+- 将可复用逻辑提取到 hooks
+- 在合适场景优先使用受控组件 API
+- props 定义清晰且类型明确
+- 优先复用现有设计系统组件
+- 保持可访问性与键盘交互
+- 避免过深的 JSX 嵌套和重复分支
+- 对可推导的值不要额外存 state
+
+---
+
+
+## 组件目录建议
+
+当组件复杂度较低时，可只保留一个文件。  
+当组件包含样式、子组件、hooks、测试时，推荐使用如下结构：
+
+```text
+ComponentName/
+├── ComponentName.tsx
+├── ComponentName.types.ts
+├── ComponentName.styles.css
+├── hooks/
+│   └── useComponentLogic.ts
+├── components/
+│   └── SubComponent.tsx
+└── __tests__/
+    └── ComponentName.spec.tsx
+```
+
+说明：
+
+- 类型复杂时再拆 `ComponentName.types.ts`
+- 存在局部逻辑复用时再拆 `hooks/`
+- 子组件仅在当前组件内部使用时，放到当前目录 `components/`
+- 测试是否就近放置，应遵循仓库现有约定
+
+---
+