# 人事管理系统HRMS

**Repository Path**: helloWorldTiaoTiaoWa/HRMS

## Basic Information

- **Project Name**: 人事管理系统HRMS
- **Description**: 一个开源的人事管理系统，支持员工信息管理、考勤、薪资与流程审批，助力企业高效人事运营。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 10
- **Forks**: 3
- **Created**: 2026-07-31
- **Last Updated**: 2026-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Vue, Java, React

## README

<div align="center">


# HRMS 人事管理系统

**线上访问地址：<http://39.96.73.55:18080/>** —— 我的这个轻量应用服务器内存只有1G，cpu只有1核, 用的是 H2 内嵌数据库一体包部署。 因为h2数据库适配目前还存在一些bug，线上环境可能存在一些问题，仅供演示，具体使用建议下载或者git拉取源码本地使用mysql部署。

**演示账号（线上可直接登录）：** 管理员 `admin` / `Admin@123` · 部门主管 `manager` / `Manager@123` · 人事专员 `hr` / `Hr@123456` · 普通员工 `employee` / `Employee@123`

**基于 Spring Boot 3 + Vue 3 + 微信小程序 构建的现代化企业人事管理平台**

员工档案 · 组织架构 · 考勤打卡 · 加班休假 · 补卡审批 · 入转调离 · 地图围栏 · 移动办公

<p>
  
  <img src="https://img.shields.io/badge/Spring%20Boot-3.3.2-6DB33F?style=flat-square\&logo=springboot\&logoColor=white" alt="Spring Boot">
  
  <img src="https://img.shields.io/badge/Vue-3.5-42B883?style=flat-square\&logo=vuedotjs\&logoColor=white" alt="Vue">
  
  <img src="https://img.shields.io/badge/TypeScript-6.0-3178C6?style=flat-square\&logo=typescript\&logoColor=white" alt="TypeScript">
  
  <img src="https://img.shields.io/badge/MySQL-8.0-4479A1?style=flat-square\&logo=mysql\&logoColor=white" alt="MySQL">
  
  <img src="https://img.shields.io/badge/Java-17+-ED8B00?style=flat-square\&logo=openjdk\&logoColor=white" alt="Java">
  
  <img src="https://img.shields.io/badge/License-Apache--2.0-blue?style=flat-square" alt="License">
  
</p>

[项目预览](#项目预览) · [核心功能](#核心功能) · [导航与设置](#导航与设置) · [微信小程序端功能介绍](#微信小程序端功能介绍) · [快速开始](#快速开始) · [配置说明](#配置说明) · [更新日志](./CHANGELOG.md)

</div>

---

## 项目简介

HRMS 是一套面向中小型企业的人事管理系统，采用前后端分离架构，覆盖组织资料、员工档案、入转调离、定位打卡、考勤报表、加班休假、补卡审批、假期余额、通知及报表等常见人事业务。

系统内置 `EMPLOYEE`、`MANAGER`、`HR`、`ADMIN` 四类角色，通过前端菜单与操作可见性、路由守卫和后端接口鉴权实现多层权限控制。项目包含完整数据库迁移、演示数据、Excel 导入导出、附件管理、微信小程序移动端及 Windows 新手启动文档，可用于学习、二次开发或内部系统原型搭建。

> 本项目默认配置与演示账号仅用于本地开发和功能体验。正式部署前请修改数据库密码、JWT 密钥及所有初始密码。

## 项目预览

### 工作台

集中展示员工、加班、休假、审批等核心业务数据，让待办事项和人事动态一目了然。

![HRMS 工作台](./pic/工作台.png)

### 员工管理

统一维护员工档案、组织归属、登录账号、假期额度及附件资料，支持 Excel 批量导入导出。

![HRMS 员工管理](./pic/员工管理.png)

### 休假管理

支持休假申请、余额提示、职务代理人确认、材料上传及完整审批进度追踪。

![HRMS 休假管理](./pic/休假管理.png)

<details>

<summary><strong>查看更多系统截图</strong></summary>

#### 系统设置

工作时段、工作日、加班上限、休假规则、验证码及统一假期标准均可动态配置。

![HRMS 系统设置](./pic/系统设置.png)

#### 节假日管理

维护法定节假日、调休日和补班日期，为工时与休假计算提供准确依据。

![HRMS 节假日管理](./pic/节假日.png)

#### 通知中心

集中查看审批通知和业务消息，支持未读提醒、消息弹窗和已读管理。

![HRMS 通知中心](./pic/通知中心.png)

</details>

### 微信小程序端

> 小程序（hrms-wx）面向全体员工，提供移动端的自助办公能力。员工无需登录 PC，在手机上即可发起请假 / 加班、查看本人假期余额、处理待办审批、接收站内消息。截图如下：

| 登录页 | 首页（工作台） |
| --- | ------- |
| 登录页 | 首页      |

| 我的（个人中心） | 单据（请假 / 加班记录） |
| -------- | ------------- |
| 我的       | 单据            |

| 审批（待办 / 已办） | 消息（站内通知） |
| ----------- | -------- |
| 审批          | 消息       |


## 核心功能

| 模块          | 功能说明                                                                                    |
| ----------- | --------------------------------------------------------------------------------------- |
| 工作台         | 人员、加班、休假、审批等核心数据概览                                                                      |
| 员工管理        | 员工档案、组织归属、账号创建、密码重置、账号解锁、Excel 导入导出                                                     |
| 组织管理        | 公司、分支、部门、岗位、职级、负责人维护与可视化组织架构                                                            |
| 入转调离        | 入职、转正、调动和离职事件，支持业务日期、审批流转与幂等生效                                                          |
| 考勤管理        | 本人考勤记录、HR 月度报表、上下班打卡、迟到早退、缺卡和工作日统计                                                      |
| 电子围栏        | 多办公地点、地图点击/拖动选点、半径预览、地址搜索、GCJ-02 坐标及服务端范围校验（可按需开关「围栏校验」）                                             |
| 补卡管理        | PC/小程序补卡申请、月度次数限制、重复校验、统一审批、考勤回填与结果通知                                                   |
| 加班管理        | 加班申请、草稿编辑、附件上传、动态工时计算、审批记录及审批通过后生成调休                                                    |
| 休假管理        | 休假申请、职务代理人确认、审批流程、证明材料及权威余额校验                                                           |
| 假期余额        | 全员统一标准、员工个人额度、人工调整、有效期、余额明细与调休来源控制                                                      |
| 审批中心        | 加班、休假、补卡和员工生命周期待办/已办，支持业务详情、审批时间线与规则化审批人解析                                              |
| 审批规则        | 按部门和业务类型配置审批流程与审批节点，支持 `MAKEUP` 等工作流类型                                                  |
| 津贴管理        | 津贴记录、附件维护与 Excel 批量处理                                                                   |
| 节假日         | 法定节假日、调休日和补班日期维护，为考勤与工时计算提供依据                                                           |
| 系统设置        | 按 Tab 管理业务功能开关、工作制度、考勤、加班、假期和登录安全参数；功能开关同时约束 PC、微信小程序和后端接口                              |
| 考试管理        | 题库分类与题目维护、手工录题、按分类/题型随机组卷、考卷总分与及格分配置、考场/场次配置、考生绑定与专属二维码；客观题自动评分、简答题人工评卷；支持 PC 直连与手机扫码作答 |
| 通知中心        | 申请提交、审批待办、进度、通过/驳回消息，以及未读和已读管理                                                          |
| 报表中心        | 人事业务统计与可视化分析                                                                            |
| 个人中心        | 个人资料、账号安全、密码修改及本人假期余额                                                                   |
| 公告管理 / 公告中心 | 公告的标题、类型、有效期与状态维护；员工在公告中心查阅已发布公告                                                        |
| 审计日志        | 按操作人、模块检索系统操作留痕                                                                         |
| 数据健康检查      | 数据一致性与异常项体检，按错误/警告分级展示                                                                  |
| 劳动合同        | 合同编号、合同类型、期限、签订日期、状态与合同附件管理                                                             |
| 证明申请        | 在职/收入等证明的申请、用途与开具状态跟踪                                                                   |
| 员工关怀        | 关怀积分与积分记录、勋章定义与授予记录、积分排行                                                                |
| 绩效管理        | 考核周期、绩效目标与权重、绩效评分、360 评价                                                                |
| 招聘管理        | 招聘需求、候选人跟踪、面试安排与结果、Offer 管理                                                             |
| 培训管理        | 培训计划、课程安排与签到记录，课程可关联考卷                                                                  |
| 班次管理        | 班次上下班时间、迟到/早退宽容分钟数、默认班次与展示颜色                                                            |
| 排班表         | 按部门/员工安排每日班次                                                                            |
| q出差管理       | 出差申请单、目的地、起止日期、天数、交通工具、预估费用与附件                                                          |
| 报销管理        | 报销单与多明细（费用类别、金额、发生日期、发票凭证、说明）                                                           |
| 薪资核算        | 工资月份与计薪周期；薪资记录含基本工资、津贴、加班费、奖金、扣款、社保、公积金、个税与实发工资，并支持自定义薪资项目                              |
| 奖惩与福利       | 奖励/处罚登记（走审批生效，单号 RD- 前缀）、审批留痕与台账统计；生日/节日/婚育/慰问福利发放台账，转已发放自动通知员工                            |
| 移动办公（小程序）   | 手机登录、定位打卡、补卡、请假/加班、假期余额、统一审批和站内消息                                                       |

## 导航与设置

### PC 二级菜单

左侧导航按使用频率和业务相关性组织，路由地址保持不变：

| 导航层级   | 模块                                      |
| ------ | --------------------------------------- |
| 高频一级入口 | 工作台、审批中心、通知中心、公告中心                      |
| 组织人事   | 员工档案、组织架构、入转调离、劳动合同、奖惩与福利、招聘管理          |
| 员工自助   | 证明申请、员工关怀                               |
| 绩效发展   | 绩效管理                                    |
| 培训发展   | 培训管理                                    |
| 考勤休假   | 考勤管理、班次管理、排班表、出差管理、报销管理、休假管理、加班管理、节假日管理 |
| 薪酬数据   | 津贴管理、薪资核算、报表中心                          |
| 系统配置   | 组织设置、审批规则、系统设置、公告管理、审计日志、数据健康检查         |
| 考试管理   | 题库管理、考卷配置、考场配置、考生配置                     |

除一级入口外，所有业务模块都受功能开关约束：模块对应的业务开关关闭时菜单项自动隐藏，后端同时拒绝相关操作。

菜单会依据当前角色过滤；没有可访问子项的目录自动隐藏。当前页面所属目录自动展开，侧栏折叠时可通过弹出子菜单访问，移动端选择菜单后会自动关闭导航。

### 系统设置分类

系统设置使用六个 Tab 分隔展示：

| Tab  | 设置项                                                      |
| ---- | -------------------------------------------------------- |
| 功能管理 | 分别控制考勤打卡（含「围栏校验」子开关）、请假、加班三类业务及其审批；关闭业务时同步关闭审批，设置同时作用于 PC、微信小程序和后端接口 |
| 工作制度 | 上午/下午工作时段、每周工作周期和制度摘要                                    |
| 考勤规则 | 电子围栏、地图选点、地址搜索、打卡位置要求和每月补卡次数                                    |
| 加班规则 | 工作日每日上限、月累计上限、单次上限和默认加班时段                                |
| 假期规则 | 休假取整粒度、调休有效期和统一假期标准                                      |
| 登录安全 | 图形验证码开关                                                  |

基础参数由页面右上角统一保存；围栏和假期标准分别通过各自操作即时维护。功能管理保存后立即刷新 PC 菜单；小程序进入工作台或业务页面时获取最新配置。关闭业务后客户端入口隐藏且后端拒绝相关操作；仅关闭审批时暂停申请提交与审批处理，历史记录仍保留可查。

## 微信小程序端功能介绍

`hrms-wx` 是面向**全体员工**的移动办公入口，让员工不必登录 PC 即可在手机上处理人事事务。小程序与 `hrms-server` 后端共用同一套 JWT 鉴权与数据，和 PC 端数据实时互通。

### 功能地图

| 页面 / 模块  | 功能说明                                                  |
| -------- | ----------------------------------------------------- |
| 登录页      | 支持微信授权快速登录；已绑定账号可直接输入工号 / 手机号 + 密码登录，登录态本地持久化         |
| 首页（工作台）  | 展示待办审批、我的请假/加班概览、同事生日、公司公告等人事动态，提供考勤和业务快捷入口           |
| 考勤打卡     | 展示今日工作日、标准班次、上下班状态和定位信息；每次打卡重新获取 `GCJ-02` 坐标并由服务端校验围栏 |
| 补卡申请     | 选择日期、上/下班卡类型、拟补时间和原因，展示当月次数及申请历史，并进入统一审批流             |
| 我的（个人中心） | 查看个人信息、本人假期余额、账号安全入口，统一跳转各业务功能                        |
| 单据       | 我的请假、加班和补卡单据列表与详情，支持状态筛选、审批进度、驳回原因和材料附件               |
| 审批       | 待办/已办双标签；处理加班、休假、补卡等工作流，支持业务详情、同意、驳回和审批时间线            |
| 消息       | 站内通知中心，覆盖提交、待审批、审批进度和结果通知，支持未读提醒与已读管理                 |
| 请假申请     | 选择假种、日期区间与职务代理人；调用后端实时估算请假时长，支持上传证明材料                 |
| 加班申请     | 支持一天内多段加班明细（计划/实际起止）、读取系统工作时段计算时长，可上传附件               |
| 假期余额     | 汇总展示调休、年假等可用余额，逐条列出额度明细与有效期；未审批加班不产生调休                |
| 个人资料     | 维护个人资料、修改密码等账号安全设置                                    |

### 计算与一致性设计

- **工时计算动态读取系统设置**：请假 / 加班时长、起止时间均依据后端 `system_setting` 表中配置的工作时段（如上午 `08:30-12:00`、下午 `13:00-17:30`）与工作日规则计算，不写死固定上下班点，跟随管理后台设置实时变化。
- **假期余额同源**：余额页汇总与 PC 端一致，统一来自后端的 `LeaveBalanceService`，避免「首页显示 0、列表显示 5 天」这类口径不一致。
- **日期解析兼容**：接口接受 `2026-07-31 09:00:00` 与 `2026-07-31T09:00:00` 两种格式，避免解析失败导致 500。
- **本地估算 + 后端权威**：端内对工时、围栏距离做即时估算以提升交互体验，最终以后端返回值为准。
- **实时定位与围栏**：每次打卡重新调用 `wx.getLocation({ type: 'gcj02' })`，服务端根据启用围栏重新计算距离，客户端坐标和按钮状态不能绕过服务端校验。
- **补卡审批一致性**：补卡与加班、休假共用 `approval_task`，审批通过后才回填考勤；并发审批使用状态前置检查和数据库锁避免重复处理。
- **跨端功能开关**：小程序工作台、打卡、补卡、请假、加班及审批页面实时读取系统功能配置；PC 与小程序仅负责入口和操作可见性，后端对打卡、申请提交和审批处理进行最终强制校验。
- **调休来源控制**：调休余额统一读取 `leave_balance.remaining_amount`，只有审批通过且补偿方式为 `COMP_LEAVE` 的加班才能产生调休。

### 技术要点

- 原生小程序运行时（WXML / WXSS / JS），无需打包构建，导入微信开发者工具即可运行。
- 网络层基于 `wx.request` 封装，统一附加 `Authorization: Bearer <token>`；附件使用 `wx.uploadFile` 上传。
- 环境通过 `config/index.js` 的 `ENV` 切换（`dev` / `prod`），分别对应本地与线上 `baseUrl`。
- 底部导航使用 `custom-tab-bar` 自定义，红点提示审批与消息未读数。

### 安全能力

- Spring Security + JWT 无状态认证
- 登录密码使用一次性 RSA-OAEP-256 公钥加密传输
- 数据库密码使用 BCrypt 单向散列
- 可开关图形验证码
- 1 分钟内连续登录失败 5 次，临时锁定账号 5 分钟
- 管理员可查看锁定状态并手动解锁
- 登录过期统一返回 `401`，前端提示并引导重新登录
- 普通权限不足保持 `403`，不会错误清除登录状态
- 前端菜单、路由、操作入口与后端接口权限协同控制

## 角色权限

| 角色              | 主要权限                               |
| --------------- | ---------------------------------- |
| `EMPLOYEE` 普通员工 | 查看个人工作台、提交本人加班与休假、处理代理确认、查看通知和个人资料 |
| `MANAGER` 部门主管  | 普通员工能力、审批待办、查看员工及组织信息、访问管理报表       |
| `HR` 人事专员       | 员工与组织维护、假期额度、津贴、节假日、审批规则及系统业务参数管理  |
| `ADMIN` 系统管理员   | 系统全部管理能力、账号安全管理及锁定账号解锁             |

## 技术栈

### 后端

| 技术                | 版本 / 用途                 |
| ----------------- | ----------------------- |
| Java              | 17+                     |
| Spring Boot       | 3.3.2                   |
| Spring Security   | 身份认证与角色权限               |
| Spring JDBC       | 基于 `JdbcTemplate` 的数据访问 |
| MySQL             | 8.0（开发/生产环境）            |
| H2                | 2.2.224（内嵌模式，轻量部署）      |
| Flyway            | 数据库版本迁移                 |
| JJWT              | 0.12.6，JWT 签发与校验        |
| Apache POI        | 5.3.0，Excel 模板、导入与导出    |
| SpringDoc OpenAPI | 2.6.0，Swagger 接口文档      |
| Maven             | 项目构建与依赖管理               |

### 前端

| 技术           | 版本 / 用途             |
| ------------ | ------------------- |
| Vue          | 3.5                 |
| TypeScript   | 6.0                 |
| Vite         | 8.1                 |
| Element Plus | 2.14                |
| Pinia        | 4.0，状态管理            |
| Vue Router   | 5.2，路由与权限守卫         |
| Axios        | 1.19，HTTP 请求与登录过期拦截 |
| ECharts      | 6.1，数据可视化           |
| Day.js       | 日期时间格式化             |

### 微信小程序端

| 技术      | 版本 / 用途                                              |
| ------- | ---------------------------------------------------- |
| 微信小程序原生 | 基于 WXML / WXSS / JS 的运行时，无需构建工具                      |
| 微信开发者工具 | libVersion 3.4.0，真机预览与代码上传                           |
| 网络层     | `wx.request` 封装 + `wx.uploadFile` 上传附件，Bearer JWT 鉴权 |
| 本地存储    | `wx.setStorageSync` 持久化登录态（token / 用户 / 档案）          |
| 业务逻辑    | 工时计算、假期余额汇总、请假 / 加班时长估算均在端内封装                        |


## 项目结构

```text
HRMS/
├─ hrms-server/                         # Spring Boot 后端
│  ├─ src/main/java/com/asys/hrms/
│  │  ├─ auth/                          # 登录、验证码与账号锁定
│  │  ├─ security/                      # JWT 与安全配置
│  │  ├─ employee/                      # 员工管理与入转调离
│  │  ├─ organization/                  # 组织架构
│  │  ├─ attendance/                    # 考勤、围栏、补卡和地图地点搜索
│  │  ├─ overtime/                      # 加班管理
│  │  ├─ leave/                         # 休假与假期余额
│  │  ├─ approval/                      # 审批任务与规则
│  │  ├─ allowance/                     # 津贴管理
│  │  ├─ holiday/                       # 节假日管理
│  │  ├─ notification/                  # 通知中心
│  │  ├─ settings/                      # 系统设置
│  │  └─ excel/                         # Excel 导入导出
│  └─ src/main/resources/
│     ├─ application.yml                # 应用配置
│     └─ db/migration/                  # Flyway 迁移脚本
├─ hrms-web/                            # Vue 3 前端
│  └─ src/
│     ├─ views/                         # 业务页面
│     ├─ components/                    # 公共组件
│     ├─ layouts/                       # 页面布局
│     ├─ router/                        # 路由配置
│     ├─ stores/                        # Pinia 状态
│     └─ utils/                         # 请求、权限、字典工具
├─ hrms-wx/                             # 微信小程序端
│  ├─ pages/                            # 页面：登录、首页、我的、单据、审批、消息等
│  │  ├─ login/                         # 微信登录（手机号授权 + 账号绑定）
│  │  ├─ home/                          # 首页工作台，待办与人事动态概览
│  │  ├─ attendance/                    # 实时定位打卡与当月考勤
│  │  ├─ makeup/                        # 补卡申请与申请历史
│  │  ├─ leave-apply/                   # 请假申请，含时长自动估算
│  │  ├─ overtime-apply/                # 加班申请，支持多段明细与附件
│  │  ├─ balance/                       # 假期余额汇总与明细
│  │  ├─ profile/                       # 个人资料与安全设置
│  │  ├─ bills/                         # 请假 / 加班单据列表与详情
│  │  ├─ approval/                      # 待办 / 已办审批
│  │  ├─ message/                       # 站内消息中心
│  │  ├─ about/                         # 关于与版本信息
│  │  └─ mine/                          # 我的（个人中心入口）
│  ├─ components/                       # 业务组件（审批卡片、详情、tab-bar 等）
│  ├─ utils/                            # api、request、working-time 等封装
│  ├─ config/                           # 环境配置（dev / prod 的 baseUrl）
│  ├─ custom-tab-bar/                   # 自定义底部导航
│  ├─ app.js / app.json / app.wxss      # 小程序全局逻辑、页面与样式
│  └─ project.config.json              # 微信开发者工具项目配置
├─ 人事管理系统操作手册.md
├─ 人事管理系统新手初次启动手册.md
└─ README.md
```

## 快速开始


### 方式一：一体包部署（推荐，无需 MySQL）

适用于轻量服务器或快速体验，使用内嵌 H2 数据库，前端资源打包在 jar 中。

#### 1. 环境要求

| 环境  | 推荐版本     |
| --- | -------- |
| JDK | 17 或更高版本 |

#### 2. 构建一体包

```cmd
cd /d D:\OtherProject\HRMS
build-allinone.bat
```

或 Linux/Mac：

```bash
./build-allinone.sh
```

该脚本会自动：

1. 构建前端（`npm install && npm run build`）
2. 将前端产物复制到后端的 `static` 目录
3. 打包后端 jar（内嵌 H2 数据库，无需 MySQL）

#### 3. 启动应用

Windows：

```cmd
start-hrms.bat
```

或 Linux/Mac：

```bash
./start-hrms.sh
```

首次启动会自动创建 H2 数据库文件（`hrms-server/hrms-data/`）并执行全部数据迁移。

访问地址：`http://localhost:8080`

默认账号：`admin` / `Admin@123`

> 内嵌模式使用 `embedded` profile，数据保存在本地 H2 文件中。适合单机部署和快速体验；如需多实例或大数据量，建议使用方式二（MySQL）。

#### 4. Linux 服务器后台部署（H2 一体包）

将构建产物 `hrms-server-1.0.0.jar` 上传到服务器（示例目录 `/home/HRMS/`），指定 `embedded` Profile 并通过 `--server.port` 指定端口，使用 `nohup` 后台启动：

```bash
nohup /path/to/jdk/bin/java -jar /home/HRMS/hrms-server-1.0.0.jar \
  --spring.profiles.active=embedded \
  --server.port=18080 \
  > /home/HRMS/app.log 2>&1 &
```

查看启动日志：

```bash
tail -f /home/HRMS/app.log
```

确认端口监听：

```bash
ss -lntp | grep 18080
```

放行防火墙端口（firewalld 示例；云服务器还需在云平台安全组中放行对应端口）：

```bash
sudo firewall-cmd --permanent --add-port=18080/tcp
sudo firewall-cmd --reload
```

当前示例线上地址：

```text
http://39.96.73.55:18080/
```

> H2 数据文件保存在启动目录下的 `hrms-data/` 中，备份时请同时备份该目录；`embedded` Profile 下默认无需外部 MySQL。

---

### 方式二：开发环境（需要 MySQL）

#### 1. 环境要求

| 环境      | 推荐版本                          |
| ------- | ----------------------------- |
| JDK     | 17 或更高版本                      |
| Maven   | 3.9.x，或直接使用项目内的 Maven Wrapper |
| Node.js | 22 LTS，至少满足 Vite 8 的运行要求      |
| npm     | 随 Node.js 安装                  |
| MySQL   | 8.0                           |

Windows 新手可以参考 [《人事管理系统新手初次启动手册》](./人事管理系统新手初次启动手册.md)，其中包含 Java、Maven、Node.js、MySQL 及 phpStudy 的安装说明。

### 2. 准备数据库

确保 MySQL 8 已启动。默认开发配置如下：

```text
地址：localhost:3306
数据库：hrms
用户名：root
密码：root
```

数据库连接串启用了 `createDatabaseIfNotExist=true`。数据库账号具有建库权限时，首次启动会自动创建 `hrms` 数据库，并由 Flyway 执行全部表结构和初始化数据迁移。

如果本机密码不是 `root`，可通过环境变量覆盖：

```cmd
set DB_USERNAME=root
set DB_PASSWORD=你的数据库密码
```

也可同时自定义数据库地址：

```cmd
set DB_URL=jdbc:mysql://localhost:3306/hrms?createDatabaseIfNotExist=true^&useUnicode=true^&characterEncoding=utf8^&serverTimezone=Asia/Shanghai^&allowPublicKeyRetrieval=true^&useSSL=false
```

### 3. 启动后端

后端未显式指定 Profile 时默认使用 `dev`：本地数据库默认为 `localhost:3306/hrms`、账号密码为 `root/root`，并可通过前述 `DB_*` 环境变量覆盖。生产部署必须显式指定 `prod`，且必须提供数据库和 JWT 环境变量。

打开一个新的 `cmd` 窗口：

```cmd
cd /d D:\OtherProject\HRMS\hrms-server
mvnw.cmd spring-boot:run
```

如果已全局安装 Maven，也可以使用：

```cmd
mvn spring-boot:run
```

后端默认地址：

```text
http://localhost:8080
```

生产环境必须显式激活 `prod`：

```cmd
set SPRING_PROFILES_ACTIVE=prod
set DB_URL=jdbc:mysql://数据库地址:3306/hrms
set DB_USERNAME=生产数据库账号
set DB_PASSWORD=生产数据库密码
set JWT_SECRET=至少32字节的随机密钥
mvnw.cmd spring-boot:run
```

也可使用 `mvnw.cmd spring-boot:run -Dspring-boot.run.profiles=prod`。不要在生产环境省略 Profile，否则会按设计使用 `dev`。

Swagger 接口文档：

```text
http://localhost:8080/swagger-ui.html
```

### 4. 启动前端

再打开一个新的 `cmd` 窗口：

```cmd
cd /d D:\OtherProject\HRMS\hrms-web
npm ci
npm run dev
```

浏览器访问：

```text
http://localhost:5173
```

开发环境中，Vite 会将 `/api` 请求代理到 `http://localhost:8080`。

### 5. 运行微信小程序端

1. 用[微信开发者工具](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html)打开 `hrms-wx` 目录（已内置 `project.config.json`，AppID：`wx536861e25cc26da8`）。
2. 在微信开发者工具中勾选 **「不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书」**（开发阶段必须，否则无法访问 `localhost`）。
3. 确认 `hrms-wx/config/index.js` 中的环境为 `dev`，接口地址指向 `http://localhost:8080/api/v1`；若要连接正式环境，将 `ENV` 改为 `prod` 并填写对应域名。
4. 编译预览，使用小程序端「登录页」以演示账号（如 `employee / Employee@123`）登录即可进入工作台。

> 小程序登录与后端共用同一套 JWT；PC 端与小程序端可使用相同账号互通数据。

## 演示账号

Flyway 初始化数据包含以下本地演示账号：

| 角色    | 用户名        | 初始密码           |
| ----- | ---------- | -------------- |
| 系统管理员 | `admin`    | `Admin@123`    |
| 部门主管  | `manager`  | `Manager@123`  |
| 人事专员  | `hr`       | `Hr@123456`    |
| 普通员工  | `employee` | `Employee@123` |

> 演示账号仅供本地体验。正式环境必须修改或停用这些账号，并避免在公开环境使用默认密码。

## 配置说明

后端主配置位于：

```text
hrms-server/src/main/resources/application.yml
```

常用环境变量：

| 环境变量                          | 默认值                        | 说明                            |
| ----------------------------- | -------------------------- | ----------------------------- |
| `DB_URL`                      | 本机 `hrms` 数据库              | JDBC 数据库连接串                   |
| `DB_USERNAME`                 | `root`                     | 数据库用户名                        |
| `DB_PASSWORD`                 | `root`                     | 数据库密码                         |
| `SERVER_PORT`                 | `8080`                     | 后端服务端口                        |
| `JWT_SECRET`                  | 内置开发值                      | JWT 签名密钥                      |
| `JWT_EXPIRATION_HOURS`        | `12`                       | 登录令牌有效小时数                     |
| `APP_ATTACHMENT_STORAGE_PATH` | `./data/attachments`       | 附件保存目录                        |
| `WX_APP_ID`                   | 空                          | 微信小程序 AppID                   |
| `WX_APP_SECRET`               | 空                          | 微信小程序 AppSecret               |
| `WX_MOCK_ENABLED`             | `true`                     | 未配置微信凭据时是否启用本地模拟模式            |
| `AMAP_WEB_SERVICE_KEY`        | 空                          | 高德地图“Web 服务”类型 Key，用于电子围栏地点搜索 |
| `AMAP_API_BASE`               | `https://restapi.amap.com` | 高德 Web 服务 API 地址，一般无需修改       |

### 地图与地点搜索配置

电子围栏底图、地图点击、标记拖动和半径预览由 PC 前端 Leaflet 组件完成。地点关键词搜索由后端代理高德 Web 服务，以避免将 Key 暴露到浏览器。

1. 在高德开放平台创建应用并申请 **Web 服务** 类型 Key。
2. 启动后端前设置环境变量：

```cmd
set AMAP_WEB_SERVICE_KEY=你的高德Web服务Key
```

1. 重启后端，在“系统配置 → 系统设置 → 考勤规则 → 新增打卡范围”中搜索地点。

地图和微信小程序统一使用 `GCJ-02` 坐标。浏览器“定位当前位置”依赖 Windows 位置服务；台式机没有可用定位源时可能超时，不影响搜索地点、点击地图或拖动标记选点。

### 微信小程序配置

本地开发未配置 `WX_APP_ID`/`WX_APP_SECRET` 时，可通过 `WX_MOCK_ENABLED=true` 使用模拟模式。正式环境应设置真实凭据并关闭模拟模式：

```cmd
set WX_APP_ID=你的微信小程序AppID
set WX_APP_SECRET=你的微信小程序AppSecret
set WX_MOCK_ENABLED=false
```

正式发布还需要在微信公众平台配置合法的 HTTPS `request`、`uploadFile` 和 `downloadFile` 域名。开发者工具中的 `localhost` 仅适用于模拟器，真机连接本机后端时应使用局域网 IP 并允许防火墙访问。

生产环境至少应设置：

```cmd
set DB_URL=你的生产数据库连接串
set DB_USERNAME=你的数据库账号
set DB_PASSWORD=高强度数据库密码
set JWT_SECRET=长度足够且随机生成的JWT密钥
```

请勿将真实密码、密钥、员工隐私数据和生产环境配置提交到 Git 仓库。

## 数据库迁移

项目使用 Flyway 自动管理数据库版本，迁移脚本位于：

```text
hrms-server/src/main/resources/db/migration
```

应用启动时自动执行尚未运行的迁移。已经执行过的迁移文件不应直接修改；数据库结构发生变化时，应创建新的 `V{版本号}__描述.sql` 文件。

当前功能管理由 `V22__business_feature_switches.sql` 初始化，新增考勤、请假、加班三类业务及审批开关，默认均为启用。`system_setting` 的新增记录必须同时提供非空的 `value_type` 和 `category` 字段。若本地数据库曾执行过早期有误的 V22 并留下 `Failed` 记录，应先清理半成品数据，再执行 Flyway `repair` 后重新迁移；正常首次安装无需人工处理。

### 考试管理

四个 PC 配置页（位于侧边栏“考试管理”二级菜单，仅 `HR`/`ADMIN` 可见）：

1. **题库配置**：维护题目分类与题库题目，支持单选题、多选题、判断题、简答题及选项、正确答案和解析。
2. **考卷配置**：支持手工录题和从题库随机组卷；随机组卷可按分类、题型、数量和每题分值配置。新建考卷默认总分 `100`、及格分 `60`，题目或组卷规则的分值合计必须与配置总分一致。
3. **考场配置**：设置考试场次，关联已发布考卷，配置开放时间窗、考试限时、考场地点、座位数与及格分；支持开启/关闭、考生统计。
4. **考生配置**：为考场绑定考生，支持从员工批量导入或手动添加；每位考生生成专属考试二维码（含 `session`、`cand`、`token`）；支持重置、删除与简答题人工评卷。

考试作答与评卷逻辑：

- 考生通过专属链接进入考试，支持 **PC 浏览器直连**与**手机扫码**（微信浏览器或小程序 `web-view` 加载同一套响应式 H5 页面）。
- 服务端权威计时：考试开始时间以考生首次进入为准，截止时间为 `开始时间 + 限时` 与场次结束时间取早者；到时自动交卷。
- 客观题（单选/多选/判断）提交后自动评分；简答题标记“待评卷”，由 HR 在考生配置中评卷并发布总分。
- 状态机：`READY → STARTED → SUBMITTED/GRADED/EXPIRED`，防止重复提交；作答每 15 秒自动保存。
- 公开考试接口（`/api/v1/exam/public/**`）仅依赖考生 `token` 鉴权，已在 `SecurityConfig` 中放行，无需登录即可作答。

考试相关迁移：`V23__exam_paper.sql`（考卷/考题）、`V24__exam_session.sql`（考场/场次）、`V25__exam_candidate.sql`（考生/作答/成绩）、`V26__exam_question_bank.sql`（题库分类/题库题目/组卷规则）、`V27__remove_question_bank_default_score.sql`（移除题库默认分值）、`V28__exam_paper_configured_total_score.sql`（考卷配置总分）。

### V29 及以后

| 版本                                    | 说明                                                                             |
| ------------------------------------- | ------------------------------------------------------------------------------ |
| `V29`                                 | 人事字段校验约束                                                                       |
| `V30`                                 | 业务单号序号表                                                                        |
| `V31`                                 | 已上传附件的归属记录                                                                     |
| `V32`                                 | 同一业务单据仅保留单一待办审批任务                                                              |
| `V33` / `V34`                         | 审计日志表及其查询索引                                                                    |
| `V35` / `V36`                         | 登录锁定策略设置、审计日志保留期设置                                                             |
| `V37`                                 | 员工头像                                                                           |
| `V38` / `V39` / `V40`                 | 通知偏好、公告、登录页品牌配置                                                                |
| `V41`                                 | 劳动合同                                                                           |
| `V42`                                 | 班次与排班                                                                          |
| `V43` / `V44` / `V45`                 | 出差、费用报销、证明申请                                                                   |
| `V46` / `V47` / `V48` / `V49` / `V50` | 绩效、招聘、培训、薪资、员工关怀                                                               |
| `V51`                                 | 证明申请纳入审批流                                                                      |
| `V52` / `V53`                         | 绩效反馈、账号与员工绑定的唯一约束                                                              |
| `V54`                                 | 扩展功能开关（覆盖新增业务模块）                                                               |
| `V55`                                 | 登录尝试记录补充 IP 维度，支持按账号 + IP 复合锁定                                                 |
| `V56`                                 | 补 `leave_application.agent_id` 索引，避免附件鉴权中 `OR` 退化为全表扫描                         |
| `V57`                                 | 补 `leave_application.start_time`、`overtime_record.apply_date` 索引，支撑看板月份统计的范围查询 |
| `V58`                                 | 奖惩与福利：`reward_discipline`（奖惩记录，审批生效）、`welfare_record`（福利发放台账）及功能开关       |

## 构建与部署

### 后端构建

```cmd
cd /d D:\OtherProject\HRMS\hrms-server
mvnw.cmd clean package
```

构建产物：

```text
hrms-server/target/hrms-server-1.0.0.jar
```

运行 JAR：

```cmd
java -jar hrms-server\target\hrms-server-1.0.0.jar
```

### 前端构建

```cmd
cd /d D:\OtherProject\HRMS\hrms-web
npm ci
npm run build
```

构建产物：

```text
hrms-web/dist
```

生产环境建议使用 Nginx、IIS 或其他 Web 服务器托管 `dist`，并将 `/api` 反向代理到后端服务。

## 项目文档

- [更新日志](./CHANGELOG.md)：版本功能、新增配置、数据库迁移与问题修复记录
- [人事管理系统操作手册](./人事管理系统操作手册.md)：角色权限、业务流程与系统操作说明
- [人事管理系统新手初次启动手册](./人事管理系统新手初次启动手册.md)：Windows 环境安装、首次启动、构建部署与常见问题
- [后端模块说明](./hrms-server/README.md)
- [前端模块说明](./hrms-web/README.md)

## 常见问题

<details>

<summary><strong>启动后端时无法连接 MySQL</strong></summary>

确认 MySQL 服务已经启动，端口为 `3306`，并检查 `DB_USERNAME`、`DB_PASSWORD` 与实际账号一致。MySQL 账号还需具备创建和访问 `hrms` 数据库的权限。

</details>

<details>

<summary><strong>前端请求接口失败</strong></summary>

确认后端已在 `8080` 端口启动。开发环境由 Vite 自动代理 `/api`；如果修改了后端端口，需要同步修改 `hrms-web/vite.config.ts`。

</details>

<details>

<summary><strong>数据库表没有自动创建</strong></summary>

检查后端启动日志中的 Flyway 信息，并确认数据库账号具备建库和建表权限。不要手动删除 `flyway_schema_history`，除非明确了解迁移恢复流程。

</details>

<details>

<summary><strong>登录后提示账号被锁定</strong></summary>

同一账号在 1 分钟内连续输入错误密码 5 次会锁定 5 分钟。可等待自动解锁，或联系系统管理员在员工管理中手动解除锁定。

</details>

## 开发建议

1. 数据库变更统一通过新的 Flyway 迁移提交。
2. 新增接口时同步配置后端 `@PreAuthorize` 和前端操作可见性。
3. 不依赖前端隐藏实现安全控制，敏感接口必须在后端鉴权。
4. 提交前执行后端构建和前端类型检查：

```cmd
cd /d D:\OtherProject\HRMS\hrms-server
mvnw.cmd -DskipTests package

cd /d D:\OtherProject\HRMS\hrms-web
npm run build
```

## 联系方式

如果在使用、部署或二次开发过程中发现问题，或对项目有改进建议，欢迎通过以下方式联系：

- **创建 Issue**：请在当前 Gitee 仓库的 Issue 页面提交问题或建议。建议附上问题描述、复现步骤、运行环境及相关截图或错误日志，便于快速定位。
- **发送邮件**：[`1125196499@qq.com`](mailto:1125196499@qq.com?subject=HRMS%20人事管理系统问题反馈)

发送邮件时，请在邮件标题或正文中注明：

```text
项目名称：HRMS 人事管理系统
问题类型：功能异常 / 启动部署 / 使用建议 / 其他
问题描述：请描述操作步骤、预期结果和实际结果
环境信息：操作系统、Java、Node.js、MySQL 版本
```

> 为保护数据安全，请勿在公开 Issue 或邮件中发送数据库密码、JWT 密钥、真实员工隐私数据等敏感信息。

## License

本项目基于 [Apache License 2.0](./LICENSE) 开源。

---

<div align="center">

如果这个项目对你有帮助，欢迎在 Gitee 点一个 Star。  

  
有问题或建议，欢迎提交 Issue 或发送邮件交流。

</div>