# dormitory-repair-report-frontend

**Repository Path**: xiaohanyes/dormitory-repair-report-frontend

## Basic Information

- **Project Name**: dormitory-repair-report-frontend
- **Description**: CQUPT实训课程B：
使用Augment快速开发crud，体会AI提示词工程，AI工具调用等AI工作流。 
宿舍维修申报平台前端系统，用于处理和管理学生宿舍维修请求，支持高效、便捷的报修流程。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-16
- **Last Updated**: 2025-12-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 宿舍维修报修平台前端

基于 Vue 3 + TypeScript + Ant Design Vue 开发的现代化宿舍维修报修平台前端应用。

## 📋 项目概述

本项目是一个宿舍维修报修管理系统的前端应用，采用现代化的前端技术栈构建。**这是项目的第一版本**，实现了基础的用户权限管理、工单流程管理、物料库存管理等核心功能。系统支持三种用户角色，具备基本的权限控制机制。

⚠️ **注意**: 这是项目的初始版本，部分功能仍在开发中，存在一些已知问题和待完善的功能。

## ✨ 已实现特性

- 🚀 **现代化技术栈**: Vue 3 Composition API + TypeScript + Vite
- 🎨 **UI组件库**: Ant Design Vue 4.x 组件库，自定义主题色彩
- 📱 **响应式设计**: 基本的桌面端和移动端适配
- 🔐 **权限控制**: 基于角色的路由和菜单控制
- 🌙 **主题切换**: 支持亮色/暗色主题切换
- 📊 **基础统计**: 工单数量统计和物料库存预警
- 🔔 **通知系统**: 基础的消息中心功能
- 🤖 **AI推荐**: 基于技能匹配的维修工推荐（已集成）
- 🔄 **状态管理**: Pinia状态管理，支持数据持久化
- 🛡️ **类型安全**: 基础的TypeScript类型定义

## 👥 用户角色

### 学生 (Student)
- 创建维修工单，描述问题详情
- 查看自己提交的工单状态和进度
- 对完成的维修服务进行评价和反馈
- 接收工单状态变更通知

### 维修工 (Repair Worker)
- 查看分配给自己的工单任务
- 更新工单处理状态和进度
- 管理个人技能标签
- 管理物料库存，申请补充物料
- 查看库存预警信息

### 管理员 (Admin)
- 用户管理：注册新用户、管理用户信息
- 工单分配：手动分配或AI智能推荐维修工
- 系统管理：维修类别管理、物料管理
- 数据统计：查看工单统计和系统运营数据
- 技能管理：为维修工分配和管理技能标签

## 🏗️ 技术架构

### 核心技术栈

#### 前端框架
- **Vue 3.5.17**: 采用Composition API，提供更好的逻辑复用和类型推导
- **TypeScript 5.8**: 严格类型检查，提供完整的类型安全保障
- **Vite 7.0**: 基于ESBuild的快速构建工具，支持HMR热更新

#### UI组件库
- **Ant Design Vue 4.2.6**: 企业级UI组件库，提供丰富的组件和主题定制
- **@ant-design/icons-vue 7.0.1**: 官方图标库，支持按需加载

#### 状态管理
- **Pinia 3.0.3**: Vue官方推荐的状态管理库，支持TypeScript
- **pinia-plugin-persistedstate 4.4.1**: 状态持久化插件，支持localStorage

#### 路由和网络
- **Vue Router 4.5.1**: 官方路由管理器，支持动态路由和路由守卫
- **Axios 1.10.0**: HTTP客户端，统一的请求/响应拦截器

#### 开发工具
- **ESLint 9.29.0**: 代码质量检查，配合Vue和TypeScript规则
- **Prettier 3.5.3**: 代码格式化工具，保持代码风格一致
- **Vue DevTools**: Vue官方开发者工具支持

### 项目架构设计

#### 目录结构
```
src/
├── api/                    # API接口封装层
│   ├── user.ts            # 用户相关接口
│   ├── workorder.ts       # 工单相关接口
│   ├── material.ts        # 物料相关接口
│   ├── category.ts        # 类别相关接口
│   ├── notification.ts    # 通知相关接口
│   └── skill.ts           # 技能相关接口
├── assets/                 # 静态资源
│   ├── main.css           # 全局样式和CSS变量
│   └── base.css           # 基础样式重置
├── components/             # 可复用组件
│   ├── Layout/            # 布局组件
│   │   └── MainLayout.vue # 主布局（侧边栏+顶栏）
│   └── WorkOrder/         # 工单相关组件
│       └── AssignWorkerModal.vue # 分配维修工模态框
├── views/                  # 页面组件
│   ├── LoginPage.vue      # 登录页面
│   ├── RegisterPage.vue   # 注册页面（管理员）
│   ├── DashboardPage.vue  # 仪表板首页
│   ├── ProfilePage.vue    # 个人中心
│   ├── WorkOrder/         # 工单管理模块
│   │   ├── WorkOrderListPage.vue    # 工单列表
│   │   ├── WorkOrderCreatePage.vue  # 创建工单
│   │   └── WorkOrderDetailPage.vue  # 工单详情
│   ├── TestPage.vue       # 测试页面
│   ├── NotFoundPage.vue   # 404页面
│   ├── User/              # 用户管理模块
│   │   └── UserListPage.vue         # 用户列表
│   ├── Category/          # 维修类别管理
│   │   └── CategoryListPage.vue     # 类别列表
│   ├── Material/          # 物料管理模块
│   │   └── MaterialListPage.vue     # 物料列表
│   ├── Skill/             # 技能管理模块
│   │   ├── SkillManagePage.vue      # 技能管理
│   │   └── SkillOverviewPage.vue    # 技能概览
│   └── Notification/      # 通知中心
│       └── NotificationListPage.vue # 通知列表
├── stores/                 # Pinia状态管理
│   ├── app.ts             # 应用全局状态（主题、侧边栏等）
│   └── user.ts            # 用户状态管理
├── router/                 # 路由配置
│   └── index.ts           # 路由定义和守卫
├── utils/                  # 工具函数
│   ├── request.ts         # Axios封装和拦截器
│   ├── theme.ts           # 主题配置
│   └── pagination.ts     # 分页工具
├── types/                  # TypeScript类型定义
│   └── index.ts           # 全局类型定义
├── App.vue                # 根组件
└── main.ts                # 应用入口
```

#### 架构特点
- **模块化设计**: 按功能模块组织代码，便于维护和扩展
- **类型安全**: 完整的TypeScript类型定义，减少运行时错误
- **组件复用**: 抽象通用组件，提高开发效率
- **状态管理**: 集中式状态管理，支持数据持久化
- **路由守卫**: 完善的权限控制和路由保护机制

## 快速开始

### 环境要求
- Node.js >= 16.0.0
- npm >= 7.0.0

### 安装依赖
```bash
npm install
```

### 开发环境
```bash
npm run dev
```

### 生产构建
```bash
npm run build
```

### 代码检查
```bash
npm run lint
```

### 类型检查
```bash
npm run type-check
```

## 🔧 功能模块详解

### 1. 认证与权限系统 ✅
- **用户登录/注销**: 基于Session+Cookie的身份认证机制
- **权限控制**: 基于角色的访问控制，动态路由和菜单
- **路由守卫**: 自动验证用户身份和权限，支持登录重定向
- **状态持久化**: 用户登录状态localStorage存储，页面刷新保持登录
- **Session管理**: 自动检测Session过期，清除本地状态并跳转登录页

### 2. 工单管理系统 ✅
- **工单创建**: 学生可创建维修工单，选择维修类别，描述问题详情
- **工单列表**: 支持多条件筛选（工单编号、报修人、处理人、标题、地址、状态）、分页查询
- **工单详情**: 完整的工单信息展示，包括基本信息和状态
- **智能分配**:
  - 管理员手动分配维修工（已实现）
  - AI智能推荐：基于技能匹配的推荐算法（已集成后端接口）
- **状态管理**: 支持工单状态更新和取消操作
- **服务评价**: 🚧 评价功能界面已准备，待完善

### 3. 用户管理系统 ✅
- **用户列表**: 管理员查看所有用户，支持按角色、账号、昵称筛选
- **用户注册**: 管理员为新用户创建账号，分配角色
- **用户删除**: 支持删除用户操作
- **权限管理**: 角色权限控制，确保数据安全
- **个人中心**: 用户查看和修改个人信息
- **⚠️ 限制**: 用户编辑功能暂未实现（需要后端更新接口）

### 4. 维修类别管理 ✅
- **类别管理**: 管理员创建、编辑、删除维修类别
- **状态控制**: 启用/禁用类别，控制是否可选择
- **基础功能**: 支持类别的基本CRUD操作

### 5. 物料库存管理 ✅
- **物料管理**: 维修工和管理员可管理物料信息（增删改查）
- **库存跟踪**: 实时跟踪物料库存数量
- **库存预警**: 自动检测库存不足，仪表板显示预警信息
- **搜索筛选**: 支持按名称、型号、单位、库存状态筛选

### 6. 技能管理系统 ✅
- **技能管理**: 管理员可管理技能标签
- **技能分配**: 为维修工分配专业技能标签
- **技能匹配**: AI推荐算法基于技能匹配推荐维修工

### 7. 通知中心 ✅
- **消息列表**: 显示用户相关通知消息
- **未读提醒**: 仪表板显示未读消息数量
- **消息管理**: 支持标记已读、删除等基本操作
- **⚠️ 限制**: 当前为基础实现，实时推送功能待完善

### 8. 数据统计与仪表板 🚧
- **基础统计**: 仪表板显示工单数量、用户数量等基本统计
- **库存预警**: 显示库存不足的物料信息
- **最近工单**: 显示最近的工单列表
- **⚠️ 待完善**: 详细的数据可视化图表、趋势分析等功能

## 🚨 已知问题与待改进

### 当前存在的Bug

#### 1. 路由守卫无限循环问题 🔴
**问题描述**: 当用户已登录且服务器重启时，出现路由守卫无限循环验证的情况。

**原因分析**:
- 用户信息存储在localStorage中持久化
- 服务器重启后Session失效，但前端仍认为用户已登录
- 路由守卫中的`fetchUserInfo()`调用失败时的处理逻辑存在问题

**当前状态**:
- 在`src/router/index.ts`第232-248行已添加错误处理逻辑
- 当Session验证失败时，自动清除本地状态并跳转登录页
- 但在某些情况下仍可能出现循环

**待改进**: 需要优化Session验证机制，添加更robust的错误恢复逻辑

#### 2. 用户编辑功能缺失 🟡
**问题描述**: 用户管理页面的编辑功能暂未实现。

**具体位置**: `src/views/User/UserListPage.vue`第458行
**当前状态**: 点击编辑按钮显示"编辑功能暂未实现，需要后端提供更新接口"
**待改进**: 等待后端提供用户更新接口后实现

#### 3. 错误处理机制不够完善 🟡
**问题描述**: 部分API调用的错误处理不够统一。

**具体表现**:
- 网络错误时的提示信息不够友好
- 某些接口失败后没有合适的降级处理
- 缺少自动重试机制

### 技术债务

#### 1. TypeScript类型定义 🟡
- 存在`@ts-expect-error`注释（如`src/stores/app.ts`第56行）
- 部分API接口的类型定义可以更完善
- 需要完善全局类型定义

#### 2. 组件优化 🟡
- 部分页面组件较大，可以进一步拆分
- 缺少组件单元测试
- 需要添加组件文档

#### 3. 性能优化 🟡
- 大列表组件可以考虑虚拟滚动
- 路由组件已实现懒加载
- 静态资源可以进一步优化

### 功能待完善

#### 1. 实时通信 🔵
- 当前通知系统为基础实现
- 需要升级为WebSocket实时推送
- 工单状态变更需要实时通知

#### 2. 移动端优化 🔵
- 当前已有基本响应式设计
- 移动端体验可以进一步优化
- 可以添加移动端专用交互

#### 3. 数据导出 🔵
- 缺少工单数据导出功能
- 需要支持Excel、PDF等格式导出

#### 4. 高级功能 🔵
- 工单评价功能界面已准备，待完善
- 详细的数据可视化图表
- 高级搜索和筛选功能
- 批量操作功能

## 🔗 API接口

### 接口配置
- **基础地址**: `http://localhost:8181/api`
- **认证方式**: Session + Cookie
- **数据格式**: JSON
- **CORS**: 已配置跨域支持

### 主要接口模块
- **`/user/*`** - 用户管理：登录、注册、用户信息管理
- **`/workorder/*`** - 工单管理：创建、查询、分配、状态更新
- **`/category/*`** - 维修类别：类别管理、状态控制
- **`/material/*`** - 物料管理：库存管理、预警查询
- **`/notification/*`** - 通知管理：消息推送、已读状态
- **`/skill/*`** - 技能管理：技能分配、匹配算法

### 接口特性
- **统一响应格式**: 所有接口返回统一的`BaseResponse<T>`格式
- **错误处理**: 完善的HTTP状态码和业务错误码处理
- **请求拦截**: 自动添加认证信息和请求头
- **响应拦截**: 统一处理认证失效和错误提示

## 🛠️ 开发指南

### 环境要求
- **Node.js**: >= 16.0.0 (推荐使用 18.x 或 20.x LTS版本)
- **npm**: >= 7.0.0 (或使用 yarn、pnpm)
- **浏览器**: Chrome >= 87, Firefox >= 78, Safari >= 14, Edge >= 88

### 快速开始

#### 1. 克隆项目
```bash
git clone <repository-url>
cd Dormitory-repair-report-front
```

#### 2. 安装依赖
```bash
npm install
# 或使用 yarn
yarn install
# 或使用 pnpm
pnpm install
```

#### 3. 启动开发服务器
```bash
npm run dev
```
访问 `http://localhost:5173` 查看应用

#### 4. 构建生产版本
```bash
npm run build
```

#### 5. 预览构建结果
```bash
npm run preview
```

### 开发规范

#### 代码规范
- **ESLint + Prettier**: 自动代码格式化和质量检查
- **Vue 3 Composition API**: 优先使用组合式API，提高代码复用性
- **TypeScript严格模式**: 启用严格类型检查，避免类型错误
- **组件命名**: 采用PascalCase，如`UserListPage.vue`
- **文件命名**: 采用kebab-case，如`user-list-page.vue`
- **变量命名**: 采用camelCase，如`userInfo`
- **常量命名**: 采用UPPER_SNAKE_CASE，如`API_BASE_URL`

#### 项目结构规范
- **单一职责**: 每个文件和组件只负责一个功能
- **模块化**: 按功能模块组织代码，便于维护
- **类型定义**: 所有API接口和数据结构都要有完整的类型定义
- **组件复用**: 抽象通用组件，避免重复代码

#### Git提交规范
```bash
feat: 新功能开发
fix: Bug修复
docs: 文档更新
style: 代码格式调整（不影响功能）
refactor: 代码重构（不改变功能）
perf: 性能优化
test: 测试相关
chore: 构建过程或辅助工具的变动
ci: CI/CD相关变更
```

#### 代码质量检查
```bash
# 代码检查
npm run lint

# 类型检查
npm run type-check

# 代码格式化
npm run format
```

### 环境配置

#### 环境变量
项目使用Vite的环境变量系统，在项目根目录创建对应的环境文件：

```bash
# .env.development (开发环境)
VITE_API_BASE_URL=http://localhost:8181/api
VITE_APP_TITLE=宿舍维修报修平台

# .env.production (生产环境)
VITE_API_BASE_URL=https://your-api-domain.com/api
VITE_APP_TITLE=宿舍维修报修平台
```

#### 开发工具配置
推荐使用以下VSCode扩展：
- Vue Language Features (Volar)
- TypeScript Vue Plugin (Volar)
- ESLint
- Prettier
- Auto Rename Tag
- Bracket Pair Colorizer

### 调试技巧

#### 1. Vue DevTools
安装Vue DevTools浏览器扩展，可以：
- 查看组件树和状态
- 调试Pinia状态管理
- 监控路由变化
- 性能分析

#### 2. 网络调试
- 使用浏览器开发者工具的Network面板查看API请求
- 检查请求头、响应数据和状态码
- 使用Console查看错误日志

#### 3. 常见问题排查
- **登录问题**: 检查Session Cookie是否正确设置
- **权限问题**: 确认用户角色和路由权限配置
- **样式问题**: 检查CSS变量和主题配置
- **API问题**: 确认后端服务是否正常运行

## 🌐 浏览器支持

| 浏览器 | 版本要求 | 说明 |
|--------|----------|------|
| Chrome | >= 87 | 推荐使用最新版本 |
| Firefox | >= 78 | 支持ES2020特性 |
| Safari | >= 14 | 支持现代CSS特性 |
| Edge | >= 88 | 基于Chromium内核 |

## 📄 许可证

MIT License

## 🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📞 联系方式

如有问题或建议，请通过以下方式联系：

- 项目Issues: [GitHub Issues](项目地址/issues)
- 邮箱: xiaoh@example.com

## 🙏 致谢

感谢以下开源项目的支持：
- [Vue.js](https://vuejs.org/)
- [Ant Design Vue](https://antdv.com/)
- [TypeScript](https://www.typescriptlang.org/)
- [Vite](https://vitejs.dev/)

**注意**：以上均为AI编写，请自己辨别