做环卫工人管理系统这个项目最初源于一个很具体的需求朋友所在的环卫站每天还要靠纸质表和微信群去排班、点名、对考勤月底算工资更是头疼经常因为漏记、重复记吵得不可开交。当时我正好手头熟悉 Python就决定用 Flask 写一套轻量化的管理系统把人员档案、区域划分、排班、考勤、任务分配和工资统计都收进去。这篇博文就是把整个项目的设计过程、核心代码、踩坑经历完整记录下来适合正在做 Flask Web 开发、或者想拿类似系统做课程设计和毕业设计的朋友参考代码不复杂重点在于把业务逻辑理清楚让系统真正能落地用起来。1. 需求梳理与整体设计先搞清楚系统要管什么1.1 用户角色与核心工作流任何管理系统第一步都不是写代码而是把“谁在用、每天在干什么事”摸清楚。这个系统里我设计了三个角色系统管理员负责人事档案的录入和变更维护班组、责任区域、班次类型处理请假、调班查看全站出勤和工资汇总。班组长负责排班、考勤确认、给工人下任务、处理巡查记录。环卫工人登录后能查看自己的排班表、当日任务、个人考勤记录也能进行上班签到。核心工作流其实是一条线管理员录入工人和区域 → 班组长按周排班 → 工人上班签到 → 班组长巡查确认 → 系统月末统计考勤和工资 → 管理员导出表格。因为环卫工人群体普遍年龄偏大手机操作能力有限所以前端必须极简一个按钮“签到”就够尽量不要有复杂的交互这也是设计时的一个重要约束。1.2 模块划分与数据库表设计我采用了轻量化方案框架用 Flask数据库用 SQLite。整体模块包括用户登录认证、工人档案管理、区域班组管理、排班管理、考勤管理、任务管理和工资统计。数据库层面我用 Flask-SQLAlchemy 来操作 SQLite表结构大致这样设计User 表id、username、password_hash、roleadmin/leader/worker、worker_id 外键。Worker 表id、work_no工号、name、gender、phone、group_name班组、area_id 外键。Area 表id、area_name、address、responsible_id。WorkSchedule 表id、worker_id、area_id、work_date、shift_type早班/晚班、status。Attendance 表id、worker_id、work_date、check_in_time、check_out_time、status正常/迟到/早退/缺勤、remark。Task 表id、worker_id、area_id、task_date、content、status待执行/已完成/超期、remark。选择 SQLite 的原因很简单环卫站的工人和排班数据量一般在一万条以内SQLite 单文件运行不用额外装 MySQL备份时直接拷贝文件就行对这种小型内部系统完全够用。如果以后并发访问量大了SQLAlchemy 的 ORM 代码基本不用改只需要把连接字符串换成 MySQL 即可这是一开始用 ORM 不用裸 sqlite3 的最大好处。1.3 为什么选 Flask 而不是 Django 或 Spring被问得最多的一个问题是这种管理系统用 Django 不是更好吗Django 确实自带了 Admin 后台、认证、ORM功能非常强大但缺点也明显——框架比较重很多自带模块这里用不上写起来反而觉得束手束脚。Flask 的核心非常精简路由、模板、session 全都自由灵活我可以完全按业务需要去组织代码结构。另一个实际因素是环卫站要跑在很普通的 Windows 电脑上Python 环境只要装一堆轻量依赖就能跑部署成本低。加上 Flask 的模板引擎 Jinja2 和 Bootstrap 配合得很好做出来的界面虽然谈不上惊艳但功能清晰、不杂乱对内部系统来说“能看懂、点得到”比“好看”重要得多。2. 核心功能实现排班、考勤、任务分配2.1 工人档案与责任区域管理工人档案是整个系统的地基必须保证数据准确。录入时需要校验工号唯一、手机号格式合规、班组名称不能重复。我用一个表单页完成新增和编辑字段包括工号、姓名、性别、手机号、班组、责任区域。责任区域是从 Area 表下拉选择而不是让用户手输这样可以避免同一个区域被写成“人民路一段”和“人民路1段”导致后面统计不上。区域管理的表单也一样区域名称和所属班组绑定。需要注意的一点是如果一个区域已经被某个工人使用删除前要给出禁用提示否则排班表里会留下悬空的外键。我在实际开发中给 Worker 表的 area_id 设置了外键约束并且删除区域时先查询是否有人关联有的话就拒绝删除并提示“该区域已绑定工人请先取消绑定”。在这个逻辑上我吃过亏一开始图省事没做校验后台一删区域排班表全乱了。2.2 排班表生成逻辑与避坑排班是这系统里最容易出错的地方。业务要求是班组长选择一个班组然后选择日期范围再点“一键生成排班”系统自动给这个班组下的所有人生成每天一条排班记录。听起来简单但生成前必须做好重复校验。如果某个工人某天已经有排班再生成就会产生重复数据后面统计考勤时会按日期去重但界面显示会很难看。我这里采用“先查再插”的方式遍历日期和该班组下的工人查询 WorkSchedule 表是否存在同日期同工人记录如果存在就跳过如果不存在才插入。同时允许班组长在排班列表页手动调整单个人的班次类型或区域调整操作就类比成“编辑”一条数据直接修改对应字段即可。这样既保证了批量生成的效率又保留了个性化调整的入口。2.3 考勤签到逻辑与补签机制考勤功能我做得比较克制没有上钉钉、企业微信那套复杂的 GPS 定位打卡因为很多环卫工用的还是老年机GPS 定位不稳定反而会引发大量误判。我的方案是工人登录后进到一个简洁的签到页页面上显示今天的排班班次和区域点击“签到”按钮系统记录当前服务器时间。班组长也可以代打卡主要用于工人手机没电或者忘记签到的情况但代打卡会记录操作人的账号方便回溯。判迟到逻辑是拿签到时间和排班班次做比较早班是 6:00晚班是 11:30允许 30 分钟宽限期超过就算迟到。这里有个很重要的细节日期跨天和班次边界问题。比如早班签到如果工人凌晨 5 点签了系统不能算成昨天晚班签到如果拖到凌晨也要归到当天。我在判断时给签到页直接取“当日排班日期”作为上下文而不是直接拿数据库里的最新时间戳去比对这样就避免了跨天误判。2.4 任务分配与巡查闭环任务分配是给班组长用的“派活”功能。班组长选择工人、责任区域、日期填写任务内容比如“清理片区花坛白色垃圾”“沿街果皮箱换袋”等。发布后工人登录系统就能在“我的任务”里看到待执行任务。工人点击“完成任务”按钮后系统把状态改成已完成。如果到了第二天任务还是待执行系统会在任务列表加载时自动把过期任务置为“超期”这个我用了一段很简单的查询逻辑更新状态前把任务日期小于当前日期且状态为待执行的数据批量更新为超期。要注意的一点是自动更新不应该写在一个每次请求都调用的全局函数里而应该单独放在任务列表视图函数中避免影响其他页面的响应速度。实际运行时数据量不大所以也不需要考虑定时任务页面加载时顺手刷一下状态就够了。3. 关键代码实现Flask 路由、模板与数据交互3.1 项目目录结构与数据库初始化一个清晰的项目结构能让人少走弯路。我推荐用下面这种扁平结构简单直接app.py # 主程序创建app、注册路由 models.py # 数据模型类 templates/ # Jinja2 模板 base.html # 所有页面的母版 login.html # 登录页 worker_list.html # 工人管理 schedule.html # 排班页 attendance.html # 考勤页 task.html # 任务页 static/ css/ # 自定义样式 js/ # 自定义脚本 uploads/ # 上传的附件 requirements.txtmodels.py 里定义一个 SQLAlchemy 实例随后创建模型类。需要注意的是 Flask-SQLAlchemy 3.x 的初始化写法跟旧版有些区别建议使用from flask import Flask from flask_sqlalchemy import SQLAlchemy db SQLAlchemy() def create_app(): app Flask(__name__) app.config[SECRET_KEY] your-secret-key app.config[SQLALCHEMY_DATABASE_URI] sqlite:///workers.db app.config[SQLALCHEMY_TRACK_MODIFICATIONS] False db.init_app(app) return app在 Windows 下千万别忘了设置 UTF-8 编码环境否则控制台中文输出或 SQLite 中文查询会遇到问题。我一般会加一句环境变量设置在运行前执行set PYTHONIOENCODINGutf-8。3.2 登录认证与权限控制认证我是用 Flask 内置的 session 做的不用 Flask-Login 也没问题。登录成功以后把 user_id 和 role 存进 session然后写一个登录校验装饰器所有需要登录的页面都加上。权限控制则通过角色判断班组长可以访问排班和任务管理普通工人只能访问自己的页面。装饰器长这样from functools import wraps from flask import session, redirect, url_for def login_required(f): wraps(f) def decorated(*args, **kwargs): if user_id not in session: return redirect(url_for(login)) return f(*args, **kwargs) return decorated再写一个role_required用来限制只有管理员和班组长才能打开管理页面。密码存储上不要用明文用werkzeug.security里的generate_password_hash和check_password_hash做哈希比较这是基本的安全习惯。3.3 模板渲染与表单数据交互Jinja2 模板是 Flask 非常好用的部分流程也很直观视图函数把数据通过render_template传给模板模板里用{{ 变量 }}输出、{% for %}循环。比如工人列表页的核心代码table classtable theadtrth工号/thth姓名/thth班组/thth手机号/th/tr/thead tbody {% for w in workers %} tr td{{ w.work_no }}/td td{{ w.name }}/td td{{ w.group_name }}/td td{{ w.phone }}/td /tr {% else %} trtd colspan4暂无数据/td/tr {% endfor %} /tbody /table在视图函数里接收表单数据时最常见的是用request.form.get(参数名)获取 POST 请求的表单值。注意.get方法即使参数不存在也不会报错而是返回默认值空字符串所以推荐先.strip()去掉空格再存入数据库。如果前端用的不是普通表单而是 fetch 发送 JSON 数据视图里就要用request.get_json()获取这两个方式容易搞混排查问题时先确认请求头里的 content-type。3.4 统计报表接口与前端图表统计报表不用做成特别复杂的 BI我只需要“本月每个工人的出勤天数”和“今日班组出勤率”两张图就够了。后端构造一个返回 JSON 的接口前端用 ECharts 画柱状图。接口代码大致这样app.route(/api/attendance_stats) login_required def attendance_stats(): month request.args.get(month, datetime.now().strftime(%Y-%m)) rows db.session.query( Worker.name, func.count(Attendance.id).label(days) ).join(Attendance, Worker.id Attendance.worker_id) \ .filter(Attendance.work_date.like(month %)) \ .group_by(Worker.id).all() data [{name: r.name, days: r.days} for r in rows] return jsonify(data)在烧录数据时前端读取 JSON 后直接塞给 ECharts。要注意月参数必须做格式校验比如用正则确保是YYYY-MM拼接的形式不然用户乱传参数容易把 SQL 查询拖慢虽然 SQLite 不会达到数据库崩掉的程度但该防的还是要防。4. 部署与踩坑记录从本地到 Windows 服务器4.1 本地运行与依赖安装这个项目在 Windows 上运行前提是要有合适的 Python 版本和虚拟环境。我推荐 Python 3.9 到 3.11 的任意版本Flask 2.x 和 Flask-SQLAlchemy 3.x 在这些版本下都很稳定。创建虚拟环境并激活的命令是python -m venv venv venv\Scripts\activate pip install -r requirements.txtrequirements.txt 里最核心的几个依赖是Flask、Flask-SQLAlchemy和openpyxl做 Excel 导出用。如果在国内安装依赖慢建议切成国内镜像源。装完之后运行python app.py控制台会输出本地地址浏览器打开即可。启动前务必要执行数据库初始化我经常在这上面浪费好几分钟忘掉第一次执行db.create_all()建表结果访问页面时报 no such table。4.2 附件上传路径错误是重灾区热词里有“附件路径错误”这确实是 Flask 项目部署到 Windows 上最常见的坑。很多新手喜欢直接填相对路径比如UPLOAD_FOLDER static/uploads开发的时候一切正常但一旦用python app.py从别的目录启动或者部署成 Windows 服务相对路径就会失效出现上传成功但页面找不到文件的灵异事件。正确的做法是把路径写成基于当前文件所在目录的绝对路径import os BASE_DIR os.path.abspath(os.path.dirname(__file__)) UPLOAD_FOLDER os.path.join(BASE_DIR, static, uploads) ALLOWED_EXTENSIONS {png, jpg, jpeg, gif}模板里引用上传后的文件时不要手动拼路径要用url_for(static, filenameuploads/ filename)这样 Flask 会自动处理 URL 前缀也不会因为多一个斜杠写错。还有一点需要提醒Windows 下os.path.join会自动生成反斜杠路径这个路径只适合给文件系统用千万不要直接拼到 URL 上否则浏览器访问不了。正确做法是保存时存储文件名取回来时用url_for生成访问地址问题就没了。4.3 无效信息过滤与数据可靠性“无效信息过滤”这个概念在很多管理系统里都适用。这个系统里最典型的无效数据是重复工号、空手机号、乱写的区域名。我在新增工人时除了前端 JS 校验后端必须再校验一次因为前端校验可以被绕过。手机号校验我用了正则import re def is_valid_phone(phone): pattern r^1[3-9]\d{9}$ return bool(re.match(pattern, phone))另外数据库层也要加唯一约束比如工号字段加上uniqueTrue这样就算后端漏了校验数据库也会报错提醒你排查而不是静默写入坏数据。系统里我加了统一的异常处理当 SQLite 唯一约束错误发生时捕获异常并返回“工号已存在”的提示而不会抛给用户一个乱糟糟的 500 页面。数据可靠性还体现在删除保护上凡是有关联数据的记录一定要给二次确认这是我后期补上的补完之后整个系统的可用性上了一个台阶。4.4 常见问题速查表整理一份我实际踩过的坑和解决方案做成了速查表方便大家复制粘贴排查现象根本原因解决办法页面报 500 错误视图函数内部有语法错误或 NoneType 取值查看控制台堆栈定位到具体行Jinja2 报 TemplateNotFound模板目录不在当前工作目录下用绝对路径os.path.join(BASE_DIR, templates)SQLite 提示 database is locked多线程同时写数据库SQLALCHEMY_ENGINE_OPTIONS 加 connect_timeout或检查是否遗漏 commit中文显示成乱码Windows 控制台编码或数据库编码问题设置 PYTHONIOENCODINGutf-8URL 连接后加 charsetutf8session 一直没有登录态SECRET_KEY 未设置或每次重启随机在 app.config 里设置为固定字符串上传图片后显示 404路径拼错或静态文件夹未设置用 url_for 生成访问地址检查 uploads 目录权限这张表基本覆盖了小型 Flask 系统从开发到部署的常见雷区建议大家遇到问题时先对号入座不要盲目改代码。5. 后续优化方向与个人心得5.1 可以继续扩展的实用功能系统上线后我陆续收到了很多新的需求其中有几个方向特别有参考价值。Excel 工资表导出月底考勤统计出来后用 openpyxl 直接生成包含基本工资、请假扣款、迟到扣款、实发金额的表格管理员不再需要手动从系统里抄数到 Excel。实现起来很快就是查询考勤和请假日数后按规则计算。自动排班优化现在的排班是班组循环生成如果工人请假就会有空缺。可以扩展一个接口把请假人自动替换成同组休息日的工人这里用简单的约束匹配就能做到。登录加固目前还是账号密码登录后续可以加固定 IP 白名单或者扫码登录减少账号被盗用后误操作考勤的可能。数据备份SQLite 单文件虽然方便但也容易损坏。可以写一个后台定时复制 workers.db 的脚本每天保留一份这个成本非常低。这些扩展基本不改变现有框架只要在原模型上增加字段和页面即可前期设计时把数据模型分得足够细扩展起来就会轻松不少。5.2 踩过几次坑之后我想说的东西做完这个系统我最大的体会是Flask 这类轻量框架真正适合的就是内部工具和小团队管理系统它把“核心功能怎么写”的选择权完全交给开发者不需要为用不到的功能买单。但是轻量也意味着很多默认行为需要自己心里有数比如路径问题、编码问题、session 安全问题这些在大型框架里可能已经帮你拉平了在 Flask 里就得自己处理。好在这套项目不算复杂一旦把目录、数据库连接、模板继承这些基础打牢后面加功能就是堆面包一样一层一层往上叠就行。如果让我给后来者一个建议那就是不要一开始就纠结要不要加 Redis、加 Celery先把排班、考勤这条主链路用最简单的代码跑通再考虑性能优化。这系统实际运行下来的稳定性比我预想的好很多日常维护成本基本为零每天只要打开电脑、启动服务所有人就能正常使用。对个人开发者来说这就是一个非常理想的项目形态。