@bovinphang/frontend-craft 2.5.0 → 2.7.0

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

@@ -0,0 +1,59 @@
+# 性能分析报告模板
+
+```markdown
+# 前端性能分析报告
+
+> 生成时间: YYYY-MM-DD HH:mm
+> 目标页面/流程: ...
+> 环境: 设备、浏览器、网络、分支或版本
+
+## 性能目标
+
+- 关注指标: LCP / CLS / INP / TBT / bundle size / memory / FPS
+- 项目预算或目标阈值
+- 用户主路径和 P95 场景
+
+## 基线数据
+
+| 指标 | 当前值 | 采集方式 | 备注 |
+| --- | --- | --- | --- |
+| LCP | ... | Lighthouse / RUM / trace | ... |
+
+## 瓶颈定位
+
+- 加载层、渲染层、数据层、主线程或资源层问题
+- 关联文件、路由、chunk、组件或请求
+- 支持该判断的 trace、bundle、日志或截图证据
+
+## 候选门禁
+
+| 候选问题 | 指标支撑 | 定位范围 | 前端可验证性 | 结论 |
+| --- | --- | --- | --- | --- |
+| ... | RUM / trace / bundle / network | route / component / chunk / request | 是 / 否 / 需协作 | investigate / defer / reject |
+
+## 优先级
+
+| 优先级 | 问题 | 用户影响 | 风险 |
+| --- | --- | --- | --- |
+| P0 / P1 / P2 | ... | ... | ... |
+
+## 优化方案
+
+- 具体改法
+- 替代方案
+- 可维护性、可访问性和产品行为影响
+
+## 验证对比
+
+| 指标 | 优化前 | 优化后 | 采集方式 |
+| --- | --- | --- | --- |
+| ... | ... | ... | ... |
+
+## 剩余风险
+
+- 未覆盖设备、网络或浏览器
+- 需要后端、设计、产品或基础设施协作的部分
+- 建议监控或后续任务
+```
+
+分析完成后，将报告保存到 `reports/performance-review-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。

package/skills/fec-pwa-implementation/SKILL.md

@@ -17,10 +17,10 @@ description: Use when adding or reviewing Progressive Web App capabilities such
 4. 用 Workbox 或框架插件管理 precache/runtime cache；登录、支付、权限变更等敏感请求必须走网络。
 5. 提供 offline fallback 页面和安装提示 UI，并验证首次加载、离线访问、更新激活、卸载重装。
 
-## Detailed References
+## 详细参考
 
-- Load [references/manifest-and-icons.md](references/manifest-and-icons.md) for manifest fields, HTML links, icon requirements, screenshots, and iOS notes.
-- Load [references/service-worker-workbox.md](references/service-worker-workbox.md) for Service Worker registration, Workbox strategies, Vite integration, offline fallback, and update flow.
+- 需要 manifest 字段、HTML 引用、图标要求、截图和 iOS 注意事项时，加载 [references/manifest-and-icons.md](references/manifest-and-icons.md)。
+- 需要 Service Worker 注册、Workbox 策略、Vite 集成、离线兜底和更新流程时，加载 [references/service-worker-workbox.md](references/service-worker-workbox.md)。
 
 ## Constraints
 
@@ -33,4 +33,3 @@ description: Use when adding or reviewing Progressive Web App capabilities such
 ## Expected Output
 
 产出可安装的 Web 应用、离线 fallback、可见更新提示和明确缓存策略。验证 Lighthouse PWA、DevTools Application 面板、离线模式、更新发布和移动端安装流程。
-

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
 
-## Detailed References
+## 详细参考
 
-需要具体 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/`
+- 测试是否就近放置，应遵循仓库现有约定
+
+---
+

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

@@ -0,0 +1,131 @@
+# React quality patterns
+
+## 样式接入
+
+本 skill 不强制具体样式方案，默认遵循仓库现状。
+
+适配时注意：
+
+- Tailwind 项目继续使用 Tailwind
+- CSS Modules 项目保持命名与文件组织一致
+- styled-components 项目继续沿用其模式
+- 主题、颜色、字号、间距等优先复用仓库 token / CSS 变量
+- 避免在组件内硬编码大量视觉常量
+- 禁止内联样式（除动态值外）
+- 响应式处理需与项目断点约定一致
+
+---
+
+## 注释规范
+
+- **优先使用中文**：解释「为什么这样做」、业务约束、边界情况、非显而易见的权衡时，优先用中文撰写注释，便于团队与业务方阅读。
+- **与代码语言一致时的例外**：对接第三方协议字段名、HTTP 头、规范中的英文术语时，注释里可保留英文专有名词，必要时中英文并列说明。
+- **少而精**：能通过清晰命名与类型表达清楚的逻辑不写废话注释；复杂分支、临时兼容、性能取舍必须写清意图。
+- **公开 API**：模块或 hooks 的对外契约可用 JSDoc（`@param` / `@returns` / `@example`），说明用中文即可，除非仓库统一要求英文。
+
+---
+
+## TypeScript 规范
+
+通用 TypeScript 工程规则由 `fec-typescript-project-standard` 负责，包括 `tsconfig`、strictness、DTO / view model 边界、`unknown` 收窄、public API 类型、声明产物和类型测试。
+
+React 规范只补充组件、Props、事件和 TSX 泛型写法；复杂类型建模或跨框架类型契约先分流到 `fec-typescript-project-standard`。
+
+### React 项目补充约定
+
+- Props interface 命名: `ComponentNameProps`
+- 事件处理函数: `handle` 前缀（如 `handleClick`）
+- 回调 Props: `on` 前缀（如 `onChange`、`onSubmit`）
+- 组件优先写显式 props 与返回值类型（`JSX.Element` / `React.ReactElement`），避免依赖 `React.FC` 的隐式 `children` 等行为差异
+- 泛型组件使用 `<T>` 约束，保持调用处类型推导；回调与事件类型优先使用 DOM / React 自带类型（如 `React.ChangeEvent<HTMLInputElement>`）
+
+```tsx
+interface TableProps<T extends Record<string, unknown>> {
+  data: T[];
+  columns: ColumnDef<T>[];
+  onRowClick?: (row: T) => void;
+}
+```
+
+---
+
+## 测试规范
+
+### 应优先覆盖的内容
+
+- 核心交互行为（点击、输入、提交）
+- 条件渲染（loading / error / empty / data）
+- 关键 hooks 的返回值和副作用
+- API 调用 mock 与模块级集成测试
+
+### 推荐风格
+
+- 测试用户行为，而不是实现细节
+- 优先使用 `screen.getByRole`、`getByLabelText`
+- 避免围绕内部 state 写脆弱测试
+- 只测关键行为，不机械追求覆盖率数字
+
+### 示例
+
+```tsx
+describe("UserForm", () => {
+  it("should submit with valid data", async () => {
+    const onSubmit = vi.fn();
+    render(<UserForm onSubmit={onSubmit} />);
+
+    await userEvent.type(screen.getByLabelText("用户名"), "test");
+    await userEvent.click(screen.getByRole("button", { name: "提交" }));
+
+    expect(onSubmit).toHaveBeenCalledWith({ username: "test" });
+  });
+
+  it("should show error on invalid input", async () => {
+    render(<UserForm onSubmit={vi.fn()} />);
+    await userEvent.click(screen.getByRole("button", { name: "提交" }));
+    expect(screen.getByText("用户名不能为空")).toBeInTheDocument();
+  });
+});
+```
+
+---
+
+
+## 常见反模式
+
+避免：
+
+- prop drilling 过深却不考虑组合或局部封装
+- 对局部问题过度使用 context
+- 把数据请求、视图渲染、命令式 DOM 操作全塞进一个文件
+- 在 useEffect 中做可以在事件处理函数中完成的事
+- 用 `useEffect + setState` 模拟本可直接计算的派生值
+- 将所有状态都推进全局 store
+- 在 `components/` 中放业务耦合组件
+- 直接绕过模块出口，从 feature 深层路径导入
+- 没有明显收益却提前做复杂优化
+- **新增类组件**或手写类式 Error Boundary（应函数组件 + `react-error-boundary` 等）
+
+---
+
+## 输出检查清单
+
+输出 React 代码或方案时，至少检查：
+
+- [ ] 是否先对齐了仓库现有约定
+- [ ] 页面 / feature / 通用组件边界是否清晰
+- [ ] 目录结构是否与模块复杂度匹配
+- [ ] Props 类型完整且明确
+- [ ] 解释性注释是否优先使用中文且点到要害
+- [ ] 可复用逻辑是否已提取为 hooks
+- [ ] loading / error / empty / data 状态是否齐全
+- [ ] API 层是否具备类型约束和统一错误处理
+- [ ] 复杂 DTO、外部数据收窄、公共类型或 `tsconfig` 问题是否已分流到 `fec-typescript-project-standard`
+- [ ] 状态管理是否符合就近原则
+- [ ] 路由级或重型模块是否考虑懒加载
+- [ ] 样式方案是否与仓库保持一致
+- [ ] 关键行为是否有测试覆盖
+- [ ] 关键模块已用 **`react-error-boundary`**（等）包裹，且未手写类组件式 Boundary
+- [ ] 超长列表是否评估虚拟化；弹窗/复合组件是否具备键盘与焦点约定
+- [ ] 是否引入了不必要的新依赖或新范式
+
+---