python/finyx_data_frontend

Fork 0

李季 6ec4ff9666 完整迁移调整 vue 并且融合原代码结构。

2026-01-08 14:34:06 +08:00

12 KiB

Raw Blame History

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 使用规范

// ✅ 正确：使用 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
组件名: 与文件名保持一致

<!-- ✅ 正确 -->
<script setup lang="ts">
// SidebarItem.vue
</script>

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

3. 导入顺序规范

// 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 类型定义

// ✅ 正确：使用 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 定义

<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 响应式数据

<script setup lang="ts">
// ✅ 正确：明确类型
const count = ref<number>(0)
const projects = ref<Project[]>([])

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

2. Vue 组件规范

2.1 Composition API

<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 组件结构

<template>
  <!-- 模板内容 -->
</template>

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

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

2.3 事件处理

<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 使用

<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 响应式设计

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

3.3 自定义样式

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

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

4. 组件设计规范

4.1 组件职责

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

4.2 Props 设计

<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 事件定义

<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. 代码注释

// ✅ 正确：清晰的注释
/**
 * 计算项目进度百分比
 * @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. 性能检查

无不必要的重渲染
异步操作正确处理
大列表已优化

📚 参考资源

📅 更新记录

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

👥 维护者

Finyx AI 前端团队

12 KiB Raw Blame History Unescape Escape

Finyx AI 前端开发规范与约束

📋 文档说明

🎨 设计系统规范

1. 色彩系统

1.1 主色调

1.2 文本颜色

1.3 边框颜色

1.4 状态颜色

1.5 使用规范

2. 字体系统

2.1 字体族

2.2 字体大小

2.3 字重

3. 间距系统

3.1 基础间距单位

3.2 页面内边距

4. 阴影系统

4.1 标准阴影

🏗️ 技术栈约束

1. 核心框架

2. 状态管理

3. UI 组件库

4. 禁止使用的技术

📁 项目结构规范

1. 目录结构

2. 文件命名规范

2.1 组件文件

2.2 组件命名

3. 导入顺序规范

💻 代码规范

1. TypeScript 规范

1.1 类型定义

1.2 Props 定义

1.3 响应式数据

2. Vue 组件规范

2.1 Composition API

2.2 组件结构

2.3 事件处理

3. 样式规范

3.1 Tailwind CSS 使用

3.2 响应式设计

3.3 自定义样式

4. 组件设计规范

4.1 组件职责

4.2 Props 设计

4.3 事件定义

🎯 与旧系统融合规范

1. 色彩一致性

2. 组件风格

3. 技术栈兼容

4. 样式隔离

🚫 禁止事项

1. 代码层面

2. 样式层面

3. 依赖层面

✅ 最佳实践

1. 性能优化

2. 可访问性

3. 错误处理

4. 代码注释

📝 提交规范

1. Commit 消息格式

2. Type 类型

3. 示例

🔍 代码审查清单

1. 功能检查

2. 代码质量

3. 样式检查

4. 性能检查

📚 参考资源

📅 更新记录

👥 维护者

12 KiB

Raw Blame History