宿舍楼里的灯管坏了、水龙头漏水、门锁失灵以前学生报修基本靠跑宿管值班室填一张纸质单子维修师傅能不能及时看到全靠运气。我最近把 python101 系列里这个高校学生宿舍报修系统完整落地了一遍服务端用 Python 写前端页面用 Vue3 搭前后端分离从学生提交报修到维修工接单、管理员派单、进度回填、学生确认评价整条链路都跑通了。很多人觉得这种系统不就是个增删改查吗真正把业务状态机、权限、图片上传、消息通知串起来之后会发现有一堆值得抠的细节。这篇就从头到尾拆一遍我的设计思路、接口实现和踩过的坑适合正在做 Vue3 或 Python 后端项目的同学参考。1. 项目整体设计与技术选型思路1.1 需求拆解报修业务里到底藏着哪些功能坑先说清楚这套系统在真实场景下要解决什么问题。高校宿舍报修的核心参与方有三类学生、维修工、宿管/后勤管理员。学生要能提交报修单、查看处理进度、确认维修结果维修工要能看到分给自己的工单、更新处理状态管理员要能管理楼栋信息、分配工单、查统计报表。如果只做一张表加三个页面那确实简单但真实业务远比这个复杂。比如一个报修单从提交到关闭中间要经历待审核、待接单、维修中、待确认、已完成、已取消、异常退回这么多状态再比如学生提交报修时可能要上传现场照片维修工接单后要填写维修结果管理员还要判断这个维修是否需要派给外包单位。状态一多字段一变单纯的增删改查很容易写成一团乱麻。我在设计功能模块时把整个业务分成五个块报修工单管理、楼栋宿舍管理、用户与权限管理、维修进度与日志、统计与评价。其中工单管理是核心其他模块都是为它服务的。工单表本身尽量只存订单主信息像状态变更记录单独建一张日志表这样以后要追溯“谁在什么时候改了什么状态”就非常方便不需要去翻代码猜逻辑。1.2 技术栈选型为什么锁定 Python 加 Vue3这套系统的后端我选的是 Python 生态。很多同学会纠结 Flask、Django、FastAPI 到底选哪个我的判断标准很简单项目规模、上手成本、后续扩展。Flask 太轻所有东西都要自己拼Django 自带 Admin 后台但重量级大对前端分离场景反而累赘FastAPI 有自动生成 Swagger 文档、Pydantic 数据校验、异步支持做纯 API 后端体验非常顺。最终我选了 FastAPI SQLAlchemy这个组合写起来快数据模型清晰接口文档还能直接给前端同学看。前端用 Vue3 是这两年非常主流的选择。Vue3 的 Composition API 在处理复杂表单、复用逻辑时比 Options API 舒服得多配合 Vite 开发服务器启动快、热更新也快。UI 组件库用的是 Element Plus表格、表单、弹窗、步骤条这些现成组件能省很多事。状态管理用 Pinia路由用 Vue Router 4请求用 axios 封装。这套组合基本是 Vue3 后台管理系统的标准答案社区资料多遇到问题随便搜都能找到解决方案。1.3 数据库设计先把表结构想清楚再动代码数据库是这类业务系统的地基。我一开始犯过一个错误想把所有状态变化都塞进报修单表的一个字段里后来发现一旦需要展示“时间线”就非常被动。正确做法是拆一张工单状态日志表每变更一次状态就插一条记录。核心表我设计了四张表名主要字段说明userid, username, password_hash, role, name, phone, dorm_info角色区分 student / repairer / adminbuildingid, name, address, manager_id楼栋信息管理员可维护repair_orderid, order_no, user_id, building_id, room_no, title, description, images, status, priority, assignee_id, created_at, updated_at报修工单主表repair_logid, order_id, operator_id, action, remark, created_at状态变更日志用于时间线展示在设计时注意几个细节密码字段一定存哈希不要明文图片不要直接存 base64 字符串进数据库存文件路径状态字段用字符串枚举而不是数字可读性更高order_no 建议用日期加序号生成方便线下沟通时对单。这些细节看着小真上线跑起来会节省大量沟通和排查成本。2. 后端核心设计与实现要点2.1 FastAPI 项目结构与数据库接入后端项目我按功能模块拆目录而不是按文件类型堆一起。功能模块拆法的好处是以后加新业务不用到处找代码在哪。我当时的目录结构大致是backend/ ├── app/ │ ├── main.py # 应用入口 │ ├── config.py # 配置项 │ ├── database.py # 数据库连接 │ ├── models/ # SQLAlchemy 模型 │ │ ├── user.py │ │ ├── building.py │ │ ├── repair_order.py │ │ └── repair_log.py │ ├── schemas/ # Pydantic 请求响应模型 │ ├── routers/ # 路由模块 │ │ ├── auth.py │ │ ├── order.py │ │ ├── user.py │ │ └── stats.py │ ├── services/ # 业务逻辑层 │ └── utils/ # 通用工具 └── requirements.txt数据库连接我用的 SQLAlchemy 2.0 风格底层用 PyMySQL 驱动连 MySQL。开发初期也可以先用 SQLite 顶一下等到需要部署再切 MySQL代码层面基本不用大改。配置上把数据库地址、JWT 密钥、文件上传路径都放到环境变量或 config 文件里别写死在代码里这是最基本的工程习惯。模型定义里有个小坑SQLAlchemy 模型和 Pydantic Schema 不要混用。查询出来的是 ORM 对象接口返回前要转成 Schema 或字典直接用模型序列化很容易把密码字段带出去。我用的方式是自定义一个序列化方法手动控制要返回哪些字段安全性高很多。2.2 接口设计状态机与权限控制怎么落报修系统最核心的接口是工单流转。后端不能只做简单的 CRUD要维护一套状态机逻辑。我的实现方式是每个状态都定义了“允许谁来改、改到什么状态”后端在更新前先做校验。举个例子维修工接单这个动作只有当前状态为“待接单”、操作人角色为 repairer 或 admin 时才能把状态改成“维修中”。学生提交后如果长时间没人接单管理员也可以手动指派。这些条件写在 service 层里路由只负责提取参数和返回结果。接口划分为三类公开接口登录、获取楼栋列表基础信息学生接口提交报修、查看自己的工单列表、确认完成、取消工单管理接口审核工单、指派维修工、查看全部工单、数据统计权限用 FastAPI 的依赖注入实现。每次请求先从 Header 里拿 Token解析出用户 ID 和角色再校验当前接口允许哪些角色访问。用户信息挂到 request.state 上后续业务逻辑随时可以取。这样后端每个接口都自带权限校验不会出现学生调管理员接口的情况。2.3 关键接口代码示例报修提交与状态流转报修提交接口的核心逻辑接收学生上传的文本和图片路径生成工单号把初始状态设为“待审核”同时写一条日志。代码大概是这样的router.post(/orders) def create_order( payload: OrderCreate, current_user: User Depends(get_current_user), db: Session Depends(get_db) ): if current_user.role ! student: raise HTTPException(status_code403, detail仅学生可提交报修) order_no generate_order_no() # 例: 202501071001 order RepairOrder( order_noorder_no, user_idcurrent_user.id, building_idpayload.building_id, room_nopayload.room_no, titlepayload.title, descriptionpayload.description, imagespayload.images, statuspending_audit, prioritypayload.priority, created_atdatetime.now() ) db.add(order) db.add(RepairLog(order_idorder.id, operator_idcurrent_user.id, actionsubmit, remark学生提交报修)) db.commit() return {code: 0, data: {order_no: order_no}}状态转换我更推荐写成一个独立服务函数全局所有接口只通过这个函数改状态。这样以后加状态或者改流程只需要动这一处。比如“接单”动作def transition_order(db, order, target_status, operator, remark): allowed { pending_audit: [approved, rejected, cancelled], pending_assign: [assigned, cancelled], assigned: [repairing, cancelled], repairing: [completed_pending_confirm, rejected], completed_pending_confirm: [finished, reopen] } if target_status not in allowed.get(order.status, []): raise HTTPException(status_code400, detail非法的状态流转) order.status target_status order.updated_at datetime.now() db.add(RepairLog(order_idorder.id, operator_idoperator.id, actiontarget_status, remarkremark)) db.commit()状态机写清楚之后前端就能很轻松地根据当前状态渲染操作按钮。比如状态是 assigned按钮就显示“开始维修”状态是 repairing按钮就变成“完成维修”逻辑完全对齐后端。3. 前端 Vue3 实现与交互细节3.1 Vite 工程搭建与前端目录规划前端我用 Vite 创建 Vue3 项目命令就一行npm create vitelatest frontend -- --template vue接着安装 Element Plus、Pinia、Vue Router、axiosnpm install element-plus pinia vue-router4 axios前端目录结构按“页面 视图 组件”的方式组织。views 下面分 student、repairer、admin 三个业务目录components 放通用组件api 目录按资源模块封装请求store 放 Pinia 状态。这样每个人负责自己角色范围内的页面代码不会互相打架。有一个细节我必须强调环境变量。开发环境和生产环境的接口地址不一样我在 .env.development 里写 VITE_API_BASE_URL生产环境在 .env.production 里写axios 封装里统一读取。千万别把接口地址写死在业务组件里否则部署时改地址能改到怀疑人生。3.2 Composition API 实战报修表单怎么写得既灵活又干净Vue3 里写表单Composition API 的体验比 Options API 好太多。报修表单的字段比较多楼栋、宿舍号、标题、描述、图片、优先级。如果全用 data 对象维护校验逻辑会很散我选择用 reactive 包一个 form 对象配合 Element Plus 的表单校验规则。图片上传这里值得多说几句。Element Plus 的 el-upload 默认上传行为是组件自己发请求但我在前后端分离场景下更习惯先拿到文件手动统一上传到后端再把返回的 URL 存进表单。这样做的好处是用户可以一次性选多张图、预览顺序可控、提交工单时图片 URL 一起提交避免部分图片已传、工单没提交成功造成的孤儿文件。script setup import { reactive, ref } from vue import { ElMessage } from element-plus import { uploadImage } from /api/file import { submitOrder } from /api/order const form reactive({ buildingId: , roomNo: , title: , description: , images: [], priority: low }) async function handleSubmit() { // 图片逐个上传拿到 URL 数组 const urls [] for (const file of form.images) { const res await uploadImage(file) urls.push(res.data.url) } await submitOrder({ ...form, images: urls }) ElMessage.success(报修提交成功) } /scriptComposition API 的优势在这里非常明显上传图片、组装数据、提交请求的逻辑可以直接写在 setup 里不用在 methods 和 data 之间来回跳。如果以后要把这段逻辑复用到别的地方抽成一个 useSubmitOrder 的组合式函数就行。3.3 状态管理与接口联调用 Pinia 把登录态和工单数据理清楚Pinia 比 Vuex 少了很多样板代码。我建了一个 auth store 和 order store。auth store 管理登录态登录成功后把 token 存到 localStoragestate 里维护用户信息和角色order store 负责当前页面对应的工单列表和筛选条件。接口联调时axios 封装里要统一做三件事请求头带上 token、响应里统一解包 code 和 data、遇到 401 自动跳登录页。这里有个容易忽略的细节Element Plus 的 message 组件在业务层手动弹提示就行但 axios 拦截器里不要到处弹错误否则会出现“接口报错弹一次、业务代码又弹一次”的重复提示。我的经验是拦截器里只处理 401 跳转和网络错误业务错误在调用处统一处理。登录态还有一个常见问题刷新页面后 Pinia 里的用户信息会丢。解决方法是刷新后从 localStorage 里读 token再调用一个 /auth/me 接口拉最新用户信息。启动时在 App.vue 或路由守卫里做一次初始化确保刷新后登录态不掉线。3.4 后台管理页面路由守卫与权限菜单管理端页面要区分学生、维修工、管理员三种身份。我的做法是路由配置里给每个页面标记 meta.roles路由守卫里读当前用户的角色做判断。无权限的用户跳转到一个 403 页面未登录跳登录页。菜单用动态渲染实现登录后根据角色从后端接口拿可访问的菜单列表前端渲染成侧边栏。这样以后要调整菜单权限改数据库配置就行不用每次发版改前端代码。4. 实操过程遇到的问题排查与经验总结4.1 高频问题实录整套系统做完我在联调和部署阶段遇到了不少问题挑几个有代表性的分享下。第一个是跨域问题。开发时前端跑在 5173 端口后端跑在 8000 端口直接 axios 请求必然跨域。我做了两层处理后端在 FastAPI 里挂 CORSMiddleware允许本机开发地址同时 Vite 配置 proxy 把 /api 前缀代理到后端地址。两层都配好之后开发和生产环境都能顺畅请求。第二个是图片上传后的访问路径问题。开发时 FastAPI 挂载了 StaticFiles上传的文件放在 uploads 目录访问 URL 直接拼 /uploads/xxx.jpg。但前端拿到的可能是相对路径跨域部署后就不对。我在后端返回图片 URL 时统一拼上配置好的域名前缀前端展示时不用再做转换。第三个是时间字段序列化问题。SQLAlchemy 查出来的 datetime 字段Pydantic 默认序列化成 ISO 字符串前端想按“2025-01-07 14:30”展示还得转换一遍。我在 Schema 层把时间统一格式化为字符串返回前端直接用少写不少处理代码。4.2 常见问题速查表问题现象可能原因解决方案登录后刷新页面退出token 未持久化localStorage 存 token启动时调 /auth/me 恢复用户图片上传成功但报修单里看不到图片 URL 未随工单提交上传和提交分开处理提交时携带返回的 URL 数组维修工接口提示 403角色判断写错或未加权限依赖检查路由装饰器与 get_current_user 的角色校验表单校验通过了但接口报错前后端字段命名不一致统一用 camelCase 或 snake_case前端做映射生产环境接口 404Nginx 未配置代理或 history 路由回退配置 location /api 反向代理try_files 指向 index.html状态流转操作无反应前端按钮与后端状态机不一致前端根据订单状态动态渲染按钮不写死操作4.3 避坑技巧与优化建议根据我的实际经验这种管理系统有几个地方值得提前规划。第一别为了省事把状态字段塞一个字符串里满天飞。状态机写在后端 service 层前端只渲染状态对应文案和按钮。调试的时候只需要盯着 repair_log 表整个工单生命周期一目了然。第二图片上传一定要限制大小和类型。Element Plus 的 before-upload 钩子里做一次校验后端再用 python 端校验文件扩展名和文件头双重保险。不校验会吃大亏之前测试时上传了个很大的视频文件直接把后端内存干爆了。第三报修单的 order_no 要全局唯一且最好让人能一眼看出是哪天的单子。我的格式是年月日加当天序号比如 20250107001虽然简单但非常好用线下沟通时说“20250107001那单”双方都知道是哪天的事。第四Vue3 项目里能用计算属性就别在模板里写复杂表达式。工单列表的状态文案、时间显示、操作按钮可见性全部用 computed 封装好模板保持干净维护起来省心太多。这套系统从前端页面到后端接口从数据库表到权限控制完整跑下来之后我对前后端分离项目的理解比之前零散写 demo 要深刻得多。说实话宿舍报修系统本身不算多高深的技术项目但正因为业务链路完整它把权限、状态、文件存储、接口设计这些后台管理系统最常遇到的坑都逼着你踩一遍。如果你也在写类似的 Vue3 或 Python 后端项目我建议先把状态流转图和数据表关系画清楚再动手写代码。表结构一旦定了后面改起来成本特别高状态机一旦理清楚前后端联调的效率会提升非常多。最后再分享一个小技巧开发这类系统时把 repair_log 这类日志表的写入逻辑从业务代码里彻底抽出来所有状态变更都走统一函数。这套系统我做完之后有一次学生反馈维修完成后想重新报修我只需要给状态机加一条 reopen 流转路径顺手把前端按钮和文案同步改掉十分钟就完成了不用动任何业务逻辑。这就是把状态和操作分离设计带来的实际收益。