勤致 - 员工考勤管理系统

智能、灵活、高效的考勤管理解决方案 —— 让每一次打卡都有据可循，让每一份报表自动生成。

---

📖 项目简介

“勤致”是一款轻量级、智能化、可配置的 Web 考勤管理系统。它解决了传统考勤方式中数据分散、统计耗时、防作弊能力弱、难以适应弹性工作制等痛点，为企业提供了一套完整的数字化考勤解决方案。

系统支持：

• ✅ GPS 地理位置验证打卡（基于高德地图 API）
• ✅ 固定班次 / 弹性工时两种考勤规则
• ✅ 请假、加班、外勤、补卡在线审批流程
• ✅ 部门/公司多维考勤报表与可视化图表
• ✅ 员工账号管理、组织架构维护、考勤组配置
• ✅ 国际化（中/英）与明暗双主题

无论是初创团队还是中大型企业，“勤致”都能帮助你轻松管理员工出勤，提升管理效率。

---

🚀 核心功能

模块	功能描述
员工管理	员工信息增删改查，支持部门、岗位、角色（员工/部门主管/HR/管理员）
组织架构	树形部门结构管理，部门负责人指派，岗位维护
考勤规则	多时段打卡（上下班固定时间） / 总时长弹性工作制，迟到/早退阈值可调
打卡地点	自定义打卡地点（经纬度 + 有效半径），支持多地点关联考勤组
智能打卡	基于浏览器 Geolocation + 高德逆地理编码，实时校验位置有效性，超出范围无法打卡
考勤申请	员工在线提交请假/加班/外勤/补卡申请，支持附件上传
审批流程	部门主管/HR/管理员在线审批，驳回需填写理由
个人考勤	日历视图展示每日打卡状态（正常/迟到/缺卡/请假），月度明细表格
部门报表	按部门/日期范围生成考勤统计表，支持 ECharts 柱状图/饼图可视化，一键导出 Excel
月度趋势	公司级每日打卡率折线图，实时了解整体出勤动态
多语言	简体中文 / English 动态切换，i18n 全流程支持
主题切换	日间 / 暗夜主题，适应不同工作环境

---

🧰 技术栈

前端 (Frontend)

• 核心框架：Vue 3.6 (组合式 API) + Vue Router 5 + Pinia 3
• UI 组件库：Element Plus 2.13 + 自定义组件
• HTTP 请求：Axios 1.14
• 图表可视化：ECharts 6.0
• 地图服务：高德地图 JS API 2.0 (AMapLoader)
• 工具库：@vueuse/core 14 (组合式工具)、QRCode、FontAwesome 7
• 样式预处理器：Sass (modern-compiler)
• 构建工具：Vite 8 + Rolldown
• 代码规范：ESLint + Oxlint + Prettier
• 测试：Vitest 4 (单元) + Playwright 1.59 (E2E)

后端 (Backend)

• 核心框架：Spring Boot 4.0.6 + Spring MVC + Spring Data JPA
• 安全框架：Spring Security + JWT (JJWT 0.13)
• 数据库：MySQL 8.0 + HikariCP 连接池
• 对象映射：Lombok
• API 文档：OpenAPI 3.0 (YAML 定义)
• 构建工具：Maven 3.8+

数据库设计亮点

• 考勤组 attendance_group 与考勤地点 location 多对多关联
• 员工 employee 关联考勤组、部门、职位
• 请假申请支持 JSON 字段存储动态明细（请假类型/加班补偿/外勤地点等）
• 打卡记录 clock_record 支持上班/下班类型区分，记录经纬度及有效性

---

🏗️ 系统架构简览

graph LR
    A[浏览器客户端] -->|GPS 定位| B[高德地图 API]
    A -->|HTTP / WebSocket| C[Nginx / 直接访问]
    C --> D[Spring Boot 后端]
    D --> E[MySQL 数据库]
    D --> F[JWT 认证]
    D --> G[文件存储]
    G --> H[静态资源 / 附件]

Loading

• 前后端分离：Vue SPA 通过 RESTful API 与后端交互，后端同时提供静态资源托管。
• JWT 无状态认证：Token 存储在 localStorage / sessionStorage，请求拦截器自动携带。
• Mock 模拟层：开发环境前端自带 SQLite 模拟数据，可独立运行，无需后端。

---

📦 快速开始

环境要求

• 前端：Node.js 20+ / pnpm 8+
• 后端：JDK 21, Maven 3.8+, MySQL 8.0+

前端（独立开发）

# 1. 克隆项目
git clone https://gitee.com/nfupt4/Diligence.git
cd Diligence/code/frontend/diligence

# 2. 安装依赖
pnpm install

# 3. 启动开发服务器（默认开启 Mock 数据，无需后端）
pnpm run dev
# 访问 http://localhost:7265

💡 前端开发模式自带 SQLite 模拟数据库 + JWT 模拟服务，可独立完成所有功能调试。

后端（与前端联调）

# 1. 准备数据库
mysql -u root -p -e "CREATE DATABASE diligence CHARACTER SET utf8mb4;"

# 2. 修改后端配置文件
cd ../code/backend/diligence
# 编辑 src/main/resources/application.yml，设置 spring.datasource.password

# 3. 构建前端生产包（可选，或直接使用前端 dev 代理）
cd ../frontend/diligence
pnpm run build-only
# 产物自动输出到 backend/src/main/resources/static

# 4. 回到后端目录，启动 Spring Boot
mvn clean spring-boot:run
# 访问 http://localhost:8080

注意：开发环境支持跨域，前端 vite.config.ts 已配置代理 /api/v1 → 后端 localhost:8080。

测试账号

系统内置了预置数据（通过 InitTestUserRunner 自动创建）：

• 普通员工：工号 EXP20260001，密码 Aa123456
• 管理员：工号 ADMIN001，密码 Admin123 (需手动创建或启用 admin profile)

---

🧪 测试与文档

类型	命令	说明
单元测试	pnpm run test:unit	Vitest 单元测试（stores, utils）
E2E 测试	pnpm run test:e2e	Playwright 全浏览器测试
API 文档	openapi.yaml	符合 OpenAPI 3.0 规范，可导入 Postman / Swagger UI
后端测试	mvn test	Spring Boot 单元测试

---

🤝 贡献指南

我们欢迎任何形式的贡献！请阅读 CONTRIBUTING.md 了解：

• 任务分配与看板使用
• 分支命名规范 (feat/, fix/, docs/ …)
• Commit 消息格式 (feat: #123 add avatar upload)
• Pull Request 与 Issue 关联规则
• 测试人员如何提交缺陷报告

所有开发请基于 main 分支创建个人工作分支，完成后发起 PR，经 Code Review 后合并。

---

📄 许可证

Copyright © 2026 NFUPT4. All rights reserved.
本项目采用 CC BY-NC-SA 4.0 许可证，即 署名-非商业性使用-相同方式共享。

• ✅ 允许分享、修改，但必须署名原作者
• ❌ 禁止用于商业用途
• 🔁 衍生作品需使用相同许可证

详细条款请查阅 LICENSE。

---

🙏 致谢

• 高德地图开放平台 – 提供精准的地理编码与定位服务
• Element Plus 团队 – 优雅的 Vue 3 组件库
• Vue.js 及周边生态 – 让前端开发如此愉悦
• Spring 社区 – 企业级开发的坚实底座

---

勤能致远，致勤致诚 – 我们坚信，好的工具能让管理回归简单。
立即开始使用“勤致”，开启企业考勤数字化新篇章！