Python全栈项目--校园智能宿舍管理系统

一、项目简介

校园宿舍管理通常涉及楼栋维护、宿舍床位统计、学生入住、维修工单、访客登记等工作。传统表格记录方式容易出现信息分散、权限缺失、统计不及时等问题。本文实现一个可运行的 Python 全栈项目：校园智能宿舍管理系统，通过 FastAPI 提供后端接口，SQLite 保存业务数据，Vue 3 + Vite 构建前端管理台。

项目重点不是单一算法演示，而是完整的全栈闭环：用户注册登录、JWT 鉴权、数据库建模、RESTful 接口、前端状态管理、表单录入和数据看板。

二、技术栈

后端：Python 3、FastAPI、SQLAlchemy、Pydantic、Uvicorn
数据库：SQLite
认证：passlib bcrypt 密码哈希、python-jose JWT Token
前端：Vue 3、Vite、Fetch API、CSS 响应式布局
项目交付：README 运行说明、源码 zip 压缩包

三、系统架构

系统采用前后端分离架构：

text 复制代码

浏览器 Vue 3 管理台
        |
        | HTTP + Bearer Token
        v
FastAPI REST API
        |
        | SQLAlchemy ORM
        v
SQLite 数据库 dormitory.db

前端负责登录注册、菜单切换、表单录入和数据展示；后端负责认证鉴权、业务校验、数据库读写；SQLite 适合教学、小型校园部门试运行和本地演示。

四、功能模块

用户模块：注册、登录、当前用户信息、退出登录。
楼栋宿舍模块：新增楼栋、新增宿舍、查看宿舍容量和入住人数。
学生入住模块：学生档案录入、宿舍绑定、按姓名或学号搜索。
报修管理模块：提交维修工单、查看状态、标记完成。
访客登记模块：记录访客、被访学生、宿舍和来访事由。
数据看板：统计楼栋数、宿舍数、学生数、入住率、待处理报修数。

五、数据库/数据模型设计

后端核心模型位于 backend/app/models.py。

python 复制代码

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True, index=True)
    username = Column(String(50), unique=True, index=True, nullable=False)
    hashed_password = Column(String(255), nullable=False)
    role = Column(String(20), default="manager")

用户表不保存明文密码，只保存 bcrypt 哈希值。业务表包括：

buildings：楼栋名称、宿管、楼层数。
rooms：宿舍号、容量、状态、所属楼栋。
students：姓名、学号、学院、电话、宿舍 ID。
repair_orders：宿舍、报修标题、描述、处理状态。
visitor_logs：访客姓名、被访学生、宿舍、事由和时间。

这种设计将楼栋、宿舍、学生通过外键关联，可以方便统计入住率和宿舍占用情况。

六、后端接口设计

接口统一以 /api 开头，核心业务接口均需要登录后携带 Bearer Token。

方法	地址	说明	是否鉴权
POST	`/api/register`	用户注册	否
POST	`/api/login`	用户登录并返回 Token	否
GET	`/api/me`	获取当前用户	是
GET	`/api/dashboard`	数据看板	是
GET/POST	`/api/buildings`	楼栋列表/新增	是
GET/POST	`/api/rooms`	宿舍列表/新增	是
GET/POST	`/api/students`	学生列表/新增	是
GET/POST	`/api/repairs`	报修列表/新增	是
PATCH	`/api/repairs/{id}`	更新报修状态	是
GET/POST	`/api/visitors`	访客列表/新增	是

鉴权依赖函数如下：

python 复制代码

def get_current_user(token: str = Depends(oauth2_scheme), db: Session = Depends(get_db)):
    username = decode_token(token)
    if not username:
        raise HTTPException(status_code=401, detail="无效或过期的登录凭证")
    user = crud.get_user_by_username(db, username)
    if not user or not user.is_active:
        raise HTTPException(status_code=401, detail="用户不存在或已禁用")
    return user

所有业务接口都依赖 get_current_user，避免未登录用户直接操作宿舍数据。

七、前端页面设计

前端位于 frontend/，采用 Vue 3 + Vite 结构：

text 复制代码

frontend/
  package.json
  index.html
  src/
    main.js
    App.vue
    api.js
    style.css

页面设计包含登录注册卡片和登录后的管理后台。后台左侧是菜单：数据看板、楼栋宿舍、学生入住、报修管理、访客登记；右侧根据菜单显示表格和表单。api.js 负责统一封装请求，并自动附加 Token：

javascript 复制代码

async function request(path, options={}){
  const headers = { 'Content-Type': 'application/json', ...(options.headers || {}) }
  const token = getToken()
  if(token) headers.Authorization = `Bearer ${token}`
  const res = await fetch(`${API_BASE}${path}`, { ...options, headers })
  if(!res.ok) throw new Error('请求失败')
  return res.json()
}

八、核心代码讲解

1. 密码哈希与 Token

backend/app/auth.py 使用 passlib 对密码进行哈希，登录成功后用 JWT 保存用户名：

python 复制代码

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

def get_password_hash(password: str) -> str:
    return pwd_context.hash(password)

def create_access_token(data: dict, expires_delta: timedelta | None = None) -> str:
    to_encode = data.copy()
    expire = datetime.utcnow() + (expires_delta or timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES))
    to_encode.update({"exp": expire})
    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)

2. 数据看板统计

crud.dashboard 聚合多个表的数据，计算入住率：

python 复制代码

def dashboard(db: Session):
    total_students = db.query(models.Student).count()
    capacity = sum(r.capacity for r in db.query(models.Room).all()) or 1
    return {
        "buildings": db.query(models.Building).count(),
        "rooms": db.query(models.Room).count(),
        "students": total_students,
        "occupancy_rate": round(total_students / capacity * 100, 2),
    }

3. Vue 登录状态处理

前端登录成功后保存 Token，并在刷新页面时通过 /api/me 恢复登录状态：

javascript 复制代码

async function login(){
  const res = await api.login(auth)
  setToken(res.access_token)
  user.value = await api.me()
  await loadAll()
}

onMounted(async()=>{
  if(getToken()){
    user.value = await api.me()
    await loadAll()
  }
})

九、部署与运行步骤

1. 启动后端

bash 复制代码

cd project/backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

后端默认地址为 http://127.0.0.1:8000，接口文档为 http://127.0.0.1:8000/docs。

2. 启动前端

bash 复制代码

cd project/frontend
npm install
npm run dev

前端默认地址为 http://127.0.0.1:5173。进入页面后先注册账号，再登录使用系统。

3. 使用流程

注册管理员账号。
登录进入管理后台。
创建楼栋和宿舍。
办理学生入住。
提交报修工单并处理。
登记访客并查看数据看板统计结果。

十、项目总结

该项目实现了一个主题明确、结构完整的校园宿舍管理全栈系统。后端通过 FastAPI 提供清晰的 RESTful 接口，SQLite 降低部署门槛，JWT 与密码哈希保证基础安全；前端使用 Vue 3 + Vite 构建后台页面，完成注册、登录、鉴权请求、数据展示和业务录入。后续可以继续扩展床位分配算法、宿舍卫生评分、设备巡检、消息通知和多角色权限控制等能力。

项目代码

下载链接