1

Design/frontend_Design/Frontend_Design.md

@@ -0,0 +1,550 @@
+# 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` 分支自动部署到生产环境