550 lines
14 KiB
Markdown
550 lines
14 KiB
Markdown
# EMS 前端设计文档
|
|
|
|
## 1. 技术栈
|
|
|
|
- **前端框架**: Vue 3
|
|
- **构建工具**: Vite
|
|
- **状态管理**: Pinia
|
|
- **路由管理**: Vue Router
|
|
- **UI 组件库**: Element Plus
|
|
- **HTTP 客户端**: Axios
|
|
- **CSS 预处理器**: SCSS
|
|
- **类型检查**: TypeScript
|
|
- **地图组件**: Leaflet.js
|
|
- **图表库**: ECharts
|
|
- **表单验证**: Vee-Validate
|
|
- **国际化**: Vue I18n
|
|
- **测试框架**: Vitest
|
|
|
|
## 2. 架构设计
|
|
|
|
### 2.1 目录结构
|
|
|
|
```
|
|
ems-frontend/
|
|
├── public/ # 静态资源
|
|
├── src/
|
|
│ ├── api/ # API 请求模块
|
|
│ │ ├── auth.ts # 认证相关 API
|
|
│ │ ├── dashboard.ts # 仪表盘相关 API
|
|
│ │ └── ...
|
|
│ ├── assets/ # 静态资源
|
|
│ │ ├── styles/ # 全局样式
|
|
│ │ └── images/ # 图片资源
|
|
│ ├── components/ # 通用组件
|
|
│ │ ├── common/ # 基础组件
|
|
│ │ ├── layout/ # 布局组件
|
|
│ │ └── business/ # 业务组件
|
|
│ ├── composables/ # 组合式函数
|
|
│ ├── config/ # 配置文件
|
|
│ ├── constants/ # 常量定义
|
|
│ ├── directives/ # 自定义指令
|
|
│ ├── hooks/ # 自定义 Hooks
|
|
│ ├── locales/ # 国际化资源
|
|
│ ├── router/ # 路由配置
|
|
│ ├── stores/ # Pinia 状态管理
|
|
│ ├── types/ # TypeScript 类型定义
|
|
│ ├── utils/ # 工具函数
|
|
│ ├── views/ # 页面组件
|
|
│ │ ├── auth/ # 认证相关页面
|
|
│ │ ├── dashboard/ # 仪表盘页面
|
|
│ │ └── ...
|
|
│ ├── App.vue # 根组件
|
|
│ ├── main.ts # 入口文件
|
|
│ └── env.d.ts # 环境变量类型声明
|
|
├── .env # 环境变量
|
|
├── .env.development # 开发环境变量
|
|
├── .env.production # 生产环境变量
|
|
├── index.html # HTML 模板
|
|
├── package.json # 依赖配置
|
|
├── tsconfig.json # TypeScript 配置
|
|
└── vite.config.ts # Vite 配置
|
|
```
|
|
|
|
### 2.2 核心模块
|
|
|
|
1. **认证模块**: 处理用户登录、注册、密码重置等功能
|
|
2. **仪表盘模块**: 展示系统概览、数据统计和图表
|
|
3. **地图模块**: 展示地理信息、网格分布和污染热图
|
|
4. **任务管理模块**: 处理任务分配、查看和审核
|
|
5. **反馈管理模块**: 处理用户反馈的提交和管理
|
|
6. **人员管理模块**: 管理系统用户、角色和权限
|
|
7. **个人中心模块**: 查看和修改个人信息
|
|
|
|
## 3. 页面结构
|
|
|
|
### 3.1 基础布局
|
|
|
|
系统将采用以下几种基础布局:
|
|
|
|
1. **主布局**: 包含侧边导航栏、顶部导航栏和内容区域
|
|
2. **认证布局**: 用于登录、注册等不需要导航的页面
|
|
3. **空白布局**: 用于全屏展示的页面，如地图全屏模式
|
|
|
|
### 3.2 响应式设计
|
|
|
|
- 采用移动优先的响应式设计
|
|
- 断点设置:
|
|
- 移动端: < 768px
|
|
- 平板: 768px - 1024px
|
|
- 桌面: > 1024px
|
|
- 关键组件的响应式行为:
|
|
- 侧边栏在移动端变为可折叠抽屉
|
|
- 表格在移动端优化为卡片式布局
|
|
- 表单在移动端采用单列布局
|
|
|
|
## 4. 路由设计
|
|
|
|
### 4.1 路由结构
|
|
|
|
```javascript
|
|
const routes = [
|
|
// 认证相关路由
|
|
{
|
|
path: '/auth',
|
|
component: AuthLayout,
|
|
children: [
|
|
{ path: 'login', component: LoginView },
|
|
{ path: 'register', component: RegisterView },
|
|
{ path: 'forgot-password', component: ForgotPasswordView },
|
|
{ path: 'reset-password', component: ResetPasswordView },
|
|
],
|
|
meta: { requiresAuth: false }
|
|
},
|
|
|
|
// 主应用路由
|
|
{
|
|
path: '/',
|
|
component: MainLayout,
|
|
children: [
|
|
{ path: '', component: DashboardView, meta: { requiresAuth: true, roles: ['ADMIN', 'DECISION_MAKER'] } },
|
|
{ path: 'map', component: MapView, meta: { requiresAuth: false } },
|
|
{ path: 'tasks', component: TasksView, meta: { requiresAuth: true } },
|
|
{ path: 'feedback', component: FeedbackView, meta: { requiresAuth: true } },
|
|
{ path: 'personnel', component: PersonnelView, meta: { requiresAuth: true, roles: ['ADMIN'] } },
|
|
{ path: 'profile', component: ProfileView, meta: { requiresAuth: true } },
|
|
]
|
|
},
|
|
|
|
// 错误页面路由
|
|
{ path: '/404', component: NotFoundView },
|
|
{ path: '/403', component: ForbiddenView },
|
|
{ path: '/:pathMatch(.*)*', redirect: '/404' }
|
|
]
|
|
```
|
|
|
|
### 4.2 路由守卫
|
|
|
|
```javascript
|
|
router.beforeEach((to, from, next) => {
|
|
const authStore = useAuthStore();
|
|
|
|
// 检查路由是否需要认证
|
|
const requiresAuth = to.matched.some(record => record.meta.requiresAuth !== false);
|
|
|
|
// 检查用户角色权限
|
|
const hasRequiredRole = to.matched.every(record => {
|
|
if (!record.meta.roles) return true;
|
|
return authStore.user && record.meta.roles.includes(authStore.user.role);
|
|
});
|
|
|
|
if (requiresAuth && !authStore.isAuthenticated) {
|
|
// 未登录，重定向到登录页
|
|
next({ path: '/auth/login', query: { redirect: to.fullPath } });
|
|
} else if (requiresAuth && !hasRequiredRole) {
|
|
// 无权限访问
|
|
next({ path: '/403' });
|
|
} else {
|
|
// 正常导航
|
|
next();
|
|
}
|
|
});
|
|
```
|
|
|
|
## 5. 状态管理
|
|
|
|
### 5.1 Pinia Store 设计
|
|
|
|
```typescript
|
|
// 认证状态管理
|
|
export const useAuthStore = defineStore('auth', {
|
|
state: () => ({
|
|
user: null,
|
|
token: localStorage.getItem('token'),
|
|
error: null,
|
|
}),
|
|
getters: {
|
|
isAuthenticated: state => !!state.token,
|
|
userRole: state => state.user?.role || null,
|
|
},
|
|
actions: {
|
|
async login(credentials) { /* 实现登录逻辑 */ },
|
|
async logout() { /* 实现登出逻辑 */ },
|
|
async fetchUserProfile() { /* 获取用户信息 */ },
|
|
}
|
|
});
|
|
|
|
// 任务状态管理
|
|
export const useTaskStore = defineStore('task', {
|
|
state: () => ({
|
|
tasks: [],
|
|
currentTask: null,
|
|
loading: false,
|
|
error: null,
|
|
}),
|
|
getters: {
|
|
tasksByStatus: state => status => state.tasks.filter(task => task.status === status),
|
|
},
|
|
actions: {
|
|
async fetchTasks(filters) { /* 获取任务列表 */ },
|
|
async fetchTaskById(id) { /* 获取任务详情 */ },
|
|
async assignTask(taskId, userId) { /* 分配任务 */ },
|
|
async submitTask(taskId, data) { /* 提交任务 */ },
|
|
}
|
|
});
|
|
|
|
// 其他模块状态管理...
|
|
```
|
|
|
|
### 5.2 持久化策略
|
|
|
|
- 使用 localStorage 存储认证 token
|
|
- 关键用户设置使用 localStorage 持久化
|
|
- 敏感数据不进行持久化，每次会话重新获取
|
|
|
|
## 6. API 请求封装
|
|
|
|
### 6.1 基础请求客户端
|
|
|
|
```typescript
|
|
// api/client.ts
|
|
import axios from 'axios';
|
|
import { useAuthStore } from '@/stores/auth';
|
|
|
|
const apiClient = axios.create({
|
|
baseURL: import.meta.env.VITE_API_BASE_URL,
|
|
timeout: 10000,
|
|
headers: {
|
|
'Content-Type': 'application/json',
|
|
}
|
|
});
|
|
|
|
// 请求拦截器
|
|
apiClient.interceptors.request.use(
|
|
config => {
|
|
const authStore = useAuthStore();
|
|
if (authStore.token) {
|
|
config.headers.Authorization = `Bearer ${authStore.token}`;
|
|
}
|
|
return config;
|
|
},
|
|
error => Promise.reject(error)
|
|
);
|
|
|
|
// 响应拦截器
|
|
apiClient.interceptors.response.use(
|
|
response => response,
|
|
error => {
|
|
const authStore = useAuthStore();
|
|
|
|
// 处理 401 未授权错误
|
|
if (error.response && error.response.status === 401) {
|
|
authStore.logout();
|
|
router.push('/auth/login');
|
|
}
|
|
|
|
return Promise.reject(error);
|
|
}
|
|
);
|
|
|
|
export default apiClient;
|
|
```
|
|
|
|
### 6.2 模块化 API 封装
|
|
|
|
```typescript
|
|
// api/auth.ts
|
|
import apiClient from './client';
|
|
|
|
export const authApi = {
|
|
login: (credentials) => apiClient.post('/auth/login', credentials),
|
|
register: (userData) => apiClient.post('/auth/signup', userData),
|
|
requestPasswordReset: (email) => apiClient.post('/auth/request-password-reset', { email }),
|
|
resetPassword: (data) => apiClient.post('/auth/reset-password', data),
|
|
};
|
|
|
|
// api/tasks.ts
|
|
import apiClient from './client';
|
|
|
|
export const taskApi = {
|
|
getTasks: (params) => apiClient.get('/management/tasks', { params }),
|
|
getTaskById: (id) => apiClient.get(`/management/tasks/${id}`),
|
|
assignTask: (taskId, data) => apiClient.post(`/management/tasks/${taskId}/assign`, data),
|
|
reviewTask: (taskId, data) => apiClient.post(`/management/tasks/${taskId}/review`, data),
|
|
};
|
|
|
|
// 其他模块 API...
|
|
```
|
|
|
|
## 7. 组件设计
|
|
|
|
### 7.1 基础组件
|
|
|
|
- **AppButton**: 统一按钮样式和行为
|
|
- **AppCard**: 卡片容器组件
|
|
- **AppForm**: 表单容器组件
|
|
- **AppInput**: 输入框组件
|
|
- **AppSelect**: 下拉选择组件
|
|
- **AppTable**: 表格组件
|
|
- **AppPagination**: 分页组件
|
|
- **AppModal**: 模态框组件
|
|
- **AppAlert**: 提示框组件
|
|
|
|
### 7.2 业务组件
|
|
|
|
- **TaskCard**: 任务卡片组件
|
|
- **FeedbackForm**: 反馈提交表单
|
|
- **UserSelector**: 用户选择器
|
|
- **StatusBadge**: 状态标签组件
|
|
- **MapGrid**: 地图网格组件
|
|
- **PollutionTypeIcon**: 污染类型图标
|
|
- **TaskFilterPanel**: 任务筛选面板
|
|
- **StatisticCard**: 统计数据卡片
|
|
|
|
## 8. 主题设计
|
|
|
|
### 8.1 色彩系统
|
|
|
|
- **主色**: #1890ff (蓝色)
|
|
- **成功色**: #52c41a (绿色)
|
|
- **警告色**: #faad14 (黄色)
|
|
- **错误色**: #f5222d (红色)
|
|
- **中性色**:
|
|
- 标题: #262626
|
|
- 正文: #595959
|
|
- 辅助文字: #8c8c8c
|
|
- 禁用: #bfbfbf
|
|
- 边框: #d9d9d9
|
|
- 分割线: #f0f0f0
|
|
- 背景: #f5f5f5
|
|
- 表格头部: #fafafa
|
|
|
|
### 8.2 字体系统
|
|
|
|
- **主字体**: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'PingFang SC', 'Helvetica Neue', Arial, sans-serif
|
|
- **代码字体**: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, Courier, monospace
|
|
- **字体大小**:
|
|
- 小号: 12px
|
|
- 正文: 14px
|
|
- 标题: 16px, 18px, 20px, 24px
|
|
|
|
### 8.3 间距系统
|
|
|
|
- **基础单位**: 4px
|
|
- **间距尺寸**:
|
|
- xs: 4px
|
|
- sm: 8px
|
|
- md: 16px
|
|
- lg: 24px
|
|
- xl: 32px
|
|
- xxl: 48px
|
|
|
|
### 8.4 阴影系统
|
|
|
|
- **轻微阴影**: 0 2px 8px rgba(0, 0, 0, 0.15)
|
|
- **中等阴影**: 0 4px 12px rgba(0, 0, 0, 0.15)
|
|
- **深度阴影**: 0 8px 16px rgba(0, 0, 0, 0.15)
|
|
|
|
## 9. 国际化
|
|
|
|
支持中文和英文两种语言，使用 Vue I18n 实现国际化。
|
|
|
|
```typescript
|
|
// locales/zh-CN.json
|
|
{
|
|
"auth": {
|
|
"login": "登录",
|
|
"register": "注册",
|
|
"forgotPassword": "忘记密码",
|
|
"email": "邮箱",
|
|
"password": "密码",
|
|
"confirmPassword": "确认密码"
|
|
},
|
|
"dashboard": {
|
|
"title": "仪表盘",
|
|
"stats": "统计数据",
|
|
"tasks": "任务概览",
|
|
"feedback": "反馈概览"
|
|
}
|
|
}
|
|
|
|
// locales/en-US.json
|
|
{
|
|
"auth": {
|
|
"login": "Login",
|
|
"register": "Register",
|
|
"forgotPassword": "Forgot Password",
|
|
"email": "Email",
|
|
"password": "Password",
|
|
"confirmPassword": "Confirm Password"
|
|
},
|
|
"dashboard": {
|
|
"title": "Dashboard",
|
|
"stats": "Statistics",
|
|
"tasks": "Task Overview",
|
|
"feedback": "Feedback Overview"
|
|
}
|
|
}
|
|
```
|
|
|
|
## 10. 权限控制
|
|
|
|
### 10.1 角色定义
|
|
|
|
- **ADMIN**: 系统管理员，拥有所有权限
|
|
- **SUPERVISOR**: 主管，负责任务分配和审核
|
|
- **GRID_WORKER**: 网格员，负责执行任务
|
|
- **DECISION_MAKER**: 决策者，查看数据和报表
|
|
|
|
### 10.2 权限指令
|
|
|
|
```typescript
|
|
// 创建自定义指令控制元素的显示/隐藏
|
|
app.directive('permission', {
|
|
mounted(el, binding) {
|
|
const { value } = binding;
|
|
const authStore = useAuthStore();
|
|
|
|
if (value && !authStore.hasPermission(value)) {
|
|
el.parentNode && el.parentNode.removeChild(el);
|
|
}
|
|
}
|
|
});
|
|
|
|
// 使用示例
|
|
<button v-permission="'ADMIN'">删除用户</button>
|
|
<div v-permission="['ADMIN', 'SUPERVISOR']">管理内容</div>
|
|
```
|
|
|
|
## 11. 错误处理
|
|
|
|
### 11.1 全局错误处理
|
|
|
|
```typescript
|
|
// 全局错误处理
|
|
app.config.errorHandler = (err, vm, info) => {
|
|
console.error('全局错误:', err);
|
|
|
|
// 上报错误到监控系统
|
|
errorReportingService.report(err, {
|
|
component: vm?.$options?.name,
|
|
info,
|
|
user: useAuthStore().user?.id
|
|
});
|
|
|
|
// 显示用户友好的错误提示
|
|
ElMessage.error('操作失败，请稍后重试');
|
|
};
|
|
```
|
|
|
|
### 11.2 API 错误处理
|
|
|
|
```typescript
|
|
// 统一处理 API 错误
|
|
export const handleApiError = (error) => {
|
|
if (error.response) {
|
|
// 服务器响应错误
|
|
const { status, data } = error.response;
|
|
|
|
switch (status) {
|
|
case 400:
|
|
ElMessage.error(data.message || '请求参数错误');
|
|
break;
|
|
case 401:
|
|
ElMessage.error('会话已过期，请重新登录');
|
|
break;
|
|
case 403:
|
|
ElMessage.error('没有权限执行此操作');
|
|
break;
|
|
case 404:
|
|
ElMessage.error('请求的资源不存在');
|
|
break;
|
|
case 500:
|
|
ElMessage.error('服务器内部错误，请稍后重试');
|
|
break;
|
|
default:
|
|
ElMessage.error('请求失败，请稍后重试');
|
|
}
|
|
} else if (error.request) {
|
|
// 请求发出但没有收到响应
|
|
ElMessage.error('网络连接失败，请检查网络设置');
|
|
} else {
|
|
// 请求配置错误
|
|
ElMessage.error('请求配置错误');
|
|
}
|
|
|
|
return Promise.reject(error);
|
|
};
|
|
```
|
|
|
|
## 12. 性能优化
|
|
|
|
### 12.1 代码分割
|
|
|
|
- 使用动态导入实现路由级别的代码分割
|
|
- 将大型第三方库单独打包
|
|
|
|
### 12.2 资源优化
|
|
|
|
- 图片资源使用 WebP 格式并进行压缩
|
|
- 使用 SVG 图标代替图片图标
|
|
- 使用字体图标减少 HTTP 请求
|
|
|
|
### 12.3 渲染优化
|
|
|
|
- 使用虚拟滚动处理长列表
|
|
- 合理使用 `v-show` 和 `v-if`
|
|
- 大型表格使用分页加载
|
|
- 使用 `keep-alive` 缓存组件状态
|
|
|
|
## 13. 测试策略
|
|
|
|
### 13.1 单元测试
|
|
|
|
- 使用 Vitest 进行单元测试
|
|
- 重点测试工具函数、Hooks 和小型组件
|
|
- 使用 Vue Test Utils 测试组件
|
|
|
|
### 13.2 端到端测试
|
|
|
|
- 使用 Cypress 进行端到端测试
|
|
- 覆盖关键用户流程:
|
|
- 用户注册和登录
|
|
- 任务创建和分配
|
|
- 反馈提交和处理
|
|
|
|
## 14. 部署策略
|
|
|
|
### 14.1 构建配置
|
|
|
|
- 开发环境: `vite build --mode development`
|
|
- 测试环境: `vite build --mode staging`
|
|
- 生产环境: `vite build --mode production`
|
|
|
|
### 14.2 环境变量
|
|
|
|
```
|
|
# .env.development
|
|
VITE_API_BASE_URL=http://localhost:8080/api
|
|
VITE_APP_TITLE=EMS开发环境
|
|
|
|
# .env.production
|
|
VITE_API_BASE_URL=/api
|
|
VITE_APP_TITLE=环境监测系统
|
|
```
|
|
|
|
### 14.3 CI/CD 流程
|
|
|
|
- 使用 GitHub Actions 自动化构建和部署
|
|
- 提交到 `develop` 分支自动部署到测试环境
|
|
- 提交到 `main` 分支自动部署到生产环境 |