# 盘古用户平台 - 前端UI规范文档 v1.0

> 适用于本项目所有前端页面开发
> 作者：pangu
> 创建时间：2026-01-31

---

## 一、设计原则

### 1.1 统一性原则
- 保持全系统视觉风格一致
- 相同功能使用相同交互模式
- 统一的间距、颜色、字体规范

### 1.2 简洁性原则
- 页面布局清晰，信息层次分明
- 避免过度设计，突出核心功能
- 表格列宽合理，无大面积空白

### 1.3 易用性原则
- 操作直观，减少用户学习成本
- 反馈及时，状态清晰可见
- 错误提示友好，引导用户纠正

---

## 二、色彩规范

### 2.1 主题色

| 类型 | 色值 | 用途 |
|------|------|------|
| 主色 | `#409EFF` | 按钮、链接、选中态 |
| 成功色 | `#67C23A` | 正常状态、成功提示 |
| 警告色 | `#E6A23C` | 警告提示 |
| 危险色 | `#F56C6C` | 停用状态、删除操作、错误提示 |
| 信息色 | `#909399` | 辅助信息 |

### 2.2 中性色

| 类型 | 色值 | 用途 |
|------|------|------|
| 主文本 | `#303133` | 标题、正文 |
| 常规文本 | `#606266` | 表格、描述 |
| 次要文本 | `#909399` | 提示、禁用态 |
| 占位文本 | `#C0C4CC` | placeholder |
| 边框色 | `#DCDFE6` | 边框、分割线 |
| 背景色 | `#F5F7FA` | 表头、背景 |

### 2.3 侧边栏配色

| 类型 | 色值 |
|------|------|
| 背景色 | `#304156` |
| 选中背景 | `#409EFF` |
| 文字颜色 | `#FFFFFF` |

---

## 三、布局规范

### 3.1 页面结构

```vue
<template>
  <div class="app-container">
    <!-- 搜索区域 -->
    <el-card shadow="never" class="search-wrapper">
      <el-form>...</el-form>
    </el-card>
    
    <!-- 表格区域 -->
    <el-card shadow="never" style="margin-top: 12px;">
      <!-- 操作按钮 -->
      <el-row :gutter="10" style="margin-bottom: 12px;">
        <el-col :span="1.5">
          <el-button type="primary" :icon="Plus">新增</el-button>
        </el-col>
      </el-row>
      
      <!-- 表格 -->
      <el-table>...</el-table>
      
      <!-- 分页 -->
      <el-pagination />
    </el-card>
    
    <!-- 弹窗 -->
    <el-dialog>...</el-dialog>
  </div>
</template>

<style scoped>
.app-container {
  padding: 16px;
}
.search-wrapper {
  margin-bottom: 0;
}
</style>
```

### 3.2 左右分栏布局

适用于：学校管理、学生管理等需要左侧树形筛选的页面

```vue
<el-row :gutter="16">
  <!-- 左侧树形区域 -->
  <el-col :span="6">
    <el-card shadow="never">
      <template #header>区域筛选</template>
      <el-input v-model="filterText" placeholder="输入关键字过滤" />
      <el-tree :data="treeData" :filter-node-method="filterNode" />
    </el-card>
  </el-col>
  
  <!-- 右侧列表区域 -->
  <el-col :span="18">
    <!-- 搜索表单 + 表格 -->
  </el-col>
</el-row>
```

### 3.3 间距规范

| 场景 | 间距值 |
|------|--------|
| 页面内边距 | 16px |
| 卡片间距 | 12px |
| 表单项间距 | 默认（16px） |
| 按钮组间距 | 10px |
| 表格与分页间距 | 16px |

---

## 四、表格规范

### 4.1 基础表格属性

```vue
<el-table 
  :data="tableData" 
  border 
  stripe
  v-loading="loading"
  :header-cell-style="{ background: '#f5f7fa', color: '#606266' }"
  style="width: 100%"
>
```

**必须设置的属性：**
- `border`：显示边框
- `stripe`：斑马纹
- `v-loading`：加载状态
- `header-cell-style`：表头样式
- `style="width: 100%"`：全宽显示

### 4.2 列宽规范

| 字段类型 | 推荐宽度 | 说明 |
|---------|---------|------|
| ID/编号 | `width="80-140"` | 固定宽度 |
| 名称/标题 | `min-width="120-200"` | 弹性宽度，使用min-width |
| 编码 | `width="100-120"` | 固定宽度 |
| 状态/类型 | `width="80-100"` | 固定宽度，居中 |
| 日期时间 | `width="160"` | 固定宽度 |
| 手机号 | `width="120"` | 固定宽度 |
| 操作列 | `width="120-200"` | 根据按钮数量，固定右侧 |

### 4.3 列定义示例

```vue
<!-- 名称列：弹性宽度 + 溢出提示 -->
<el-table-column prop="name" label="名称" min-width="150" show-overflow-tooltip />

<!-- 状态列：固定宽度 + 居中 + Tag -->
<el-table-column prop="status" label="状态" width="80" align="center">
  <template #default="{ row }">
    <el-tag :type="row.status === '0' ? 'success' : 'danger'">
      {{ row.status === '0' ? '正常' : '停用' }}
    </el-tag>
  </template>
</el-table-column>

<!-- 操作列：固定右侧 -->
<el-table-column label="操作" width="180" fixed="right" align="center">
  <template #default="{ row }">
    <el-button link type="primary" :icon="Edit" @click="handleEdit(row)">编辑</el-button>
    <el-button link type="danger" :icon="Delete" @click="handleDelete(row)">删除</el-button>
  </template>
</el-table-column>
```

### 4.4 空数据处理

```vue
<el-table :data="tableData">
  <template #empty>
    <el-empty description="暂无数据" />
  </template>
</el-table>
```

### 4.5 树形表格

```vue
<el-table
  :data="tableData"
  row-key="id"
  border
  :default-expand-all="isExpand"
  :tree-props="{ children: 'children', hasChildren: 'hasChildren' }"
>
```

**注意事项：**
- `row-key` 必须指定为唯一标识字段
- 确保数据结构中的字段名与 `prop` 一致

---

## 五、表单规范

### 5.1 搜索表单

```vue
<el-form :model="queryParams" :inline="true" class="search-form">
  <el-form-item label="名称" prop="name">
    <el-input 
      v-model="queryParams.name" 
      placeholder="请输入名称" 
      clearable 
      style="width: 200px" 
      @keyup.enter="handleQuery"
    />
  </el-form-item>
  <el-form-item label="状态" prop="status">
    <el-select v-model="queryParams.status" placeholder="全部" clearable style="width: 100px">
      <el-option label="正常" value="0" />
      <el-option label="停用" value="1" />
    </el-select>
  </el-form-item>
  <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>
```

### 5.2 弹窗表单

```vue
<el-dialog 
  v-model="dialogVisible" 
  :title="dialogTitle" 
  width="600px"
  :close-on-click-modal="false"
  destroy-on-close
>
  <el-form 
    ref="formRef" 
    :model="form" 
    :rules="rules" 
    label-width="100px"
  >
    <el-form-item label="名称" prop="name">
      <el-input v-model="form.name" placeholder="请输入名称" />
    </el-form-item>
    <el-form-item label="状态" prop="status">
      <el-switch v-model="form.status" active-value="0" inactive-value="1" />
    </el-form-item>
  </el-form>
  <template #footer>
    <el-button @click="dialogVisible = false">取消</el-button>
    <el-button type="primary" @click="handleSubmit" :loading="submitLoading">确定</el-button>
  </template>
</el-dialog>
```

### 5.3 输入框宽度规范

| 场景 | 推荐宽度 |
|------|---------|
| 搜索表单-短输入 | 100-150px |
| 搜索表单-中输入 | 200px |
| 搜索表单-日期范围 | 240px |
| 弹窗表单 | 100%（默认） |

---

## 六、分页规范

```vue
<el-pagination
  v-model:current-page="queryParams.pageNum"
  v-model:page-size="queryParams.pageSize"
  :page-sizes="[10, 20, 50, 100]"
  :total="total"
  layout="total, sizes, prev, pager, next, jumper"
  style="margin-top: 16px; justify-content: flex-end"
  @size-change="handleQuery"
  @current-change="handleQuery"
/>
```

**必须设置：**
- `layout="total, sizes, prev, pager, next, jumper"`：完整布局
- `style="justify-content: flex-end"`：右对齐
- `:page-sizes="[10, 20, 50, 100]"`：页码选项

---

## 七、状态Tag规范

### 7.1 状态类型映射

| 状态 | Tag类型 | 示例 |
|------|---------|------|
| 正常/启用 | `success` | 正常 |
| 停用/禁用 | `danger` | 停用 |
| 家长 | `primary`（默认） | 家长 |
| 教师 | `success` | 教师 |
| 男 | `primary`（默认） | 男 |
| 女 | `danger` | 女 |
| 未知 | `info` | 未知 |

### 7.2 代码示例

```vue
<!-- 状态Tag -->
<el-tag :type="row.status === '0' ? 'success' : 'danger'">
  {{ row.status === '0' ? '正常' : '停用' }}
</el-tag>

<!-- 身份类型Tag -->
<el-tag :type="row.identityType === '1' ? '' : 'success'">
  {{ row.identityType === '1' ? '家长' : '教师' }}
</el-tag>

<!-- 性别Tag -->
<el-tag :type="row.gender === '1' ? '' : row.gender === '2' ? 'danger' : 'info'">
  {{ { '0': '未知', '1': '男', '2': '女' }[row.gender] }}
</el-tag>
```

---

## 八、交互规范

### 8.1 删除确认

```javascript
const handleDelete = (row) => {
  ElMessageBox.confirm(`确定要删除"${row.name}"吗？`, '提示', {
    confirmButtonText: '确定',
    cancelButtonText: '取消',
    type: 'warning'
  }).then(() => {
    deleteApi(row.id).then(() => {
      ElMessage.success('删除成功')
      handleQuery()
    })
  }).catch(() => {})
}
```

### 8.2 消息提示

| 场景 | 类型 | 示例 |
|------|------|------|
| 操作成功 | `success` | 新增成功、修改成功、删除成功 |
| 操作失败 | `error` | 操作失败，请重试 |
| 警告提示 | `warning` | 请先选择数据 |
| 信息提示 | `info` | 已复制到剪贴板 |

```javascript
ElMessage.success('操作成功')
ElMessage.error('操作失败')
ElMessage.warning('请先选择数据')
ElMessage.info('已复制到剪贴板')
```

### 8.3 Loading状态

- 表格加载：使用 `v-loading` 指令
- 按钮提交：使用 `:loading` 属性
- 页面加载：使用全局Loading

---

## 九、Mock数据规范

### 9.1 响应格式

```javascript
// 成功响应
{ code: 200, msg: '操作成功', data: { ... } }

// 分页响应
{ code: 200, msg: '查询成功', total: 100, rows: [ ... ] }

// 错误响应
{ code: 500, msg: '操作失败' }
```

### 9.2 Mock文件规范

```javascript
/**
 * XXX模块Mock数据
 * @author pangu
 */
import Mock from 'mockjs'

// 预置数据定义
const dataList = [...]

// GET请求用RegExp匹配URL（支持query参数）
Mock.mock(/\/api\/xxx\/list/, 'get', (options) => {
  return { code: 200, total: 100, rows: [...] }
})

// POST/PUT/DELETE用字符串或正则匹配
Mock.mock('/api/xxx', 'post', { code: 200, msg: '新增成功' })
```

### 9.3 字段命名规范

**重要：Mock数据中的字段名必须与视图中 `prop` 属性保持一致！**

```javascript
// ✅ 正确：字段名与视图prop一致
{ regionName: '湖北省', regionCode: 'HB' }
// 对应视图：<el-table-column prop="regionName" />

// ❌ 错误：字段名与视图prop不一致
{ name: '湖北省', code: 'HB' }
// 对应视图：<el-table-column prop="regionName" /> -- 会导致数据不显示
```

---

## 十、文件命名规范

### 10.1 视图文件

| 类型 | 位置 | 命名 |
|------|------|------|
| 主页面 | `views/xxx/index.vue` | index.vue |
| 弹窗组件 | `views/xxx/components/XxxDialog.vue` | 大驼峰+Dialog |

### 10.2 API文件

| 位置 | 命名 | 示例 |
|------|------|------|
| `src/api/` | 小驼峰.js | `school.js`, `member.js` |

### 10.3 Mock文件

| 位置 | 命名 | 示例 |
|------|------|------|
| `src/mock/` | 小驼峰.js | `school.js`, `member.js` |
| 入口文件 | `src/mock/index.js` | 汇总所有mock |

---

## 十一、已知问题清单

### 11.1 区域管理页面

**问题类型：** Mock数据字段不匹配  
**严重程度：** 高  
**问题描述：** 区域名称列显示为空  
**原因分析：**
- 视图使用 `prop="regionName"`，但Mock返回 `name`
- 视图使用 `prop="regionCode"`，但Mock返回 `code`

**修复方案：**
```javascript
// 修改 src/mock/region.js，将字段名改为：
{ regionName: '湖北省', regionCode: 'HB', ... }
// 或修改视图 prop 为：
<el-table-column prop="name" label="区域名称" />
```

### 11.2 应用管理页面

**问题类型：** Mock数据字段不匹配  
**严重程度：** 中  
**问题描述：** 授权接口列为空  
**原因分析：**
- 视图使用 `row.apis`，但Mock返回 `row.apiAuth`

**修复方案：**
```javascript
// 修改 src/views/application/index.vue 第38行
// 将 row.apis 改为 row.apiAuth
<el-tag v-for="api in (row.apiAuth || []).slice(0, 3)" ...>
```

### 11.3 年级管理页面

**问题类型：** Mock接口未正确匹配  
**严重程度：** 高  
**问题描述：** 表格显示"No Data"  
**原因分析：** API调用路径与Mock匹配可能有问题

**修复方案：** 检查API调用路径是否与Mock正则匹配

### 11.4 班级管理、学科管理页面

**问题类型：** 同年级管理  
**需确认：** 同样可能存在Mock匹配问题

### 11.5 学校管理页面

**问题类型：** 样式问题  
**严重程度：** 低  
**问题描述：** 
- 操作列按钮显示为多行，较拥挤
- 创建时间列可能被截断

**修复方案：** 
- 增加操作列宽度到 220px 或 240px
- 减少操作按钮文字，如"新增年级"改为"加年级"

### 11.6 Mock数据时间问题

**问题类型：** 数据质量  
**严重程度：** 低  
**问题描述：** 部分Mock生成的时间数据不合理（如1970年、1971年）  
**修复方案：** 限制时间范围为近5年

---

## 十二、修复优先级

| 优先级 | 页面 | 问题 | 影响 |
|--------|------|------|------|
| P0 | 区域管理 | 字段不匹配导致数据不显示 | 页面不可用 |
| P0 | 年级/班级/学科管理 | Mock未返回数据 | 页面不可用 |
| P1 | 应用管理 | 授权接口列为空 | 功能缺失 |
| P2 | 学校管理 | 操作列过窄 | 体验不佳 |
| P3 | 全局 | Mock时间数据不合理 | 影响展示 |

---

*文档版本：v1.0*  
*创建时间：2026-01-31*  
*维护团队：pangu*