@bovinphang/frontend-craft 2.6.0 → 2.8.0

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

@@ -1,33 +1,33 @@
-# 代码注释
+# Code comments
 
-编写或评审前端实现时应用本文件。
+Use this document when writing or reviewing front-end implementations.
 
-## 原则
+## Principles
 
-- 意图优先靠**命名、类型与结构**表达；注释用于说明**为什么**、**约束与背景**，而不是复述代码在做什么。
-- 避免「整文件零注释」：在**非显而易见**处用**简短**注释降低误改成本，与「不写废话注释」不矛盾。
+- Intention is expressed first through **naming, type and structure**; comments are used to explain **why**, **constraints and background**, rather than reiterating what the code is doing.
+- Avoid "zero comments in the entire file": Use **short** comments in **non-obvious** places to reduce the cost of accidental modifications, which is not inconsistent with "no nonsense comments".
 
-## 应当注释的情况
+## Situations that should be commented
 
-- **业务或产品规则**：权限、展示条件、校验逻辑背后的依据（与需求或领域约定相关时）。
-- **非直观的实现或取舍**：为何选用当前写法（性能、兼容、与后端/第三方约定等）。
-- **外部契约**：与接口、设计稿、枚举或单位相关的字段含义、映射关系。
-- **临时方案与技术债**：`TODO` / `FIXME` 应写明预期收尾或关联工单（若有）。
-- **易踩坑点**：第三方库版本差异、必须满足的调用顺序、已知限制。
+- **Business or product rules**: permissions, display conditions, and the basis behind the verification logic (when related to requirements or domain agreements).
+- **Non-intuitive implementation or trade-offs**: Why choose the current writing method (performance, compatibility, agreement with backend/third party, etc.).
+- **External Contract**: Field meanings and mapping relationships related to interfaces, design drafts, enumerations or units.
+- **Interim Solutions and Technical Debt**: `TODO` / `FIXME` should indicate expected closure or associated work orders (if any).
+- **Easy pitfalls**: Third-party library version differences, the calling sequence that must be met, and known limitations.
 
-## 应避免的情况
+## Situations to avoid
 
-- 逐行翻译已能从代码直接看出的行为。
-- 注释与实现长期不一致；修改逻辑时同步更新或删除误导性注释。
-- 用大段注释代替应抽取的函数或应补全的类型。
+- Line-by-line translation of behavior that can be seen directly from the code.
+- Annotations are chronically inconsistent with the implementation; misleading annotations are updated or deleted synchronously when the logic is modified.
+- Use large comments to replace functions that should be extracted or types that should be completed.
 
-## 形式建议
+## Format Suggestions
 
-- 语言与仓库现有注释保持一致（中文或英文）。
-- 复杂模块或组件可在文件顶部用 **1～3 行** 说明职责与关键约束；跨包或对外导出的 API 宜用 **JSDoc** 说明参数、返回值与副作用。
-- 复杂条件分支或 `useEffect`：若依赖或触发条件不直观，用一行说明**触发条件**或**不变量**。
-- 临时规避、兼容旧系统或性能取舍必须说明原因和退出条件。
+- The language is consistent with the existing comments in the warehouse (Chinese or English).
+- Complex modules or components can use **1~3 lines** at the top of the file to describe responsibilities and key constraints; cross-package or externally exported APIs should use **JSDoc** to describe parameters, return values and side effects.
+- Complex conditional branches or `useEffect`: If the dependency or triggering condition is not intuitive, use one line to describe the **triggering condition** or **invariant**.
+- Temporary circumvention, compatibility with old systems or performance trade-offs must state reasons and exit conditions.
 
-## 文档同步
+## Document synchronization
 
-当修改公开命令、skill、agent、模板、报告命名或安装路径时，同步更新 README、runtime docs、项目结构文档和多语言说明。注释解释局部代码，公开文档解释团队如何使用能力，两者不要互相替代。
+When modifying public commands, skills, agents, templates, report naming or installation paths, synchronize updates to README, runtime docs, project structure documents and multi-language instructions. Comments explain local code, and public documentation explains how the team uses capabilities. The two should not replace each other.

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

@@ -1,248 +1,72 @@
-# 设计系统规则
+# Design system rules
 
-凡是任务涉及 UI 实现、设计稿转代码、样式、设计 Token 或组件复用时，都应用本文件。
+This document should be used whenever the task involves UI implementation, design draft conversion to code, style, design token, or component reuse. This article only retains the project's resident design constraints; product design direction, design system generation, page-level override, and UI QA details are handed over to `fec-ui-design`; Tailwind token, variant, dark mode and class management are handed over to `fec-tailwind-design-system`; responsive layout is handed over to `fec-responsive-layout`.
 
-## 核心优先级
+## Core priority
 
-按以下顺序优先处理：
+1. Reuse existing components.
+2. Expand on existing components.
+3. Create a new leaf component.
+4. Only create new shared base components if there is good reason, clear boundaries, and if they will be reused.
 
-1. 复用已有组件
-2. 在已有组件上扩展
-3. 创建新的叶子组件
-4. 只有在理由非常充分时，才创建新的共享基础组件
+## Product design direction
 
-## 产品化设计方向
+- Tool-type pages, SaaS backend, CRM, and operations desk: Prioritize quiet, dense, and scannable, and the core work area is directly displayed on the first screen.
+- Brand page, portfolio, release page: It can be more expressive, but H1 should be the brand, product, object or category, and the description copy should be placed in the subtitle.
+- Visualization, games, and creative tools: You can use stronger visual assets and animations, but you must keep the interaction controllable and the status clear.
+- Every important interface should have a visual anchor that fits the business, such as real media, data form, industry material, font character, spatial organization or interaction rhythm.
+- Bold design must serve the scene; high-frequency tools focus on efficiency and stability, and display-type pages focus on subject recognition and memory points.
 
-开始 UI 实现前，先明确界面语气：
+Avoid:
 
-- 工具型页面、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、资源或交互细节
+- Turn daily high-frequency tools into marketing landing pages.
+- Use purple gradient, decorative light spots, stacked cards, empty hero or non-contextual default font by default.
+- Large areas of the page are card-based, especially card sets.
+- Use visible explanatory text to explain the functions that common controls are supposed to express.
+- Let the entire interface consist of only one shade of hue.
+
+## Design draft conversion code rules
+
+- When given design context, read the source of truth first through MCP or screenshots/annotations, and don’t rely on guesswork to determine layout, spacing, fonts, colors, or status.
+- Colors, spacing, rounded corners, shadows, and fonts in the design should be mapped to existing tokens, CSS variables, theme variables, or component variants.
+- Check existing component libraries and business components before creating new components and prioritize reuse.
+- Default verification is mobile(375px), tablet(768px), desktop(1440px).
+- Pixel restoration requirements are subject to the project agreement; if there is no agreement, the core structure, spacing, fonts, status and interaction will take precedence over mechanical pursuit of screenshot overlap.
+- Before implementing complex design tasks, a brief implementation plan is given, describing reused components, new components, possible changed files, responsive strategies and token mapping.
+
+## Design Token and style
+
+- Prefer using existing design tokens, CSS variables, or theme variables; do not hard-code colors, rounded corners, spacing, shadows, and font values.
+- When required tokens are missing, clearly point them out and centrally complete or record them, rather than scattering literals in multiple components.
+- In the Tailwind project, tokens should be inherited through semantic `theme.extend`, CSS variables or component variants; do not copy specific values such as `blue-600` and `rounded-xl` into de facto standards.
+- Component variants should distinguish semantic tone, size, density and state; do not let a string parameter carry multiple business meanings at the same time.
+- Dynamic Tailwind classes must be recognized by build scans; use explicit objects, variant tools, or safelist for complex mappings.
+- Prioritize the use of local, controlled styles instead of large-scale global coverage; be consistent with the project's existing CSS Modules, Tailwind, component libraries or style systems.
+
+## Interface texture baseline
+
+- Nested fillets maintain an optical relationship: the outer fillet is approximately equal to the inner fillet + spacing.
+- Asymmetric graphics such as icon buttons, arrows, and playback triangles are fine-tuned according to the visual center.
+- The hit area of the small control should be at least 40x40px, and 44x44px is preferred if space allows.
+- `text-wrap: balance` can be used for titles and short texts, and `text-wrap: pretty` can be used for short and medium text.
+- Use `font-variant-numeric: tabular-nums` for counters, prices, times, and tabular numbers.
+- Animation only declares actual change attributes, prohibits `transition: all` and `will-change: all`, and respects `prefers-reduced-motion`.
+
+## Dark mode
+
+- Project-level dark mode only selects one main strategy: CSS variables, root node class, `data-theme` or component library theme.
+- When supporting manual theme switching, user preferences must be initialized before the first screen is drawn to avoid theme flickering; the implementation details are left to Tailwind / design-system skill reference.
+- Review disabled, focus, selected, invalid, skeleton, chart, form controls, third-party components and shadow levels for both light and dark colors.
+- Don't just reduce the transparency to express disabled, don't just fill in the background color and ignore text, borders, charts and focus states.
+
+## Accessibility Baseline
+
+- Prefer semantic HTML.
+- Form controls have labels and pure icon buttons have accessible names.
+- Menus, tabs, dialog boxes and custom controls support keyboard operation.
+- Focus styles are visible, title levels are correct, and real table data uses table semantics.
+- Color contrast, touch targets, reduced-motion and error prompts cannot be destroyed by visual polish.
+
+## UI task output
+
+After the implementation is completed, explain what was reused, what was newly created, deviations from the design draft or project token, and what resources or interaction details are missing. Complex UIs should also account for state overrides, responsive validation, and remaining design risks.

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

@@ -1,200 +1,56 @@
-# 错误处理规范
+# Error handling specifications
 
-## 错误分层
+This document agrees on the resident boundaries of front-end error handling. React/Vue component boundary details are handed over to the corresponding framework skill, API error mapping and authentication refresh are handed over to `fec-api-integration`, and security-sensitive errors are handed over to `fec-security-review`.
 
-| 层级 | 错误类型 | 处理方式 |
-|------|----------|----------|
-| 全局 | 未捕获异常、Promise rejection | 全局捕获 + 上报 + 降级 UI |
-| 路由/页面 | 页面级组件渲染错误 | Error Boundary + 页面级降级 |
-| 模块 | 功能模块内的运行时错误 | Error Boundary + 模块级降级 |
-| 组件 | 数据请求失败、操作失败 | 用户提示 + 重试机制 |
-| 表单 | 校验失败 | 字段级错误提示 |
+## Error layering
 
-## 全局错误捕获
+| Hierarchy | Error type | Default handling |
+| ---- | -------- | -------- |
+| Global | Uncaught exceptions, Promise rejection | Capture, reporting, global downgrade UI |
+| Routing / Page | Page-level rendering exception | Error Boundary / Frame error boundary + Page-level degradation |
+| Module | Function module runtime exception | Module-level boundary + local degradation |
+| Component/Request | Data request failure, operation failure | User-understandable prompts + recoverable actions |
+| Form | Validation failure | Field-level error prompts and correction entry |
 
-### React
+## Global and module boundaries
 
-```tsx
-// main.tsx — 未捕获的 Promise
-window.addEventListener("unhandledrejection", (event) => {
-  reportError(event.reason);
-});
+- Uncaught exception and Promise rejection monitoring should be registered at the application entrance and connected to the project error reporting platform.
+- React uses the project's unified Error Boundary solution; business components remain functional and no new handwritten class component boundaries are added.
+- Vue uses project-unified `app.config.errorHandler`, `onErrorCaptured` or framework-level error boundaries.
+- Independent functional modules should have local downgrade capabilities, and module crashes should not cause the entire page to go blank.
+- Error Boundary handles rendering exceptions; normal API failures should fall into the loading/error/empty/data state and recoverable operations.
 
-// 推荐：react-error-boundary，业务侧保持函数组件 + FallbackComponent
-import { ErrorBoundary } from "react-error-boundary";
+## API error handling
 
-function GlobalErrorFallback({
-  error,
-  resetErrorBoundary,
-}: {
-  error: Error;
-  resetErrorBoundary: () => void;
-}) {
-  return (
-    <div role="alert">
-      <p>页面出现异常</p>
-      <button type="button" onClick={resetErrorBoundary}>
-        重试
-      </button>
-    </div>
-  );
-}
+- The request layer uniformly normalizes error shapes, and components do not directly parse backend exceptions, token refresh or retry strategies.
+- Each type of error should have a clear next step: retry, log in again, modify input, return to the previous level, refresh conflicting data, contact support, or try again later.
+- `401`, `403`, `404`, `409`, `422`, `429`, `5xx` and network errors should have distinguishable user prompts and log semantics.
+- The UI can display request id / trace id to facilitate support troubleshooting, but must not expose internal stacks, SQL, service names, keys or sensitive fields.
 
-// 根节点包裹示例（root 来自 createRoot(document.getElementById("root")!) 等）
-root.render(
-  <ErrorBoundary
-    FallbackComponent={GlobalErrorFallback}
-    onError={(error, info) => {
-      reportError(error, { componentStack: info.componentStack });
-    }}
-  >
-    <App />
-  </ErrorBoundary>,
-);
-```
+## User experience
 
-### Vue
+- Each data display area handles four states: Loading, Error, Empty, and Success.
+- Global-level error pages provide paths to return to the home page, refresh or retry; module-level downgrades only affect this module; operation-level errors provide the next step.
+- The retry strategy must be restrained: users’ manual retries are given priority, and automatic retries must have upper limits, backoff and stop conditions.
+- Error prompts should retain what the user has entered to avoid losing the form or context due to failure.
 
-```typescript
-// main.ts
-app.config.errorHandler = (err, instance, info) => {
-    reportError(err, {
-        component: instance?.$options.name,
-        lifecycleHook: info,
-    });
-};
+## Error reporting
 
-window.addEventListener('unhandledrejection', (event) => {
-    reportError(event.reason);
-});
-```
+The reported content should include the error stack, page URL, browser/device information, user or session ID, operation context, request ID, and version information. Clean tokens, passwords, personal sensitive fields and large payloads before reporting.
 
-## Error Boundary 策略
+## Anti-pattern
 
-```
-App (GlobalErrorBoundary)
-├── Header
-├── Main
-│   ├── Sidebar (ErrorBoundary)
-│   └── Content
-│       ├── Dashboard (ErrorBoundary)
-│       └── UserList (ErrorBoundary)
-└── Footer
-```
+- Empty `catch` blocks swallow errors.
+- All errors are reported with `alert()` or a vague toast.
+- When the interface fails, there is no feedback from the UI, or the original exception from the backend is directly displayed to the user.
+- Error Boundary has no retry or return path.
+- Write repeated `try/catch` everywhere in the component instead of uniformly encapsulating request boundaries.
+- Use Error Boundary to handle common API errors, making it impossible for users to understand or recover.
 
-- 每个独立功能模块用 Error Boundary 包裹
-- 模块崩溃不应导致整个页面白屏
-- 降级 UI 应提供"重试"操作
+## Checklist
 
-## 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 提供了"重试"操作
-- [ ] 错误信息上报到监控平台
+- [ ] Global uncaught exceptions and Promise rejections are listened to.
+- [ ] Critical pages or modules have frame error boundaries and partially degraded UI.
+- [ ] API requests have unified error normalization, hierarchical processing and recoverable actions.
+- [ ] Data area override Loading / Error / Empty / Success.
+- [ ] Error reports contain sufficient location information and do not leak sensitive data.