宿舍水龙头坏了，报修单填了三遍还没人管；教学楼灯管闪了一个月，后勤办公室却以为没人报修过——这种场景在高校里太常见了。我当初做这个基于Django的高校后勤报修信息管理系统，就是因为在某高校信息中心实习时，亲眼看着后勤处老师用Excel登记几百条报修记录，漏单、重复单、超时单全靠人肉比对。这个项目本质上不是一个"CRUD管理系统"那么简单，它要把线下零散、口头的报修流程，整理成一整套可跟踪、可统计、可考核的线上闭环。适合正在学Django想做实战项目的同学，也适合高校后勤信息化改造的参考实现。这篇文章我会把从需求分析、数据库设计、核心功能实现到部署避坑的完整过程写出来，全程拿这个项目说话。
1. 为什么高校后勤需要一套独立的报修管理系统
1.1 从一张纸质报修单说起
先还原一下传统高校的报修场景。学生在宿舍楼下宿管处领一张纸质报修单，填写房间号、故障描述，然后宿管打电话给后勤维修组，维修工再拿单子去现场。运气好的当天能解决，运气不好这张单子就被压在文件夹里，一压就是一两周。更麻烦的是，报修人对维修质量不满，没有任何反馈渠道；后勤处长想统计"哪栋楼的故障最多"，只能让人翻纸质档案。
我调研过几个学校，发现即使有线上系统的，也多半是用腾讯问卷、微信接龙，信息进了后台还是得靠人工整理微信聊天记录。这就是典型的信息管理真空带：报修入口五花八门，状态全靠问，数据全靠猜。
1.2 高校后勤报修的三个核心痛点
做这个系统之前，我把痛点归结成三条，这三条直接决定了系统功能设计：
- 入口不统一：学生不知道该找宿管、打电话还是发邮件，导致漏报和重复报修并存。
- 过程不透明：学生不知道单子卡在哪个环节，只能反复追问；维修工不知道下一个任务是什么，全靠后勤统一调度，调度员本身也是信息中转站。
- 结果不可考核：维修是否及时、同一故障是否反复发生、哪个维修团队响应慢，完全没有数据支撑。
如果只是做一个"报修登记表"，那网上开个问卷就行，用不着专门开发一套Django系统。真正的价值在于：把流程固化下来，让每个角色在正确的时间看到正确的数据。
1.3 技术选型：为什么是Django而不是Flask或FastAPI
我在学院里用Flask写过不少小工具，但一到这种涉及多角色、多状态、带权限管理的系统，Flask需要自己搭的组件太多了——用户认证、Admin管理后台、ORM、表单校验，全部从零拼装虽然灵活，但周期长，而且容易漏掉安全细节。
对比一下当时考虑的三个框架：
| 框架 | 适合场景 | 对管理类系统的短板 |
|---|---|---|
| Flask | 轻量API、微服务、小工具 | 需要自己集成Admin、ORM、认证，项目一复杂维护成本高 |
| FastAPI | 高并发API、异步场景 | 生态偏API优先，Admin后台要靠第三方，Django模板+表单体系用不上 |
| Django | 数据模型复杂、后台管理需求多的业务系统 | 异步支持相对弱，但报修系统并发量不高，根本用不到 |
Django自带Admin后台，这在这个项目里帮了大忙。后勤处的老师不习惯用命令行，也不愿意记一堆表格操作，但Django Admin只要做好字段展示配置，他们直接在浏览器里就能筛选、导出、修改工单状态，上手成本几乎为零。再加上自带的用户认证体系、ORM、表单验证、CSRF防护，天然适合这种"数据重、流程长、权限分角色"的管理系统。
2. 需求拆解与数据库模型设计
2.1 角色与权限的梳理
系统上线前首先要搞清有多少种人会用这套系统。这个项目里一共四类角色：
- 学生/教职工（报修人）：提交报修、查看进度、对完工工单评价。
- 宿管/楼栋管理员：代报修、核对本楼栋报修单。
- 维修工：查看派给自己的任务、更新维修状态、填写维修结果。
- 后勤管理员：受理报修、分派维修工、查看报表、管理楼栋和人员信息。
这些角色在系统里对应Django的Group或UserProfile里的role字段。我没有用Django自带的Group做权限，而是直接给User模型加了一个role字段，因为角色之间是互斥的，不存在一个用户同时是学生又是维修工的场景。权限控制则在视图中用装饰器和mixin做校验。
设计经验：角色"互斥"时用字段比用Group简单；角色"组合"时（比如一个人既管维修又管评审）才适合用Group+Permission。
2.2 核心数据模型：校区、楼栋、报修单、维修记录
数据库设计是整个系统的地基，这一步错了后面返工成本很高。我的models.py核心部分长这样：
from django.db import models from django.contrib.auth.models import AbstractUser from django.utils import timezone class User(AbstractUser): ROLE_CHOICES = ( ('student', '报修人'), ('dorm_manager', '宿管'), ('repairman', '维修工'), ('admin', '后勤管理员'), ) role = models.CharField(max_length=20, choices=ROLE_CHOICES, default='student') phone = models.CharField(max_length=20, blank=True) # 报修人所属宿舍楼，维修工所属班组可按需扩展 building = models.ForeignKey('repair.Building', null=True, blank=True, on_delete=models.SET_NULL) class Building(models.Model): name = models.CharField(max_length=100) # 如"5号学生公寓" area = models.CharField(max_length=50) # 校区/区域 manager = models.ForeignKey(User, null=True, blank=True, on_delete=models.SET_NULL) class RepairOrder(models.Model): STATUS_CHOICES = ( ('pending', '待受理'), ('assigned', '待维修'), ('repairing', '维修中'), ('finished', '待验收'), ('completed', '已完成'), ('cancelled', '已取消'), ('timeout', '已超时'), ) title = models.CharField(max_length=200) description = models.TextField() reporter = models.ForeignKey(User, on_delete=models.CASCADE, related_name='repair_orders') building = models.ForeignKey(Building, on_delete=models.SET_NULL, null=True) room = models.CharField(max_length=50) repairman = models.ForeignKey(User, on_delete=models.SET_NULL, null=True, blank=True, related_name='assigned_orders') status = models.CharField(max_length=20, choices=STATUS_CHOICES, default='pending') created_at = models.DateTimeField(auto_now_add=True) assigned_at = models.DateTimeField(null=True, blank=True) finished_at = models.DateTimeField(null=True, blank=True) images = models.JSONField(default=list, blank=True) # 上传故障照片的URL列表这里有几个设计细节值得说明。images字段直接用了JSONField，报修人上传的照片路径存成一个列表，这样不用额外建一张图片表，对这个体量的项目足够。RepairOrder的reporter和repairman都是外键指向User，但用related_name区分了反向查询名，避免冲突。
2.3 状态机的设计与流转规则
报修单的核心不是字段多少，而是状态流转规则。这套系统里状态一共七种，流转路径是：
- 学生提交后状态为
pending（待受理） - 后勤管理员受理并分派维修工，变为
assigned（待维修） - 维修工接单开始维修，变为
repairing（维修中） - 维修工填写完工说明，变为
finished（待验收） - 报修人验收通过，变为
completed（已完成） - 报修人验收不通过，退回
assigned（待维修，重新分派） - 管理员取消或超时未处理的单子，分别变为
cancelled和timeout
状态迁移我会在视图层统一校验，而不是让每个视图随便改。写了一个状态转移表：
ALLOWED_TRANSITIONS = { 'pending': ['assigned', 'cancelled'], 'assigned': ['repairing', 'cancelled', 'timeout'], 'repairing': ['finished'], 'finished': ['completed', 'assigned'], 'timeout': ['assigned', 'cancelled'], }每次状态更新时检查当前状态和目标状态是否在表里，不合法就直接拒绝。这比"前端控制按钮显示"靠谱得多，因为后端的校验才是真正卡口的。
注意：不要把状态流转规则全写死在视图里，后期加"转派"、"改期"这些操作时，状态表式的设计会帮你省掉一大半改代码的时间。
3. Django开发实战：核心功能落地
3.1 项目初始化与app划分
我习惯把一个完整的Django项目按业务域拆成多个app，而不是全塞进一个app里。这个项目分成了三个app：
accounts：用户、角色、登录注册building：校区、楼栋、房间基础数据repair：报修单核心业务（提交、分派、维修、验收、统计）
拆分app最大的好处是模型和视图的边界清晰，后期新增功能时（比如加上备件仓库管理），新建一个sparepartmentapp就行，不用动老代码。
初始化命令很简单：
django-admin startproject estate_repair . python manage.py startapp accounts python manage.py startapp building python manage.py startapp repair记得在settings.py的INSTALLED_APPS里注册这三个app，然后把AUTH_USER_MODEL指向自定义用户类：
AUTH_USER_MODEL = 'accounts.User'3.2 自定义用户模型与登录认证
AbstractUser继承之后，默认的username字段我保留作为学号/工号。登录页用Django自带的LoginView改模板就能用，没有自己造轮子。
# accounts/views.py from django.contrib.auth.views import LoginView class CustomLoginView(LoginView): template_name = 'accounts/login.html' redirect_authenticated_user = True注册功能稍微处理一下，因为不同角色的注册方式不同：学生用学号注册，维修工由管理员后台创建账号，不在前台开放注册。所以系统里前台只开放学生注册，其他角色都在Django Admin里由后勤管理员创建。
3.3 报修工单的提交、受理与分派
提交报修这一块，我用Django Form做校验，而不是直接手写HTML表单。好处是后端校验和错误回显都是现成的。
# repair/forms.py class RepairCreateForm(forms.ModelForm): class Meta: model = RepairOrder fields = ['title', 'description', 'building', 'room', 'images']提交后创建一个pending状态的报修单，然后立刻通知后勤管理员："有新报修单待受理"。这里用到Django的信号（Signal）机制，在RepairOrder创建后发送通知。
# repair/signals.py from django.db.models.signals import post_save from django.dispatch import receiver @receiver(post_save, sender=RepairOrder) def order_created_notify(sender, instance, created, **kwargs): if created: # 给所有后勤管理员发站内信 admins = User.objects.filter(role='admin', is_active=True) Notification.objects.bulk_create([ Notification(user=admin, content=f'新报修单：{instance.title}') for admin in admins ])3.4 Django ORM中查询与删除对象的关键细节
这个项目里用得最多的就是QuerySet操作，其中"查询"和"删除"是新手翻车高发区。先说查询。
Django ORM的查询是惰性的，filter返回QuerySet，真正执行SQL是在你迭代、取值或调用len()时。拿到报修单列表时，如果每一条都要显示报修人的姓名和楼栋名称，直接用RepairOrder.objects.all()会导致N+1查询——1条主查询，N条外键查询。解决办法是select_related（适用于外键）和prefetch_related（适用于多对多和反向外键）：
orders = RepairOrder.objects.filter(status='pending').select_related('reporter', 'building', 'repairman')这样一次查询就把关联对象全部join出来，列表页快很多。
再说删除。这个项目里我几乎没有用过delete()方法。报修单删除会产生连锁问题：如果直接RepairOrder.objects.get(id=1).delete()，关联的Notification记录会因为外键on_delete=models.CASCADE一起被删掉，这会让用户已经读过的通知突然消失。我的做法是给模型加一个is_active布尔字段，删除操作更新为：
RepairOrder.objects.filter(id=order_id).update(is_active=False)也就是"软删除"。查询列表时默认再加一个.filter(is_active=True)。
Django的
delete()还有一个坑：它在QuerySet批量调用时是分批执行的，不会触发每个对象自定义的delete()方法，除非你重写模型层的delete()。所以对有关联数据、有日志需求的场景，提前做软删除比依赖on_delete行为安全得多。
4. 关键功能实现：自动分派、通知与会话保持
4.1 维修工自动分派的逻辑与实现
报修单受理后，需要一个维修工去现场。这个"分派"操作在实操中有两种模式，一种是管理员手动指派，一种是根据规则自动分派。我做了自动分派，规则很简单：在所有当前未完工单最少的维修工里随机抽一个。
这个用ORM的annotate加Count就能算出来：
from django.db.models import Count def auto_assign(repairman_queryset): # 统计每个维修工目前手上还没完成的工单数量 qs = repairman_queryset.annotate( active_count=Count( 'assigned_orders', filter=Q(assigned_orders__status__in=['assigned', 'repairing']) ) ).order_by('active_count', 'id') candidate = qs[:1].first() return candidate自动分派不是炫技，是要解决"人工分派"在高峰期的瓶颈。报修高峰期（比如刚开学）一天几十单，管理员一个个指派手都麻了。这个规则的核心不是"最优解"，而是"够用且公平"——每个维修工手上的量基本均衡。
4.2 通知机制：站内信+页面轮询
报修人和维修工之间需要实时沟通进度。我没有上WebSocket，因为对这个项目来说性价比太低。我用的是站内信通知 + 前端定时轮询。
通知模型长这样：
class Notification(models.Model): user = models.ForeignKey(User, on_delete=models.CASCADE, related_name='notifications') content = models.CharField(max_length=255) is_read = models.BooleanField(default=False) created_at = models.DateTimeField(auto_now_add=True)前端每隔30秒请求一次未读通知数量，数字变了就提示用户刷新。用Django模板渲染的视图返回JSON：
# repair/views.py from django.http import JsonResponse def unread_count(request): count = Notification.objects.filter(user=request.user, is_read=False).count() return JsonResponse({'count': count})轮询虽然不如WebSocket"实时"，但胜在稳定、简单、不占资源。一台服务器跑几千学生同时在线，30秒一次轮询完全扛得住。
4.3 报修统计看板：用annotate搞定展示数据
后勤老大最关心什么？"上周报修了多少单""哪个楼栋报修最多""维修平均时长多少"。这些统计Django ORM都能一行查询出来。
按楼栋统计报修数量：
from django.db.models import Count from django.db.models.functions import TruncDate stats = (RepairOrder.objects .filter(is_active=True) .values('building__name') .annotate(total=Count('id')) .order_by('-total'))按天统计最近30天趋势：
daily = (RepairOrder.objects .filter(created_at__gte=timezone.now() - timezone.timedelta(days=30)) .annotate(day=TruncDate('created_at')) .values('day') .annotate(count=Count('id')))如果是"维修平均时长"，就用F表达式算两个时间字段的差：
from django.db.models import F, Avg avg_hours = (RepairOrder.objects .filter(finished_at__isnull=False) .annotate(duration=F('finished_at') - F('assigned_at')) .aggregate(avg=Avg('duration')))统计报表这一块，我强烈建议把查询逻辑单独放在services.py里，不要堆在views中。因为报表SQL会越来越复杂，单独抽出来可读性高而且方便写单元测试。
5. 部署上线与性能优化
5.1 开发与生产环境的settings拆分
项目一开始我在开发环境用python manage.py runserver，数据库是SQLite。真正上线时，数据库换成了MySQL，静态文件交给Nginx，DEBUG必须关闭。我直接切成三个settings文件：
settings/base.py：公共配置settings/dev.py：开发配置，DEBUG=True，SQLitesettings/prod.py：生产配置，DEBUG=False，MySQL，安全项全部收紧
运行方式为了省事，我是通过环境变量控制：
DJANGO_SETTINGS_MODULE=estate_repair.settings.prod python manage.py runserver5.2 数据库选型与迁移注意
生产环境用了MySQL，这里有一个特别常见的坑：中文乱码。建库时一定要指定utf8mb4字符集：
CREATE DATABASE estate_repair CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;如果建库时用了latin1，改起来就麻烦了。Django连接配置里也要带上选项：
DATABASES = { 'default': { 'ENGINE': 'django.db.backends.mysql', 'NAME': 'estate_repair', 'USER': 'repair_user', 'PASSWORD': 'xxx', 'HOST': '127.0.0.1', 'PORT': '3306', 'OPTIONS': {'charset': 'utf8mb4'}, } }模型改完后一定要执行：
python manage.py makemigrations python manage.py migrate5.3 安全加固清单
Django安全配置不能只靠框架默认值。我上线前检查了这几项：
DEBUG = False，否则出错会弹出含服务器路径的调试页ALLOWED_HOSTS = ['repair.example.edu.cn']，不写*- 开启HTTPS，配置
SECURE_SSL_REDIRECT = True - 设置
SESSION_COOKIE_SECURE = True和CSRF_COOKIE_SECURE = True - 上传报修图片前校验扩展名和文件大小
在验证上传文件时，我写了一个校验函数：
def validate_upload_image(image): ext = os.path.splitext(image.name)[1].lower() if ext not in ['.jpg', '.png', '.jpeg', '.webp']: raise ValidationError('仅支持图片格式') if image.size > 5 * 1024 * 1024: # 5MB raise ValidationError('图片大小不能超过5MB')提醒一句：只校验扩展名是不够的，图片内容可能被伪装成jpg的脚本。更严谨的做法是用Pillow库真正打开图片，如果抛错就拒绝上传。
5.4 静态文件与媒体文件的处理
Django开发环境能直接runserver带静态文件，生产环境必须把静态文件和上传图片分开处理。我用collectstatic收集静态文件，上传的图片统一存到/data/media/repair_images/，Nginx处理媒体文件的读写。Django的MEDIA_ROOT和MEDIA_URL配置好之后，视图里返回图片路径，前端用{{ order.images.0 | default:'' }}显示。
6. 实战中踩过的坑与处理经验
6.1 ORM的N+1查询问题：列表页越写越慢
第一次做完报修列表页，数据不到一千条就开始卡。问题就是把所有报修单列出来，每条都要查一次报修人姓名、楼栋名称。后来用select_related一次性搞定外键关联查询，列表接口响应时间从2秒降到了300毫秒左右。经验是：写列表页之前先想清楚要展示哪些关联字段，然后主动在QuerySet里加上select_related或prefetch_related。
6.2 TimeZone与统计口径不一致
Django默认USE_TZ=True时，存储到数据库的时间是UTC时间，展示给用户时要转成北京时间。我在统计"今天报修了几单"时，直接用timezone.now().date()去filter，结果因为UTC和北京时间差了8小时，凌晨时段的数据统计错位。处理方式是在查询前先转成当地时区：
from django.utils import timezone from zoneinfo import ZoneInfo local_now = timezone.now().astimezone(ZoneInfo('Asia/Shanghai')) orders_today = RepairOrder.objects.filter(created_at__date=local_now.date())或者更稳妥的方式是直接按UTC日期范围过滤，因为created_at在数据库里就是UTC，按本地日期换算成UTC起止点再过滤。后者索引利用率更高。
6.3 并发提交与事务问题
报修高峰期，两个管理员同时受理同一张单子，就可能出现"都分派了不同的维修工"的情况。Django ORM默认每一条SQL单独提交，不开启事务。解决办法是在分派逻辑上用select_for_update加行锁：
from django.db import transaction with transaction.atomic(): order = RepairOrder.objects.select_for_update().get(id=order_id) if order.status != 'pending': return JsonResponse({'code': 1, 'msg': '该工单已被受理'}) order.status = 'assigned' order.repairman = assign_worker() order.save()加了行锁之后，同一时刻只能有一个请求能读到pending状态的工单并修改它。这在一个工单只能被分派一次的业务里非常关键。
6.4 外键删除策略引发的数据"蒸发"
前面说到我做了软删除，但即便做了软删除，外键的on_delete策略如果设置不当，还是会导致"关联数据蒸发"。比如RepairOrder的reporter是外键指向User，一旦某个人离职、账号被删，他的所有报修单按照默认PROTECT或CASCADE策略都会出问题。报修单作为业务数据，原则上永远不该因为用户账号删除而消失，也不该被硬删。所以这里的on_delete=models.SET_NULL配合null=True是对的选择——用户没了，报修单还在，至少还能追溯历史记录。
设计外键时我问自己一句话：这条数据删了，依赖它的数据还有存在价值吗？有价值就
SET_NULL，没价值就CASCADE，不确定就PROTECT（先防止误删）。
6.5 Django Admin的定制，后勤老师也能直接上手
系统上线后，后勤管理员最常用的其实不是前端页面，而是Django Admin。我把Admin配置得尽可能"傻瓜化"，把列表筛选、搜索、导出都配好。尤其卡在状态的流转上，我在Admin里用list_editable直接修改状态和维修工，后勤老师的实际体验是"点开列表，下拉框选一下，保存，就完事了"。这个部分几乎不用写额外代码，但能决定这个系统好不好用。
# repair/admin.py @admin.register(RepairOrder) class RepairOrderAdmin(admin.ModelAdmin): list_display = ('id', 'title', 'building', 'room', 'status', 'repairman', 'created_at') list_filter = ('status', 'building__name') search_fields = ('title', 'description', 'room') list_editable = ('status', 'repairman') list_per_page = 20list_editable是我要特别安利的一个配置，它把"编辑状态"这个高频操作直接内联到列表页，不用点进详情再点保存。这让管理员的鼠标点击次数减少了三分之二。
后续还能怎么扩展
这个项目跑起来之后，我列了几个可以继续深入的方向，供做同类系统的同学参考：一是加上备件库存管理，维修工在工单里关联消耗的材料，后勤能统计每月耗材成本；二是加上地图定位，把报修位置标记到校园地图上，分派时按距离优先；三是把通知从轮询换成WebSocket，真正实现"有新单马上弹窗"。
我个人在实际部署中最深的体会是：管理系统类项目的成败，往往不在技术难点，而在流程理解和细节体验。你用的框架是Django还是别的其实不重要，重要的是你能不能让宿管阿姨少点几下鼠标、让维修工少跑几趟冤枉路、让处长一眼看出问题楼栋。把这三点做好，这个系统才算真正落地。
