diff --git a/.cursorrules b/.cursorrules new file mode 100644 index 0000000..e740367 --- /dev/null +++ b/.cursorrules @@ -0,0 +1,305 @@ +# 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 +// ✅ 正确 +
按钮
+
内容
+
边框
+ +// ❌ 错误 - 禁止硬编码颜色 +
按钮
+
按钮
+``` + +### 颜色变量映射 +- `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 + + + + + +``` + +### 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(0) +const projects = ref([]) + +// ❌ 错误 +const count = ref(0) // 缺少类型 +const data: any = {} // 使用 any +``` + +## 样式规范 + +### Tailwind CSS 使用 +- 优先使用 Tailwind 工具类 +- 使用配置的颜色变量（app-*） +- 响应式设计使用 Tailwind 断点（sm, md, lg, xl） +- 避免自定义 CSS，除非绝对必要 + +```vue + +``` + +### 字体和间距 +- 基础字号: 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 = {} + +// 禁止硬编码颜色 +
按钮
+ +// 禁止使用内联样式 +
内容
+ +// 禁止使用 React +import React from 'react' + +// 禁止使用 Element Plus (新功能) +import { ElButton } from 'element-plus' +``` + +### ✅ 正确 +```typescript +// 使用具体类型 +const data: Project = {} + +// 使用 Tailwind 配置的颜色 +
按钮
+ +// 使用 Tailwind 类 +
内容
+ +// 使用 Vue +import { ref } from 'vue' + +// 使用 Tailwind 构建组件 + +``` + +## 代码审查重点 + +在生成或修改代码时，确保： +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. **代码质量**: 遵循最佳实践，确保可维护性 diff --git a/.eslintrc.cjs b/.eslintrc.cjs index 2617cbb..94902df 100644 --- a/.eslintrc.cjs +++ b/.eslintrc.cjs @@ -13,6 +13,11 @@ module.exports = { parserOptions: { ecmaVersion: 2021, }, + ignorePatterns: [ + '旧代码/**', + 'dist/**', + 'node_modules/**', + ], rules: { 'vue/multi-word-component-names': 'off', }, diff --git a/docs/【FINYX-AI】数据资产产品规划-20260105-2.xlsx b/docs/【FINYX-AI】数据资产产品规划-20260105-2.xlsx deleted file mode 100644 index 3ff4873..0000000 Binary files a/docs/【FINYX-AI】数据资产产品规划-20260105-2.xlsx and /dev/null differ diff --git a/docs/前端开发规范.md b/docs/前端开发规范.md new file mode 100644 index 0000000..eab0eae --- /dev/null +++ b/docs/前端开发规范.md @@ -0,0 +1,528 @@ +# Finyx AI 前端开发规范与约束 + +## 📋 文档说明 + +本文档定义了 Finyx AI 前端项目的开发规范、约束和最佳实践，确保代码质量、一致性和可维护性。所有开发人员必须遵循本规范。 + +**最后更新**: 2025-01-XX +**适用版本**: v1.0.0+ + +--- + +## 🎨 设计系统规范 + +### 1. 色彩系统 + +#### 1.1 主色调 +- **主色 (Primary)**: `#3067EF` - 用于主要操作按钮、链接、激活状态 +- **背景色 (Background)**: `#F4F8FF` - 页面主背景色 +- **白色 (White)**: `#ffffff` - 卡片、侧边栏背景 + +#### 1.2 文本颜色 +- **主文本**: `#1f2329` - 主要文本内容 +- **次文本**: `#646a73` - 次要文本、说明文字 +- **禁用文本**: `#bbbfc4` - 禁用状态的文本 + +#### 1.3 边框颜色 +- **默认边框**: `#dee0e3` - 卡片、输入框边框 +- **激活边框**: `#3067EF` - 激活状态的边框 + +#### 1.4 状态颜色 +- **悬停背景**: `rgba(48, 103, 239, 0.06)` - 鼠标悬停时的背景色 +- **激活背景**: `#ECF2FF` - 激活状态的背景色 + +#### 1.5 使用规范 +```typescript +// ✅ 正确：使用 Tailwind 配置的颜色类 +
按钮
+
内容
+ +// ❌ 错误：直接使用颜色值 +
按钮
+
按钮
+``` + +### 2. 字体系统 + +#### 2.1 字体族 +- **主字体**: `PingFang SC`, `AlibabaPuHuiTi`, `sans-serif` +- **等宽字体**: 用于代码显示 + +#### 2.2 字体大小 +- **基础字号**: `14px` (Tailwind: `text-base`) +- **标题层级**: + - H1: `24px` (`text-2xl`) + - H2: `20px` (`text-xl`) + - H3: `18px` (`text-lg`) + - H4: `16px` (`text-base`) + +#### 2.3 字重 +- **常规**: `400` (`font-normal`) +- **中等**: `500` (`font-medium`) +- **加粗**: `600` (`font-bold`) + +### 3. 间距系统 + +#### 3.1 基础间距单位 +- **基础单位**: `8px` (对应 Tailwind 的 `1` 单位) +- **常用间距**: + - `4px` (`p-1`, `m-1`) + - `8px` (`p-2`, `m-2`) + - `12px` (`p-3`, `m-3`) + - `16px` (`p-4`, `m-4`) + - `24px` (`p-6`, `m-6`) + +#### 3.2 页面内边距 +- **页面容器**: `24px` (`p-6`) +- **卡片内边距**: `16px` (`p-4`) 或 `24px` (`p-6`) + +### 4. 阴影系统 + +#### 4.1 标准阴影 +- **卡片阴影**: `0px 2px 4px 0px rgba(31, 35, 41, 0.12)` (`shadow-app`) +- **悬停阴影**: 可适当增强 + +--- + +## 🏗️ 技术栈约束 + +### 1. 核心框架 +- **前端框架**: Vue 3.4.0+ (Composition API) +- **开发语言**: TypeScript 5.2.2+ +- **构建工具**: Vite 5.0.8+ +- **样式方案**: Tailwind CSS 3.3.6+ + +### 2. 状态管理 +- **状态管理库**: Pinia 2.1.0+ +- **路由管理**: Vue Router 4.2.0+ + +### 3. UI 组件库 +- **图标库**: Lucide Vue Next 0.344.0+ +- **图表库**: Recharts 2.10.3+ (如需要) + +### 4. 禁止使用的技术 +- ❌ **React**: 本项目已迁移至 Vue，禁止使用 React +- ❌ **Element Plus**: 旧系统使用，新功能应使用 Tailwind CSS 构建 +- ❌ **SCSS/SASS**: 统一使用 Tailwind CSS，禁止使用 SCSS +- ❌ **内联样式**: 除非动态样式，否则使用 Tailwind 类 + +--- + +## 📁 项目结构规范 + +### 1. 目录结构 +``` +src/ +├── components/ # 通用可复用组件 +│ ├── common/ # 基础通用组件 +│ └── business/ # 业务相关组件 +├── layouts/ # 布局组件 +├── pages/ # 页面组件 +│ └── engagement/ # 业务模块子页面 +├── stores/ # Pinia 状态管理 +├── types/ # TypeScript 类型定义 +├── utils/ # 工具函数 +├── api/ # API 接口定义 +├── assets/ # 静态资源 +└── styles/ # 全局样式（如需要） +``` + +### 2. 文件命名规范 + +#### 2.1 组件文件 +- **Vue 组件**: 使用 PascalCase，如 `SidebarItem.vue` +- **TypeScript 文件**: 使用 camelCase，如 `mockData.ts` +- **工具函数**: 使用 camelCase，如 `formatDate.ts` + +#### 2.2 组件命名 +- **单文件组件**: 使用 PascalCase +- **组件名**: 与文件名保持一致 + +```vue + + + + + +``` + +### 3. 导入顺序规范 +```typescript +// 1. Vue 核心 +import { ref, computed, onMounted } from 'vue' + +// 2. 第三方库 +import { useRouter } from 'vue-router' +import { useToast } from '@/components/Toast' + +// 3. 项目内部组件 +import { SidebarItem } from '@/components/SidebarItem' + +// 4. 类型定义 +import type { Project, Step } from '@/types' + +// 5. 工具函数 +import { formatDate } from '@/utils/date' + +// 6. 样式（如需要） +import './styles.css' +``` + +--- + +## 💻 代码规范 + +### 1. TypeScript 规范 + +#### 1.1 类型定义 +```typescript +// ✅ 正确：使用 interface 定义对象类型 +interface Project { + id: string + name: string + progress: number +} + +// ✅ 正确：使用 type 定义联合类型 +type Step = 'setup' | 'inventory' | 'context' | 'value' | 'delivery' + +// ❌ 错误：使用 any +function processData(data: any) { } +``` + +#### 1.2 Props 定义 +```vue + +``` + +#### 1.3 响应式数据 +```vue + +``` + +### 2. Vue 组件规范 + +#### 2.1 Composition API +```vue + +``` + +#### 2.2 组件结构 +```vue + + + + + +``` + +#### 2.3 事件处理 +```vue + + + +``` + +### 3. 样式规范 + +#### 3.1 Tailwind CSS 使用 +```vue + +``` + +#### 3.2 响应式设计 +```vue + +``` + +#### 3.3 自定义样式 +```vue + +``` + +### 4. 组件设计规范 + +#### 4.1 组件职责 +- **单一职责**: 每个组件只负责一个功能 +- **可复用性**: 通用组件应设计为可复用 +- **可组合性**: 复杂组件应由简单组件组合而成 + +#### 4.2 Props 设计 +```vue + +``` + +#### 4.3 事件定义 +```vue + +``` + +--- + +## 🎯 与旧系统融合规范 + +### 1. 色彩一致性 +- **必须使用**: 旧系统的色彩变量（已在 `tailwind.config.js` 中定义） +- **禁止**: 使用新的颜色值，除非经过设计团队批准 + +### 2. 组件风格 +- **侧边栏**: 白色背景，浅色激活状态 +- **卡片**: 白色背景，浅色边框，标准阴影 +- **按钮**: 主色背景，圆角设计 + +### 3. 技术栈兼容 +- **新功能**: 使用 Vue 3 + TypeScript + Tailwind CSS +- **旧功能**: 保持 Vue 3 + Element Plus + SCSS +- **融合策略**: 新功能作为独立模块，通过路由集成 + +### 4. 样式隔离 +- **新组件**: 使用 Tailwind CSS，避免全局样式污染 +- **旧组件**: 保持现有样式，不强制迁移 +- **冲突处理**: 使用 CSS Modules 或作用域样式 + +--- + +## 🚫 禁止事项 + +### 1. 代码层面 +- ❌ 禁止使用 `any` 类型（除非特殊情况） +- ❌ 禁止使用 `@ts-ignore`（除非有充分理由） +- ❌ 禁止使用内联样式（除非动态样式） +- ❌ 禁止直接修改 DOM（使用 Vue 响应式系统） + +### 2. 样式层面 +- ❌ 禁止使用 SCSS/SASS（统一使用 Tailwind） +- ❌ 禁止使用硬编码颜色值（使用 Tailwind 配置的颜色） +- ❌ 禁止使用 `!important`（除非绝对必要） + +### 3. 依赖层面 +- ❌ 禁止引入 React 相关依赖 +- ❌ 禁止引入 Element Plus（新功能） +- ❌ 禁止引入未经过审查的第三方库 + +--- + +## ✅ 最佳实践 + +### 1. 性能优化 +- 使用 `computed` 而非 `watch`（如可能） +- 使用 `v-show` 而非 `v-if`（频繁切换） +- 大列表使用虚拟滚动 +- 图片使用懒加载 + +### 2. 可访问性 +- 使用语义化 HTML 标签 +- 为交互元素添加 `aria-label` +- 确保键盘导航可用 +- 确保颜色对比度符合 WCAG 标准 + +### 3. 错误处理 +- 使用 try-catch 处理异步操作 +- 使用 Toast 显示错误信息 +- 提供友好的错误提示 + +### 4. 代码注释 +```typescript +// ✅ 正确：清晰的注释 +/** + * 计算项目进度百分比 + * @param completed - 已完成步骤数 + * @param total - 总步骤数 + * @returns 进度百分比 (0-100) + */ +const calculateProgress = (completed: number, total: number): number => { + return Math.round((completed / total) * 100) +} +``` + +--- + +## 📝 提交规范 + +### 1. Commit 消息格式 +``` +(): + + + +