# kq **Repository Path**: GoBetter/kq ## Basic Information - **Project Name**: kq - **Description**: 考勤管理系统 (Attendance Management System) 一个基于 Flask 框架开发的企业级考勤管理系统，提供完整的员工考勤记录、部门管理、数据统计分析等功能。系统采用现代化的 Web 技术栈，界面美观、操作便捷，支持数据导入导出，满足企业日常考勤管理需求 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 2 - **Created**: 2026-07-07 - **Last Updated**: 2026-07-07 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 考勤管理系统 (Attendance Management System) 一个基于 Flask 框架开发的企业级考勤管理系统，提供完整的员工考勤记录、部门管理、数据统计分析等功能。系统采用现代化的 Web 技术栈，界面美观、操作便捷，支持数据导入导出，满足企业日常考勤管理需求。 ## 📋 项目简介 本系统是一个功能完善的考勤管理解决方案，旨在帮助企业高效管理员工考勤信息。系统支持多用户权限管理、部门层级管理、日度和月度考勤记录、数据统计分析等功能，并提供 Excel 数据导入导出能力，方便与现有办公系统集成。 ## ✨ 核心功能 ### 🔐 用户认证与权限管理 - 用户登录/退出功能 - 基于角色的权限控制（管理员/普通用户） - 会话管理和安全认证 - 登录状态持久化 ### 👥 员工管理 - 员工信息的增删改查 - 员工工号、姓名、部门等信息管理 - 员工信息批量导入 - 员工搜索和筛选功能 - 员工备注信息管理 ### 🏢 部门管理 - 部门信息的完整管理（增删改查） - 支持多层级部门结构（父子部门关系） - 部门编码和名称管理 - 部门状态启用/禁用 - 部门排序功能 - 部门变动记录追踪 ### 📅 考勤记录管理 - **日度考勤记录** - 员工每日打卡记录（上班时间/下班时间） - 考勤记录查询和筛选 - 按日期范围、员工、部门筛选 - 考勤记录备注功能 - **月度考勤汇总** - 按月统计员工考勤情况 - 支持31天的考勤数据记录 - 月度考勤数据查询和导出 - 月度考勤数据导入 ### 📊 数据统计与分析 - **仪表板概览** - 员工总数统计 - 部门数量统计 - 月度考勤记录统计 - 部门变动记录统计 - **可视化图表** - 部门人数分布饼图 - 最近7天考勤趋势折线图 - 实时数据更新 ### 📥📤 数据导入导出 - Excel 格式数据导入 - 支持员工信息批量导入 - 支持考勤记录批量导入 - 数据格式验证和错误提示 - Excel 格式数据导出 - 考勤记录导出为 Excel - 月度考勤汇总导出 - 自定义导出格式和样式 ### 🔄 部门变动管理 - 员工部门调动记录 - 部门变动历史查询 - 变动原因和备注记录 - 变动时间追踪 ## 🛠️ 技术栈 ### 后端技术 - **Python 3.8+** - 编程语言 - **Flask 3.1.0** - Web 框架 - **Flask-SQLAlchemy 3.1.1** - ORM 数据库操作 - **Flask-Login 0.6.3** - 用户会话管理 - **Flask-Migrate 4.0.7** - 数据库迁移工具 - **SQLAlchemy 2.0.37** - 数据库 ORM - **Alembic 1.14.0** - 数据库迁移引擎 ### 数据库 - **SQLite** - 轻量级关系型数据库（开发环境） - 支持迁移到 PostgreSQL/MySQL（生产环境） ### 前端技术 - **Bootstrap 4/5** - 响应式 UI 框架 - **jQuery 3.5.1** - JavaScript 库 - **Chart.js** - 数据可视化图表库 - **Font Awesome** - 图标库 ### 数据处理 - **Pandas 2.0.3+** - 数据处理和分析 - **openpyxl 3.1.5** - Excel 文件读写 - **xlrd 1.2.0** - Excel 文件读取支持 ## 📁 项目结构 ``` kq/ ├── app/ # 应用主目录 │ ├── __init__.py # 应用初始化 │ ├── commands.py # Flask CLI 命令 │ ├── models/ # 数据模型 │ │ ├── __init__.py │ │ ├── user.py # 用户模型 │ │ ├── employee.py # 员工模型 │ │ ├── department.py # 部门模型 │ │ └── attendance.py # 考勤记录模型 │ ├── views/ # 视图路由 │ │ ├── auth.py # 认证视图 │ │ ├── home.py # 首页/仪表板 │ │ ├── attendance.py # 考勤管理视图 │ │ └── department.py # 部门管理视图 │ ├── templates/ # HTML 模板 │ │ ├── base.html # 基础模板 │ │ ├── auth_base.html # 认证基础模板 │ │ ├── login.html # 登录页面 │ │ ├── dashboard.html # 仪表板 │ │ ├── employees.html # 员工管理 │ │ ├── departments.html # 部门管理 │ │ ├── daily.html # 日度考勤 │ │ └── monthly.html # 月度考勤 │ └── static/ # 静态资源 │ ├── css/ # 样式文件 │ ├── js/ # JavaScript 文件 │ └── webfonts/ # 字体文件 ├── instance/ # 实例文件夹 │ └── kq.db # SQLite 数据库文件 ├── img/ # 项目截图和文档图片 ├── config.py # 配置文件 ├── run.py # 应用启动文件 ├── init_db.py # 数据库初始化脚本 ├── create_admin.py # 创建管理员脚本 ├── migrations.py # 数据库迁移脚本 ├── requirements.txt # Python 依赖包 └── README.md # 项目说明文档 ``` ## 🚀 快速开始 ### 环境要求 - Python 3.8 或更高版本 - pip 包管理器 ### 安装步骤 1. **克隆项目** ```bash git clone git@github.com:LiuJun666888/kq.git cd kq ``` 2. **创建虚拟环境** ```bash # Windows python -m venv venv venv\Scripts\activate # Linux/Mac python3 -m venv venv source venv/bin/activate ``` 3. **安装依赖** ```bash pip install -r requirements.txt ``` 4. **初始化数据库** ```bash python init_db.py ``` 5. **创建管理员账号（可选）** ```bash python create_admin.py ``` 或使用 Flask CLI： ```bash flask create-admin ``` 6. **运行应用** ```bash python run.py ``` 7. **访问应用** 打开浏览器访问：http://localhost:5000 ### 默认账号 系统初始化后会创建以下测试账号： - **管理员账号** - 用户名：`admin` - 密码：`admin123` - 权限：完整系统管理权限 - **普通用户** - 用户名：`user` - 密码：`user123` - 权限：查看和基本操作权限 > ⚠️ **安全提示**：生产环境部署前请务必修改默认密码！ ## 📖 使用说明 ### 登录系统 1. 访问系统首页，系统会自动跳转到登录页面 2. 输入用户名和密码 3. 点击"登录"按钮 ### 仪表板 登录成功后进入仪表板，可以查看： - 系统统计概览（员工数、部门数等） - 部门人数分布图表 - 最近7天考勤趋势 - 最近的部门变动记录 ### 员工管理 1. 点击导航栏"员工管理" 2. 可以添加、编辑、删除员工信息 3. 支持按工号、姓名、部门搜索 4. 支持批量导入员工信息（Excel 格式） ### 部门管理 1. 点击导航栏"部门管理" 2. 可以创建、编辑、删除部门 3. 支持设置部门层级关系 4. 支持部门排序和状态管理 ### 考勤记录 1. **日度考勤** - 查看每日考勤记录 - 支持按日期范围筛选 - 支持导出 Excel 2. **月度考勤** - 查看月度考勤汇总 - 支持按月筛选 - 支持导入和导出 Excel ### 数据导入 1. 准备符合格式要求的 Excel 文件 2. 在相应页面点击"导入"按钮 3. 选择文件并上传 4. 系统会自动验证数据格式并导入 ## ⚙️ 配置说明 ### 环境配置 系统配置文件位于 `config.py`，支持以下配置： - **开发环境** (`development`) - `DEBUG = True` - 启用调试模式 - **生产环境** (`production`) - `DEBUG = False` - 关闭调试模式 ### 数据库配置 默认使用 SQLite 数据库，文件位置：`instance/kq.db` 如需使用其他数据库（如 PostgreSQL、MySQL），修改 `config.py` 中的 `SQLALCHEMY_DATABASE_URI`： ```python # PostgreSQL 示例 SQLALCHEMY_DATABASE_URI = 'postgresql://user:password@localhost/kq' # MySQL 示例 SQLALCHEMY_DATABASE_URI = 'mysql://user:password@localhost/kq' ``` ### 安全配置 生产环境部署前，请务必： 1. 修改 `config.py` 中的 `SECRET_KEY` ```python SECRET_KEY = os.environ.get('SECRET_KEY') or 'your-secret-key-here' ``` 2. 使用环境变量管理敏感信息 3. 启用 HTTPS 4. 配置防火墙规则 ## 🔧 开发指南 ### 数据库迁移 使用 Flask-Migrate 进行数据库版本管理： ```bash # 创建迁移 flask db migrate -m "描述信息" # 应用迁移 flask db upgrade # 回滚迁移 flask db downgrade ``` ### 代码结构 - **模型层** (`app/models/`)：定义数据模型和数据库表结构 - **视图层** (`app/views/`)：处理 HTTP 请求和响应 - **模板层** (`app/templates/`)：HTML 模板文件 - **静态资源** (`app/static/`)：CSS、JavaScript、图片等 ### 添加新功能 1. 在 `app/models/` 中定义数据模型 2. 在 `app/views/` 中创建视图函数 3. 在 `app/templates/` 中创建模板文件 4. 在 `app/__init__.py` 中注册蓝图 ## 🐛 常见问题 ### 数据库初始化失败 - 确保 `instance` 目录存在且有写权限 - 检查 Python 版本是否符合要求 - 确认所有依赖包已正确安装 ### 导入 Excel 失败 - 检查 Excel 文件格式是否符合要求 - 确认文件编码为 UTF-8 - 检查必填字段是否完整 ### 登录后无法访问页面 - 检查用户权限设置 - 确认 Flask-Login 配置正确 - 查看浏览器控制台错误信息 ## 📝 更新日志 ### v1.0.0 - 初始版本发布 - 实现基础考勤管理功能 - 支持员工、部门、考勤记录管理 - 支持数据导入导出 ## 🤝 贡献指南 欢迎提交 Issue 和 Pull Request 来帮助改进项目。 ## 📄 许可证 本项目采用 MIT 许可证。 ## 👤 作者 - **LiuJun** - [GitHub](https://github.com/LiuJun666888) ## 🙏 致谢 感谢所有为本项目做出贡献的开发者和用户。 --- **注意**：本项目仅供学习和参考使用，生产环境部署前请进行充分的安全测试和性能优化。