@bovinphang/frontend-craft 2.5.0

package/templates/shared/rules/fec-ci-cd.md

@@ -0,0 +1,128 @@
+# CI/CD 规则
+
+本文件约定持续集成与部署流水线的结构与行为。
+
+## 流水线阶段
+
+建议顺序：
+
+1. **安装依赖** — `npm ci` 或 `pnpm install --frozen-lockfile`
+2. **Lint** — ESLint、Stylelint
+3. **类型检查** — `tsc --noEmit`
+4. **单元测试** — Jest / Vitest
+5. **构建** — `npm run build` 或 `pnpm build`
+6. **包体/性能预算**（可选）— size-limit、Lighthouse CI、bundle analyzer
+7. **依赖与供应链检查**（可选）— audit、license、lockfile diff、依赖升级验证
+8. **E2E 测试**（可选）— Playwright / Cypress
+9. **部署** — 构建产物上传或触发部署服务
+
+任一阶段失败则中止后续步骤。
+
+## GitHub Actions 示例
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v2
+        with:
+          version: 8
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run lint
+      - run: pnpm run typecheck
+      - run: pnpm run test
+      - run: pnpm run build
+
+      - name: Upload build
+        if: success() && github.ref == 'refs/heads/main'
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+```
+
+## GitLab CI 示例
+
+```yaml
+stages:
+  - install
+  - lint
+  - test
+  - build
+  - deploy
+
+variables:
+  PNPM_VERSION: "8"
+
+install:
+  stage: install
+  script:
+    - corepack enable pnpm
+    - pnpm install --frozen-lockfile
+  cache:
+    key: ${CI_COMMIT_REF_SLUG}
+    paths:
+      - node_modules/
+      - .pnpm-store/
+
+lint:
+  stage: lint
+  script:
+    - pnpm run lint
+    - pnpm run typecheck
+  needs: [install]
+
+test:
+  stage: test
+  script:
+    - pnpm run test
+  needs: [install]
+
+build:
+  stage: build
+  script:
+    - pnpm run build
+  artifacts:
+    paths:
+      - dist/
+  needs: [lint, test]
+```
+
+## 环境变量与密钥
+
+- 敏感信息使用 CI 平台的 Secrets，不写入仓库
+- 构建时注入 `VITE_*` / `NEXT_PUBLIC_*` 等前端环境变量
+- E2E 的 baseURL、测试账号等从 Secrets 读取
+- 只允许公开前缀的环境变量进入客户端 bundle；服务端密钥不得使用 `VITE_*` / `NEXT_PUBLIC_*`
+
+## 产物与证据
+
+- 上传测试报告、覆盖率、E2E trace、截图、构建产物和性能预算结果。
+- CI 失败时保留足够日志定位根因，不只返回“命令失败”。
+- 发布前确认版本、变更说明、迁移事项和回滚路径。
+- 依赖升级 PR 保留 lockfile diff、关键包版本、release notes 摘要和验证矩阵。
+- Monorepo affected 快速验证可以用于 PR 反馈，但 release 或主干合并前应保留全量验证入口。
+
+## 强约束
+
+- 使用锁文件（`package-lock.json`、`pnpm-lock.yaml`），禁止 `npm install` 无锁安装
+- 构建产物不提交到仓库，由 CI 生成并上传
+- 部署前必须通过 lint、typecheck、test、build
+- 不跳过失败门禁直接部署，除非有明确风险接受和回滚方案

package/templates/shared/rules/fec-code-comments.md

@@ -0,0 +1,33 @@
+# 代码注释
+
+编写或评审前端实现时应用本文件。
+
+## 原则
+
+- 意图优先靠**命名、类型与结构**表达；注释用于说明**为什么**、**约束与背景**，而不是复述代码在做什么。
+- 避免「整文件零注释」：在**非显而易见**处用**简短**注释降低误改成本，与「不写废话注释」不矛盾。
+
+## 应当注释的情况
+
+- **业务或产品规则**：权限、展示条件、校验逻辑背后的依据（与需求或领域约定相关时）。
+- **非直观的实现或取舍**：为何选用当前写法（性能、兼容、与后端/第三方约定等）。
+- **外部契约**：与接口、设计稿、枚举或单位相关的字段含义、映射关系。
+- **临时方案与技术债**：`TODO` / `FIXME` 应写明预期收尾或关联工单（若有）。
+- **易踩坑点**：第三方库版本差异、必须满足的调用顺序、已知限制。
+
+## 应避免的情况
+
+- 逐行翻译已能从代码直接看出的行为。
+- 注释与实现长期不一致；修改逻辑时同步更新或删除误导性注释。
+- 用大段注释代替应抽取的函数或应补全的类型。
+
+## 形式建议
+
+- 语言与仓库现有注释保持一致（中文或英文）。
+- 复杂模块或组件可在文件顶部用 **1～3 行** 说明职责与关键约束；跨包或对外导出的 API 宜用 **JSDoc** 说明参数、返回值与副作用。
+- 复杂条件分支或 `useEffect`：若依赖或触发条件不直观，用一行说明**触发条件**或**不变量**。
+- 临时规避、兼容旧系统或性能取舍必须说明原因和退出条件。
+
+## 文档同步
+
+当修改公开命令、skill、agent、模板、报告命名或安装路径时，同步更新 README、runtime docs、项目结构文档和多语言说明。注释解释局部代码，公开文档解释团队如何使用能力，两者不要互相替代。

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

@@ -0,0 +1,248 @@
+# 设计系统规则
+
+凡是任务涉及 UI 实现、设计稿转代码、样式、设计 Token 或组件复用时，都应用本文件。
+
+## 核心优先级
+
+按以下顺序优先处理：
+
+1. 复用已有组件
+2. 在已有组件上扩展
+3. 创建新的叶子组件
+4. 只有在理由非常充分时，才创建新的共享基础组件
+
+## 产品化设计方向
+
+开始 UI 实现前，先明确界面语气：
+
+- 工具型页面、SaaS 后台、CRM、运营台：优先安静、密集、可扫描，首屏直接呈现核心工作区
+- 品牌页、作品集、发布页：可以更有表现力，但 H1 应是品牌/产品/对象/品类，说明文案放在副标题
+- 可视化、游戏、创作工具：可以使用更强视觉资产和动效，但必须保持交互可控、状态清晰
+- 每个重要界面都应有一个贴合业务的视觉锚点：真实媒体、数据形态、行业材质、字体性格、空间组织或交互节奏
+- 大胆设计必须服务场景；高频工具重效率和稳定，展示型页面重主体识别和记忆点
+
+避免：
+
+- 把日常高频工具做成营销落地页
+- 默认使用紫色渐变、装饰光斑、堆叠卡片或空泛 hero
+- 使用无语境默认字体、平均分布的弱对比配色、模板化双栏 hero 或重复圆角卡片作为通用答案
+- 页面区块大面积卡片化，尤其是卡片套卡片
+- 用可见说明文字解释常见控件本该表达的功能
+- 让整个界面只由一个色相的深浅变化组成
+
+### 视觉语言基线
+
+- 字体：优先复用项目字体体系；新建方向时，标题和正文应形成性格与可读性的分工
+- 色彩：区分主色、强调色、状态色和中性色，关键动作与风险状态不能只靠透明度表达
+- 动效：只为入场、层级展开、状态确认、错误反馈和重点引导编排节奏，并尊重 `prefers-reduced-motion`
+- 空间：根据任务选择高密度、留白、非对称、分栏、画布式或编辑器式布局，不套用固定卡片模板
+- 质感：背景、纹理、阴影和透明度应解释层级或语境，不作为无内容装饰
+
+### 设计系统生成与覆盖
+
+- 项目缺少设计方向时，可先生成轻量设计系统建议，再根据真实业务、组件库和数据校正
+- `design-system/<project>/MASTER.md` 记录跨页面共享的产品类型、视觉语言、token 方向、动效、图表和 QA 规则
+- `design-system/<project>/pages/<page>.md` 只记录页面差异：首屏结构、组件密度、图表选择、状态覆盖和局部 token 调整
+- 构建页面或检查 UI 时，先读取页面 override，再读取 Master；页面规则不能复制全量 Master
+- 产品类型推理要落到界面决策：行业风险、用户频率、数据密度、触摸/鼠标场景、图表任务和转化路径
+- 交付前 QA 至少覆盖可访问性、交互反馈、布局溢出、字体色彩、动效降级、表单、导航和图表可读性
+
+## 设计稿转代码规则
+
+当存在设计上下文时：
+
+- 先通过 MCP 读取设计上下文（Figma / MasterGo / Pixso / 墨刀 / Sketch，摹客则使用截图/标注）
+- 设计稿中的颜色/间距 token 必须从 design token 文件中引用
+- 如果已有设计上下文，不要靠猜测来决定布局、间距、字体、颜色或状态
+- 在创建新组件前，先检查现有组件，优先复用现有组件库中的组件
+- 响应式断点: mobile(375px) / tablet(768px) / desktop(1440px)
+- 像素还原精度要求: ≥ 95%
+- 在改文件前先给出简短实现计划
+
+始终要考虑：
+
+- loading 状态
+- empty 状态
+- error 状态
+- disabled 状态
+- hover 状态
+- focus 状态
+- 在相关场景下的 selected 状态
+- 响应式行为
+
+## 设计 Token 规则
+
+- 优先使用已有 design token、CSS 变量或主题变量
+- 当已有 Token 可用时，不要硬编码颜色、圆角、间距、阴影和字体取值
+- 如果缺少所需 Token，要明确指出，不要悄悄到处硬编码
+- Token 使用方式要与周边模块保持一致
+- Tailwind 项目中，token 应通过语义化 `theme.extend`、CSS 变量或组件 variant 承接；不要把 `blue-600`、`rounded-xl` 等具体值复制成事实标准
+- 组件 variant 应区分语义 tone、尺寸 size、密度 density 和状态 state；不要让一个字符串参数承载多种业务含义
+- 动态 Tailwind class 必须可被构建扫描识别；复杂映射使用显式对象、variant 工具或 safelist
+
+## 样式规则
+
+- 优先使用局部、受控的样式，而不是大范围全局覆盖
+- 保持当前断点下的响应式行为
+- 与项目现有样式体系保持一致
+- 检查 hover、active、focus、disabled、selected 等状态
+- 除非没有合适 Token 或刻度值，否则不要使用 magic number
+
+### 界面质感基线
+
+- 嵌套圆角保持光学关系：外层圆角约等于内层圆角 + 间距
+- 图标按钮、箭头、播放三角等非对称图形按视觉中心微调
+- 小控件命中区域至少 40x40px，空间允许时优先 44x44px
+- 标题和短文本可用 `text-wrap: balance`，短中正文可用 `text-wrap: pretty`
+- 计数器、价格、时间、表格数字使用 `font-variant-numeric: tabular-nums`
+- 图片在浅/深色背景上边缘不清时，使用中性 alpha 内描边，不使用品牌色描边
+- 动效只声明实际变化属性，禁止 `transition: all` 和 `will-change: all`
+- 进入/退出动效要克制，并尊重 `prefers-reduced-motion`
+
+## 暗色模式
+
+提供与系统主题同步的手动切换能力，减少视觉疲劳并满足可访问性要求。
+
+### CSS 变量方案
+
+```css
+:root {
+  --color-bg-primary: #ffffff;
+  --color-bg-secondary: #f5f5f5;
+  --color-text-primary: #1a1a1a;
+  --color-text-secondary: #666666;
+  --color-border: #e0e0e0;
+}
+
+[data-theme="dark"] {
+  --color-bg-primary: #1a1a1a;
+  --color-bg-secondary: #2a2a2a;
+  --color-text-primary: #f0f0f0;
+  --color-text-secondary: #a0a0a0;
+  --color-border: #404040;
+}
+
+body {
+  background-color: var(--color-bg-primary);
+  color: var(--color-text-primary);
+}
+```
+
+### Tailwind 方案
+
+```js
+// tailwind.config.js
+module.exports = {
+  darkMode: "class", // 通过 .dark 类控制，而非 prefers-color-scheme
+};
+```
+
+```html
+<div class="bg-white dark:bg-gray-900 text-gray-900 dark:text-gray-100">
+  <!-- 内容 -->
+</div>
+```
+
+### 主题切换 Hook
+
+```tsx
+import { useState, useEffect } from "react";
+
+function useTheme() {
+  const [theme, setTheme] = useState<"light" | "dark">("light");
+
+  useEffect(() => {
+    // 1. 优先读取用户保存的偏好
+    const saved = localStorage.getItem("theme") as "light" | "dark" | null;
+    if (saved) {
+      setTheme(saved);
+      return;
+    }
+    // 2. 回退到系统偏好
+    const prefersDark = window.matchMedia(
+      "(prefers-color-scheme: dark)",
+    ).matches;
+    setTheme(prefersDark ? "dark" : "light");
+  }, []);
+
+  useEffect(() => {
+    const root = document.documentElement;
+    if (theme === "dark") {
+      root.classList.add("dark");
+      root.setAttribute("data-theme", "dark");
+    } else {
+      root.classList.remove("dark");
+      root.setAttribute("data-theme", "light");
+    }
+    localStorage.setItem("theme", theme);
+  }, [theme]);
+
+  const toggle = () => setTheme((t) => (t === "light" ? "dark" : "light"));
+
+  return { theme, toggle };
+}
+```
+
+### FOUC 防护（主题闪烁）
+
+在 `<head>` 中同步执行主题初始化脚本（阻塞渲染），避免首次加载时出现错误的主题色：
+
+```html
+<head>
+  <script>
+    // 同步执行 — 在 body 渲染前确定主题
+    (function () {
+      const theme =
+        localStorage.getItem("theme") ||
+        (window.matchMedia("(prefers-color-scheme: dark)").matches
+          ? "dark"
+          : "light");
+      if (theme === "dark") {
+        document.documentElement.classList.add("dark");
+        document.documentElement.setAttribute("data-theme", "dark");
+      }
+    })();
+  </script>
+</head>
+```
+
+### 暗色模式注意事项
+
+- **图片**: 亮色图片在暗色模式下刺眼，使用 `filter: brightness(0.8)` 降低亮度
+- **阴影**: 暗色模式下阴影不明显，改用 `box-shadow: 0 0 15px rgba(255,255,255,0.05)` 或边框替代
+- **颜色对比度**: 确保暗色模式下文本与背景的对比度 ≥ 4.5:1（WCAG AA）
+- **表单控件**: 输入框、下拉框、开关等原生控件在暗色模式下需要自定义样式
+- **第三方组件**: 检查 UI 组件库是否支持暗色模式，必要时用 CSS 变量覆盖
+- **Tailwind 组件**: 暗色模式下需复核 focus、disabled、selected、invalid、skeleton、chart 和阴影层级，不只补 `dark:` 背景色
+
+---
+
+## 可访问性基线
+
+优先使用语义化 HTML。
+
+确保：
+
+- 表单控件具备标签
+- 纯图标按钮具有可访问名称
+- 菜单、标签页、对话框和自定义控件支持键盘操作
+- 焦点样式可见
+- 编辑页面时标题层级正确
+- 真实表格数据使用正确表格语义
+
+## UI 任务的输出要求
+
+对于较复杂的设计类任务，开始时先给出：
+
+- 复用的组件
+- 新建的组件
+- 可能改动的文件
+- 响应式策略
+- Token 映射或样式策略
+
+实现完成后，需要说明：
+
+- 复用了什么
+- 新建了什么
+- 与设计稿有哪些偏差
+- 缺少哪些 Token、资源或交互细节

package/templates/shared/rules/fec-error-handling.md

@@ -0,0 +1,200 @@
+# 错误处理规范
+
+## 错误分层
+
+| 层级 | 错误类型 | 处理方式 |
+|------|----------|----------|
+| 全局 | 未捕获异常、Promise rejection | 全局捕获 + 上报 + 降级 UI |
+| 路由/页面 | 页面级组件渲染错误 | Error Boundary + 页面级降级 |
+| 模块 | 功能模块内的运行时错误 | Error Boundary + 模块级降级 |
+| 组件 | 数据请求失败、操作失败 | 用户提示 + 重试机制 |
+| 表单 | 校验失败 | 字段级错误提示 |
+
+## 全局错误捕获
+
+### React
+
+```tsx
+// main.tsx — 未捕获的 Promise
+window.addEventListener("unhandledrejection", (event) => {
+  reportError(event.reason);
+});
+
+// 推荐：react-error-boundary，业务侧保持函数组件 + FallbackComponent
+import { ErrorBoundary } from "react-error-boundary";
+
+function GlobalErrorFallback({
+  error,
+  resetErrorBoundary,
+}: {
+  error: Error;
+  resetErrorBoundary: () => void;
+}) {
+  return (
+    <div role="alert">
+      <p>页面出现异常</p>
+      <button type="button" onClick={resetErrorBoundary}>
+        重试
+      </button>
+    </div>
+  );
+}
+
+// 根节点包裹示例（root 来自 createRoot(document.getElementById("root")!) 等）
+root.render(
+  <ErrorBoundary
+    FallbackComponent={GlobalErrorFallback}
+    onError={(error, info) => {
+      reportError(error, { componentStack: info.componentStack });
+    }}
+  >
+    <App />
+  </ErrorBoundary>,
+);
+```
+
+### Vue
+
+```typescript
+// main.ts
+app.config.errorHandler = (err, instance, info) => {
+    reportError(err, {
+        component: instance?.$options.name,
+        lifecycleHook: info,
+    });
+};
+
+window.addEventListener('unhandledrejection', (event) => {
+    reportError(event.reason);
+});
+```
+
+## Error Boundary 策略
+
+```
+App (GlobalErrorBoundary)
+├── Header
+├── Main
+│   ├── Sidebar (ErrorBoundary)
+│   └── Content
+│       ├── Dashboard (ErrorBoundary)
+│       └── UserList (ErrorBoundary)
+└── Footer
+```
+
+- 每个独立功能模块用 Error Boundary 包裹
+- 模块崩溃不应导致整个页面白屏
+- 降级 UI 应提供"重试"操作
+
+## API 错误处理
+
+### 统一错误格式
+
+```typescript
+interface ApiError {
+    code: string;
+    message: string;
+    details?: Record<string, string[]>;
+}
+```
+
+### 错误分级处理
+
+```typescript
+function handleApiError(error: ApiError) {
+    switch (error.code) {
+        case 'UNAUTHORIZED':
+            redirectToLogin();
+            break;
+        case 'FORBIDDEN':
+            showToast('无权限执行此操作');
+            break;
+        case 'VALIDATION_ERROR':
+            return error.details; // 返回给表单显示字段级错误
+        case 'NETWORK_ERROR':
+            showToast('网络异常，请检查网络连接');
+            break;
+        default:
+            showToast(error.message || '操作失败，请稍后重试');
+            reportError(error);
+    }
+}
+```
+
+### 请求拦截器
+
+在 axios / fetch 封装层统一处理：
+
+- 401 → 跳转登录（或刷新 token）
+- 403 → 权限不足提示
+- 500 → 通用错误提示 + 上报
+- 网络超时 → 超时提示 + 可选重试
+
+### 用户可恢复动作
+
+每类错误都应对应明确下一步：
+
+- `401`：重新登录或静默刷新失败后跳转登录
+- `403`：说明无权限并提供返回或申请权限路径
+- `404`：返回列表、重新搜索或创建入口
+- `409`：展示冲突对象和刷新/覆盖/取消选择
+- `422`：字段级错误回填表单
+- `429`：告知等待时间或稍后重试
+- `5xx` / 网络错误：重试、离线提示或联系支持
+
+UI 可显示 request id / trace id 方便支持排查，但不得暴露内部堆栈、SQL、服务名或敏感字段。
+
+## 用户体验
+
+### 错误状态 UI
+
+每个数据展示区域应处理四种状态：
+
+1. **Loading** — 骨架屏或 spinner
+2. **Error** — 错误描述 + 重试按钮
+3. **Empty** — 空状态引导
+4. **Success** — 正常数据展示
+
+### 降级 UI 设计
+
+- 全局级：显示友好的错误页面，提供"返回首页"和"重试"
+- 模块级：显示该模块的占位错误卡片，页面其他部分正常
+- 操作级：Toast 提示 + 具体的下一步指引
+
+### 重试策略
+
+- 用户手动重试（按钮）
+- 自动重试（指数退避，最多 3 次）
+- 数据请求库的内置重试（React Query retries 等）
+
+## 错误上报
+
+<!-- 请根据项目实际的错误监控平台调整：Sentry / 自建 / 其他 -->
+
+上报内容应包含：
+
+- 错误堆栈
+- 用户 ID / 会话 ID
+- 当前页面 URL
+- 浏览器/设备信息
+- 复现上下文（操作步骤、请求参数）
+
+## 反模式
+
+- 空 catch 块吞掉错误
+- 所有错误统一用 `alert()` 提示
+- 接口失败时 UI 无任何反馈
+- Error Boundary 没有重试机制，用户只能刷新页面
+- 在组件中到处写重复的 try/catch 而不是统一封装
+- 不上报错误，依赖用户反馈来发现问题
+- 用 Error Boundary 承接普通 API 错误，导致用户无法理解或恢复
+- 把后端原始异常、内部错误码或敏感字段直接展示给用户
+
+## 检查清单
+
+- [ ] 全局有未捕获异常和 Promise rejection 的监听
+- [ ] 关键功能模块有 Error Boundary（React）或 onErrorCaptured（Vue）包裹
+- [ ] API 请求有统一的错误拦截和分级处理
+- [ ] 所有数据展示区域处理了 Loading / Error / Empty / Success 四种状态
+- [ ] 降级 UI 提供了"重试"操作
+- [ ] 错误信息上报到监控平台

package/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
+- 未说明验证命令或已知剩余风险就提交高风险改动