1、企业传统考勤数据以 Excel 文件形式由人事每月手工汇总、分发，员工无法自助查询，HR 也面临数据处理繁琐、迟到早退缺卡统计易错、报表分发滞后等问题。本项目立项旨在将"企业微信/今视频 APP 导出的原始打卡 Excel"自动化入库与清洗计算，搭建一套覆盖"员工自助查询 + HR 后台管理"的考勤管理系统。
2、业务场景面向中大型企业人力资源部门及全体员工：员工登录后可按月查看本人的考勤统计卡片与彩色日历视图，直观掌握正常、迟到、早退、缺卡、旷工、请假、外出等每日状态；管理员可在后台按月份、部门、打卡规则、姓名多维度筛选全公司考勤数据，一键导入月度 Excel（实时进度推送）、导出三 Sheet 标准报表，并完成员工账号的批量开通与管理，实现考勤数据"采集—清洗—统计—展示—归档"全流程线上化。
系统采用前后端分离架构，分为四大功能模块：
1. 用户认证与权限模块：手机号+密码登录，JWT Token 鉴权（7天有效期），pbkdf2_sha256 密码加密；区分管理员/普通用户两级角色，前端路由守卫 + 后端 require_admin 依赖双重权限校验；支持账号激活状态控制。
2. 员工个人考勤模块：月度十项指标统计卡片（总天数、节假日、工作日、正常、迟到、早退、缺卡、旷工、请假、外出）；周一起排的考勤日历，按严重程度优先级（旷工＞缺卡＞迟到＞早退＞请假＞外出＞正常）着色展示，点击任意日期可查看当天上下班打卡时间、打卡状态及异常明细；支持历史月份切换。
3. HR 管理后台模块：支持月份/部门/打卡规则/姓名组合筛选；三个数据页签——"考勤结果"（每人一行+1~31日动态明细列，含迟到/早退/旷工/缺卡次数）、"APP 打卡记录"（每次打卡一条）、"考勤记录汇总明细"（每人每天一行，含打卡结果、请假情况、节假日标记）；点击姓名可下钻查看任意员工的月度汇总与日历；支持一键导出与页签严格对应的三 Sheet Excel 报表（冻结表头、动态日期列带星期）。
4. Excel 数据导入与员工管理模块：管理员上传考勤原始 Excel 后，后台线程执行"清表→pandas 读取清洗→批量入库→版本化 SQL 脚本四步加工（日期清洗、APP记录导入、员工表关联、迟到/早退/缺卡计算）"，并通过 SSE（Server-Sent Events）实时推送处理进度与心跳保活；员工管理支持用户增删改查、按姓名/手机号/部门/角色/激活状态筛选、重置密码、角色分配，以及从考勤库 attendance_user 表按手机号去重批量导入账号（默认密码 123456）。全系统关键操作（登录、导入、导出、用户变更）均写入操作日志留痕。
本人独立负责系统的需求分析、架构设计与全栈编码。技术栈：后端 Python + FastAPI + Uvicorn，数据层 **PostgreSQL（psycopg2）**双库设计——考勤库 jsp_data 只读、用户库 news_db 读写；pandas + openpyxl/xlsxwriter 负责 Excel 读写；前端 Vue 3（Composition API）+ Vite + Element Plus + Vue Router + Axios；认证采用 JWT（python-jose）+ passlib。提供 start.py 一键启动脚本，自动清理 8000/5173 端口并拉起前后端、支持局域网访问。
实现亮点与难点：① 双数据源隔离：原始考勤库保持只读，账号体系独立建表，通过真实姓名/jid/手机号多字段关联，避免污染生产数据；② 版本化 SQL 加工管线：复杂考勤规则（节假日判定、迟到早退缺卡计算、员工与 APP 打卡记录关联）沉淀为 v1.0.0.sql 并以 versions.json 管理版本，导入接口按中文步骤注释正则切分语句、逐条执行并过滤 SELECT，保证可演进；③ SSE 实时进度：长耗时 Excel 处理放入守护线程，借助 queue.Queue 向 StreamingResponse 传递分步进度，配合 45 秒心跳解决代理超时与线程异常感知；④ 状态优先级归并算法：同一天 result 文本含多种异常关键词时，按业务严重度优先级映射为唯一日历状态色；⑤ 三页签与导出文件严格同构：接口数据结构直接复用于 xlsxwriter 内存流导出，动态生成"5/1 周五"式日期表头、冻结窗格、UTF-8 文件名编码；⑥ 权限上采用 FastAPI 依赖注入（get_current_user/require_admin），普通用户仅能访问本
评论