智慧实验室设备预约与资产管理系统

一个面向高校实验室场景的管理平台，覆盖设备资产管理、预约审批、维修上报、公告发布与数据看板，支持管理员、教师、学生三类角色。

核心功能

• 用户认证与权限控制（JWT）
• 用户 / 角色 / 权限管理
• 实验室、设备分类、设备资产管理
• 预约申请、审批、取消与冲突控制
• 维修工单与公告管理
• 仪表盘统计（概览、趋势、排行）

技术栈

• 后端：Spring Boot + Spring Security + MyBatis-Plus
• 前端：Vue 3 + TypeScript + Vite + Element Plus
• 数据库：MySQL 8.0
• 容器化：Docker + Docker Compose

目录结构

smartlab/
├─ server/            # 后端服务（默认 8080，API 前缀 /api）
├─ web/               # 前端项目（开发 5173）
├─ sql/               # 数据库脚本（schema.sql / seed.sql）
├─ docs/              # 接口与数据库设计文档
└─ docker-compose.yml # 一键部署（mysql + server + web）

部署与启动（推荐：Docker Compose）

1) 前置要求

• 已安装 Docker、Docker Compose

2) 启动服务

在项目根目录执行：

docker compose up -d --build

服务默认端口：

• 前端：http://localhost:5173
• 后端：http://localhost:8080/api
• MySQL：localhost:3306

3) 初始化数据库（首次部署建议执行）

docker compose exec -T mysql mysql --default-character-set=utf8mb4 -uroot -proot smartlab < sql/schema.sql
docker compose exec -T mysql mysql --default-character-set=utf8mb4 -uroot -proot smartlab < sql/seed.sql

4) 常用运维命令

docker compose ps
docker compose logs -f server
docker compose down

本地开发启动（前后端分离）

1) 环境准备

• JDK 21（建议，需与后端运行环境匹配）
• Maven 3.9+
• Node.js 20+
• MySQL 8.0

2) 启动数据库

可直接复用 compose 的 MySQL：

docker compose up -d mysql

3) 启动后端

cd server
mvn spring-boot:run

默认地址：http://localhost:8080/api

4) 启动前端

cd web
npm install
npm run dev

默认地址：http://localhost:5173（已通过 Vite 代理 /api 到 http://localhost:8080）

5) 一键启动开发环境

首次执行前请确保本机已安装 docker、curl、Node.js、JDK，并且前端依赖已安装完成：

cd web
npm install
cd ..
chmod +x scripts/dev-up.sh scripts/dev-down.sh
./scripts/dev-up.sh

脚本会完成这些动作：

• 启动 docker compose 中的 MySQL
• 在后台启动后端开发服务并轮询 http://127.0.0.1:8080/api/health
• 在固定端口 5173 启动前端开发服务

停止本地前后端：

./scripts/dev-down.sh

开发环境默认端口和变量：

• 前端固定使用 127.0.0.1:5173
• 后端固定使用 127.0.0.1:8080
• 前端示例变量见 web/.env.example
• 后端生产变量模板见 server/.env.prod.example

CI 门禁

仓库已补充 GitHub Actions 工作流：前端执行 npm run build，后端执行 ./mvnw test。工作流文件位于 .github/workflows/ci.yml。

E2E 测试

前端已接入 Playwright 基础设施，测试文件位于 web/tests/e2e/，当前覆盖：

• 登录跳转与登录成功
• 错误密码提示
• 学生预约提交流程

首次运行前建议安装浏览器：

cd web
npm run test:e2e:install

启动前后端后执行：

cd web
npm run test:e2e

如测试地址不是默认的 http://127.0.0.1:5173，可通过环境变量覆盖：

PLAYWRIGHT_BASE_URL=http://127.0.0.1:4173 npm run test:e2e

生产环境变量基线

后端生产配置建议至少显式设置以下变量：

• DB_HOST / DB_PORT / DB_NAME / DB_USER / DB_PASSWORD
• JWT_SECRET
• CORS_ALLOWED_ORIGIN_PATTERNS

示例模板见 server/.env.prod.example。其中 JWT_SECRET 必须替换，CORS_ALLOWED_ORIGIN_PATTERNS 不应保留为宽泛通配。

默认账号（种子数据）

• 管理员：admin / 123456
• 教师：teacher / 123456
• 学生：student / 123456

相关文档

• 接口文档：docs/api.md
• 数据库设计：docs/db-design.md
• 异常码约定：docs/exception-codes.md
• 优化记录：docs/improvements.md
• 学习指南入口：docs/learning-guide.md
• 目录版学习指南：docs/learning/README.md