---
description: 原型实现与设计稿还原规范
globs:
alwaysApply: false
---
# 原型实现与设计稿还原规范

进行原型实现或设计稿还原时，需要遵守以下准则：

## 设计稿处理

1. **Figma 设计稿获取**：当存在 Figma 链接时，使用 Figma MCP 工具获取设计信息。保证实现代码尽可能符合设计稿：
   - Figma Dev Mode MCP 服务器提供一个可提供图像和 SVG 资产的资产端点。
   - IMPORTANT：如果 Figma Dev Mode MCP 服务器为图像或 SVG 返回一个 localhost 源，请直接使用该图像或 SVG 源。
   - IMPORTANT：不要导入或添加新的图标包，所有资产都应在 Figma 负载中，或者 Lucide 图标库（已安装）。
   - IMPORTANT：如果提供了 localhost 源，则不要使用或创建占位符。
2. **设计与开发平衡**：在保持设计一致性的前提下，优先考虑代码的可维护性和性能。

## 样式实现规范

### 基础样式规则

3. **样式系统**：所有样式必须使用 Tailwind CSS，**禁止**在 `<style>` 或 `<style scoped>` 中设置样式。
4. **尺寸处理策略**：
   - **禁止使用固定宽度或长度**，优先使用相对宽度或长度（如 `w-3/4`、`h-screen`）
   - 当必须使用固定尺寸时，选择 Tailwind CSS 预设的 `rem` 值，保持一致性与响应性
   - 避免使用 `w-[123px]` 等任意值，优先使用预设值如 `w-32`、`w-64`

### 视觉样式规范

5. **颜色与视觉效果**：颜色、背景、边框、渐变、阴影、字体颜色等样式应尽可能符合设计稿，使用项目中预定义的 CSS 变量。

## 布局实现规范

### 布局系统

6. **布局实现方式**：
   - **必须**使用 `flex` 或 `grid` 布局，实现响应式布局
   - **严禁**使用绝对布局（`absolute`、`fixed`）定位元素，除非确实需要层叠效果

### 间距处理

7. **元素间距**：
   - **优先使用**：`gap-`、`space-x-`、`space-y-` 类
   - **尽量避免**：`mt-`、`mb-`、`ml-`、`mr-` 类
   - **推荐模式**：父容器设置 `gap`，子元素不设置外边距

## 组件化开发

### 组件抽象原则

8. **模块化思维**：
   - 识别重复的 UI 模式，将其抽象为独立的 Vue 组件
   - 页面组件应尽可能少包含原生 HTML 元素，多使用组件化元素
   - 单个组件职责单一，功能内聚

### 组件库优先级

9. **组件选择策略**：
   - **第一优先级**：使用 Shadcn Vue 组件库
   - **第二优先级**：使用项目现有的自定义组件
   - **最后选择**：实现新的自定义组件

### 组件设计原则

10. **组件动态性**：
    - 组件的具体内容（标题、图片、图标、文本等）应作为 `props` 传入
    - 避免在组件内硬编码具体内容
    - 提供合理的默认值和类型定义

## 图标与资源

11. **图标使用**：优先使用 `lucide-vue-next` 图标库，保持图标风格统一性。

## 响应式设计

### 断点系统

12. **响应式实现**：
    - 使用 Tailwind CSS 响应式前缀：`tablet:`、`desktop:`、`screen:`
    - 三种设备适配：
      - **平板电脑**：768px-1536px (`tablet:`)
      - **桌面显示器**：1536px-2304px (`desktop:`)
      - **超大屏幕**：2304px及以上 (`screen:`)
    - 实现样例：`mt-2 tablet:mt-4 desktop:mt-6 screen:mt-8`

### 响应式最佳实践

13. **移动优先**：从最小屏幕开始设计，逐步增强到大屏幕。

## 国际化处理

14. **多语言支持**：
    - 文本内容从 `dictionary.json` 字典获取
    - 更新字典后运行 `npm run i18n` 生成类型
    - 使用方式：`import I18N from '@/utils/i18n.base';` + `{{ I18N.xxx }}`

15. **时间格式处理**：
    - 时间国际化或格式化使用 `@internationalized/date` 库，**禁止随意使用**自定义的时间格式化函数
    - 标准用法：`new DateFormatter(I18N.locale, options).format(date)`
    - 支持的格式选项：`year`、`month`、`day`、`hour`、`minute`、`second` 等
    - 示例：

## 数据可视化

### 图表组件规范

16. **可视化图表**：
    - **优先使用** vue-echarts 库
    - **避免直接使用**原生 echarts（除特殊情况）
    - 图表组件放置在 `components/echarts` 目录
    - 必须提供 `props`：标题、tooltip、坐标轴名称、数据
    - 支持三种响应式尺寸：`tablet`、`desktop`、`screen`

### 图表最佳实践

17. **图表性能优化**：
    - 大数据量时考虑数据采样
    - 使用 `vue-echarts` 的懒加载特性
    - 合理设置图表的 `resize` 行为

## 性能优化

18. **组件性能**：
    - 使用 `defineAsyncComponent` 进行组件懒加载
    - 大列表使用虚拟滚动
    - 图片使用懒加载和适当的格式（WebP）

19. **渲染优化**：
    - 合理使用 `v-memo` 和 `v-once`
    - 避免在模板中进行复杂计算
    - 使用 `computed` 缓存计算结果

## 开发环境

20. **本地开发**：本地开发服务器运行在 `http://localhost:5173/`，无需手动启动。

## 文档获取与参考

### 第三方依赖文档

21. **Context7 MCP 工具使用**：
    - 当需要查阅第三方依赖的官方文档时，使用 Context7 MCP 工具获取最新、准确的文档信息
    - **优先获取文档的依赖**：
      - **Shadcn Vue**：组件库使用方法、API 参考、最佳实践
      - **Vue-ECharts**：图表配置、事件处理、响应式设计
      - **Pinia**：状态管理模式、store 设计、数据持久化
      - **Vue Router**：路由配置、导航守卫、动态路由
      - **Tailwind CSS**：样式类参考、响应式设计、自定义配置
      - **Lucide**：图标使用方法、图标列表、自定义图标

### 文档查阅策略

22. **文档优先级**：
    - **第一优先级**：使用 Context7 MCP 工具获取官方文档
    - **第二优先级**：参考项目内现有的实现示例
    - **第三优先级**：基于经验进行合理推断

### 文档应用原则

23. **文档实践应用**：
    - 在使用新的 API 或组件前，先通过 Context7 MCP 工具查阅相关文档
    - 确保 API 使用方式与官方文档一致，避免过时或错误的用法
    - 参考文档中的最佳实践和性能优化建议
    - 遵循文档中的命名约定和代码风格

## 代码质量

### 注释规范

24. **注释策略**：
    - **必须**：为每个类、函数添加 JSDoc 格式的块级注释
    - **适度**：仅在代码关键部分与逻辑复杂部分添加行级注释
    - **避免**：过度注释显而易见的代码

### 代码结构

25. **文件组织**：
    - 组件文件使用 PascalCase 命名
    - 工具函数使用 camelCase 命名
    - 常量使用 UPPER_SNAKE_CASE 命名

## 错误处理与边界情况

26. **错误处理**：
    - API 调用必须包含错误处理
    - 组件 props 提供类型检查和默认值
    - 使用 `try-catch` 处理可能的运行时错误

27. **边界情况**：
    - 考虑空数据状态的 UI 展示
    - 处理加载状态和错误状态
    - 提供合理的 loading 和 error 组件

## 代码检查清单

在提交代码前，请确认：

- [ ] 所有样式都使用 Tailwind CSS
- [ ] 没有使用固定宽高（除非必要）
- [ ] 布局使用 flex/grid，避免绝对定位
- [ ] 重复的 UI 已抽象为组件
- [ ] 组件内容通过 props 传入
- [ ] 添加了必要的 JSDoc 注释
- [ ] 考虑了响应式设计
- [ ] 处理了错误和边界情况
- [ ] 进行了基本的性能优化
- [ ] 使用 Context7 MCP 工具查阅了相关第三方依赖文档
- [ ] API 使用方式与官方文档一致
- [ ] 遵循了文档中的最佳实践和命名约定