Python Flask构建学生宿舍管理系统：从数据库设计到可视化大屏

1. 项目先想清楚：学生宿舍管理系统到底要管什么

先说点实际的。我接触过不少类似的学生宿舍管理系统，很多人一上来就急着写代码，结果做到一半发现需求都没理清，数据库表改来改去，最后变成一个"啥都能点但啥都不好用"的半成品。这个项目标题里的核心词其实很明确：Python + Flask、学生宿舍管理、可视化。这三个词基本就框定了技术栈和方向，但在动手之前，我们先花点时间把"系统要解决什么问题"这件事掰扯清楚。

学生宿舍管理的痛点其实很典型：宿舍分配靠Excel或者纸质台账，查一个学生住哪栋楼哪个房间要翻半天；报修信息散落在微信群或者电话记录里，处理进度没人跟踪；卫生检查打分全凭感觉，月末汇总统计更是痛苦；宿管老师和辅导员想看看整个宿舍楼的入住率、男女比例、报修趋势，根本拿不出直观数据。所以，这套系统的核心价值不是"做个网站"，而是把宿舍管理的日常事务数字化、流程化，再把数据变成可视化图表，让管理者能一眼看懂情况。

那这个系统到底适合谁来参考和学习？如果你是正在做课程设计、毕业设计的学生，这个项目能帮你快速掌握 Flask Web 开发的全流程，从数据库设计、后端接口到前端图表渲染都能学到；如果你是刚入门 Python Web 开发、想找个完整案例练手的开发者，这个项目同样合适，麻雀虽小五脏俱全，一个典型的业务管理系统该有的模块它都有。

在我开始拆解具体设计之前，有个特别想提醒的点：不要把"可视化"想得太玄乎。很多初学者一听"可视化"就觉得要高难度技术，其实在这个项目里，可视化说白了就是几个统计图表——柱状图、饼图、折线图，把宿舍管理的核心数据展示在一个仪表盘页面上。用什么技术实现？ECharts 就够了，完全不复杂，后面我会详细讲。

2. 技术选型思路：为什么这套组合最省心

既然标题定了 Python + Flask，那技术栈基本就锁定了大半，但数据库、前端模板、图表库这些还是要自己拿主意的。我先说说我为什么推荐这样一套组合，以及每个选择的底层逻辑是什么。

2.1 框架选择：Flask 和 Django 之间的权衡

很多人在做这种管理系统时会纠结用 Flask 还是 Django。我个人的看法是：如果你追求快速开发和灵活可控，Flask 是更好的选择。Django 自带 Admin 后台、ORM、模板系统，功能确实强大，但它的"全家桶"风格对新手不太友好，很多功能你用不上，反而增加了理解成本。Flask 以简单灵活著称，核心功能少，但通过扩展库几乎什么都能做——Flask-SQLAlchemy 管数据库，Flask-Login 管登录，Flask-WTF 管表单，需要什么拿什么。

而且从课程设计或毕业设计的角度来说，Flask 的项目结构更清晰，代码量适中，答辩的时候你能讲清楚每一个模块的实现原理。Django 里面很多东西是"自动魔法"，写起来快，但问到你细节的时候容易答不上来。Flask 则每个路由、每个视图函数都是你自己写的，一通百通。

2.2 数据库选择：开发用 SQLite，部署换 MySQL

数据库方面，我强烈建议开发阶段用 SQLite，部署阶段再切 MySQL。为什么？SQLite 是 Python 内置支持的轻量级数据库，不需要安装任何服务，一个文件就是整个数据库，非常适合学习和本地开发。你写代码、跑测试的时候完全感受不到数据库的存在，省心极了。

如果你的项目要求必须用 MySQL，也完全可以，只需要改一下数据库连接配置，ORM 层（SQLAlchemy）的代码几乎不用动。毕竟它是 ORM，不是裸写 SQL 语句，数据库之间切换成本很低。我的建议是：先把功能跑通，最后再考虑要不要换 MySQL。不要一开始就在数据库选型上纠结半天，那是在浪费时间。

2.3 可视化图表：ECharts 为什么是首选

可视化方案我对比过不少：原生 Canvas 画图表工作量太大，不适合业务系统；Plotly 的功能虽然强大但接入稍重；Highcharts 商用有授权问题；最后看下来，Apache ECharts 是最合适的选择。它是国产开源项目，免费商用，文档和示例极其丰富，中文社区活跃，你想要的图表类型基本都有现成的官方示例可以直接抄。

还有一个关键点：ECharts 本身是纯前端的 JavaScript 库，但它的数据来源完全靠后端的 API 接口动态提供。这正好体现了 Flask 后端的一个核心能力——设计 JSON 数据接口。后端从数据库把统计结果查出来，转换成 JSON 返回给前端，前端拿到数据一个 setOption() 就把图表渲染出来了。这个"前后端分离"的数据交互模式，是大项目必用的思路，在咱们这个管理系统里提前练手，非常划算。

2.4 前端模板：Jinja2 + Bootstrap 快速搭界面

很多 Flask 初学者以为要做前端就得上 Vue、React 这些框架。其实对于这种后台管理系统，完全没有必要。Flask 内置的 Jinja2 模板引擎 + Bootstrap 就足够了。Jinja2 天然支持在 HTML 里写 {% %} 和 {{ }} 语法，可以循环渲染表格、判断按钮状态、复用公共模板。配合 Bootstrap 的样式框架，不用写一行复杂的 CSS，界面就能看得过去。

我们后面要做可视化的仪表盘页面，用 Bootstrap 的栅格系统（row + col）来布局图表，用 ECharts 渲染图表本体，这种组合非常成熟，网上能找到大量参考案例。

3. 数据库设计：这个系统的地基

数据库设计是整套系统最核心的部分。很多新手项目最后改得乱七八糟，追根溯源基本都是表结构没设计好。设计数据库的时候要反复问自己：一个宿舍管理员每天会用这个系统干什么？每次操作要涉及哪些数据？哪些数据之间有关联？把这些想透了，表结构就自然浮现出来了。

3.1 核心表结构：八个模块六张表

我按照宿舍管理的实际业务场景，拆解出六个核心功能模块，对应六张数据表：

• 用户表（User）：存储系统登录账号，区分管理员、宿管老师、学生三种角色。
• 学生表（Student）：存储学生的基本信息和住宿信息，和宿舍表关联。
• 宿舍表（Dorm）：存储楼栋、房间号、床位数、当前入住人数、宿舍类型（四人间/六人间）。
• 报修表（Repair）：存储报修单，包含报修宿舍、报修内容、状态（待处理/处理中/已完成）、提交时间。
• 卫生检查表（Inspection）：存储每次卫生检查的评分、检查人、备注。
• 访客登记表（VisitLog）：存储访客信息和被访学生信息，用于宿舍安全管理。

这六张表覆盖了一个学生从入住、日常管理到退宿的全部场景。有个很容易踩的坑：只建了学生表和宿舍表，做可视化图表的时候发现没有女性，巧妇难为无米之炊。所以一开始就要想想首页仪表盘要展示哪些指标，反推需要哪些统计数据。

3.2 表字段设计与关系定义

下面重点说一下每张表的字段设计，以及为什么这么设计。

User 用户表

密码绝对不能在数据库里存明文，这是底线。我通常用 Flask 内置的 generate_password_hash 和 check_password_hash，底层走的是 werkzeug 的安全哈希算法，简单好用，不用自己实现。

Dorm 宿舍表

current_count 和 is_full 这两个字段很容易被忽略。你想，给新生分配宿舍的时候，宿管老师需要快速知道哪些宿舍有空床位。如果每次都要 count 一下入驻这个宿舍的学生数，不仅慢，而且代码写起来啰嗦。直接在宿舍表里维护当前入住人数和是否满员，分配宿舍的时候查一下这两个字段，效率高很多。

Student 学生表

注意，dorm_id 是外键，用来关联学生和宿舍。一个宿舍可以住多个学生，一个学生一次只住在一个宿舍，这是典型的多对一关系，在 SQLAlchemy 里用 db.ForeignKey 定义。

Repair 报修表

报修表的 status 字段要好好设计，我见过不少系统直接用一个布尔值表示"处理/未处理"，这样太简单了。实际上报修流程应该是：提交 -> 处理中 -> 已完成，三步流程。所以用字符串枚举更合理，也方便后续做状态筛选和统计。

3.3 可视化统计要用的"派生数据"

做好六张表之后，我们就可以反推可视化仪表盘需要哪些统计指标了。一眼看过去，至少有这几类图表可以做：

• 各楼栋入住人数柱状图：按 building 分组，统计每个楼栋的入住总人数。
• 男女生比例饼图：按 gender 分组统计学生数量，直观对比。
• 宿舍入住率进度条：每栋楼的已入住人数/总床位数，算一个百分比。
• 报修状态环形图：按 status 分组，看各状态工单数量。
• 近半年报修趋势折线图：按月统计报修数量，看出报修高峰时段。

这些指标的 SQL 查询其实都不难，关键是你在建表的时候就要想到它们。比如你要做"男女生比例饼图"，学生表里必须有 gender 字段；你要做"近半年报修趋势"，报修表里必须有 create_time 字段。看吧，这就是我前面说的——先想可视化需求，再反推表结构。

4. Flask 项目结构与核心功能实现

数据库设计好了，接下来就是搭项目框架、把功能一个个做出来。我第一次做 Flask 项目的时候踩过不少坑，尤其是项目结构一团乱麻，到后面自己都找不到代码在哪。下面这个结构是我试过多次之后觉得最舒服的一套，既不复杂又能清晰分离各个模块。

4.1 推荐的 Flask 项目目录

code复制dormitory_system/
├── app.py                  # 应用入口，创建 app、注册蓝图
├── models.py               # 数据库模型定义（所有表）
├── extensions.py           # 扩展库实例化（db、login_manager）
├── config.py               # 配置文件（数据库地址、密钥等）
├── requirements.txt        # 项目依赖
├── views/
│   ├── __init__.py
│   ├── auth.py             # 登录、登出、注册蓝图
│   ├── student.py          # 学生管理蓝图
│   ├── dorm.py             # 宿舍管理蓝图
│   ├── repair.py           # 报修管理蓝图
│   ├── inspection.py       # 卫生检查蓝图
│   └── stats.py            # 可视化统计蓝图
├── templates/
│   ├── base.html           # 公共模板（导航栏、侧边栏）
│   ├── login.html
│   ├── dashboard.html      # 可视化仪表盘页
│   ├── student_list.html
│   ├── dorm_list.html
│   ├── repair_list.html
│   └── ...
└── static/
    ├── css/
    ├── js/                 # echarts.min.js 等
    └── img/

为什么要按蓝图（Blueprint）来组织视图？核心原因是可以根据功能模块拆分代码，避免一个 app.py 写到几千行的悲剧。Flask 的蓝图功能就是干这个的，相当于把不同的功能模块拆成不同的"子应用"，最终在 app.py 里统一注册。

需要重点说明的是 extensions.py，这个文件是我后来踩坑才加的。如果你把 db = SQLAlchemy() 写在 app.py 里，models.py 又需要 import 这个 db，会出现循环引用的问题。把 db 单独放一个文件，两边都从 extensions.py 导入，问题就解决了。这也是 Flask 开发中非常经典的一个"坑解法"。

4.2 登录与权限控制：没有它系统就是个空壳

一个没有权限控制的宿舍管理系统是不完整的。如果是访客，谁都可以改数据，那这个系统就没有实际意义了。这里我们用 Flask-Login 扩展来管理用户会话，做角色权限控制。

首先在 models.py 里定义 User 模型，并让它继承 Flask-Login 的 UserMixin：

python复制from extensions import db, login_manager
from flask_login import UserMixin
from werkzeug.security import generate_password_hash, check_password_hash

class User(UserMixin, db.Model):
    __tablename__ = 'user'
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(50), unique=True, nullable=False)
    password_hash = db.Column(db.String(128), nullable=False)
    role = db.Column(db.String(20), nullable=False, default='student')  # admin/manager/student

    def set_password(self, password):
        self.password_hash = generate_password_hash(password)

    def check_password(self, password):
        return check_password_hash(self.password_hash, password)

登录路由的设计要兼顾两个功能：校验身份和维持会话。校验身份靠密码哈希比对，维持会话靠 Flask-Login 的 login_user 函数写 Session。这里有个细节我觉得值得提醒：一定要给密码设置哈希后再入库，否则数据库一旦泄露，用户的密码就全裸奔了，图一时方便会出大问题。

角色权限控制我一般用 Flask 的 before_request 钩子来实现。比如只有 admin 能进入 /admin/ 开头的路由，学生角色只能看到和自己相关的数据，宿管老师可以操作所有日常管理功能。这个逻辑不用写得很复杂，一个装饰器函数就搞定。

4.3 学生与宿舍管理：经典 CRUD 模块

任何管理系统都离不开增删改查，学生管理模块就是很典型的 CRUD。它的重点在于：列表要分页、查询要支持筛选、宿舍分配要联动宿舍表的容量处理。

新增学生的核心逻辑里有个很容易漏的点：分配宿舍时，宿舍的 current_count 要加 1，满了要置 is_full。反过来，学生退宿时，要减 1，把 is_full 改回 False。这两步操作必须和新增/删除学生放在同一个事务里，否则数据就对不上了。用 Flask-SQLAlchemy 的 db.session 可以保证事务的原子性：

python复制@student_bp.route('/add', methods=['POST'])
def add_student():
    data = request.form
    dorm = Dorm.query.get(data['dorm_id'])
    if dorm.is_full:
        flash('该宿舍已满，无法分配', 'danger')
        return redirect(url_for('student.list_students'))

    new_student = Student(
        student_no=data['student_no'],
        name=data['name'],
        gender=data['gender'],
        phone=data['phone'],
        dorm_id=dorm.id,
        check_in_date=datetime.now().date(),
        status='在住'
    )
    db.session.add(new_student)
    # 更新宿舍容量
    dorm.current_count += 1
    if dorm.current_count >= dorm.capacity:
        dorm.is_full = True
    db.session.commit()
    flash('添加成功', 'success')
    return redirect(url_for('student.list_students'))

这个例子可以说是整个系统的"操作标准模板"：先做业务校验（宿舍是否满员），再操作数据（新增学生），然后是联动更新（修改宿舍容量），最后统一提交事务。我见过很多错误写法是把 db.session.commit() 放循环里执行，不仅慢，而且一旦中途出错，数据库会处于不一致状态，这个习惯一定要改。

宿舍管理的 CRUD 相对简单，主要是楼栋和房间号的增删改查。我在这里还会加一个搜索功能——按楼栋、房间号筛选，方便管理很多宿舍时快速定位。搜索条件不复杂，就是在 query 后面加一个 filter_by 或 filter 即可。

4.4 报修流程与卫生检查：状态流转是个加分项

报修模块看起来也是 CRUD，但比学生管理的"纯增删改查"要多一点业务逻辑——状态流转。用户提交报修单后，宿管人员看到工单，先"接单"（把状态从待处理改为处理中），修好之后再"完成"（把状态改为已完成）。这个状态流转逻辑用 Flask 路由实现非常简单：

python复制@repair_bp.route('/<int:repair_id>/process', methods=['POST'])
def process(repair_id):
    repair = Repair.query.get_or_404(repair_id)
    repair.status = '处理中'
    db.session.commit()
    flash('已接单，请尽快处理', 'warning')
    return redirect(url_for('repair.list_repairs'))

卫生检查模块则要设计评分规则。我习惯用 0~100 分制，每次检查记录分数、检查人、备注。列表页会展示最近一次检查的结果，并给每间宿舍加一个"卫生等级"标签：90 分以上优秀，80 分以上良好，60 分以上及格，60 分以下待改进。这个等级判断逻辑我推荐写成一个函数，在列表页和详情页复用，避免重复代码。

5. 可视化大屏：让数据自己会说话

这个项目相比传统的"增删改查管理系统"，最大的亮点就是可视化。既然标题里特别强调了可视化，那这个部分就值得花大功夫做。我习惯把仪表盘放在登录后的首页，一进来就能看到整个宿舍管理的大盘数据，非常直观，也很有成品感。

5.1 可视化方案拆解：确定指标、梳理数据接口

做可视化第一件事不是写页面，而是确定"首页到底放几张图、每张图回答什么问题"。我给这个系统列了六个核心指标，对应首页的六块图表区域：

确定好指标之后，后端要做的就是把这些统计用 SQLAlchemy 写出来，封装成 JSON 接口。这一步是可视化模块的核心工作，我称之为"数据层开发"。每个接口只做一件事，返回标准格式的 JSON。比如各楼栋入住人数接口：

python复制@stats_bp.route('/api/dorm_occupancy')
def dorm_occupancy():
    # 按楼栋分组统计学生人数
    results = db.session.query(
        Dorm.building,
        func.count(Student.id).label('total')
    ).join(Student, Student.dorm_id == Dorm.id) \
     .filter(Student.status == '在住') \
     .group_by(Dorm.building).all()

    data = {
        'categories': [r.building for r in results],
        'values': [r.total for r in results]
    }
    return jsonify(data)

看到没，这就是一个典型的分组统计查询：query 指定要查哪张表哪些字段，join 关联学生表和宿舍表，group_by 按楼栋分组，func.count 统计人数。最后把结果包装成 categories（楼栋名）和 values（人数）两个数组，供前端用。

男生女生比例接口就更简单了，只需要对学生表做一次分组：

python复制@stats_bp.route('/api/gender_ratio')
def gender_ratio():
    results = db.session.query(
        Student.gender,
        func.count(Student.id).label('count')
    ).filter(Student.status == '在住') \
     .group_by(Student.gender).all()

    data = {
        'categories': ['男', '女'],
        'values': [0, 0]
    }
    for r in results:
        if r.gender == '男':
            data['values'][0] = r.count
        elif r.gender == '女':
            data['values'][1] = r.count
    return jsonify(data)

5.2 前端渲染：ECharts 与 Flask 模板的集成

后端接口准备好了，接下来就是前端。在 dashboard.html 模板中，我通过 fetch 从后端接口获取数据，然后调用 ECharts 渲染图表。关键代码示例：

html复制<div class="row">
    <div class="col-md-6">
        <div id="buildingChart" style="height:350px;"></div>
    </div>
    <div class="col-md-6">
        <div id="genderChart" style="height:350px;"></div>
    </div>
</div>

<script src="{{ url_for('static', filename='js/echarts.min.js') }}"></script>
<script>
    // 渲染柱状图：各楼栋入住人数
    fetch('/api/dorm_occupancy')
        .then(res => res.json())
        .then(data => {
            var chart = echarts.init(document.getElementById('buildingChart'));
            chart.setOption({
                title: { text: '各楼栋入住人数统计' },
                tooltip: {},
                xAxis: { data: data.categories },
                yAxis: {},
                series: [{
                    type: 'bar',
                    data: data.values,
                    itemStyle: { color: '#4a90d9' }
                }]
            });
        });

    // 渲染饼图：男女生比例
    fetch('/api/gender_ratio')
        .then(res => res.json())
        .then(data => {
            var chart = echarts.init(document.getElementById('genderChart'));
            chart.setOption({
                title: { text: '男女生比例' },
                tooltip: {},
                series: [{
                    type: 'pie',
                    data: [
                        { name: '男', value: data.values[0] },
                        { name: '女', value: data.values[1] }
                    ]
                }]
            });
        });

    // 窗口大小变化时让图表自适应
    window.addEventListener('resize', function() {
        var charts = echarts.getInstanceByDom(document.getElementById('buildingChart'));
        if (charts) charts.resize();
    });
</script>

这段代码的核心就两个动作：fetch 拿到后端数据，setOption 画图表。我强烈建议 ECharts 图表所在的 div 给一个固定高度，比如 style="height:350px;"，否则很多浏览器默认高度是 0，图表会显示不出来。这个坑我踩过好几次，页面渲染完一片空白，一查是容器高度为 0。

动态接口加前端渲染，就把可视化仪表盘做出来了。做这类页面有个很深的心得：图表不是越多越好，关键是每一张图都要回答一个具体的管理问题。住宿率说明"住满了没有"，报修趋势说明"最近维修压力大不大"，男女比例说明"这栋楼是男生楼还是女生楼"，这样的仪表盘才是合格的数据产品。

6. 实战记录：从零到可演示只花一下午

光看概念可能还是有点飘，我把整个项目从初始化到跑通核心功能的实操过程记录下来，按照真实的环境和时间节点走一遍，大家直接照着做就能复现出这个系统。

6.1 环境准备：Python 虚拟环境和依赖安装

第一步当然是把开发环境准备好。我建议用虚拟环境，把项目的依赖隔离起来，避免污染全局环境。具体操作：

bash复制mkdir dormitory_system
cd dormitory_system
python -m venv venv
# Windows 激活方式
venv\Scripts\activate
# Mac/Linux 激活方式
# source venv/bin/activate

pip install flask flask-sqlalchemy flask-login

如果你还没装 Python，先去官网下载安装包，注意安装的时候要勾选"Add Python to PATH"这个选项。然后验证版本：

bash复制python --version

这里我解释一下为什么用虚拟环境。Python 项目的依赖经常版本冲突，A 项目用 Flask 2.x，B 项目用 Flask 3.x，如果全部装到全局，会互相干扰到怀疑人生。虚拟环境相当于给每个项目单独开了一个"干净的房间"，里面装的东西互不影响，这是 Python 开发的基础素养，但很多教程都不讲。

依赖装完之后，把依赖列表导出来，方便别人一键复现环境：

bash复制pip freeze > requirements.txt

6.2 核心代码文件：搞定应用入口和模型

接下来是写代码。app.py 是整个应用的入口，也是把模型、蓝图和配置串起来的地方。我用一个相对简洁但不失完整性的写法：

python复制from flask import Flask, redirect, url_for
from extensions import db, login_manager
from config import Config

def create_app():
    app = Flask(__name__)
    app.config.from_object(Config)

    # 初始化扩展
    db.init_app(app)
    login_manager.init_app(app)
    login_manager.login_view = 'auth.login'

    # 注册蓝图
    from views.auth import auth_bp
    from views.student import student_bp
    from views.dorm import dorm_bp
    from views.repair import repair_bp
    from views.inspection import inspection_bp
    from views.stats import stats_bp

    app.register_blueprint(auth_bp)
    app.register_blueprint(student_bp)
    app.register_blueprint(dorm_bp)
    app.register_blueprint(repair_bp)
    app.register_blueprint(inspection_bp)
    app.register_blueprint(stats_bp)

    # 创建数据库表
    with app.app_context():
        db.create_all()

    return app

if __name__ == '__main__':
    app = create_app()
    app.run(debug=True, port=5000)

config.py 里是配置信息，最关键的是数据库连接和密钥：

python复制import os

class Config:
    SECRET_KEY = 'your-secret-key-change-in-production'
    SQLALCHEMY_DATABASE_URI = 'sqlite:///dormitory.db'
    SQLALCHEMY_TRACK_MODIFICATIONS = False
    # 如果要用 MySQL，把上面这行换成：
    # SQLALCHEMY_DATABASE_URI = 'mysql+pymysql://root:password@localhost/dormitory'

SECRET_KEY 一定要改掉，不要用默认值，否则 Session 安全方面会出问题。SQLALCHEMY_TRACK_MODIFICATIONS = False 是关闭 SQLAlchemy 的修改追踪，能让内存少费一点、性能好一些，建议加上。

6.3 初始化数据：没有数据的可视化就是空壳

系统跑起来之后，我发现数据库是空的，仪表盘上一片空白，什么图表都画不出来。这时候需要写一个初始化脚本，往数据库里塞上测试数据。我一般写成一个独立的脚本 seed_data.py，跑一遍就能填充所有表：

python复制from app import create_app
from extensions import db
from models import User, Dorm, Student, Repair, Inspection

app = create_app()

with app.app_context():
    # 创建管理员账号
    admin = User(username='admin', role='admin')
    admin.set_password('admin123')
    db.session.add(admin)

    # 创建 6 间宿舍
    dorms = [
        Dorm(building='1号楼', room_no='101', capacity=4),
        Dorm(building='1号楼', room_no='102', capacity=4),
        Dorm(building='2号楼', room_no='201', capacity=6),
        Dorm(building='2号楼', room_no='202', capacity=6),
    ]
    db.session.add_all(dorms)

    # 创建学生
    students = [
        Student(student_no='2024001', name='张三', gender='男', dorm_id=1),
        Student(student_no='2024002', name='李四', gender='男', dorm_id=1),
        Student(student_no='2024003', name='王五', gender='男', dorm_id=2),
        Student(student_no='2024004', name='赵六', gender='男', dorm_id=2),
    ]
    db.session.add_all(students)

    # 创建报修记录
    repairs = [
        Repair(dorm_id=1, description='空调不制冷'),
        Repair(dorm_id=2, description='水龙头漏水'),
        Repair(dorm_id=3, description='灯管坏了'),
    ]
    db.session.add_all(repairs)

    db.session.commit()
    print('初始化数据完成')

初始化脚本跑完之后，再登录系统，仪表盘上就有数据渲染了。这算是我自己的一个小习惯：涉及可视化的项目，一定会先准备一批像样的演示数据，否则界面再好看也是空壳。

6.4 JQuery 还是原生 fetch：选哪个都行但要保持一致

在写前端 Ajax 的时候，我遇到过一个问题：JQuery 的 $.ajax 在页面里用起来很方便，但如果页面同时又用了原生 fetch，代码风格会很乱，而且 JQuery 整个库引进来只为几个请求，太重了。我这里直接用浏览器原生 fetch，如果要引入第三方库，我只引入 ECharts 一个，这样页面加载效率最高。如果你更习惯用 JQuery，也不是不行，但我的建议是——不管选哪种，整个项目保持一致，不要让同一种操作有两种写法。

7. 常见问题与排查技巧实录

做这个项目的过程中，我陆陆续续遇到了一些问题，有环境问题，有代码问题，也有自己粗心踩的坑。我整理成一张速查表，并挑几个典型的详细说说排查思路，希望你看完能少走点弯路。

7.1 问题速查表

7.2 典型问题一：图表不显示的排查经验

图表区域一片空白是可视化模块最常遇到的问题，排查思路也相对固定。第一步按 F12 打开浏览器的开发者工具，看 Console 区域有没有报错，最常见的是 ECharts is not defined，那就是 JS 文件没加载进来，检查一下 static/js/echarts.min.js 的路径对不对，是不是把文件放错目录了。

如果没有报错，第二步看 Network 面板，检查 /api/dorm_occupancy 这个请求是否正常返回了 JSON 数据。如果接口返回 500，基本可以确定是后端查询写错了，把 SQLAlchemy 日志打开就能看到具体的报错信息。如果接口返回正常 JSON，那问题大概率出在 setOption 里的数据映射写错了，比如把 data.categories 写成了 data.cat，这种低级错误调试起来也挺费眼。

还有一种容易被忽略的情况：浏览器页面在 ECharts 渲染后，你把浏览器窗口从窄拉宽，图表不会自动适应，会留白。解决办法就是我在前面代码里写到的 window.addEventListener('resize', function() { ... }) 这个监听事件，ECharts 实例跟着 resize。

7.3 典型问题二：报修状态统计不准

有次我在演示系统的时候，发现报修状态环形图显示"待处理 10、处理中 0、已完成 20"，但点开报修列表发现明明有 3 条"处理中"的记录。这个问题的根源在于模拟数据里没造过"处理中"状态的记录，不是代码问题，是数据问题。

但排查的过程中我倒是养成了一个习惯：所有涉及统计的接口，我都会先在数据库里手动造几条不同状态的数据，再用 SQL 语句和接口返回对比一遍。你的系统如果统计数字老是跟列表对不上，十有八九是查询条件里漏了过滤条件，比如统计没加 status == '在住' 的过滤，把已退宿的人也数进去了，自然就对不上。

7.4 避坑心得：数据库迁移要趁早

最后一个我认为极其重要的经验是数据库迁移。开发过程中改模型是家常便饭，今天给表加个字段，明天改个字段名。db.create_all() 只会在表不存在时创建表，如果表已经存在，它不会自动加新字段。最直接的办法是删掉旧的数据库文件重建，但这样之前录入的测试数据就全没了。

正确的做法是尽早引入 Flask-Migrate 做数据库迁移管理。刚开始可能觉得多余，等到模型越改越多，测试数据越来越丰富的时候，迁移工具的价值就体现出来了。如果你现在才刚开始做这个项目，我强烈建议先把 Flask-Migrate 配置好，后面能帮你省下大量返工的时间。

坦白说，Linux 里面没有那么多完美的"一次到位"，开发也是一样，很多问题是踩了坑才知道怎么避免的。这个学生宿舍管理系统不算复杂，但把登录、CRUD、状态流转、可视化这几个核心能力做完，你基本就掌握了中小型 Web 业务系统的开发套路。把整套流程跑通之后，你再去看 Flask 源码、理解 SQLAlchemy 的会话管理，都会顺畅很多。练手项目嘛，最重要的就是在"做"里面把知识变成自己的东西。