@bovinphang/frontend-craft 2.5.0

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

@@ -0,0 +1,227 @@
+# 响应式设计规则
+
+凡是任务涉及移动端适配、响应式布局、多端兼容时，都应用本文件。
+
+## 核心原则
+
+- **移动优先**: 从小屏幕开始设计，逐步增强到大屏幕
+- **内容优先**: 移动端优先展示核心内容，次要内容折叠或延后
+- **触摸友好**: 所有交互元素必须适配手指操作
+- **性能优先**: 移动端网络和设备性能较弱，需优化加载
+- **容器感知**: 可复用组件优先适配所在容器，而不是假设整页断点
+- **稳定尺寸**: 工具栏、表格列、棋盘、卡片网格和计数器需要稳定约束，避免状态变化导致布局跳动
+
+## 断点策略
+
+| 断点        | 宽度   | 设备            | Tailwind | 说明                 |
+| ----------- | ------ | --------------- | -------- | -------------------- |
+| **Mobile**  | 375px  | 手机竖屏        | （默认） | 基础样式，无媒体查询 |
+| **Tablet**  | 768px  | 平板 / 手机横屏 | `md:`    | 两列布局起点         |
+| **Desktop** | 1024px | 笔记本          | `lg:`    | 完整布局             |
+| **Large**   | 1280px | 桌面显示器      | `xl:`    | 宽屏优化             |
+| **XLarge**  | 1536px | 超宽屏          | `2xl:`   | 最大内容宽度         |
+
+### 移动优先 CSS
+
+```css
+/* 基础样式 — 移动端 */
+.container {
+  padding: 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+/* Tablet — 768px+ */
+@media (min-width: 768px) {
+  .container {
+    padding: 24px;
+    flex-direction: row;
+    gap: 24px;
+  }
+}
+
+/* Desktop — 1024px+ */
+@media (min-width: 1024px) {
+  .container {
+    max-width: 960px;
+    margin: 0 auto;
+    padding: 32px;
+  }
+}
+```
+
+### Tailwind 移动优先
+
+Tailwind 默认移动优先，无前缀类作用于所有屏幕，前缀仅覆盖更大断点：
+
+```html
+<!-- 移动端: 单列, 小间距 | Tablet: 双列 | Desktop: 三列 -->
+<div
+  class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4 md:gap-6 lg:gap-8"
+>
+  <!-- 卡片: 移动端小字, Desktop 大字 -->
+  <div class="p-4 md:p-6 text-sm md:text-base">...</div>
+</div>
+
+<!-- 导航: 移动端隐藏, Desktop 显示 -->
+<nav class="hidden md:flex">...</nav>
+
+<!-- 移动端汉堡菜单, Desktop 隐藏 -->
+<button class="md:hidden" aria-label="菜单">☰</button>
+```
+
+**关键约定**：
+
+- 始终使用 `min-width` 媒体查询（mobile-first），不用 `max-width`
+- Tailwind 前缀从小到大：`sm:` → `md:` → `lg:` → `xl:`
+- 不要在桌面端写默认样式然后用 `max-width` 覆盖移动端
+
+## 触摸目标
+
+| 元素        | 最小尺寸  | 说明                        |
+| ----------- | --------- | --------------------------- |
+| 按钮        | 44×44px   | WCAG 2.2 触摸目标要求       |
+| 链接        | 44×44px   | 可通过 padding 扩大点击区域 |
+| 表单输入    | 44px 高度 | 避免 iOS 自动缩放           |
+| 复选框/单选 | 24×24px   | 最小可见尺寸                |
+| 关闭按钮    | 44×44px   | 模态框、Toast 的关闭按钮    |
+
+```css
+/* 扩大点击区域（视觉尺寸不变） */
+.icon-button {
+  width: 24px;
+  height: 24px;
+  padding: 10px; /* 实际点击区域 44×44 */
+}
+
+/* 表单输入 — 避免 iOS 缩放 */
+input,
+select,
+textarea {
+  font-size: 16px; /* < 16px 时 iOS Safari 会自动缩放页面 */
+}
+```
+
+## 布局模式
+
+### Container Query
+
+当组件会出现在侧栏、弹窗、卡片和主内容区等不同容器时，优先使用容器查询：
+
+```css
+.summary-panel {
+  container-type: inline-size;
+}
+
+@container (min-width: 42rem) {
+  .summary-panel__body {
+    display: grid;
+    grid-template-columns: 16rem minmax(0, 1fr);
+  }
+}
+```
+
+Flex/Grid 子项包含长文本、图表、代码或表格时，记得设置 `min-width: 0`。
+
+### Stack → Row
+
+移动端纵向堆叠，桌面端横向排列：
+
+```html
+<div class="flex flex-col md:flex-row gap-4">
+  <div class="flex-1">主内容</div>
+  <div class="md:w-64 md:flex-shrink-0">侧边栏</div>
+</div>
+```
+
+### 响应式表格
+
+```html
+<!-- 小屏横向滚动 -->
+<div class="overflow-x-auto">
+  <table class="min-w-full">
+    ...
+  </table>
+</div>
+
+<!-- 或：移动端卡片式布局 -->
+<div class="hidden md:block">
+  <table>
+    ...
+  </table>
+</div>
+<div class="md:hidden">
+  <!-- 每行变为卡片 -->
+</div>
+```
+
+移动端数据密集视图需先定义列优先级：主标识、状态和主操作优先保留；低优先级字段进入详情、展开行或抽屉。
+
+### 响应式图片
+
+```html
+<!-- srcset 按设备像素比加载 -->
+<img
+  src="/img/hero-800.jpg"
+  srcset="
+    /img/hero-400.jpg   400w,
+    /img/hero-800.jpg   800w,
+    /img/hero-1200.jpg 1200w
+  "
+  sizes="(max-width: 768px) 100vw, 800px"
+  alt="描述"
+  loading="lazy"
+/>
+
+<!-- picture 元素按断点切换 -->
+<picture>
+  <source
+    media="(min-width: 1024px)"
+    srcset="/img/hero-desktop.webp"
+    type="image/webp"
+  />
+  <source
+    media="(min-width: 768px)"
+    srcset="/img/hero-tablet.webp"
+    type="image/webp"
+  />
+  <img src="/img/hero-mobile.webp" alt="描述" loading="lazy" />
+</picture>
+```
+
+## 移动端交互注意
+
+- **悬停不可靠**: 移动端无 hover 状态，不要将关键功能隐藏在 hover 中（如 tooltip 改为点击触发）
+- **键盘弹出**: 移动端虚拟键盘会缩小可视区域，固定定位元素需注意位置调整
+- **滚动性能**: 使用 `-webkit-overflow-scrolling: touch`（iOS）或 `overscroll-behavior` 优化滚动体验
+- **安全区域**: 适配 iPhone 刘海/底部横条，使用 `env(safe-area-inset-*)`：
+
+```css
+.app-content {
+  padding-top: env(safe-area-inset-top);
+  padding-bottom: env(safe-area-inset-bottom);
+  padding-left: env(safe-area-inset-left);
+  padding-right: env(safe-area-inset-right);
+}
+```
+
+## 测试策略
+
+- 使用 Chrome DevTools Device Mode 测试主流设备
+- 优先在真实设备上测试（iOS Safari / Android Chrome）
+- 测试方向切换（横屏 / 竖屏）
+- 测试不同网络条件（3G / 4G / 弱网）
+- 不要假设桌面端是"默认"，移动端优先验证
+
+## 检查清单
+
+- [ ] 375px 宽度下布局正常，无水平溢出
+- [ ] 所有交互元素 ≥ 44×44px（触摸目标）
+- [ ] 输入框 font-size ≥ 16px（避免 iOS 缩放）
+- [ ] 无 hover 依赖的关键功能
+- [ ] 图片使用 srcset / picture 按设备加载
+- [ ] iPhone 安全区域适配（safe-area-inset）
+- [ ] 内容在断点间平滑过渡，无突变
+- [ ] 断点中间值、横竖屏切换和虚拟键盘弹出不遮挡主操作
+- [ ] 数据密集区域有列优先级或局部滚动策略

package/templates/shared/rules/fec-source-driven-development.md

@@ -0,0 +1,31 @@
+# 来源驱动开发规则
+
+当实现依赖框架、库、浏览器、运行时、构建工具或平台行为时，先确认事实来源，再写代码或评审结论。
+
+## 事实来源优先级
+
+1. 项目内 README、配置、测试、模板和已有实现。
+2. 官方文档、源码、类型定义、release notes、migration guide。
+3. Web 标准、浏览器兼容数据和平台文档。
+4. Issue、讨论、博客和第三方文章仅作为线索。
+
+## 使用场景
+
+- 框架新版本、路由、渲染模式、缓存、构建配置、浏览器 API。
+- 公共接口、组件 API、设计系统 token、CLI 命令和插件元数据。
+- 依赖升级、迁移、废弃 API 替换、跨运行时兼容。
+- 与安全、性能、可访问性相关的版本敏感判断。
+
+## 输出要求
+
+- 写清来源、版本或项目事实、决策结论、影响范围和验证方式。
+- 若项目现状与官方推荐冲突，说明冲突原因和渐进迁移策略。
+- 不复制长篇外部文档；只保留必要结论、链接或项目内文件路径。
+- 无法验证时标注不确定性和需要用户/团队确认的事项。
+
+## 反模式
+
+- 凭记忆使用版本敏感 API。
+- 用过时教程替代官方文档。
+- 为追新推翻稳定项目约定。
+- 在组件里散落外部库行为假设，而不是集中到适配层。

package/templates/shared/rules/fec-state-management.md

@@ -0,0 +1,163 @@
+# 状态管理规范
+
+## 状态分类
+
+| 类型         | 示例                             | 存放位置            |
+| ------------ | -------------------------------- | ------------------- |
+| 组件 UI 状态 | modal 开关、tab 索引、hover 状态 | 组件内 state        |
+| 表单状态     | 输入值、校验错误                 | 表单库或组件 state  |
+| 服务端数据   | 用户列表、订单详情               | 数据请求库缓存      |
+| 全局业务状态 | 当前用户、权限、主题             | 全局 Store          |
+| URL 状态     | 当前页码、筛选条件、排序         | 路由参数 / 搜索参数 |
+
+## 核心原则
+
+- **就近管理**: 状态放在需要它的最近公共祖先
+- **单一数据源**: 同一份数据只在一个地方维护
+- **派生优于同步**: 可计算的值用 computed / useMemo，而不是手动同步多个 state
+- **最小状态**: 不存储可以从已有状态推导的值
+
+## React 状态管理
+
+### 本地状态
+
+```tsx
+// 简单值 - useState
+const [count, setCount] = useState(0);
+
+// 复杂逻辑 - useReducer
+const [state, dispatch] = useReducer(formReducer, initialState);
+```
+
+### 全局状态（Zustand 示例）
+
+<!-- 请根据项目实际选型调整：Redux Toolkit / Zustand / Jotai -->
+
+```tsx
+const useAuthStore = create<AuthState>((set) => ({
+  user: null,
+  login: async (credentials) => {
+    const user = await authApi.login(credentials);
+    set({ user });
+  },
+  logout: () => set({ user: null }),
+}));
+```
+
+### 服务端状态
+
+<!-- 请根据项目实际选型调整：React Query / SWR -->
+
+```tsx
+const { data, isLoading, error } = useQuery({
+  queryKey: ["users", params],
+  queryFn: () => fetchUsers(params),
+  staleTime: 5 * 60 * 1000,
+});
+```
+
+## Vue 状态管理
+
+### 本地状态
+
+```typescript
+const count = ref(0);
+const form = reactive({ name: "", email: "" });
+```
+
+### 全局状态（Pinia）
+
+```typescript
+export const useAuthStore = defineStore("auth", () => {
+  const user = ref<User | null>(null);
+
+  async function login(credentials: LoginParams) {
+    user.value = await authApi.login(credentials);
+  }
+
+  function logout() {
+    user.value = null;
+  }
+
+  const isLoggedIn = computed(() => user.value !== null);
+
+  return { user: readonly(user), isLoggedIn, login, logout };
+});
+```
+
+### 服务端状态
+
+<!-- 请根据项目实际选型调整：VueQuery / 自定义 composable -->
+
+```typescript
+const { data, isLoading, error } = useQuery({
+  queryKey: ["users", params],
+  queryFn: () => fetchUsers(toValue(params)),
+});
+```
+
+## 选型决策矩阵
+
+### React 全局状态管理选型
+
+| 维度           | Context API                            | Zustand                                | Redux Toolkit                   | Jotai               |
+| -------------- | -------------------------------------- | -------------------------------------- | ------------------------------- | ------------------- |
+| **适用场景**   | 全局常量（主题、语言、用户信息）       | 复杂业务状态（购物车、Dashboard 筛选） | 大型应用，需要严格的状态流控制  | 细粒度原子状态      |
+| **重渲染性能** | ❌ 任何 value 变化导致所有消费者重渲染 | ✅ 通过 selector 精确订阅              | ✅ connect/useSelector 精确订阅 | ✅ 原子级订阅       |
+| **样板代码**   | 少（Provider + createContext）         | 极少（一个 create 调用）               | 多（slice / action / selector） | 极少（atom）        |
+| **DevTools**   | ❌ 无                                  | ✅ Redux DevTools（中间件）            | ✅ Redux DevTools               | ✅ 专用 DevTools    |
+| **TypeScript** | ⚠️ 需手动类型标注                      | ✅ 自动推导                            | ✅ 自动推导                     | ✅ 自动推导         |
+| **中间件**     | ❌                                     | ✅（persist / devtools / immer）       | ✅（thunk / listener）          | ✅                  |
+| **Provider**   | ✅ 必须包裹                            | ❌ 不需要（外部 store）                | ✅ Provider                     | ❌（可选 Provider） |
+
+**推荐决策流程**：
+
+```
+状态是否跨组件共享？
+├── 否 → useState / useReducer（本地状态）
+└── 是
+    ├── 值是否几乎不变？（主题、语言、配置）
+    │   └── 是 → Context API
+    │
+    ├── 是否需要严格状态流 + 时间旅行调试？
+    │   └── 是 → Redux Toolkit
+    │
+    ├── 状态是否高度关联、需要集中管理？
+    │   └── 是 → Zustand
+    │
+    └── 状态是否独立、需要细粒度订阅？
+        └── 是 → Jotai
+```
+
+### Vue 全局状态管理选型
+
+| 维度           | provide/inject                     | Pinia            |
+| -------------- | ---------------------------------- | ---------------- |
+| **适用场景**   | 局部跨层级传递（主题、表单上下文） | 全局业务状态     |
+| **响应式**     | ✅（传入 reactive/ref）            | ✅               |
+| **DevTools**   | ❌                                 | ✅ Vue DevTools  |
+| **TypeScript** | ⚠️ 需 InjectionKey                 | ✅ 自动推导      |
+| **SSR 安全**   | ⚠️ 需注意作用域                    | ✅ 内置 SSR 支持 |
+
+**Vue 选型结论**：Pinia 是 Vue 3 官方推荐，新项目直接使用。provide/inject 仅用于局部上下文传递。
+
+---
+
+## 反模式
+
+- 将所有状态都放进全局 store（应优先本地状态）
+- 在 store 中存放 UI 临时状态（modal 开关、表单输入等）
+- 手动同步多份相同数据而不是用计算属性
+- 在组件中直接修改 store 的内部数据（应通过 action / mutation）
+- 将服务端响应原封不动存入全局 store 而不用请求缓存库
+- 过度使用 Context / provide 替代 props 传递
+- 用 Context 管理频繁更新的状态（导致全量消费者重渲染，应改用 Zustand/Pinia）
+
+## 检查清单
+
+- [ ] 每个状态都有明确的归属（本地 / 全局 / URL / 服务端缓存）
+- [ ] 可派生的值没有被存为独立 state
+- [ ] 全局 store 仅包含真正需要跨组件共享的数据
+- [ ] 服务端数据通过请求库管理，而非手动存入 store
+- [ ] URL 状态（搜索、分页、筛选）与路由参数同步
+- [ ] Context 仅用于低频变更的全局值（主题、语言、用户信息）

package/templates/shared/rules/fec-testing.md

@@ -0,0 +1,98 @@
+# 测试与校验规则
+
+凡是新增、修改、重构或评审代码时，都应用本文件。
+
+## 校验顺序
+
+优先按以下顺序执行：
+
+1. lint
+2. type check
+3. unit test
+4. build
+
+优先使用仓库已有脚本。
+如果命令不确定，先检查 `package.json`。
+
+## 改动校验原则
+
+- 先修复范围最小且正确的问题
+- 每次关键修复后重新执行受影响的命令
+- 不要盲目压掉报错或关闭规则
+- 不要为了通过检查而降低类型安全
+- 不要因为一个局部测试失败就重写无关模块
+
+## 测试要求
+
+新增或修改行为时，考虑是否需要覆盖以下内容：
+
+- 组件渲染
+- 交互行为
+- 状态切换
+- 边界场景
+- loading / empty / error 状态
+- 与可访问性相关的关键交互
+
+如果没有补测试，需要说明原因。
+
+## Fixture 与 Mock
+
+- Fixture 表达业务场景，不使用随机、无语义或只对测试作者有意义的数据
+- 复杂对象使用 builder 填充默认值，每个测试只覆盖当前场景相关字段
+- 测试间不共享可变全局状态、fake timer、store 或 mock server handler
+- 网络 mock 应模拟公开契约和用户可见错误，不复制后端内部实现
+
+## TDD 与回归测试
+
+新增行为、修复 Bug 或重构关键逻辑时，优先采用 TDD：
+
+1. 先写能描述期望行为的失败测试。
+2. 运行测试并确认失败原因正确。
+3. 写最小实现让测试通过。
+4. 测试保持通过后再重构。
+
+Bug 修复应优先保留能复现问题的回归测试。若现有项目缺少测试基础设施，不要盲目引入新框架；先给出最小测试落地建议并说明维护成本。
+
+## 代码评审输出风格
+
+评审代码时，返回：
+
+- 总体评估
+- 必修问题
+- 建议优化
+- 可选优化项
+- 风险等级
+
+结论要具体且可执行。
+
+## E2E 测试规则
+
+使用 Playwright 或 Cypress 时：
+
+- 遵循 **Page Object**，spec 内不写裸选择器；优先 **`data-testid`**，其次 **`role` / `label`**
+- 用 **`test.describe` + `beforeEach`** 组织场景，单用例可独立运行、不依赖执行顺序
+- 禁止用固定 **`sleep`** 当主要同步手段；用 **Locator 自动等待**、`expect`、`waitForResponse` 等
+- Playwright：**`playwright.config.ts`** 中配置 `baseURL`、CI 下 `retries`/`workers`、`trace`/`screenshot`/`video`、**`webServer`** 与多 **`projects`（含移动端）**
+- 关键流程至少覆盖桌面、平板、移动端视口（或等价 device 项目）
+- **不稳定用例**：`test.fixme` / `test.skip` 需写原因与 issue；用 `--repeat-each` 辅助定位 flaky
+- 失败时保留 **截图、Trace、视频**，CI 用 **artifact** 上传 HTML 报告与产物
+- 高风险/资金类流程：**勿在生产跑真实 E2E**；staging 或 mock，必要时 `test.skip`
+- 测试数据可重复：优先 seed、测试账号或 mock 服务；随机值必须带唯一前缀并在 teardown 清理
+
+详细模式与示例见插件 **`fec-e2e-testing`** skill。
+
+## 重构规则
+
+进行重构时：
+
+- 除非任务明确要求改行为，否则保持行为一致
+- 说明可能的迁移风险
+- 优先做渐进式修改，而不是大范围重写
+- 总结改动文件、执行过的命令和剩余风险
+
+## 验证失败处理
+
+- 按文件和根因分组错误，一次修复一类问题。
+- 每次修复后重新运行最近的失败命令。
+- 不删除失败测试、不关闭规则、不降低类型安全来换取通过。
+- 同一错误多次修复仍失败时，停止扩大改动并报告阻塞。