diff --git a/docs/05-前端UI规范/前端UI规范文档_v1.0.md b/docs/05-前端UI规范/前端UI规范文档_v1.0.md new file mode 100644 index 0000000..4fa2545 --- /dev/null +++ b/docs/05-前端UI规范/前端UI规范文档_v1.0.md @@ -0,0 +1,552 @@ +# 盘古用户平台 - 前端UI规范文档 v1.0 + +> 适用于本项目所有前端页面开发 +> 作者：湖北新华业务中台研发团队 +> 创建时间：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 + + + +``` + +### 3.2 左右分栏布局 + +适用于：学校管理、学生管理等需要左侧树形筛选的页面 + +```vue + + + + + + + + + + + + + + + +``` + +### 3.3 间距规范 + +| 场景 | 间距值 | +|------|--------| +| 页面内边距 | 16px | +| 卡片间距 | 12px | +| 表单项间距 | 默认（16px） | +| 按钮组间距 | 10px | +| 表格与分页间距 | 16px | + +--- + +## 四、表格规范 + +### 4.1 基础表格属性 + +```vue + +``` + +**必须设置的属性：** +- `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 + + + + + + + + + + + + +``` + +### 4.4 空数据处理 + +```vue + + + +``` + +### 4.5 树形表格 + +```vue + +``` + +**注意事项：** +- `row-key` 必须指定为唯一标识字段 +- 确保数据结构中的字段名与 `prop` 一致 + +--- + +## 五、表单规范 + +### 5.1 搜索表单 + +```vue + + + + + + + + + + + + 搜索 + 重置 + + +``` + +### 5.2 弹窗表单 + +```vue + + + + + + + + + + + +``` + +### 5.3 输入框宽度规范 + +| 场景 | 推荐宽度 | +|------|---------| +| 搜索表单-短输入 | 100-150px | +| 搜索表单-中输入 | 200px | +| 搜索表单-日期范围 | 240px | +| 弹窗表单 | 100%（默认） | + +--- + +## 六、分页规范 + +```vue + +``` + +**必须设置：** +- `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 + + + {{ row.status === '0' ? '正常' : '停用' }} + + + + + {{ row.identityType === '1' ? '家长' : '教师' }} + + + + + {{ { '0': '未知', '1': '男', '2': '女' }[row.gender] }} + +``` + +--- + +## 八、交互规范 + +### 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 湖北新华业务中台研发团队 + */ +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' } +// 对应视图： + +// ❌ 错误：字段名与视图prop不一致 +{ name: '湖北省', code: 'HB' } +// 对应视图： -- 会导致数据不显示 +``` + +--- + +## 十、文件命名规范 + +### 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 为： + +``` + +### 11.2 应用管理页面 + +**问题类型：** Mock数据字段不匹配 +**严重程度：** 中 +**问题描述：** 授权接口列为空 +**原因分析：** +- 视图使用 `row.apis`，但Mock返回 `row.apiAuth` + +**修复方案：** +```javascript +// 修改 src/views/application/index.vue 第38行 +// 将 row.apis 改为 row.apiAuth + +``` + +### 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* +*维护团队：湖北新华业务中台研发团队* diff --git a/docs/05-前端UI规范/页面问题修复清单.md b/docs/05-前端UI规范/页面问题修复清单.md new file mode 100644 index 0000000..e568110 --- /dev/null +++ b/docs/05-前端UI规范/页面问题修复清单.md @@ -0,0 +1,392 @@ +# 盘古用户平台 - 页面问题修复清单 + +> 基于 2026-01-31 浏览器实际检查结果 +> 作者：湖北新华业务中台研发团队 + +--- + +## 概述 + +本文档记录了通过浏览器检查发现的所有页面问题，按模块分类，标注优先级和修复方案。 + +--- + +## 一、登录页面 `/login` + +| 状态 | 问题 | +|:----:|------| +| ✅ | 无明显问题，样式正常 | + +**页面截图确认：** +- 渐变背景色正常 +- 登录卡片居中显示 +- 表单字段完整 +- 验证码正常显示 + +--- + +## 二、首页 `/dashboard` + +| 状态 | 问题 | +|:----:|------| +| ✅ | 无明显问题，样式正常 | + +**页面截图确认：** +- 欢迎卡片显示正常 +- 统计卡片（学校数、会员数、学生数、应用数）正常显示 +- 数据展示：128、5680、23456、12 + +--- + +## 三、学校管理 `/school` + +### 问题列表 + +| 序号 | 优先级 | 问题描述 | 状态 | +|:----:|:------:|----------|:----:| +| 1 | P2 | 操作列按钮换行显示，较拥挤 | ⬜ | +| 2 | P3 | 创建时间列在窄屏下可能被截断 | ⬜ | + +### 修复方案 + +**问题1：操作列过窄** + +```vue + + + +``` + +或者精简按钮文字： + +```vue +加年级 +加班级 +``` + +--- + +## 四、会员管理 `/member` + +| 状态 | 问题 | +|:----:|------| +| ✅ | 无明显问题，样式正常 | + +**页面截图确认：** +- 搜索表单完整（手机号、昵称、身份类型、状态、注册时间） +- 表格数据正常显示 +- 手机号脱敏显示正常（如 165****2844） +- 身份类型、状态Tag颜色正确 +- 分页正常 + +--- + +## 五、学生管理 `/student` + +| 状态 | 问题 | +|:----:|------| +| ✅ | 无明显问题，样式正常 | + +**页面截图确认：** +- 左侧学校树正常显示 +- 右侧搜索表单完整 +- 表格数据正常显示 +- 新增、导入按钮正常 + +--- + +## 六、应用管理 `/application` + +### 问题列表 + +| 序号 | 优先级 | 问题描述 | 状态 | +|:----:|:------:|----------|:----:| +| 1 | P1 | 授权接口列为空，数据不显示 | ⬜ | + +### 根因分析 + +视图文件使用 `row.apis`，但Mock数据返回的是 `row.apiAuth`。 + +**视图代码（第36-42行）：** +```vue + +