plus-ui/.cursorrules

# Art Design Pro UI 规范 - Plus UI 重构版

## 设计理念
基于 Art Design Pro 的设计语言，追求现代化、精致、用户友好的界面体验。注重细节、动效和用户交互的流畅性。

## 1. 颜色系统

### 主色调 (Primary Colors)
```css
--art-primary: 93, 135, 255;        /* 主品牌色 - 蓝色 */
--art-secondary: 73, 190, 255;      /* 辅助色 - 天蓝色 */
--art-success: 19, 222, 185;        /* 成功色 - 绿色 */
--art-warning: 255, 174, 31;        /* 警告色 - 橙色 */
--art-error: 250, 137, 107;         /* 错误色 - 红色 */
--art-info: 83, 155, 255;           /* 信息色 - 蓝色 */
--art-danger: 255, 77, 79;          /* 危险色 - 红色 */
```

### 背景色系统 (Background Colors)
```css
/* 浅色主题 */
--art-bg-color: #fafbfc;            /* 页面底色 */
--art-main-bg-color: #ffffff;       /* 主要内容背景 */
--art-bg-primary: 236, 242, 255;    /* 主色背景 */
--art-bg-secondary: 232, 247, 255;  /* 辅助背景 */
--art-bg-success: 230, 255, 250;    /* 成功背景 */
--art-bg-warning: 254, 245, 229;    /* 警告背景 */
--art-bg-error: 253, 237, 232;      /* 错误背景 */

/* 暗色主题 */
html.dark {
  --art-bg-color: #070707;          /* 页面底色 */
  --art-main-bg-color: #161618;     /* 主要内容背景 */
}
```

### 灰度色系 (Gray Scale)
```css
--art-gray-100: #f9f9f9;
--art-gray-200: #f1f1f4;
--art-gray-300: #dbdfe9;
--art-gray-400: #c4cada;
--art-gray-500: #99a1b7;
--art-gray-600: #78829d;
--art-gray-700: #4b5675;
--art-gray-800: #252f4a;
--art-gray-900: #071437;
```

## 2. 字体系统

### 字体家族
```css
font-family: 'DMSans', 'Montserrat', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
```

### 字体大小
- 超大标题：24px (1.5rem)
- 大标题：20px (1.25rem)
- 中标题：18px (1.125rem)
- 小标题：16px (1rem)
- 正文：14px (0.875rem)
- 小字：12px (0.75rem)
- 辅助文字：10px (0.625rem)

### 字体权重
- Light: 300
- Normal: 400
- Medium: 500
- Semibold: 600
- Bold: 700

## 3. 间距系统

### 间距单位 (基于 4px 网格)
```css
--space-xs: 4px;
--space-sm: 8px;
--space-md: 12px;
--space-lg: 16px;
--space-xl: 20px;
--space-2xl: 24px;
--space-3xl: 32px;
--space-4xl: 48px;
--space-5xl: 64px;
```

### 内边距规范
- 卡片内边距：20px
- 按钮内边距：8px 16px
- 输入框内边距：10px 12px
- 表格单元格：12px
- 弹窗内边距：25px 20px

### 外边距规范
- 组件间距：20px
- 段落间距：16px
- 按钮间距：8px
- 表单项间距：12px

## 4. 圆角系统

### 圆角规范
```css
--border-radius-xs: 4px;
--border-radius-sm: 6px;
--border-radius-md: 8px;
--border-radius-lg: 10px;
--border-radius-xl: 12px;
--border-radius-2xl: 16px;
--border-radius-full: 50%;
```

### 应用场景
- 按钮：6px
- 输入框：8px
- 卡片：10px
- 弹窗：10px
- 图片：6px
- 头像：50%

## 5. 阴影系统

### 阴影等级
```css
--shadow-xs: 0 0.1rem 0.75rem 0.25rem rgba(0, 0, 0, 0.05);
--shadow-sm: 0 0.1rem 1rem 0.25rem rgba(0, 0, 0, 0.05);
--shadow-md: 0 0.5rem 1.5rem 0.5rem rgba(0, 0, 0, 0.075);
--shadow-lg: 0 1rem 2rem 1rem rgba(0, 0, 0, 0.1);
--shadow-card: 0px 3px 4px 0px rgba(0, 0, 0, 0.03);
```

### 应用场景
- 卡片阴影：shadow-card
- 悬浮效果：shadow-sm
- 弹窗阴影：shadow-lg
- 按钮悬浮：shadow-xs

## 6. 边框系统

### 边框颜色
```css
--border-color: #eaebf1;
--border-dashed-color: #dbdfe9;
--border-card-color: #f1f1f4;
```

### 边框宽度
- 默认：1px
- 粗边框：2px
- 表格边框：1px

## 7. 动画系统

### 缓动曲线
```css
--ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
--ease-out: cubic-bezier(0, 0, 0.2, 1);
--ease-in: cubic-bezier(0.4, 0, 1, 1);
```

### 动画时长
- 快速：0.15s
- 标准：0.3s
- 慢速：0.5s

### 常用动画
- 淡入淡出：opacity transition
- 悬浮效果：transform scale
- 按钮点击：transform scale(0.95)
- 页面切换：fade + slide

## 8. 组件规范

### 按钮 (Button)
#### 基础规范
- **尺寸系统**：Large(40px) / Default(32px) / Small(28px)
- **圆角规范**：6px(默认) / 8px(大) / 4px(小) / 50%(圆形)
- **字体权重**：500 (Medium)
- **过渡动画**：cubic-bezier(0.4, 0, 0.2, 1) 0.3s
- **字母间距**：0.02em

#### 按钮类型 - 全部采用轮廓式设计
- **Primary按钮**：轮廓式主色设计，主色边框和文字，5%透明度主色背景
- **Success按钮**：轮廓式成功色设计，成功色边框和文字，5%透明度成功色背景
- **Warning按钮**：轮廓式警告色设计，警告色边框和文字，5%透明度警告色背景
- **Danger按钮**：轮廓式危险色设计，危险色边框和文字，5%透明度危险色背景
- **Info按钮**：轮廓式信息色设计，信息色边框和文字，5%透明度信息色背景
- **Default按钮**：白色背景，灰色边框，灰色文字

#### 变体样式
- **Plain按钮**：与标准按钮完全相同的轮廓式设计，无差异化
- **Outline按钮**：轮廓式设计（现已作为全部按钮的标准样式）
- **Text按钮**：无背景边框，彩色文字，悬浮10%透明背景
- **Link按钮**：下划线样式，主色文字，无背景

#### 交互效果 - 轮廓式按钮专用
- **悬浮状态**：上移1px + 背景透明度变为10% + 边框透明度变为80% + 彩色阴影
- **点击状态**：98%缩放 + 0.1s快速过渡 + 背景透明度变为15%
- **禁用状态**：50%透明度，禁用所有交互和变换
- **加载状态**：70%透明度 + 遮罩层效果

**详细规范**：
- **默认状态**：5%透明度彩色背景 + 100%彩色边框
- **悬浮状态**：10%透明度彩色背景 + 80%透明度彩色边框 + `0 4px 12px rgba(color, 0.2)` 阴影
- **点击状态**：15%透明度彩色背景 + 边框保持80%透明度

#### 特殊状态
- **圆形按钮**：宽高相等，50%圆角，主要用于图标按钮
- **按钮组**：相邻按钮圆角归零，-1px右边距无缝连接
- **阴影规范**：轮廓式按钮悬浮阴影统一为 `0 4px 12px rgba(color, 0.2)`

#### 🎨 轮廓式按钮设计系统（2024年版本）
**设计理念**：全面采用轮廓式（Outline）按钮设计，提供更加优雅、现代和一致的用户界面体验。

**核心优势**：
- ✅ **视觉轻量化**：减少视觉重量，避免界面过于厚重
- ✅ **层次分明**：通过透明度变化清晰表达交互状态
- ✅ **品牌一致性**：所有彩色按钮都保持品牌色彩的纯净表达
- ✅ **可访问性优化**：高对比度的边框和文字确保良好的可读性

**技术实现**：
```scss
// 轮廓式按钮核心模式（适用于所有按钮，包括MessageBox）
.el-button--[type] {
  border: 1px solid rgb(var(--art-[type])) !important;
  color: rgb(var(--art-[type])) !important;
  background: rgba(var(--art-[type]), 0.05) !important;

  &:hover {
    background: rgba(var(--art-[type]), 0.1) !important;
    border-color: rgba(var(--art-[type]), 0.8) !important;
    box-shadow: 0 4px 12px rgba(var(--art-[type]), 0.2) !important;
  }

  &:active {
    background: rgba(var(--art-[type]), 0.15) !important;
  }
}

// MessageBox 专用样式确保一致性
.el-message-box .el-message-box__btns .el-button {
  // 继承全局轮廓式按钮样式，使用!important确保优先级
}
```

**适用范围**：
- ✅ 全局所有 primary、success、warning、danger、info 按钮
- ✅ 页面表单、表格操作按钮
- ✅ 确认弹窗（MessageBox）中的所有按钮
- ✅ 普通弹窗（Dialog）中的所有按钮
- ✅ 导航和功能按钮

**实施位置**：
- 样式文件：`src/assets/styles/art-element-ui.scss`
- 优先级：使用 `!important` 确保全局覆盖
- 兼容性：与现有 Element Plus 组件完全兼容

### 输入框 (Input)
- 边框：1px solid --border-color
- 圆角：8px
- 内边距：10px 12px
- 聚焦状态：主色边框
- 错误状态：红色边框

### 卡片 (Card)
- 背景：白色
- 圆角：10px
- 阴影：shadow-card
- 内边距：20px
- 边框：可选 1px --border-card-color

### 左侧菜单 (Sidebar Menu)
#### 基础规范
- **菜单宽度**: 250px(展开) / 54px(收起)
- **背景色**: 浅色主题白色 / 暗色主题深色
- **圆角**: 4px (菜单项内边距)
- **间距**: 外边距8px，内边距2px
- **过渡动画**: 0.3s ease 流畅过渡

#### 菜单项状态
- **默认状态**:
  - 文字：`--art-text-gray-700`
  - 图标：`--art-text-gray-600`
  - 背景：透明
- **悬浮状态**:
  - 文字：`--art-text-gray-800`
  - 图标：主题色 `rgb(var(--art-primary))`
  - 背景：8%主题色透明 `rgba(var(--art-primary), 0.08)`
- **选中状态**:
  - 文字：主题色 `rgb(var(--art-primary))`
  - 图标：主题色 `rgb(var(--art-primary))`
  - 背景：10%主题色透明 `rgba(var(--art-primary), 0.1)`

#### 嵌套子菜单
- **背景透明化**: 子菜单项背景透明
- **悬浮效果**: 6%主题色透明背景
- **选中效果**: 10%主题色透明背景
- **层级缩进**: 标准Element Plus缩进
- **圆角统一**: 4px内边距圆角

#### 暗色主题适配
- **悬浮背景**: 15%主题色透明 `rgba(var(--art-primary), 0.15)`
- **选中背景**: 20%主题色透明 `rgba(var(--art-primary), 0.2)`
- **子菜单悬浮**: 12%主题色透明背景
- **颜色继承**: 与浅色主题文字图标颜色保持一致

#### 收起状态
- **容器宽度**: 54px固定宽度
- **菜单项高度**: 48px，确保统一高度
- **图标规范**: 16x16px，美观合理
- **完美居中**: 使用Flexbox确保水平垂直居中
- **一级菜单特殊处理**: 使用`.el-menu > .el-menu-item`选择器确保优先级
- **tooltip支持**: 兼容`.el-tooltip`和`.el-menu-tooltip__trigger`元素
- **统一对齐**: 所有菜单项（一级、多级）完全一致的居中效果
- **提示框**: Element Plus tooltip显示完整菜单名
- **展开动画**: 0.28s流畅过渡动画

### 表格 (Table)
- 表头背景：--gray-100
- 斑马纹：--gray-50
- 边框：1px --border-color
- 悬浮行：--gray-100 背景

### 弹窗 (Modal/Dialog)
- 背景：白色
- 圆角：10px
- 阴影：shadow-lg
- 动画：scale + fade
- 遮罩：rgba(0,0,0,0.5)

#### 确认弹窗按钮样式规范
**重要原则**：确认弹窗（MessageBox.confirm）中的按钮与全局轮廓式按钮规范保持完全一致，确保整个系统的设计统一性。

**设计理念**：确认弹窗中的按钮采用轮廓式设计，与页面中的其他按钮保持一致的视觉风格，通过统一的轮廓式设计语言提供现代化、轻量化的用户体验。

- **确定按钮（Primary）**：使用轮廓式主色设计
  - 背景：5%透明度主色 `rgba(var(--art-primary), 0.05)`
  - 边框：1px 主色边框 `rgb(var(--art-primary))`
  - 文字颜色：主色 `rgb(var(--art-primary))`
  - 悬浮效果：
    - 背景：10%透明度主色 `rgba(var(--art-primary), 0.1)`
    - 边框：80%透明度主色 `rgba(var(--art-primary), 0.8)`
    - 阴影：`0 4px 12px rgba(var(--art-primary), 0.2)`
    - 上移1px效果保持
  - 点击效果：
    - 背景：15%透明度主色 `rgba(var(--art-primary), 0.15)`
    - 98%缩放效果保持

- **其他类型按钮**：使用对应色彩的轮廓式设计
  - **Success按钮**：轮廓式成功色设计，成功色边框和文字，5%透明度背景
  - **Warning按钮**：轮廓式警告色设计，警告色边框和文字，5%透明度背景
  - **Danger按钮**：轮廓式危险色设计，危险色边框和文字，5%透明度背景
  - **Info按钮**：轮廓式信息色设计，信息色边框和文字，5%透明度背景
  - 交互效果：与Primary按钮保持一致的轮廓式悬浮和点击效果

- **取消按钮**：使用默认按钮样式（保持轻量化）
  - 背景：主背景色 `var(--art-main-bg-color)`
  - 边框：1px 灰色边框 `var(--art-border-color)`
  - 文字颜色：`var(--art-text-gray-700)`
  - 阴影：`0 1px 3px rgba(0, 0, 0, 0.1)`

- **统一规范**：
  - 圆角：8px
  - 高度：32px
  - 内边距：0 16px
  - 字体权重：500
  - 过渡动画：`all 0.3s cubic-bezier(0.4, 0, 0.2, 1)`
  - 字母间距：0.02em

**设计统一性说明**：
- **全局按钮统一**：所有按钮（页面按钮和确认弹窗按钮）都采用轮廓式设计
- **视觉一致性**：确保整个系统的按钮风格保持完全一致
- **现代化体验**：通过统一的轮廓式设计提供现代化、轻量化的用户体验
- **交互规范**：所有按钮都遵循相同的悬浮、点击、透明度变化规范

**实现位置**：
- 样式文件：`src/assets/styles/art-element-ui.scss`
- 选择器：`.el-message-box .el-message-box__btns .el-button`
- 优先级：使用 `!important` 确保样式优先级
- 适用场景：confirm、alert、prompt等所有MessageBox弹窗
- 设计原则：与全局轮廓式按钮规范保持完全一致

#### MessageBox 按钮布局规范

**按钮顺序规范**：确认弹窗（MessageBox）中的按钮顺序遵循国内用户习惯，确定按钮在左侧，取消按钮在右侧。

**布局实现**：
- **按钮容器**：使用 `flex-direction: row-reverse` 实现按钮顺序调整
- **确定按钮**：`order: 2` 确保排在左侧（用户优先操作位置）
- **取消按钮**：`order: 1` 排在右侧（次要操作位置）
- **按钮间距**：使用 `gap: 12px` 确保按钮之间的合理间距

**设计理念**：
- **符合习惯**：遵循国内用户的操作习惯，确定操作在左，取消操作在右
- **视觉引导**：确定按钮的主色调设计在左侧能够更好地引导用户操作
- **一致性保证**：所有确认弹窗的按钮顺序保持完全一致

**技术实现**：
```scss
// MessageBox 按钮顺序调整
.el-message-box .el-message-box__btns {
  display: flex !important;
  flex-direction: row-reverse !important;
  justify-content: flex-start !important;
  gap: 12px !important;
}

.el-message-box .el-message-box__btns .el-button.el-button--primary {
  order: 2 !important; // 确定按钮排在前面（左侧）
}

.el-message-box .el-message-box__btns .el-button.el-button--default,
.el-message-box .el-message-box__btns .el-button:not([class*="el-button--"]) {
  order: 1 !important; // 取消按钮排在后面（右侧）
}
```

**应用场景**：
- ✅ confirm 确认弹窗：确定在左，取消在右
- ✅ alert 提示弹窗：确定按钮居左显示
- ✅ prompt 输入弹窗：确定在左，取消在右
- ✅ 所有自定义 MessageBox 弹窗

**用户体验考虑**：
- **操作优先级**：确定操作作为主要操作放在左侧，符合从左到右的阅读习惯
- **降低误操作**：确定按钮的突出位置减少用户误点取消的情况
- **一致性体验**：整个系统的确认弹窗都遵循相同的按钮顺序

#### MessageBox 按钮统一性原则

**核心要求**：MessageBox（确认弹窗）中的所有按钮必须与页面中的其他按钮保持完全一致的轮廓式设计。

**统一性体现**：
- ✅ **视觉风格**：相同的边框、背景、文字颜色规范
- ✅ **交互效果**：相同的悬浮、点击、透明度变化效果
- ✅ **尺寸规格**：相同的高度、圆角、内边距、字体权重
- ✅ **颜色系统**：使用相同的色彩变量和透明度规范

**实施保证**：
```scss
// 确保MessageBox按钮与全局按钮完全一致
.el-message-box .el-message-box__btns .el-button {
  // 所有样式属性都使用!important确保优先级
  // 严格遵循全局轮廓式按钮规范
}
```

**验收标准**：
- MessageBox中的按钮与页面按钮在视觉上无任何差异
- 所有交互状态的表现完全一致
- 不同类型的按钮（primary、success、warning等）都遵循统一规范

## 9. 布局规范

### 栅格系统
- 容器最大宽度：1200px
- 栅格列数：24列
- 间距：20px

### 页面布局
- 顶栏高度：60px
- 侧边栏宽度：240px (展开) / 80px (收起)
- 内容区域：自适应
- 底部高度：60px

### 响应式断点
```scss
$device-phone: 500px;      // 手机
$device-ipad: 800px;       // 平板
$device-ipad-pro: 1180px;  // 平板 Pro
$device-notebook: 1600px;  // 笔记本
```

## 10. 主题系统

### 主题切换
- 支持浅色/暗色主题
- 使用 CSS 变量实现
- 平滑过渡动画
- 本地存储偏好

### 颜色模式
- 浅色模式：明亮、清晰
- 暗色模式：柔和、护眼
- 跟随系统：自动切换

## 11. 交互规范

### 悬浮效果 (Hover)
- 按钮：背景变浅 + 轻微放大
- 卡片：阴影加深
- 图标：颜色变化 + 动画
- 链接：颜色变化

### 点击效果 (Active)
- 按钮：轻微缩小
- 卡片：阴影减弱
- 输入框：聚焦边框

### 加载状态
- 骨架屏：灰色占位
- 进度条：主色进度
- 加载动画：旋转图标

## 12. 图标系统

### 图标规范
- 尺寸：16px, 20px, 24px
- 线条粗细：1.5px
- 风格：线性图标
- 颜色：继承文字色或主题色

### 图标用法
- 按钮图标：16px
- 菜单图标：20px
- 页面图标：24px
- 装饰图标：根据需要

## 13. 移动端适配

### 移动端规范
- 最小点击区域：44px
- 字体适当放大
- 间距适当增加
- 简化交互方式
- 优化触摸体验

### 响应式布局
- 移动端优先
- 灵活的栅格系统
- 可收起的侧边栏
- 简化的导航方式

## 14. 可访问性 (Accessibility)

### 颜色对比度
- 文字对比度：4.5:1 以上
- 大文字对比度：3:1 以上
- 状态指示：不仅依赖颜色

### 交互可访问性
- 键盘导航支持
- 屏幕阅读器支持
- 焦点指示清晰
- 错误信息明确

## 15. 实施原则

### 开发规范
1. 优先使用 CSS 变量
2. 统一使用 SCSS 预处理器
3. 组件化开发
4. 响应式设计
5. 性能优化

### 维护规范
1. 定期更新设计规范
2. 保持组件库的一致性
3. 及时修复视觉问题
4. 收集用户反馈

### 质量保证
1. 多设备测试
2. 多浏览器兼容
3. 性能监控
4. 用户体验评估

---

## 注意事项

1. **一致性优先**：确保整个系统的视觉一致性
2. **用户体验**：以用户体验为核心进行设计
3. **性能考虑**：优化动画和样式性能
4. **可维护性**：编写可维护的样式代码
5. **扩展性**：为未来的功能扩展预留空间

## 🚀 重大更新记录

### 2024年 - 全局轮廓式按钮系统
**更新时间**：2024年

**核心变更**：将整个系统的按钮设计从填充式改为轮廓式设计

**影响范围**：
- ✅ 全局所有 primary、success、warning、danger、info 按钮
- ✅ 页面表单和表格中的操作按钮
- ✅ 确认弹窗按钮（包括 confirm、alert、prompt）
- ✅ 导航和功能按钮

**设计理念**：
- 提供更加轻量化、现代化的视觉体验
- 保持品牌色彩的纯净表达
- 通过透明度变化清晰表达交互状态
- 提升界面的整体协调性和专业感

**技术特点**：
- 使用 `!important` 确保全局覆盖优先级
- 与 Element Plus 组件完全兼容
- 支持所有交互状态（hover、active、disabled、loading）
- 统一的阴影和透明度规范

**后续维护**：
- 新增按钮类型应遵循轮廓式设计原则
- 保持透明度和阴影规范的一致性
- 确保在所有主题模式下的兼容性

### 2024年 - 确认弹窗按钮统一化设计
**更新时间**：2024年

**核心变更**：将确认弹窗（MessageBox）中的按钮与全局轮廓式按钮规范保持完全一致

**影响范围**：
- ✅ confirm 确认弹窗按钮
- ✅ alert 提示弹窗按钮
- ✅ prompt 输入弹窗按钮
- ✅ 所有 MessageBox 类型的弹窗按钮

**设计理念**：
- **全局统一**：所有按钮都使用轮廓式设计，确保系统的视觉一致性
- **现代化体验**：通过统一的轮廓式设计提供现代化、轻量化的用户体验
- **交互一致性**：所有按钮的悬浮、点击效果保持完全一致
- **维护简便**：统一的设计规范降低维护成本

**技术特点**：
- 确认按钮：轮廓式主色设计 + 主色文字
- 其他类型按钮：对应色彩的轮廓式设计
- 取消按钮：保持轻量化的默认样式
- 最高优先级：使用 `!important` 确保样式覆盖

**实施位置**：
- 样式文件：`src/assets/styles/art-element-ui.scss`
- 选择器：`.el-message-box .el-message-box__btns .el-button`

### 2024年 - MessageBox 按钮位置优化
**更新时间**：2024年

**核心变更**：调整确认弹窗（MessageBox）中的按钮顺序，确定按钮在左侧，取消按钮在右侧，符合国内用户操作习惯

**影响范围**：
- ✅ confirm 确认弹窗的按钮布局
- ✅ alert 提示弹窗的按钮布局
- ✅ prompt 输入弹窗的按钮布局
- ✅ 所有自定义 MessageBox 弹窗的按钮布局

**设计理念**：
- **用户习惯优先**：遵循国内用户的操作习惯，主要操作（确定）在左侧
- **视觉引导优化**：确定按钮的主色调设计在左侧能够更好地引导用户操作
- **降低误操作**：确定按钮的突出位置减少用户误点取消的情况
- **一致性保证**：整个系统的确认弹窗按钮顺序保持完全一致

**技术实现**：
- 使用 CSS Flexbox 的 `flex-direction: row-reverse` 调整按钮顺序
- 通过 `order` 属性精确控制按钮位置
- 使用 `gap` 属性确保按钮间距的一致性
- 保持与轮廓式按钮样式的完美兼容

**用户体验提升**：
- 符合从左到右的阅读和操作习惯
- 减少用户在确认操作时的认知负担
- 提升整体操作的直观性和效率

**实施位置**：
- 文件：`src/assets/styles/art-element-ui.scss`
- 选择器：`.el-message-box .el-message-box__btns`
- 配合：`src/plugins/modal.ts` 中的按钮类名配置

## 16. 项目架构规范

### 目录结构标准
```
src/
├── api/                    # API接口定义
│   ├── [module]/          # 模块化API
│   │   ├── index.ts       # API方法定义
│   │   └── types.ts       # 类型定义
│   ├── types.ts           # 通用类型
│   └── login.ts           # 登录相关API
├── assets/                # 静态资源
│   ├── styles/           # 样式文件
│   │   ├── art-variables.scss    # 设计变量
│   │   ├── art-element-ui.scss   # 组件样式覆盖
│   │   ├── art-dark.scss         # 暗色主题
│   │   └── index.scss            # 样式入口
│   └── images/           # 图片资源
├── components/            # 通用组件
│   └── [ComponentName]/  # 组件目录（PascalCase）
│       ├── index.vue     # 组件主文件
│       └── types.ts      # 组件类型定义（可选）
├── views/                # 页面视图
│   └── [module]/         # 模块化页面
│       └── [feature]/    # 功能页面
│           ├── index.vue # 主页面文件
│           └── components/ # 页面专用组件（可选）
├── layout/               # 布局组件
├── router/               # 路由配置
├── store/                # 状态管理
├── utils/                # 工具函数
├── plugins/              # 插件配置
├── types/                # 全局类型定义
└── main.ts               # 应用入口
```

### 文件命名规范
- **文件夹**：使用 kebab-case（小写+连字符）
- **Vue组件文件**：使用 PascalCase 或 kebab-case
- **TypeScript文件**：使用 camelCase
- **样式文件**：使用 kebab-case
- **常量文件**：使用 UPPER_SNAKE_CASE

### 模块组织原则
1. **按功能模块划分**：每个业务模块独立组织
2. **API与页面对应**：api目录结构与views保持一致
3. **类型定义集中**：每个模块都有对应的types.ts
4. **组件复用优先**：通用组件放在components目录

## 17. Vue组件开发规范

### 组件结构标准
```vue
<template>
  <!-- 使用语义化的HTML结构 -->
  <div class="component-container">
    <!-- 组件内容 -->
  </div>
</template>

<script setup lang="ts" name="ComponentName">
// 1. 引入依赖
import { ref, reactive, computed, onMounted } from 'vue';
import type { ComponentProps, ComponentEmits } from './types';

// 2. 定义Props和Emits
const props = defineProps<ComponentProps>();
const emits = defineEmits<ComponentEmits>();

// 3. 响应式数据
const loading = ref(false);
const formData = reactive({});

// 4. 计算属性
const computedValue = computed(() => {
  return /* 计算逻辑 */;
});

// 5. 方法定义
const handleClick = () => {
  // 方法实现
};

// 6. 生命周期
onMounted(() => {
  // 组件挂载后的逻辑
});
</script>

<style lang="scss" scoped>
.component-container {
  // 样式实现
}
</style>
```

### TypeScript类型定义规范
```typescript
// types.ts
export interface ComponentProps {
  title: string;
  visible: boolean;
  data?: any[];
}

export interface ComponentEmits {
  (e: 'update:visible', value: boolean): void;
  (e: 'confirm', data: any): void;
}

// 响应式数据类型
export interface ComponentState {
  loading: boolean;
  formData: FormData;
}
```

### 组件通信规范
1. **Props向下传递**：父组件向子组件传递数据
2. **Emits向上传递**：子组件向父组件传递事件
3. **v-model双向绑定**：表单组件使用v-model
4. **Provide/Inject**：跨级组件通信
5. **Pinia状态管理**：全局状态共享

## 18. 页面开发规范

### 列表页面标准模板
```vue
<template>
  <div class="p-2 page-container">
    <!-- 搜索区域 -->
    <transition :enter-active-class="proxy?.animate.searchAnimate.enter"
                :leave-active-class="proxy?.animate.searchAnimate.leave">
      <div v-show="showSearch" class="mb-[10px]">
        <el-card shadow="hover">
          <el-form ref="queryFormRef" :model="queryParams" :inline="true" label-width="100px">
            <!-- 搜索表单项 -->
            <el-form-item>
              <el-button type="primary" icon="Search" @click="handleQuery">搜索</el-button>
              <el-button icon="Refresh" @click="resetQuery">重置</el-button>
            </el-form-item>
          </el-form>
        </el-card>
      </div>
    </transition>

    <!-- 表格区域 -->
    <el-card shadow="never" class="button-card table-card">
      <template #header>
        <el-row :gutter="10" class="mb8">
          <!-- 操作按钮 -->
          <el-col :span="1.5">
            <el-button type="primary" plain icon="Plus" @click="handleAdd">新增</el-button>
          </el-col>
          <right-toolbar v-model:showSearch="showSearch" @queryTable="getList"></right-toolbar>
        </el-row>
      </template>

      <!-- 数据表格 -->
      <el-table v-loading="loading" border :data="dataList" :height="tableHeight">
        <el-table-column type="selection" width="55" align="center" />
        <!-- 数据列 -->
        <el-table-column label="操作" align="center" width="160">
          <template #default="scope">
            <!-- 操作按钮 -->
          </template>
        </el-table-column>
      </el-table>

      <!-- 分页组件 -->
      <pagination v-show="total > 0" :total="total"
                  v-model:page="queryParams.pageNum"
                  v-model:limit="queryParams.pageSize"
                  @pagination="getList" />
    </el-card>

    <!-- 弹窗组件 -->
    <el-dialog :title="dialog.title" v-model="dialog.visible" width="800px" append-to-body>
      <!-- 弹窗内容 -->
      <template #footer>
        <div class="dialog-footer">
          <el-button :loading="buttonLoading" type="primary" @click="submitForm">确 定</el-button>
          <el-button @click="cancel">取 消</el-button>
        </div>
      </template>
    </el-dialog>
  </div>
</template>
```

### 页面样式规范
```scss
.page-container {
  height: calc(100vh - 85px);
  display: flex;
  flex-direction: column;
  overflow: hidden;
  box-sizing: border-box;
  padding: 8px 8px 0 8px !important;
}

.table-card {
  flex: 1;
  display: flex;
  flex-direction: column;
  overflow: hidden;
}

.table-card :deep(.el-card__body) {
  flex: 1;
  display: flex;
  flex-direction: column;
  padding: 20px 20px 0 20px;
}
```

### 数据处理规范
```typescript
// 页面数据结构
const data = reactive<PageData<FormType, QueryType>>({
  form: { ...initFormData },
  queryParams: {
    pageNum: 1,
    pageSize: 10,
    // 查询参数
  },
  rules: {
    // 验证规则
  }
});

// 表格高度计算
const tableHeight = computed(() => {
  const searchHeight = showSearch.value ? 120 : 0;
  const toolbarHeight = 50;
  const paginationHeight = 60;
  const otherHeight = 90;
  return windowHeight.value - searchHeight - toolbarHeight - paginationHeight - otherHeight;
});
```

## 19. API开发规范

### API接口定义标准
```typescript
// api/[module]/index.ts
import request from '@/utils/request';
import type { AxiosPromise } from 'axios';
import type { DataVO, DataForm, DataQuery } from './types';

/**
 * 查询数据列表
 * @param query 查询参数
 */
export const listData = (query?: DataQuery): AxiosPromise<DataVO[]> => {
  return request({
    url: '/api/data/list',
    method: 'get',
    params: query
  });
};

/**
 * 查询数据详细信息
 * @param id 数据ID
 */
export const getData = (id: string | number): AxiosPromise<DataVO> => {
  return request({
    url: `/api/data/${id}`,
    method: 'get'
  });
};

/**
 * 新增数据
 * @param data 数据信息
 */
export const addData = (data: DataForm) => {
  return request({
    url: '/api/data',
    method: 'post',
    data: data
  });
};

/**
 * 修改数据
 * @param data 数据信息
 */
export const updateData = (data: DataForm) => {
  return request({
    url: '/api/data',
    method: 'put',
    data: data
  });
};

/**
 * 删除数据
 * @param id 数据ID或ID数组
 */
export const delData = (id: string | number | Array<string | number>) => {
  return request({
    url: `/api/data/${id}`,
    method: 'delete'
  });
};
```

### API类型定义规范
```typescript
// api/[module]/types.ts
export interface DataVO {
  /** 主键ID */
  id: string | number;
  /** 数据名称 */
  name: string;
  /** 数据状态 */
  status: string;
  /** 创建时间 */
  createTime?: string;
  /** 更新时间 */
  updateTime?: string;
}

export interface DataForm extends BaseEntity {
  /** 主键ID */
  id?: string | number;
  /** 数据名称 */
  name?: string;
  /** 数据状态 */
  status?: string;
}

export interface DataQuery extends PageQuery {
  /** 数据名称 */
  name?: string;
  /** 数据状态 */
  status?: string;
  /** 日期范围参数 */
  params?: any;
}
```

### 错误处理规范
```typescript
// 统一错误处理已在request.ts中实现
// 业务层只需要使用try-catch处理特殊情况

const handleSubmit = async () => {
  try {
    await addData(formData);
    proxy?.$modal.msgSuccess('操作成功');
    getList();
  } catch (error) {
    // 特殊错误处理（可选）
    console.error('操作失败:', error);
  }
};
```

## 20. 工具组件使用规范

### RightToolbar 工具栏
```vue
<!-- 标准用法 -->
<right-toolbar
  v-model:showSearch="showSearch"
  :columns="columns"
  @queryTable="getList">
</right-toolbar>

<!-- 列显隐控制 -->
<script setup>
const columns = ref([
  { key: 'name', label: '名称', visible: true },
  { key: 'status', label: '状态', visible: true },
  { key: 'createTime', label: '创建时间', visible: false }
]);
</script>
```

### Pagination 分页组件
```vue
<pagination
  v-show="total > 0"
  :total="total"
  v-model:page="queryParams.pageNum"
  v-model:limit="queryParams.pageSize"
  @pagination="getList" />
```

### DictTag 字典标签
```vue
<dict-tag
  :options="dict_status"
  :value="row.status" />

<script setup>
const { dict_status } = toRefs<any>(proxy?.useDict('dict_status'));
</script>
```

### ImageUpload 图片上传
```vue
<image-upload v-model="form.image" />

<!-- 图片预览 -->
<image-preview
  :src="row.image"
  :width="50"
  :height="50" />
```

## 21. 样式开发规范

### SCSS变量使用
```scss
// 使用设计变量
.component {
  background-color: var(--art-main-bg-color);
  border: 1px solid var(--art-border-color);
  border-radius: var(--border-radius-md);
  padding: var(--space-lg);
  color: var(--art-text-gray-700);
}

// 响应式设计
@media screen and (max-width: $device-phone) {
  .component {
    padding: var(--space-sm);
  }
}
```

### 暗色主题适配
```scss
// 组件支持暗色主题
.component {
  background-color: var(--art-main-bg-color);

  // 暗色主题下自动适配
  html.dark & {
    border-color: var(--art-border-color);
    color: var(--art-text-gray-700);
  }
}
```

### CSS类命名规范
- **组件容器**：`.component-name-container`
- **元素**：`.component-name__element`
- **修饰符**：`.component-name--modifier`
- **状态**：`.is-active`, `.is-disabled`, `.is-loading`
- **工具类**：`.text-center`, `.mb-4`, `.p-2`

## 22. 权限控制规范

### 页面权限
```vue
<template>
  <!-- 按钮权限控制 -->
  <el-button
    type="primary"
    @click="handleAdd"
    v-hasPermi="['system:user:add']">
    新增
  </el-button>

  <!-- 路由权限在router中配置 -->
</template>
```

### 路由权限配置
```typescript
{
  path: '/user',
  component: Layout,
  meta: {
    title: '用户管理',
    icon: 'user',
    roles: ['admin', 'user'], // 角色权限
    permissions: ['system:user:view'] // 功能权限
  }
}
```

## 23. 性能优化规范

### 组件懒加载
```typescript
// 路由懒加载
const UserManagement = () => import('@/views/system/user/index.vue');

// 组件异步加载
const LazyComponent = defineAsyncComponent(() => import('./LazyComponent.vue'));
```

### 列表优化
```vue
<!-- 虚拟滚动（大数据量） -->
<el-table-v2
  :columns="columns"
  :data="data"
  :width="800"
  :height="600"
  fixed />

<!-- 分页加载 -->
<pagination
  :total="total"
  v-model:page="queryParams.pageNum"
  v-model:limit="queryParams.pageSize" />
```

### 图片优化
```vue
<!-- 图片懒加载 -->
<el-image
  :src="imageUrl"
  lazy
  loading="lazy"
  :preview-src-list="[imageUrl]" />

<!-- 占位图 -->
<el-image
  :src="imageUrl"
  fit="cover"
  loading="lazy">
  <template #placeholder>
    <div class="image-slot">加载中...</div>
  </template>
  <template #error>
    <div class="image-slot">加载失败</div>
  </template>
</el-image>
```

## 24. 国际化规范

### 多语言配置
```typescript
// lang/zh_CN.ts
export default {
  common: {
    add: '新增',
    edit: '修改',
    delete: '删除',
    search: '搜索',
    reset: '重置'
  },
  user: {
    username: '用户名',
    email: '邮箱',
    status: '状态'
  }
};
```

### 使用方式
```vue
<template>
  <el-button>{{ $t('common.add') }}</el-button>
  <el-form-item :label="$t('user.username')">
    <el-input v-model="form.username" />
  </el-form-item>
</template>

<script setup>
const { t } = useI18n();
const buttonText = computed(() => t('common.add'));
</script>
```

## 25. 测试规范

### 单元测试
```typescript
// 组件测试
import { mount } from '@vue/test-utils';
import UserForm from '@/components/UserForm/index.vue';

describe('UserForm', () => {
  test('should render correctly', () => {
    const wrapper = mount(UserForm, {
      props: {
        visible: true,
        data: {}
      }
    });
    expect(wrapper.find('.user-form').exists()).toBe(true);
  });
});
```

### E2E测试
```typescript
// 页面流程测试
describe('User Management', () => {
  test('should add user successfully', async () => {
    await page.goto('/user');
    await page.click('[data-test="add-button"]');
    await page.fill('[data-test="username"]', 'testuser');
    await page.click('[data-test="submit-button"]');
    await expect(page.locator('.el-message')).toContainText('操作成功');
  });
});
```

## 26. 构建和部署规范

### 环境配置
```typescript
// .env.development
VITE_APP_ENV = 'development'
VITE_APP_BASE_API = '/dev-api'
VITE_APP_CLIENT_ID = 'e5cd7e4891bf95d1d19206ce24a7b32e'

// .env.production
VITE_APP_ENV = 'production'
VITE_APP_BASE_API = '/prod-api'
VITE_APP_CLIENT_ID = 'e5cd7e4891bf95d1d19206ce24a7b32e'
```

### 构建优化
```typescript
// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        chunkFileNames: 'js/[name]-[hash].js',
        entryFileNames: 'js/[name]-[hash].js',
        assetFileNames: 'assets/[name]-[hash].[ext]',
        manualChunks: {
          'element-plus': ['element-plus'],
          'vue-vendor': ['vue', 'vue-router', 'pinia']
        }
      }
    }
  }
});
```

## 27. 代码质量保证

### ESLint配置规范
```typescript
// eslint.config.ts
export default [
  {
    rules: {
      // Vue相关规则
      'vue/no-unused-vars': 'error',
      'vue/require-default-prop': 'off',
      'vue/multi-word-component-names': 'off',

      // TypeScript相关规则
      '@typescript-eslint/no-explicit-any': 'warn',
      '@typescript-eslint/no-unused-vars': 'error',

      // 通用规则
      'no-console': 'warn',
      'no-debugger': 'error'
    }
  }
];
```

### 代码提交规范
```bash
# 提交信息格式
git commit -m "feat(user): 新增用户管理功能"

# 提交类型
feat: 新功能
fix: 修复bug
docs: 文档更新
style: 代码格式调整
refactor: 重构代码
test: 测试相关
chore: 构建工具或辅助工具的变动
```

### 代码审查清单
- [ ] 代码符合项目规范
- [ ] 类型定义完整
- [ ] 组件可复用性良好
- [ ] 性能优化到位
- [ ] 无安全隐患
- [ ] 测试覆盖充分
- [ ] 文档更新及时

---

此规范基于 Art Design Pro 的优秀设计理念，结合现代 Web 设计趋势和 plus-ui 项目的实际实现，为 Plus UI 提供统一的设计语言和完整的开发标准。通过严格遵循此规范，可以确保项目的高质量、可维护性和团队协作效率。


## 26. 代码调整记录规范

### 📝 重要提醒：代码调整记录要求

**每次使用Cursor修改前端代码时，都必须在项目根目录的【代码调整记录.md】文件中记录调整信息。**

### 记录格式标准


### 记录要求
1. **及时性**: 每次代码调整完成后立即记录
2. **完整性**: 包含所有必要信息字段
3. **准确性**: 详细描述实际的调整内容
4. **可追溯性**: 便于后续查看和维护

### Cursor AI使用提醒
当您要求Cursor AI进行代码调整时，请提醒AI：
```
请在完成代码调整后，帮我在【代码调整记录.md】文件中记录本次调整的相关信息，
包括调整时间、目的、涉及文件、具体内容等。
```

### 文件管理
- 记录文件位置: 项目根目录 `代码调整记录.md`
- 记录保留期: 建议保留至少6个月的调整记录
- 定期整理: 每月可将过期记录归档到 `docs/change-logs/` 目录

这个记录制度有助于：
✅ 追踪代码变更历史
✅ 团队协作信息共享
✅ 问题排查和回溯
✅ 知识积累和经验总结
✅ 项目维护和交接

## 26. 代码调整记录规范

### 📝 重要提醒：代码调整记录要求

**每次使用Cursor修改前端代码时，都必须在项目根目录的【代码调整记录.md】文件中记录调整信息。**

### 记录格式标准
每次调整后请按以下格式记录：

```
## 调整记录 - YYYY-MM-DD HH:mm:ss

**调整时间**: YYYY-MM-DD HH:mm:ss
**调整人**: [开发者姓名/Cursor AI辅助]
**调整目的**: [简述调整原因和目标]
**涉及文件**: 
- src/views/module/file.vue
- src/api/module/file.ts
- src/components/ComponentName/index.vue

**调整内容详述**:
1. 具体调整了哪些代码
2. 修改了哪些功能
3. 优化了哪些性能
4. 修复了哪些问题

**技术细节**:
- 使用的技术栈: Vue 3.5.13 + TypeScript 5.8.3 + Element Plus 2.9.8
- 遵循的设计规范: Art Design Pro轮廓式按钮系统
- CSS变量使用: --art-*变量系统
- 其他重要技术决策

**测试验证**:
- [ ] 功能测试通过
- [ ] 样式规范检查通过
- [ ] TypeScript类型检查通过
- [ ] 响应式布局测试通过
- [ ] 暗色主题兼容性测试通过

**备注**: 其他需要说明的内容

---
```

### 记录要求
1. **及时性**: 每次代码调整完成后立即记录
2. **完整性**: 包含所有必要信息字段
3. **准确性**: 详细描述实际的调整内容
4. **可追溯性**: 便于后续查看和维护

### Cursor AI使用提醒
当您要求Cursor AI进行代码调整时，请提醒AI：
"请在完成代码调整后，帮我在【代码调整记录.md】文件中记录本次调整的相关信息，包括调整时间、目的、涉及文件、具体内容等。"

### 文件管理
- 记录文件位置: 项目根目录 `代码调整记录.md`
- 记录保留期: 建议保留至少6个月的调整记录
- 定期整理: 每月可将过期记录归档到 `docs/change-logs/` 目录

这个记录制度有助于：
✅ 追踪代码变更历史
✅ 团队协作信息共享  
✅ 问题排查和回溯
✅ 知识积累和经验总结
✅ 项目维护和交接

### ⚠️ 强制要求
**所有通过Cursor AI进行的代码调整都必须在【代码调整记录.md】中留下记录，这是项目管理的强制性要求。**