Work / Case 01

寝修宝:
用 Flask + uni-app 把宿舍报修搬上线

毕业设计做的系统,也是我唯一一个从需求走到部署的完整项目。 四类角色、五种状态的工单机、三张表、二十二个接口、十个页面。 论文里写了六章,这里只讲代码和取舍 —— 包括三处我后来知道做错了的地方。

Role独立开发(前端 + 后端)
Timeline2026 · 毕业设计
Scope学院规模 · 4 类角色
Stackuni-app · Vue · Flask · MySQL

01 / 起点

不是缺一个表单,是缺「谁在什么状态」

起因很具体:我自己宿舍的水龙头漏了两周没人来修。去问宿管,她说「报了呀,可能在排队」; 去问维修师傅,他说「没看到这个单子」。

我先去值班室看了两天他们实际怎么处理报修,记下四件事:

  • 报修走微信群,消息几小时就被刷走,宿管靠翻聊天记录找
  • 宿管用纸质本子登记,字迹和楼号经常对不上
  • 维修师傅一天来值班室抄一次单子,当天报的当天基本修不上
  • 学生唯一能做的就是再问一遍,没有人知道进度

这四条对应论文里归纳的四个问题:信息不完整、责任不清晰、进度不透明、数据难统计。 前两个靠结构化表单解决,后两个只能靠状态流转 —— 所以系统的核心不是报修表单, 而是「一张工单现在归谁、还能做什么」。

02 / 角色

四类角色,一套界面

常见的做法是只分「学生」和「管理员」两种人。但真实的报修链路里, 宿管负责派单、维修工负责接单和完工,两者能看到的工单范围与能做的操作完全不同。 所以我把使用者拆成四类,用 0–3 的整数编码:

角色与权限 / t_user.roleTINYINT
role 名称    核心职责                主要操作
────────────────────────────────────────────────────────────
 0   学生    提交报修、跟踪进度      提交 · 查看本人工单 · 催单 · 取消 · 评价 · 订水
 1   维修工  接单与现场维修          查看待办 · 开始处理 · 填写备注并完工 · 配送
 2   宿管员  工单调度与进度跟踪      查看全部工单 · 检索 · 指派维修工 · 看统计
 3   管理员  全局管理与数据分析      工单增删查 · 用户管理 · 看板 · 导出 Excel

用整数而不是字符串,一是省空间,二是查询时可以直接用 role >= 1 判断「是不是管理类角色」,不用维护一张枚举表。

权限分成两层:客户端控制体验,服务端控制数据。 前端在页面里按角色隐藏按钮,这只解决好不好用; 真正的数据范围过滤在服务端 —— 学生请求工单列表时按 user_id 过滤, 另外三类角色才返回全量。因为隐藏按钮拦不住任何人直接构造请求。

十个页面支撑四类角色,靠的是同一套模板加条件渲染,比起为每个角色写一套界面, 代码量少了大约六成。

03 / 状态机

五种状态,四条规则

一开始我想做成「谁都能改状态」,跟宿管聊完发现不行:她需要知道这单是不是经她派的, 师傅需要知道这单是不是派给自己的。于是把流程收敛成五个状态, 并把「什么状态允许什么操作」写成硬规则。

工单状态流转 / 5 states · 4 rulest_repair_order.status
学生提交
  │
  ▼
[ 0 待处理 ] ── 学生取消(仅此状态)──▶ [ 4 已取消 ] · 终态
  │
  │ 维修工接单 / 宿管指派
  ▼
[ 1 处理中 ]
  │
  │ 填写处理备注并完工
  ▼
[ 2 已完成 ]
  │
  │ 学生评分 + 文字评价
  ▼
[ 3 已评价 ] · 终态

旁路:催单不改变状态,只在 0 / 1 阶段累加 urge_count

四条规则:正向流转(0→1→2→3,每步由特定角色触发)、 取消(只有待处理能取消,师傅一旦投入工时就不允许单方面终止)、 终态约束(已评价与已取消不再接受任何变更)、 旁路操作(催单只累加次数,可以在待处理与处理中反复执行)。

状态判断全部写在服务端。这是我从这个项目里得到的最实在的一条经验:

app/blueprints/order.py — 接单Flask
# 维修工接单:状态 0 -> 1,记录处理人与接单时间
@order_bp.route('/start/<int:order_id>', methods=['POST'])
def start_order(order_id):
    order = db.session.get(RepairOrder, order_id)
    if order is None:
        return jsonify(code=404, msg='工单不存在', data=None)
    # 关键:不信任前端传来的状态,只认库里的 status
    if order.status != 0:
        return jsonify(code=400, msg='该工单已被接单或已取消', data=None)

    payload = request.get_json(silent=True) or {}
    order.status = 1
    order.handler_name = payload.get('handler_name') or '维修师傅'
    order.start_time = datetime.now()
    db.session.commit()
    return jsonify(code=200, msg='已接单', data=order.to_dict())

对已完成的工单再调一次这个接口,会返回 400 而不是把状态改回去 —— 这条在测试用例 TC08「重复接单」里专门验过。

04 / 数据表

三张表,两个刻意的取舍

系统只有三张表:用户表、报修工单表、送水订单表。工单表是全系统的数据核心, 有两个地方是我想过之后才这么写的。

取舍一:学生姓名冗余存一份

严格来说 student_name 是冗余字段,正确做法是每次关联用户表查。 但工单列表要同时显示故障描述、房间位置和学生姓名,每次都 JOIN 一次用户表, 数据量上来后损耗明显;而学生改名是极低频事件,不一致的风险很低。 所以这里选择以空间换时间 —— 这是权衡,不是疏忽。

t_repair_order(节选)MySQL 8.0 · InnoDB · utf8mb4
CREATE TABLE t_repair_order (
  id            INT AUTO_INCREMENT PRIMARY KEY COMMENT '工单标识',
  order_no      VARCHAR(32)  NOT NULL COMMENT '工单编号',
  user_id       INT          NOT NULL COMMENT '提交人标识',
  student_name  VARCHAR(32)  NOT NULL COMMENT '学生姓名(冗余)',
  dorm_building VARCHAR(32)  NOT NULL COMMENT '楼栋',
  dorm_room     VARCHAR(16)  NOT NULL COMMENT '寝室号',
  description   VARCHAR(255) NOT NULL COMMENT '故障描述',
  images        VARCHAR(512) DEFAULT NULL COMMENT '照片路径,逗号分隔',
  -- 状态:0 待处理 / 1 处理中 / 2 已完成 / 3 已评价 / 4 已取消
  status        TINYINT      NOT NULL DEFAULT 0 COMMENT '工单状态',
  handler_name  VARCHAR(32)  DEFAULT NULL COMMENT '处理人',
  urge_count    INT          NOT NULL DEFAULT 0 COMMENT '催单次数',
  rating        TINYINT      DEFAULT NULL COMMENT '评分 1-5',
  submit_time   DATETIME     NOT NULL COMMENT '提交时间',
  start_time    DATETIME     DEFAULT NULL COMMENT '接单时间',
  finish_time   DATETIME     DEFAULT NULL COMMENT '完工时间',
  confirm_time  DATETIME     DEFAULT NULL COMMENT '评价时间'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

取舍二:四个时间字段,不是一个更新时间

最省事的做法是只留一个 update_time。我留了提交、接单、完工、评价四个时间戳, 因为详情页的时间线要按节点展示,而且后面想算「平均接单时长」「平均完工时长」 必须要有分节点的时间。现在这四条数据已经存在库里,只是还没做分析 —— 这是论文第 7 章写的下一步。

工单表在 user_id、status、submit_time 三个字段上建了索引, 分别对应「按人查」「按状态筛」「按时间排序」三类查询。

05 / 接口

二十二个接口,两条约定

接口按业务域分成用户、工单、送水、统计、文件五组,都用 /api 前缀, 返回体统一是 {code, msg, data}。统一返回结构的好处很直接: 客户端写一次判断 res.data.code === 200,所有请求都能复用。

接口一览 / 22 endpointsRESTful · JSON
用户   POST /api/user/register          注册
      POST /api/user/login             登录
      GET  /api/user/workers           维修工列表

工单   POST /api/order/submit          提交报修
      GET  /api/order/list            工单列表(user_id + role)
      GET  /api/order/detail/{id}     工单详情
      POST /api/order/assign/{id}     宿管指派
      POST /api/order/start/{id}      开始处理
      POST /api/order/finish/{id}     处理完成
      POST /api/order/urge/{id}       催单
      POST /api/order/cancel/{id}     取消
      POST /api/order/evaluate        提交评价
      POST /api/order/delete/{id}     删除(管理员)
      GET  /api/order/statistics/{id} 个人统计
      GET  /api/order/todo/{id}       待办数量

送水   POST /api/water/submit          下单
      GET  /api/water/list            订单列表
      POST /api/water/start/{id}      开始配送
      POST /api/water/finish/{id}     配送完成

统计   GET  /api/statistics/dashboard  看板数据
文件   POST /api/upload                上传照片
      GET  /api/export/orders          导出 Excel

两条约定。一是查询与变更分离:查询用 GET、参数放查询串; 变更一律 POST,避免部分网络环境下 PUT / DELETE 被拦。 二是路径放标识、body 放数据:定位资源用 /finish/{id}, 业务字段(如处理备注)走 body,语义更清楚。

还有个省接口的小设计:/api/order/list 同时服务学生端和管理端。 当 role 为 0 时按 user_id 过滤只返回本人的工单, 非 0 时忽略 user_id 返回全量。一个接口两用,少了重复代码, 也让「越权查询」只有一个地方需要守。

06 / 前端

十个页面,和三个现场踩出来的坑

前端用 uni-app(Vue 3)写,编译成微信小程序和 H5 两端。十个页面分别是登录、注册、 工单列表、报修提交、工单详情、我的、工单管理、送水服务、送水订单、送水详情。 样式全部用 rpx,在 320–428px 的屏幕上都试过。

坑一:角色要在 onShow 读,不能在 onLoad 读

这是我调试送水订单列表时卡了半天的问题:切换账号后,列表还显示上一个角色的数据。 原因是我在 onLoad 里读本地缓存里的角色编码,而 onLoad 只在页面首次加载时触发,同一页面内换账号它不会重跑。onShow 每次页面显示都会触发,改成它之后就对了。

坑二:图片「选择即上传」

现场照片最多三张,我没有等表单整体提交时一起传,而是选完立即 uni.uploadFile,拿到路径后只把字符串存进数组。 好处是提交请求体积小、响应快;代价是用户最终放弃提交时会残留无用文件。 单张压缩后一般 200KB 以内,残留影响有限,所以选了这个方案 —— 如果图片更大或用户量更大,应该反过来做。

坑三:检索放在前端,是权衡不是最优

管理端的检索和状态筛选是在前端做的:一次拉全量,本地过滤。校园场景单次查询通常几百条, 本地过滤几乎没有延迟,也避免了每敲一个字就发一次请求。 但这是我清楚知道它会在数据量变大后失效的地方 —— 几千条以后必须改成服务端分页。

这三个坑的共同点:都不是「写不出来」,而是「写出来之后才发现前提不成立」。

07 / 测试

二十五条用例,六台机,一千条数据

测试用黑盒方法,按等价类划分和边界值设计用例,覆盖账号、报修、管理、统计、送水五个域, 共 25 条,正常流程和异常流程都有。异常用例里比较有价值的几条: 空字段提交、超长描述、重复提交、以学生身份请求别人的工单详情、对已完成工单重复接单。

25 / 25功能用例通过
210ms千条工单列表响应
6 款机型兼容测试

性能测试是往库里注入 1000 条工单后测的:列表接口平均 210ms,详情接口 65ms, 真机首屏约 1.2 秒,都在需求定的 500ms / 2s 之内。并发加到 50 时响应升到 400ms 左右还可接受, 加到 100 就明显波动了 —— 因为没加缓存,这也是论文里写明的不足。

测试逼出来的三个 bug

一、送水列表在角色切换后显示上一角色的数据(就是前面 onLoad 那个)。 二、完工时填的备注在前端没映射到展示字段,详情页备注是空的 —— 前后端字段名不一致,统一成 handler_note 后好了。 三、图片上传成功后立刻返回上一页,加载提示不会关,一直转圈; 改成在回调里和页面卸载钩子里都关一次。

第三条让我印象最深:它只在「手快」的时候复现,功能测试全过也抓不到。

08 / 复盘

三件重做会改的事

一、一开始就做服务端分页。现在检索在前端,几百条没事, 几千条就卡。这不是「以后优化」,而是一开始就该定的接口形态 —— 分页参数一旦后加,前端列表、下拉刷新、状态标签全要跟着改。

二、图片从第一天就别放本地磁盘。现在是 save() 存到服务器目录, 没做定期清理。跑久了会有大量孤儿文件,而且换服务器就丢。 应该用对象存储加生命周期策略,多花的只是一点配置时间。

三、给接口写测试。25 条用例是我手点的,改完状态机要回归一遍, 很费时间而且会漏。如果有一条 pytest 覆盖「状态不允许时返回 400」, 这类回归就能自动跑。

这个项目给我最大的不是「我会写全栈」,而是知道了状态机、索引、测试这些 「看起来麻烦的东西」,各自在替谁挡子弹。