# HRM 请假导入 / 加班代申请 / 批量排班 / 考勤重算 —— 联调说明(2026-11-08) ## 涉及页面 - 人事审批 → 请假申请(`hrm/leave/index`) - 人事审批 → 加班申请(`hrm/overtime/index`) - 考勤管理 → 排班管理(`hrm/schedule/index`) - 考勤管理 → 考勤统计汇总 ## 一、请假 Excel 导入 ### API | 方法 | 路径 | 权限 | 说明 | |------|------|------|------| | GET | `/hrm/leave/import-template` | `hrm:leave:import` | 下载导入模板(含示例行) | | POST | `/hrm/leave/import` | `hrm:leave:import` | multipart 上传,字段名 `file` | **模板列(顺序固定):** | 列 | 必填 | 说明 | |----|------|------| | 手机号 | 是 | 按手机号匹配员工档案;填员工档案里登记的 11 位手机号 | | 员工姓名 | 否 | 填写后会与手机号匹配到的员工姓名核对,不一致该行失败 | | 请假类型 | 是 | 事假/病假/年假/婚假/产假/丧假,或数字 1-6 | | 开始时间 | 是 | `yyyy-MM-dd HH:mm` 或 `yyyy-MM-dd HH:mm:ss`;也可只填日期 | | 结束时间 | 是 | 必须晚于开始时间 | | 请假时长(天) | 是 | 大于 0,支持 0.5 | | 请假原因 | 是 | ≤500 字 | | 备注 | 否 | ≤500 字 | **响应:** ```json { "code": 0, "data": { "totalCount": 10, "successCount": 8, "failureCount": 2, "failures": [ { "rowNum": 3, "phone": "13800138000", "employeeName": "张三", "reason": "手机号[13800138000]未匹配到员工档案,请先在「员工档案」中维护该手机号后重新导入" } ] } } ``` ### 业务规则 - **逐行独立处理**:某一行失败不影响其它行;失败原因精确到「维度 + 实际值 + 下一步动作」。 - **只生成草稿**:导入成功的数据状态为草稿(0),不会自动发起审批;需在列表逐条点「提交」。 - 员工档案必须同时满足:手机号存在、已绑定系统账号、已设置部门。 - 同一文件内不做过重校验;如需防重,按「手机号 + 开始时间」人工核对。 - 行号 `rowNum` 含表头(表头为第 1 行)。 ## 二、加班代申请 ### 变更 | 项目 | 说明 | |------|------| | 新增权限 | `hrm:overtime:manage`(菜单 1075664,已授予角色 166 生产管理员、168 经理) | | `POST /hrm/overtime/create` | `SaveReqVO` 新增 `employeeId`(申请人员工ID);不传=本人 | | 页面 | 表单新增「代申请员工」选择器,仅持有 `hrm:overtime:manage` 时显示 | ### 权限效果 | 是否持有权限 | 列表 | 详情 | 修改/删除/提交/撤销 | |--------------|------|------|---------------------| | 否 | 仅本人单子 | 本人或流程参与人 | 仅本人草稿/驳回单 | | 是 | 全部人的单子 | 全部 | 全部人的单子 | ### 校验与错误提示 - 无权限却指定他人:`无权为其他员工代申请加班:当前账号未持有 hrm:overtime:manage 权限,请移除申请人(改为本人)或联系管理员授予该权限` - 指定员工不存在:`所选申请人的员工档案不存在,请刷新员工列表后重新选择` - 无权限操作他人单子:`无权操作该加班申请:当前账号既不是申请人,也未持有 hrm:overtime:manage 权限` ### 流程发起人 代申请提交后,BPM 流程实例以**申请人员工对应的系统账号**发起(不是代申请人),撤销同样以申请人身份执行,保证审批流中的申请人、待办归属正确。 ## 三、批量排班 ### API | 方法 | 路径 | 权限 | 说明 | |------|------|------|------| | POST | `/hrm/employee-schedule/batch-assign` | `hrm:employee-schedule:save` | 按部门(含下级)+ 岗位 + 员工状态批量排班 | | GET | `/hrm/employee-schedule/leave-list` | 登录即可 | 排班页请假标记(已审批,按天展开) | **批量排班请求:** | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | deptId | Long | 是 | 部门ID,后端自动包含所有下级部门 | | postId | Long | 否 | 岗位ID;按员工档案 `postIds` 判断,不传=不限 | | employeeStatus | Integer | 否 | 1 在职 / 2 试用 / 3 离职;不传=不限 | | startDate | LocalDate | 是 | 开始日期(含) | | endDate | LocalDate | 是 | 结束日期(含),单次最多 62 天 | | shiftId | Long | 是 | 班次ID | | remark | String | 否 | 写入排班的备注 | **响应:** ```json { "matchedEmployeeCount": 12, "scheduledCount": 240, "skippedLeaveCount": 3, "clearedRestDayCount": 96 } ``` ### 排班规则(按优先级) 1. **节假日配置优先**:`hrm_attendance_holiday` 中配置覆盖的日期,以配置的类型为准(工作日/休息日);没有配置时才按周六日判断。 2. **工作日**:写入所选班次;已有排班则覆盖。 3. **休息日/节假日**:清空该员工当天的班次。 4. **已审批请假优先**:员工当天存在审批通过(status=20)的请假单时,**跳过该单元格**,不改动原有排班,也不计入写入/清空数量。 5. 单次日期区间超过 62 天会拒绝,分批执行。 ### 唯一键与逻辑删除 `hrm_employee_schedule` 的唯一键 `uk_employee_date(employee_id, date)` **不包含 `deleted`**。逻辑删除后的旧行仍占用唯一键。因此保存/批量排班时: 1. 先用包含已删除行的原始 SQL 查询该员工该日期的记录; 2. 如果命中已删除行,执行 `UPDATE ... SET deleted = 0`「复活」并覆盖班次,**不再 INSERT**; 3. 只有完全不存在记录时才 INSERT。 这样避免「删过一次再排同一天」撞唯一键导致整批事务回滚。 ## 四、排班页 | 功能 | 说明 | |------|------| | 请假标记 | 已审批请假的单元格显示紫色「请假」标签,并在图例中增加「请假(已审批)」紫色说明;悬停显示请假类型 | | 改格子即保存 | 选完班次后立即调用 `/hrm/employee-schedule/save` 保存该单元格;失败时恢复原值并提示 | | 切换条件禁止保存 | 切换月份/部门后若未重新点「查询排班」,保存按钮禁用、单元格不可编辑,并显示橙色提示条 | | 批量排班入口 | 工具栏「批量排班」弹窗:岗位、员工状态、日期区间、班次;执行后自动刷新当前页 | ## 五、考勤汇总重算 - **查询时重算**:`/hrm/attendance/summary/page`、`/get`、部门月度列表在返回前,按**当前最新节假日配置**重算 `workDays`,与库中值不同时回写。 - **生成时重算**:`/hrm/attendance/summary/generate` 原本就按节假日配置计算,保持不变。 - 同一次请求内同一年月只计算一次,避免 N 次遍历日历。 - 年月的格式必须为 `yyyy-MM`;脏数据会跳过并记录 WARN,不影响其它行返回。 ## 六、数据与配置变更 - `docs/sql/config_export_all_20261108.sql`:在 20261106 版本基础上追加 2026-11-08 权限段(阶段二)。 - `sql/mysql/hrm_20261108_menu_permissions.sql`:本次新增的两条权限、角色授权,可单独执行。 - 新增菜单: - 1075663 `请假申请-导入` / `hrm:leave:import`(父菜单 6003),授予角色 163-168 - 1075664 `加班代申请管理` / `hrm:overtime:manage`(父菜单 1065211),授予角色 166、168 ## 注意事项 - `hrm:overtime:manage`、`hrm:leave:import` 属于**按钮权限**,需要重新登录(或刷新权限缓存)后前端按钮才会显示。 - 请假导入只创建草稿,附件无法通过 Excel 带入;如审批需要附件,请导入后在详情中补充。 - 批量排班会清空休息日已有班次,属于覆盖式操作;执行前请确认日期区间。 - 排班页的「自动排班」仍是前端本地生成(按双休/单休规则),不会跳过请假;需要按节假日 + 请假跳过时请使用「批量排班」。