# 🖥️ UI 规范 — 管理端（Case-Database-Frontend-admin）

> 管理端设计规范。AI 在 `Case-Database-Frontend-admin/` 中新建页面或组件时参考本文档。
> 核心原则：**桌面优先、功能完整、Element Plus 标准优先**

---

## 1. 设计系统

| 项目 | 选型 |
|---|---|
| UI 组件库 | Element Plus（优先使用标准组件，不自定义重复造轮子） |
| CSS 方案 | Tailwind CSS（辅助布局，不覆盖 Element Plus 样式） |
| 图标 | Element Plus Icons（`@element-plus/icons-vue`） |
| 字体 | 系统字体栈 |
| 布局框架 | 侧边导航 + 顶部栏 + 内容区（标准后台布局） |

---

## 2. 色彩系统

```css
:root {
  /* 主色（Element Plus 默认蓝） */
  --el-color-primary: #409EFF;

  /* 管理端背景层级 */
  --admin-bg-sidebar:  #001529;   /* 深色侧边栏 */
  --admin-bg-header:   #FFFFFF;   /* 白色顶栏 */
  --admin-bg-content:  #F0F2F5;   /* 内容区浅灰 */
  --admin-bg-card:     #FFFFFF;   /* 卡片/表格白 */

  /* 状态色 */
  --status-active:   #52C41A;  /* 启用/正常 */
  --status-inactive: #D9D9D9;  /* 停用/禁用 */
  --status-pending:  #FAAD14;  /* 待处理 */
  --status-danger:   #FF4D4F;  /* 危险/错误 */
}
```

Element Plus 主题色配置（`src/styles/element-vars.scss`）：
```scss
@forward 'element-plus/theme-chalk/src/common/var.scss' with (
  $colors: (
    'primary': ('base': #409EFF),
  )
);
```

---

## 3. 布局规范

### 整体框架

```
┌─────────────────────────────────────────────────────────┐
│  顶栏（60px 固定）：Logo + 面包屑 + 用户信息 + 通知     │
├──────────────┬──────────────────────────────────────────┤
│              │  内容区（padding: 16px）                  │
│  侧边栏      │  ┌──────────────────────────────────────┐ │
│  （220px）   │  │  页面标题 + 操作按钮（顶部工具栏）    │ │
│              │  ├──────────────────────────────────────┤ │
│  折叠后      │  │  主内容（表格/表单/卡片）             │ │
│  → 64px     │  │                                      │ │
│              │  └──────────────────────────────────────┘ │
└──────────────┴──────────────────────────────────────────┘
```

### 响应式

管理端以桌面端为主，但需支持：
- `≥ 1280px`：完整布局（侧边栏展开）
- `1024px ~ 1279px`：侧边栏折叠（64px 图标模式）
- `< 1024px`：侧边栏收起为抽屉（移动端兜底）

---

## 4. Element Plus 组件使用规范

### 数据表格（el-table）

```vue
<el-table
  v-loading="loading"
  :data="tableData"
  stripe
  border
  highlight-current-row
  style="width: 100%"
>
  <!-- 数据列 -->
  <el-table-column prop="id" label="ID" width="80" sortable />
  <el-table-column prop="name" label="名称" min-width="180" show-overflow-tooltip />
  
  <!-- 状态列（Tag） -->
  <el-table-column label="状态" width="100">
    <template #default="{ row }">
      <el-tag :type="row.status === 1 ? 'success' : 'danger'">
        {{ row.status === 1 ? '启用' : '停用' }}
      </el-tag>
    </template>
  </el-table-column>

  <!-- 操作列（固定右侧） -->
  <el-table-column label="操作" fixed="right" width="160">
    <template #default="{ row }">
      <el-button v-permission="'module:edit'" link type="primary" @click="handleEdit(row)">编辑</el-button>
      <el-popconfirm title="确定删除？" @confirm="handleDelete(row.id)">
        <template #reference>
          <el-button v-permission="'module:delete'" link type="danger">删除</el-button>
        </template>
      </el-popconfirm>
    </template>
  </el-table-column>
</el-table>

<!-- 分页（固定格式） -->
<el-pagination
  v-model:current-page="query.page"
  v-model:page-size="query.page_size"
  :page-sizes="[10, 20, 50, 100]"
  :total="total"
  layout="total, sizes, prev, pager, next, jumper"
  class="mt-4 justify-end"
  @change="fetchData"
/>
```

### 搜索表单

```vue
<!-- 搜索栏（折叠设计，超过 3 个条件可折叠） -->
<el-card class="mb-4" shadow="never">
  <el-form :model="query" inline @keyup.enter="handleSearch">
    <el-form-item label="关键词">
      <el-input v-model="query.keyword" placeholder="请输入" clearable style="width: 200px" />
    </el-form-item>
    <el-form-item>
      <el-button type="primary" @click="handleSearch">搜索</el-button>
      <el-button @click="handleReset">重置</el-button>
    </el-form-item>
  </el-form>
</el-card>
```

### 弹窗表单

```vue
<el-dialog v-model="dialogVisible" :title="isEdit ? '编辑' : '新建'" width="600px" @close="handleDialogClose">
  <el-form ref="formRef" :model="form" :rules="rules" label-width="80px">
    <el-form-item label="名称" prop="name">
      <el-input v-model="form.name" />
    </el-form-item>
  </el-form>
  <template #footer>
    <el-button @click="dialogVisible = false">取消</el-button>
    <el-button type="primary" :loading="submitting" @click="handleSubmit">确定</el-button>
  </template>
</el-dialog>
```

规则：
- 弹窗宽度：简单表单 500px，复杂表单 700-900px
- 弹窗关闭时必须调用 `formRef.value?.resetFields()`
- 提交按钮加 `:loading` 防重复提交

---

## 5. 页面标准结构

每个管理端页面遵循以下结构：

```vue
<template>
  <div class="admin-page">
    <!-- 页面头部：标题 + 主要操作按钮 -->
    <div class="mb-4 flex items-center justify-between">
      <h2 class="text-lg font-semibold text-gray-800">页面标题</h2>
      <el-button v-permission="'module:create'" type="primary" @click="handleCreate">
        <el-icon><Plus /></el-icon> 新建
      </el-button>
    </div>

    <!-- 搜索区 -->
    <!-- 表格区 -->
    <!-- 分页区 -->
    <!-- 弹窗区 -->
  </div>
</template>

<script setup>
// 1. 导入
// 2. 响应式状态
// 3. 表单/验证规则
// 4. 数据获取
// 5. 事件处理（CRUD）
// 6. 生命周期
</script>
```

---

## 6. 间距规范

| 场景 | 间距 |
|---|---|
| 内容区内边距 | `p-4`（16px） |
| 卡片间距 | `mb-4`（16px） |
| 表单项间距 | Element Plus 默认（`el-form` 管理） |
| 操作按钮间距 | `ml-2`（8px，同行按钮） |

---

## 7. 状态规范

| 状态 | 实现方式 |
|---|---|
| 加载中 | `v-loading="loading"`（`el-table`、`el-card`） |
| 空状态 | `el-empty`（有描述、有图） |
| 错误状态 | `el-result` type="error"（提供重试按钮） |
| 操作成功 | `ElMessage.success('操作成功')` |
| 操作失败 | `ElMessage.error(error.message)` |
| 危险操作确认 | `el-popconfirm`（行内）/ `ElMessageBox.confirm`（批量） |

---

*最后更新: 2026-02-26*