@bovinphang/frontend-craft 2.7.0 → 2.9.0

package/localized/zh-CN/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/localized/zh-CN/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/localized/zh-CN/skills/fec-pwa-implementation/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: fec-pwa-implementation
+description: 用于添加或审查 Progressive Web App 能力，如可安装性、manifest 元数据、Service Worker 注册、Workbox 缓存、离线兜底、应用更新提示、maskable icons 或 iOS PWA 兼容性。不要用于普通 API 缓存或不可安装的性能调优；中文触发词包括 PWA、离线、Service Worker。
+---
+
+# PWA 实现
+
+## 用途
+
+让 Web 应用具备可安装、离线兜底和可控更新能力。
+
+## 流程
+
+1. 确认 PWA 是否值得做：面向移动端/桌面安装、弱网离线、重复访问场景时优先；纯内部后台、强实时流媒体或只需要普通缓存时不要强行 PWA。
+2. 先补齐 manifest、图标、主题色和 HTML 引用；图标至少覆盖 192/512，Android 需 maskable，iOS 需 apple touch icon。
+3. 注册 Service Worker，并设计更新提示；不要静默 `skipWaiting()` 后强刷用户页面。
+4. 用 Workbox 或框架插件管理 precache/runtime cache；登录、支付、权限变更等敏感请求必须走网络。
+5. 提供 offline fallback 页面和安装提示 UI，并验证首次加载、离线访问、更新激活、卸载重装。
+
+## 详细参考
+
+- 需要 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)。
+
+## 约束
+
+- Service Worker 仅在 HTTPS 下工作（localhost 除外）。
+- 缓存策略必须区分页面、静态资源、API 与敏感操作；不要把登录、支付、权限接口缓存起来。
+- Service Worker 更新有生命周期延迟；用户可见刷新提示优先于强制刷新。
+- iOS PWA 能力弱于 Android，安装、推送和生命周期都要单独验证。
+- 缓存有配额和逐出机制，必须设置 max entries / max age。
+
+## 预期输出
+
+产出可安装的 Web 应用、离线 fallback、可见更新提示和明确缓存策略。验证 Lighthouse PWA、DevTools Application 面板、离线模式、更新发布和移动端安装流程。

package/localized/zh-CN/skills/fec-pwa-implementation/references/manifest-and-icons.md

@@ -0,0 +1,53 @@
+# Manifest、图标与安装入口
+
+## Manifest 示例
+
+```json
+{
+  "name": "我的应用",
+  "short_name": "应用",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#ffffff",
+  "theme_color": "#0052cc",
+  "description": "应用描述",
+  "icons": [
+    {
+      "src": "/icon-192.png",
+      "sizes": "192x192",
+      "type": "image/png",
+      "purpose": "any maskable"
+    },
+    {
+      "src": "/icon-512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "any maskable"
+    }
+  ],
+  "screenshots": [
+    {
+      "src": "/screenshot-desktop.png",
+      "sizes": "1280x720",
+      "type": "image/png",
+      "form_factor": "wide"
+    }
+  ]
+}
+```
+
+## HTML 引用
+
+```html
+<link rel="manifest" href="/manifest.json" />
+<meta name="theme-color" content="#0052cc" />
+<link rel="apple-touch-icon" href="/icon-192.png" />
+```
+
+## 检查要点
+
+- `display: "standalone"` 才有接近原生应用的启动体验。
+- `purpose: "any maskable"` 避免 Android 自适应图标被裁剪。
+- `start_url` 应指向登录后或游客可安全进入的入口。
+- `screenshots` 会影响安装对话框质量。
+- iOS 仍依赖 `apple-touch-icon`，安装提示也通常需要用户手动完成。

package/localized/zh-CN/skills/fec-pwa-implementation/references/service-worker-workbox.md

@@ -0,0 +1,68 @@
+# Service Worker、Workbox 与更新流
+
+## 注册 Service Worker
+
+```ts
+export function registerServiceWorker() {
+  if (!("serviceWorker" in navigator)) return;
+
+  window.addEventListener("load", async () => {
+    const registration = await navigator.serviceWorker.register("/sw.js", {
+      scope: "/",
+    });
+
+    registration.addEventListener("updatefound", () => {
+      const nextWorker = registration.installing;
+      nextWorker?.addEventListener("statechange", () => {
+        if (nextWorker.state === "installed" && navigator.serviceWorker.controller) {
+          showUpdatePrompt();
+        }
+      });
+    });
+  });
+}
+```
+
+## 缓存策略
+
+| 策略 | 适用 | 注意 |
+| --- | --- | --- |
+| `CacheFirst` | 带 hash 的图片、字体、CSS/JS | 必须设置过期策略 |
+| `NetworkFirst` | 页面导航、低风险 GET API | 网络失败才降级缓存 |
+| `StaleWhileRevalidate` | 字体、头像、低风险静态数据 | 用户会先看到旧数据 |
+| `NetworkOnly` | 登录、支付、权限、写操作 | 不进入 SW 缓存 |
+
+## Vite 集成
+
+```ts
+import { VitePWA } from "vite-plugin-pwa";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    VitePWA({
+      registerType: "prompt",
+      injectRegister: "auto",
+      workbox: {
+        globPatterns: ["**/*.{js,css,html,ico,png,svg,woff2}"],
+        runtimeCaching: [
+          {
+            urlPattern: /\.(?:png|jpg|jpeg|svg|gif|webp)$/,
+            handler: "CacheFirst",
+            options: {
+              cacheName: "images",
+              expiration: { maxEntries: 100, maxAgeSeconds: 30 * 24 * 60 * 60 },
+            },
+          },
+        ],
+      },
+    }),
+  ],
+});
+```
+
+## 离线与更新
+
+- 为未缓存页面准备 `/offline.html`，不要让用户只看到浏览器错误页。
+- 更新提示应说明“新版本已可用”，由用户确认刷新。
+- 调试时使用 DevTools Application 面板，必要时清理旧 Service Worker 和 Cache Storage。

package/localized/zh-CN/skills/fec-react-project-standard/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: fec-react-project-standard
+description: 用于设计或审查 React + TypeScript 项目结构、feature/module 边界、组件架构、hooks 组织、路由组合、状态/API/错误/样式默认约定或仓库级 React 规范。表单、数据获取、测试、无障碍、虚拟列表、动画或安全深挖优先使用更窄的 skill；中文触发词包括 React 项目规范、React 组件架构。
+---
+
+# React 项目规范
+
+适用于 React + TypeScript 仓库中的中大型模块建设、页面重构和工程结构设计。
+
+## 用途
+
+为 React + TypeScript 项目提供工程结构、模块边界和默认实现约定，确保架构清晰、代码可维护。
+
+## 流程
+
+本 skill 主要解决 React 工程任务“如何设计和落地”的问题，不重复声明基础编码底线。处理 React 工程化任务时，按以下顺序执行：
+
+1. 识别仓库已有约定
+   - 目录组织方式
+   - 样式体系
+   - 状态管理方案
+   - 请求封装方式
+   - 测试框架
+   - UI 组件库 / 设计系统
+
+2. 判断目标属于哪一层
+   - 路由页面
+   - 页面私有组件
+   - feature 业务模块
+   - 全局通用组件
+   - hooks / services / stores / utils
+
+3. 设计边界后再落代码
+   - 哪些逻辑属于页面编排
+   - 哪些逻辑属于 feature
+   - 哪些逻辑应下沉为通用能力
+   - 哪些状态应本地管理，哪些应交给 store / query / URL
+   - 状态归属复杂时使用状态管理流程先做状态清单
+   - DTO、公共 props、泛型组件或 `tsconfig` 边界复杂时，先使用 TypeScript 项目规范流程收敛跨框架类型契约
+
+4. 输出时补齐关键质量项
+   - loading / error / empty / data 状态
+   - 错误处理与重试
+   - 类型约束
+   - 关键测试入口
+   - 必要的专项 skill 分流
+   - 依赖是否已存在于 `package.json`，缺失时先给安装命令再使用
+   - 重型 UI 能力（动效、图表、3D、编辑器、地图）是否隔离为 leaf component 并按需加载
+   - 图片、视频、字体等资源是否本地化、可缓存，并避免占位 URL 进入交付
+   - 页面级 Error Boundary、模块级 fallback、API 错误映射和用户可恢复动作是否一致
+   - Tailwind token/variant 或响应式布局需求是否应分流到对应专项 skill
+   - 对明显架构性能风险做轻量筛查，如重型依赖边界、过宽 Context、高频派生值和懒加载 fallback；需要指标证据时进入性能优化 workflow
+
+## 详细参考
+
+按需要加载更细的参考文件：
+
+- 项目目录、组件分层、组件边界和组件目录建议：加载 [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)。
+
+## 约束
+
+- 默认遵守仓库现有全局规则和 React rule
+- 若仓库已有明确目录结构、样式体系、状态管理或请求封装，优先沿用仓库约定
+- 组件文件规模宜约 **300 行**内；逾 **500 行**或复杂度过高须拆分子组件、Hooks、utils、类型
+- 禁止新增类组件（Error Boundary 用 `react-error-boundary` 等库）
+- 禁止绕过模块出口，从 feature 深层路径导入
+- 不要用 `useEffect + setState` 模拟本可直接计算的派生值
+- 避免 prop drilling 过深却不考虑组合或局部封装
+- 不在通用页面组件里同步引入 GSAP、Three.js、Lottie、富文本编辑器或地图 SDK；需要时用动态导入、路由级分包或叶子组件隔离。
+- 不在 React 组件中散落裸 `fetch`、API URL、token refresh 或上传流程；跨边界请求应收敛到 API 集成层。
+- 不用 Error Boundary 处理普通 API 失败；请求错误应优先落到 loading/error/empty/data 状态和可恢复操作。
+- 不把 React 性能建议写成无证据的全局 memo 化；先定位请求瀑布、bundle 边界、重复渲染或 effect 误用。
+
+## 预期输出
+
+- 组件边界清晰，pages/features/components 分层明确
+- Props 类型完整且明确；复杂公共类型或外部数据收窄已分流到 TypeScript 项目规范流程
+- 可复用逻辑已提取为 hooks，loading/error/empty/data 状态齐全
+- API 层具备类型约束和统一错误处理，状态管理符合就近原则
+- URL 状态、服务端状态、表单状态和全局客户端状态边界明确
+- 关键行为有测试覆盖，关键模块已用 `react-error-boundary` 包裹
+- 超长列表已评估虚拟化，弹窗/复合组件具备键盘与焦点支持
+- 先尊重仓库现状，再给推荐结构
+- 给出必要的文件划分建议
+- 必要时说明为什么这样分层
+- 对新增模块，优先输出最小可落地结构，而不是一次性过度设计
+- 对重构任务，优先保证可迁移性和风险可控
+- 对性能相关 React 变更，说明触发的风险类别、证据来源和验证命令

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

@@ -0,0 +1,35 @@
+# React 性能模式
+
+本文件保留轻量级 React 项目规范性能指导。当任务需要指标、trace、profile、包体分析、网络证据或正式性能报告时，使用前端性能工作流。
+
+### 性能（与「性能优化」一节配合）
+
+- **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/localized/zh-CN/skills/fec-react-project-standard/references/react-project-structure.md

@@ -0,0 +1,197 @@
+# React 项目结构与组件边界
+
+## 项目结构（推荐参考）
+
+以下为中大型 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/`
+- 测试是否就近放置，应遵循仓库现有约定
+
+---
+