基于Django的自习室预约管理系统

github项目地址：sgahch/studyroom

自习室预约系统 - 设计与总结报告

第一章 需求分析

为解决高校及公共自习室普遍存在的"占座难、管理乱"问题，开发本在线预约管理系统。旨在替代传统线下排队或低效管理方式，提供便捷、透明、高效的座位预定与管理服务。主要面向需要自习空间的学生及社会人士。核心功能包括用户认证、自习室浏览、座位实时状态查看、在线预约、扫码签到、后台管理等。系统致力于提供稳定、响应及时的服务，并通过前后端分离架构提升用户交互体验。（目前未进行详细竞品分析）

第二章 概要设计

2.1 系统架构

本项目采用前后端分离的混合架构模式，逐步从传统的 Django 服务端渲染向现代化的 Vue + Django REST Framework (DRF) API 架构迁移。

• 前端 (Vue): 负责用户界面展示与交互，通过 Axios 调用后端 API。
• 后端 (Django):
  • API 层 (DRF): 提供 RESTful API 接口供前端调用，处理业务逻辑，如用户认证、密码重置等。
  • 业务逻辑层 (Django): 包含原有的 Django 视图和业务逻辑，处理模板渲染相关的请求，如自习室管理、预约、签到等。
  • 数据访问层 (Django ORM): 通过 Django ORM 与 MySQL 数据库交互。
• 数据库: MySQL 存储所有业务数据。
• 架构图
• 

2.2 功能模块划分

系统主要可划分为以下模块：

1. 用户认证模块 (Vue + API):
   • 登录/注册/登出
   • 用户信息获取
   • 密码重置 (邮箱验证)
2. 自习室与座位模块 (Django Template + API):
   • 自习室列表展示
   • 座位布局与状态查看
3. 预约管理模块 (Django Template + API):
   • 座位预约
   • 预约记录查看
   • 签到/取消预约
4. 用户中心模块 (Django Template + API):
   • 个人信息修改 (头像、密码)
5. 后台管理模块 (Django Admin):
   • 数据管理 (用户、自习室、座位、预约等)

2.3 接口设计

• RESTful API (DRF):
  • /api/login/: 用户登录
  • /api/register/: 用户注册
  • /api/user/info/: 获取用户信息
  • /api/password/reset/request/: 请求密码重置验证码
  • /api/password/reset/with_code/: 使用验证码重置密码
  • 等等(还有部分未展示)
  • (未来将扩展更多业务API)
• Django URLS: 用于处理传统模板渲染的请求。

2.4 UI界面

• 新界面 (Vue): 采用 Vue 3 + Element Plus (计划中) 构建现代化、响应式的用户界面，提供更好的交互体验 (如登录、注册、忘记密码页面)。
• 旧界面 (Django Template): 使用 Bootstrap 和原生 JavaScript 构建，承载大部分现有业务功能。

第三章 详细设计

3.1 界面设计

• Vue 组件:
  • Login.vue: 用户登录表单及逻辑。
  • Register.vue: 用户注册表单及逻辑。
  • ForgotPassword.vue: 包含请求验证码和重置密码两步骤的表单及逻辑。
  • (其他组件根据功能逐步开发)
• Django 模板:
  • login/login.html, login/register.html: 原始登录注册页。
  • index/index.html: 系统主页。
  • index/seat.html, index/seat_id.html: 座位查看与详情页。
  • index/Bookings.html: 预约页面。
  • index/Recording.html: 预约记录页面。
  • index/change_avatar.html, index/change_password.html: 用户信息修改页。
  • admin/: Django自带后台管理界面。

(关键界面截图，登录页、主页、座位图页、后台管理页)

(登录界面)

(系统主页)

(自习室选择页)

(座位选择页)

(预约成功-QQ邮箱提醒)

（管理员界面）

3.2 数据库设计

• 数据库类型: MySQL 5.7+
• **主要数据表 **:
  • login_user: 存储用户信息 (用户名、哈希密码、邮箱、电话等)。
  • index_room: 存储自习室信息 (名称、位置、容量等)。
  • index_seat: 存储座位信息 (所属自习室、编号、状态等)。
  • index_booking: 存储预约记录 (用户、座位、时间段、状态等)。
  • index_music: (可能) 存储背景音乐信息。
  • auth_user, auth_group, auth_permission 等: Django认证系统自带表。
  • django_session: 存储 Session 信息。

3.3 关键算法与技术

• 密码哈希:
  • 算法: PBKDF2 + SHA256
  • 迭代次数: 320,000 次 (Django 4.0 默认)
  • 实现: 通过 Django 内建的 User.set_password() 和 check_password() 方法实现密码的设置与验证。
• 密码重置流程:
  1. 前端请求 /api/password/reset/request/ 并提供邮箱。
  2. 后端生成随机验证码，存储 (例如缓存或数据库)，并通过邮件发送 (开发模式下打印到控制台)。
  3. 用户在前端输入邮箱、验证码、新密码，请求 /api/password/reset/with_code/。
  4. 后端验证邮箱和验证码的匹配性与时效性，验证通过后更新用户密码 (哈希存储)。
• 用户认证:
  • 当前: 基于 Django Session 认证。用户登录成功后，后端设置 Session ID 到 Cookie，后续请求通过 Cookie 识别用户。
  • 计划: 迁移到 JWT (JSON Web Tokens) 认证。
• API 开发: 使用 Django REST Framework 快速构建序列化器 (Serializers)、视图集 (ViewSets) 和路由 (Routers)。
• 前端交互: Vue 3 框架，使用 Axios 库异步请求后端 API，Vue Router 管理前端路由。
• 跨域处理: 配置 django-cors-headers 中间件，在 settings.py 中设置允许访问的源 (如 http://localhost:8080)。

第四章 测试报告

• 测试标准: 遵循通用的 Web 应用测试标准，确保功能正确性、系统稳定性、安全性及用户体验。
• 测试环境: 开发环境 (Windows 10+, Python 3.12+, MySQL 5.7+), 浏览器 (Chrome, edge等)。
• 测试类型与内容:
  • 单元测试: 对 Django 后端关键函数、类 (如密码哈希、预约逻辑、模型方法) 进行测试。
  • API 测试: 使用工具 (如 Postman) 或编写测试脚本，对所有 RESTful API 进行测试 (覆盖正常、异常、边界情况)。
  • 功能测试:
    • 用户认证流程 (登录、注册、登出、密码重置)。✅
    • 自习室/座位浏览功能。 ✅
    • 核心预约流程 (预约、查看、签到、取消)。 ✅
    • 用户信息修改功能。 ✅
    • 后台管理功能。 ✅
  • 兼容性测试: 测试不同浏览器下的前端显示和功能。
  • 安全性测试:
    • 密码存储安全性 (确认哈希存储)。
    • API 访问权限控制 (未授权访问应拒绝)。
    • 跨站脚本 (XSS)、跨站请求伪造 (CSRF) 防护测试。
    • SQL 注入风险测试 (Django ORM 提供一定防护)。
  • 性能测试 (初步): 观察页面加载速度、API 响应时间。
• 总结: 系统核心功能基本可用，前后端分离部分已实现用户认证和密码重置。需进一步完善测试覆盖率，特别是针对并发预约、异常处理和安全性方面进行更深入的测试。

第五章 安装及使用

5.1 环境要求

• 操作系统: Windows 10+、Linux 和 macOS
• Python 版本: 3.12 或更高版本
• 数据库: MySQL 5.7 或更高版本
• (推荐) 包管理工具: pip
• (推荐) 虚拟环境工具: venv（项目自带）

5.2 安装过程

1. 解压项目
2. 进入项目目录: cd studyroom
3. 激活虚拟环境:
   • Windows: venv\Scripts\activate
   • Linux/Mac: source venv/bin/activate
4. 安装依赖: pip install -r requirements.txt
5. 配置数据库:
   • 启动 MySQL 服务。
   • 创建数据库 (例如 studyroom_db)。
   • 导入项目提供的 studyroom.sql 文件到创建的数据库中。
   • 修改 studyroom/settings.py 文件中的 DATABASES 配置，填入正确的数据库名、用户名、密码、主机和端口。
6. 数据库迁移:
   • python manage.py makemigrations
   • python manage.py migrate
7. 启动后端服务: python manage.py runserver (默认运行在 http://127.0.0.1:8000/)
8. (启动前端服务): 进入前端代码目录（cd frontend），根据其说明安装依赖(pip install -r requirements.txt)并启动开发服务器 (例如 npm install 和 npm run serve，通常运行在 http://localhost:8080/)。

5.3 使用流程

1. 确保后端 Django 服务已启动。
2. (如果适用) 确保前端 Vue 开发服务器已启动。
3. 在浏览器中访问前端地址 (如 http://localhost:8080/) 或 Django 服务地址 (如 http://127.0.0.1:8000/，取决于访问入口)。
4. 使用提供的测试账号登录 (账号user01\02\03/密码123) 或注册新账号。
5. 普通用户:
   • 浏览自习室列表和座位图，播放歌曲。
   • 选择可用座位进行预约。
   • 查看个人预约记录。
   • 在预约时间段内进行签到 (具体方式可能需查看代码或文档)。
   • 修改个人信息 (头像、密码)。
6. 管理员用户 (admin/123):
   • 访问 Django 后台管理界面 (通常是 http://127.0.0.1:8000/admin/)。
   • 进行用户管理、自习室/座位管理、预约记录管理等操作。

第六章 项目总结

6.1 开发感悟

• 架构演进的挑战: 从传统的 Django 单体应用向前后端分离架构迁移是一个复杂的过程，需要处理好新旧代码的兼容、接口设计、数据同步等问题。本次项目中，混合架构模式提供了一个平滑过渡的方案。
• 技术选型的重要性: 选择 Vue 3 和 DRF 作为新技术栈，提升了开发效率和用户体验，但也带来了学习成本。理解 RESTful 设计原则和前后端交互模式至关重要。
• 安全意识: 密码哈希存储、CORS 配置、CSRF 防护等安全措施是 Web 开发的基础，需要在设计和开发阶段就充分考虑。
• 文档与沟通: 清晰的文档（如 README）和有效的沟通对于项目进展和维护非常有帮助，特别是在涉及前后端协作时。

6.2 克服的困难

• 兼容旧密码: 设计并实现了对旧有明文密码用户的兼容登录及自动哈希升级机制。
• 前后端联调: 配置 CORS，解决跨域问题；调试 API 接口的请求与响应格式。
• 状态管理: 在前后端分离架构下，如何有效管理用户登录状态（当前使用 Session，未来计划 JWT）是一个关键点。

6.3 水平提升

通过本项目，加深了对 Django 框架（特别是 ORM、Admin、认证系统）的理解，掌握了 Django REST Framework 的基本使用，熟悉了 Vue 3 的基础语法和工程化实践，提升了前后端分离项目的开发能力和解决问题的能力。

6.4 后续升级与演进

根据 README.md 中的改进计划，后续可以从以下方面进行升级：

1. 认证升级: 实现 JWT 认证，提高 API 安全性与无状态性。
2. UI 现代化: 全面采用 Element Plus 或 TailwindCSS 优化界面，提升视觉效果和用户体验。
3. 性能优化: 引入 Redis 缓存热点数据，优化数据库查询（索引、分页），实现前端资源懒加载。
4. 功能增强:
   • 实现智能座位推荐。
   • 集成 WebSocket 实现预约状态、系统通知的实时推送。
   • 开发数据分析与可视化模块。
5. 开发流程优化: 配置 Docker 环境，实现 CI/CD 自动化部署，引入自动化测试和代码质量检查工具。
6. 监控系统: 集成日志收集、性能监控和错误追踪系统。

6.5 商业推广 (潜在)

若系统功能完善且稳定，可考虑向高校、图书馆、付费自习室等机构推广，提供 SaaS 服务或定制化解决方案。商业模式可围绕基础功能免费、增值功能（如智能推荐、数据分析）收费，或按用户数/座位数收取订阅费。