finyx_data_frontend/.cursorrules

# Finyx AI 前端开发 Cursor Rules

## 项目概述
这是一个基于 Vue 3 + TypeScript + Tailwind CSS 的企业级数据资产管理平台前端项目。项目需要与旧系统（Vue 3 + Element Plus + SCSS）融合，保持设计风格一致性。

## 技术栈约束

### 必须使用
- Vue 3.4.0+ (Composition API)
- TypeScript 5.2.2+
- Tailwind CSS 3.3.6+
- Pinia 2.1.0+ (状态管理)
- Vue Router 4.2.0+ (路由)
- Lucide Vue Next 0.344.0+ (图标)

### 禁止使用
- ❌ React 及其相关库
- ❌ Element Plus (新功能中)
- ❌ SCSS/SASS (统一使用 Tailwind CSS)
- ❌ 内联样式 (除非动态样式)
- ❌ `any` 类型 (除非特殊情况)
- ❌ `@ts-ignore` (除非有充分理由)

## 色彩系统规范

### 必须使用 Tailwind 配置的颜色类
所有颜色必须使用 `tailwind.config.js` 中定义的颜色变量：

```typescript
// ✅ 正确
<div className="bg-app-primary text-app-white">按钮</div>
<div className="bg-app-bg text-app-text">内容</div>
<div className="border-app-border">边框</div>

// ❌ 错误 - 禁止硬编码颜色
<div className="bg-[#3067EF]">按钮</div>
<div style={{ backgroundColor: '#3067EF' }}>按钮</div>
```

### 颜色变量映射
- `app-primary`: #3067EF (主色)
- `app-bg`: #F4F8FF (背景色)
- `app-text`: #1f2329 (主文本)
- `app-text-secondary`: #646a73 (次文本)
- `app-text-disable`: #bbbfc4 (禁用文本)
- `app-border`: #dee0e3 (边框)
- `app-white`: #ffffff (白色)
- `app-sidebar-bg`: #ffffff (侧边栏背景)
- `app-hover`: rgba(48, 103, 239, 0.06) (悬停背景)
- `app-active`: #ECF2FF (激活背景)

## 组件开发规范

### Vue 组件结构
```vue
<template>
  <!-- 模板内容 -->
</template>

<script setup lang="ts">
// 1. Vue 核心导入
import { ref, computed, onMounted } from 'vue'

// 2. 第三方库导入
import { useRouter } from 'vue-router'

// 3. 项目内部导入
import { SidebarItem } from '@/components/SidebarItem'
import type { Project } from '@/types'

// 4. Props 定义
interface Props {
  title: string
  items: Project[]
  count?: number
}

const props = withDefaults(defineProps<Props>(), {
  count: 0
})

// 5. Emits 定义
interface Emits {
  (e: 'update', value: string): void
}

const emit = defineEmits<Emits>()

// 6. 响应式数据
const count = ref<number>(0)
const projects = ref<Project[]>([])

// 7. 计算属性
const total = computed(() => projects.value.length)

// 8. 生命周期
onMounted(() => {
  // 初始化逻辑
})

// 9. 方法
const handleClick = () => {
  // 处理逻辑
}
</script>

<style scoped>
/* 仅在必要时使用自定义样式 */
</style>
```

### TypeScript 类型规范
- 所有 Props 必须定义 interface
- 所有响应式数据必须指定类型
- 禁止使用 `any`，使用 `unknown` 或具体类型
- 使用 `type` 定义联合类型，`interface` 定义对象类型

```typescript
// ✅ 正确
interface Project {
  id: string
  name: string
  progress: number
}

type Step = 'setup' | 'inventory' | 'context' | 'value' | 'delivery'

const count = ref<number>(0)
const projects = ref<Project[]>([])

// ❌ 错误
const count = ref(0) // 缺少类型
const data: any = {} // 使用 any
```

## 样式规范

### Tailwind CSS 使用
- 优先使用 Tailwind 工具类
- 使用配置的颜色变量（app-*）
- 响应式设计使用 Tailwind 断点（sm, md, lg, xl）
- 避免自定义 CSS，除非绝对必要

```vue
<template>
  <!-- ✅ 正确 -->
  <div class="bg-app-white border border-app-border rounded-lg p-6 shadow-app">
    <h2 class="text-xl font-bold text-app-text mb-4">标题</h2>
    <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
      <!-- 内容 -->
    </div>
  </div>
  
  <!-- ❌ 错误 -->
  <div style="background: white; padding: 24px;">
    内容
  </div>
</template>
```

### 字体和间距
- 基础字号: 14px (`text-base`)
- 基础间距单位: 8px
- 页面内边距: 24px (`p-6`)
- 卡片内边距: 16px (`p-4`) 或 24px (`p-6`)

## 文件命名规范

### 组件文件
- Vue 组件: PascalCase，如 `SidebarItem.vue`
- TypeScript 文件: camelCase，如 `mockData.ts`
- 工具函数: camelCase，如 `formatDate.ts`

### 组件命名
- 组件名必须与文件名保持一致
- 使用 PascalCase

## 代码质量要求

### 必须遵循
1. 所有组件必须使用 TypeScript
2. 所有 Props 必须定义类型
3. 所有事件必须使用 `defineEmits` 定义
4. 使用 Composition API，禁止 Options API
5. 使用 `ref` 和 `computed` 管理状态
6. 异步操作必须使用 try-catch
7. 错误信息使用 Toast 显示

### 性能优化
- 使用 `computed` 而非 `watch`（如可能）
- 使用 `v-show` 而非 `v-if`（频繁切换）
- 大列表考虑虚拟滚动
- 图片使用懒加载

### 可访问性
- 使用语义化 HTML 标签
- 为交互元素添加 `aria-label`
- 确保键盘导航可用
- 确保颜色对比度符合标准

## 与旧系统融合注意事项

### 色彩一致性
- 必须使用旧系统的色彩变量
- 禁止使用新的颜色值（除非经过批准）

### 组件风格
- 侧边栏: 白色背景 (`bg-app-sidebar-bg`)
- 卡片: 白色背景 (`bg-app-white`)，浅色边框 (`border-app-border`)
- 按钮: 主色背景 (`bg-app-primary`)
- 激活状态: 浅蓝色背景 (`bg-app-active`)

### 技术栈兼容
- 新功能使用 Vue 3 + TypeScript + Tailwind CSS
- 旧功能保持 Vue 3 + Element Plus + SCSS
- 新功能作为独立模块，通过路由集成

## 代码生成规则

### 生成新组件时
1. 使用 Vue 3 Composition API
2. 完整的 TypeScript 类型定义
3. 使用 Tailwind CSS 样式
4. 使用配置的颜色变量
5. 添加必要的注释
6. 遵循项目目录结构

### 修改现有代码时
1. 保持现有代码风格
2. 不破坏现有功能
3. 更新相关类型定义
4. 确保样式一致性

## 常见错误避免

### ❌ 禁止
```typescript
// 禁止使用 any
const data: any = {}

// 禁止硬编码颜色
<div className="bg-[#3067EF]">按钮</div>

// 禁止使用内联样式
<div style={{ backgroundColor: 'white' }}>内容</div>

// 禁止使用 React
import React from 'react'

// 禁止使用 Element Plus (新功能)
import { ElButton } from 'element-plus'
```

### ✅ 正确
```typescript
// 使用具体类型
const data: Project = {}

// 使用 Tailwind 配置的颜色
<div className="bg-app-primary">按钮</div>

// 使用 Tailwind 类
<div className="bg-app-white">内容</div>

// 使用 Vue
import { ref } from 'vue'

// 使用 Tailwind 构建组件
<button className="bg-app-primary text-app-white px-4 py-2 rounded-lg">
  按钮
</button>
```

## 代码审查重点

在生成或修改代码时，确保：
1. ✅ 使用正确的颜色变量（app-*）
2. ✅ TypeScript 类型完整
3. ✅ 使用 Tailwind CSS 而非内联样式
4. ✅ 遵循 Vue 3 Composition API
5. ✅ 组件结构清晰
6. ✅ 无 ESLint 错误
7. ✅ 响应式设计正确
8. ✅ 与旧系统风格一致

## 项目结构参考

```
src/
├── components/          # 通用可复用组件
├── layouts/            # 布局组件
├── pages/              # 页面组件
├── stores/              # Pinia 状态管理
├── types/              # TypeScript 类型定义
├── utils/              # 工具函数
└── api/                # API 接口定义
```

## 重要提醒

1. **色彩系统**: 始终使用 `tailwind.config.js` 中定义的颜色变量
2. **技术栈**: 新功能必须使用 Vue 3 + TypeScript + Tailwind CSS
3. **类型安全**: 所有代码必须使用 TypeScript，避免 `any`
4. **样式一致性**: 与旧系统保持设计风格一致
5. **代码质量**: 遵循最佳实践，确保可维护性