finyx_data_frontend/docs/前端开发规范.md

# 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 配置的颜色类
<div className="bg-app-primary text-app-white">按钮</div>
<div className="bg-app-bg text-app-text">内容</div>

// ❌ 错误：直接使用颜色值
<div className="bg-[#3067EF]">按钮</div>
<div style={{ backgroundColor: '#3067EF' }}>按钮</div>
```

### 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
<!-- ✅ 正确 -->
<script setup lang="ts">
// SidebarItem.vue
</script>

<!-- ❌ 错误 -->
<script setup lang="ts">
// 文件名: SidebarItem.vue，但组件名不一致
</script>
```

### 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
<script setup lang="ts">
// ✅ 正确：使用 defineProps 和类型
interface Props {
  title: string
  count?: number
  items: Project[]
}

const props = defineProps<Props>()

// ❌ 错误：不使用类型
const props = defineProps(['title', 'count'])
</script>
```

#### 1.3 响应式数据
```vue
<script setup lang="ts">
// ✅ 正确：明确类型
const count = ref<number>(0)
const projects = ref<Project[]>([])

// ❌ 错误：不指定类型
const count = ref(0)
</script>
```

### 2. Vue 组件规范

#### 2.1 Composition API
```vue
<script setup lang="ts">
// ✅ 正确：使用 Composition API
import { ref, computed, onMounted } from 'vue'

const count = ref(0)
const doubleCount = computed(() => count.value * 2)

onMounted(() => {
  // 初始化逻辑
})
</script>
```

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

<script setup lang="ts">
// 脚本内容
</script>

<style scoped>
/* 样式内容（尽量使用 Tailwind，避免使用） */
</style>
```

#### 2.3 事件处理
```vue
<template>
  <!-- ✅ 正确：使用 @click -->
  <button @click="handleClick">点击</button>
  
  <!-- ✅ 正确：传递参数 -->
  <button @click="handleDelete(item.id)">删除</button>
</template>

<script setup lang="ts">
const handleClick = () => {
  // 处理逻辑
}

const handleDelete = (id: string) => {
  // 处理逻辑
}
</script>
```

### 3. 样式规范

#### 3.1 Tailwind CSS 使用
```vue
<template>
  <!-- ✅ 正确：使用 Tailwind 类 -->
  <div class="bg-app-white border border-app-border rounded-lg p-6">
    <h2 class="text-xl font-bold text-app-text">标题</h2>
  </div>
  
  <!-- ❌ 错误：使用内联样式 -->
  <div style="background: white; border: 1px solid #dee0e3;">
    内容
  </div>
</template>
```

#### 3.2 响应式设计
```vue
<template>
  <!-- ✅ 正确：使用 Tailwind 响应式类 -->
  <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
    <!-- 内容 -->
  </div>
</template>
```

#### 3.3 自定义样式
```vue
<style scoped>
/* ✅ 仅在必要时使用自定义样式 */
.custom-animation {
  animation: fade-in 0.3s ease-out;
}

/* ❌ 避免覆盖 Tailwind 类 */
.bg-white {
  background: red; /* 错误 */
}
</style>
```

### 4. 组件设计规范

#### 4.1 组件职责
- **单一职责**: 每个组件只负责一个功能
- **可复用性**: 通用组件应设计为可复用
- **可组合性**: 复杂组件应由简单组件组合而成

#### 4.2 Props 设计
```vue
<script setup lang="ts">
// ✅ 正确：明确的 Props 定义
interface Props {
  // 必需属性
  title: string
  items: Project[]
  
  // 可选属性
  count?: number
  showActions?: boolean
  
  // 带默认值
  variant?: 'primary' | 'secondary'
}

const props = withDefaults(defineProps<Props>(), {
  showActions: true,
  variant: 'primary'
})
</script>
```

#### 4.3 事件定义
```vue
<script setup lang="ts">
// ✅ 正确：使用 defineEmits
interface Emits {
  (e: 'update', value: string): void
  (e: 'delete', id: string): void
}

const emit = defineEmits<Emits>()

const handleUpdate = (value: string) => {
  emit('update', value)
}
</script>
```

---

## 🎯 与旧系统融合规范

### 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 消息格式
```
<type>(<scope>): <subject>

<body>

<footer>
```

### 2. Type 类型
- `feat`: 新功能
- `fix`: 修复 bug
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 代码重构
- `perf`: 性能优化
- `test`: 测试相关
- `chore`: 构建/工具相关

### 3. 示例
```
feat(dashboard): 添加项目进度可视化

- 添加进度条组件
- 集成到 DashboardView
- 支持实时更新

Closes #123
```

---

## 🔍 代码审查清单

### 1. 功能检查
- [ ] 功能按需求实现
- [ ] 边界情况已处理
- [ ] 错误处理完善
- [ ] 用户体验良好

### 2. 代码质量
- [ ] TypeScript 类型完整
- [ ] 无 ESLint 错误
- [ ] 代码结构清晰
- [ ] 注释充分

### 3. 样式检查
- [ ] 使用 Tailwind 配置的颜色
- [ ] 响应式设计正确
- [ ] 与设计稿一致
- [ ] 无样式冲突

### 4. 性能检查
- [ ] 无不必要的重渲染
- [ ] 异步操作正确处理
- [ ] 大列表已优化

---

## 📚 参考资源

- [Vue 3 官方文档](https://vuejs.org/)
- [TypeScript 官方文档](https://www.typescriptlang.org/)
- [Tailwind CSS 文档](https://tailwindcss.com/docs)
- [Pinia 官方文档](https://pinia.vuejs.org/)
- [Vue Router 官方文档](https://router.vuejs.org/)

---

## 📅 更新记录

- **2025-01-XX**: 初始版本创建

---

## 👥 维护者

- Finyx AI 前端团队