feat(hrm): 新增我的考勤状态接口并开放全员打卡

gaoluyang

5 小时以前 e4432d49f9d74e69cc71ed1141ebcd30c817e998

 yudao-module-hrm/src/main/java/cn/iocoder/yudao/module/hrm/controller/admin/attendance/HrmAttendanceRecordController.java

@@ -7,27 +7,35 @@
import cn.iocoder.yudao.framework.common.pojo.PageResult;
import cn.iocoder.yudao.framework.common.util.object.BeanUtils;
import cn.iocoder.yudao.framework.excel.core.util.ExcelUtils;
import cn.iocoder.yudao.framework.operatelog.core.util.OperateLogUtils;
import cn.iocoder.yudao.module.hrm.controller.admin.attendance.vo.HrmAttendanceMyStatusRespVO;
import cn.iocoder.yudao.module.hrm.controller.admin.attendance.vo.HrmAttendanceRecordImportExcelVO;
import cn.iocoder.yudao.module.hrm.controller.admin.attendance.vo.HrmAttendanceRecordImportReqVO;
import cn.iocoder.yudao.module.hrm.controller.admin.attendance.vo.HrmAttendanceRecordPageReqVO;
import cn.iocoder.yudao.module.hrm.controller.admin.attendance.vo.HrmAttendanceRecordRespVO;
import cn.iocoder.yudao.module.hrm.dal.dataobject.attendance.HrmAttendanceRecordDO;
import cn.iocoder.yudao.module.hrm.dal.dataobject.employee.HrmEmployeeDO;
import cn.iocoder.yudao.module.hrm.enums.HrmAttendanceClockTypeEnum;
import cn.iocoder.yudao.module.hrm.service.attendance.HrmAttendanceRecordService;
import cn.iocoder.yudao.module.hrm.service.employee.HrmEmployeeService;
import cn.iocoder.yudao.module.system.api.dept.DeptApi;
import cn.iocoder.yudao.module.system.api.dept.dto.DeptRespDTO;
import cn.iocoder.yudao.module.system.api.user.AdminUserApi;
import cn.iocoder.yudao.module.system.api.user.dto.AdminUserRespDTO;
import com.mzt.logapi.starter.annotation.LogRecord;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.annotation.Resource;
import jakarta.servlet.http.HttpServletResponse;
import jakarta.validation.Valid;
import org.springframework.format.annotation.DateTimeFormat;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

import java.io.IOException;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.util.*;
import java.util.stream.Collectors;
@@ -35,7 +43,9 @@
import static cn.iocoder.yudao.framework.apilog.core.enums.OperateTypeEnum.EXPORT;
import static cn.iocoder.yudao.framework.common.exception.util.ServiceExceptionUtil.exception;
import static cn.iocoder.yudao.framework.common.pojo.CommonResult.success;
import static cn.iocoder.yudao.framework.common.util.date.DateUtils.FORMAT_YEAR_MONTH_DAY;
import static cn.iocoder.yudao.module.hrm.enums.ErrorCodeConstants.EMPLOYEE_NOT_EXISTS;
import static cn.iocoder.yudao.module.hrm.enums.LogRecordConstants.*;

@Tag(name = "管理后台 - HRM 考勤记录")
@RestController
@@ -54,36 +64,46 @@

    @PostMapping("/clock-in")
    @Operation(summary = "上班打卡")
    @PreAuthorize("@ss.hasPermission('hrm:attendance:clock')")
    public CommonResult<HrmAttendanceRecordRespVO> clockIn(@RequestParam("location") String location) {
        Long loginUserId = getLoginUserId();
        HrmEmployeeDO employee = employeeService.getEmployeeByUserId(loginUserId);
        if (employee == null) {
            throw exception(EMPLOYEE_NOT_EXISTS, "当前用户未关联员工信息，无法打卡");
            throw exception(EMPLOYEE_NOT_EXISTS,
                    "当前登录账号未关联员工档案，无法打卡。请联系管理员在【员工管理】中将该登录账号绑定到员工。");
        }
        HrmAttendanceRecordDO record = attendanceRecordService.clockIn(employee.getId(), LocalDateTime.now(), location);
        HrmAttendanceRecordRespVO respVO = BeanUtils.toBean(record, HrmAttendanceRecordRespVO.class);
        respVO.setUserName(employee.getName());
        if (record.getDeptId() != null) {
            DeptRespDTO dept = deptApi.getDept(record.getDeptId());
            if (dept != null) {
                respVO.setDeptName(dept.getName());
            }
        }
        return success(respVO);
        return success(buildClockRespVO(record, employee));
    }

    @PostMapping("/clock-out")
    @Operation(summary = "下班打卡")
    @PreAuthorize("@ss.hasPermission('hrm:attendance:clock')")
    public CommonResult<HrmAttendanceRecordRespVO> clockOut(@RequestParam("location") String location) {
        Long loginUserId = getLoginUserId();
        HrmEmployeeDO employee = employeeService.getEmployeeByUserId(loginUserId);
        if (employee == null) {
            throw exception(EMPLOYEE_NOT_EXISTS, "当前用户未关联员工信息，无法打卡");
            throw exception(EMPLOYEE_NOT_EXISTS,
                    "当前登录账号未关联员工档案，无法打卡。请联系管理员在【员工管理】中将该登录账号绑定到员工。");
        }
        HrmAttendanceRecordDO record = attendanceRecordService.clockOut(employee.getId(), LocalDateTime.now(), location);
        return success(buildClockRespVO(record, employee));
    }

    @GetMapping("/my-status")
    @Operation(summary = "获得当前登录人的考勤状态")
    @Parameter(name = "date", description = "考勤日期，格式 yyyy-MM-dd，默认服务器当天", example = "2026-10-17")
    public CommonResult<HrmAttendanceMyStatusRespVO> getMyStatus(
            @RequestParam(value = "date", required = false)
            @DateTimeFormat(pattern = FORMAT_YEAR_MONTH_DAY) LocalDate date) {
        return success(attendanceRecordService.getMyStatus(getLoginUserId(), date));
    }

    /**
     * 构建打卡返回 VO，字段与 my-status.record 保持一致
     */
    private HrmAttendanceRecordRespVO buildClockRespVO(HrmAttendanceRecordDO record, HrmEmployeeDO employee) {
        HrmAttendanceRecordRespVO respVO = BeanUtils.toBean(record, HrmAttendanceRecordRespVO.class);
        respVO.setClockInTypeName(HrmAttendanceClockTypeEnum.getNameByType(record.getClockInType()));
        respVO.setClockOutTypeName(HrmAttendanceClockTypeEnum.getNameByType(record.getClockOutType()));
        respVO.setUserName(employee.getName());
        if (record.getDeptId() != null) {
            DeptRespDTO dept = deptApi.getDept(record.getDeptId());
@@ -91,7 +111,7 @@
                respVO.setDeptName(dept.getName());
            }
        }
        return success(respVO);
        return respVO;
    }

    private Long getLoginUserId() {
@@ -100,7 +120,7 @@

    @GetMapping("/page")
    @Operation(summary = "获得考勤记录分页")
    @PreAuthorize("@ss.hasPermission('hrm:attendance:query')")
    @PreAuthorize("@ss.hasPermission('hrm:attendance-record:query')")
    public CommonResult<PageResult<HrmAttendanceRecordRespVO>> getAttendanceRecordPage(@Valid HrmAttendanceRecordPageReqVO pageReqVO) {
        PageResult<HrmAttendanceRecordDO> pageResult = attendanceRecordService.getAttendanceRecordPage(pageReqVO);
        // 转换为 VO
@@ -142,6 +162,7 @@
            HrmEmployeeDO employee = employeeMap.get(respVO.getUserId());
            if (employee != null) {
                respVO.setUserName(employee.getName());
                respVO.setPhone(employee.getPhone());
            }
            // 部门名称
            DeptRespDTO dept = deptMap.get(respVO.getDeptId());
@@ -154,7 +175,7 @@
    @GetMapping("/get")
    @Operation(summary = "获得考勤记录")
    @Parameter(name = "id", description = "记录ID", required = true)
    @PreAuthorize("@ss.hasPermission('hrm:attendance:query')")
    @PreAuthorize("@ss.hasPermission('hrm:attendance-record:query')")
    public CommonResult<HrmAttendanceRecordRespVO> getAttendanceRecord(@RequestParam("id") Long id) {
        HrmAttendanceRecordDO attendanceRecord = attendanceRecordService.getAttendanceRecord(id);
        if (attendanceRecord == null) {
@@ -166,6 +187,7 @@
            HrmEmployeeDO employee = employeeService.getEmployee(attendanceRecord.getUserId());
            if (employee != null) {
                respVO.setUserName(employee.getName());
                respVO.setPhone(employee.getPhone());
            }
        }
        if (attendanceRecord.getDeptId() != null) {
@@ -177,9 +199,118 @@
        return success(respVO);
    }

    @GetMapping("/get-import-template")
    @Operation(summary = "下载考勤记录导入模板")
    @PreAuthorize("@ss.hasPermission('hrm:attendance-record:import')")
    public void importTemplate(HttpServletResponse response) throws IOException {
        List<HrmAttendanceRecordImportExcelVO> list = Collections.singletonList(
                HrmAttendanceRecordImportExcelVO.builder()
                        .userName("张三")
                        .phone("13800138000")
                        .date(java.time.LocalDate.of(2026, 1, 15))
                        .clockInTime(java.time.LocalDateTime.of(2026, 1, 15, 8, 30))
                        .clockOutTime(java.time.LocalDateTime.of(2026, 1, 15, 17, 30))
                        .clockInType(1)
                        .clockOutType(1)
                        .location("办公区")
                        .remark("示例数据")
                        .build()
        );
        ExcelUtils.write(response, "考勤导入模板.xls", "考勤记录", HrmAttendanceRecordImportExcelVO.class, list);
    }

    @PostMapping("/import")
    @Operation(summary = "导入考勤记录")
    @PreAuthorize("@ss.hasPermission('hrm:attendance-record:import')")
    @LogRecord(type = HRM_ATTENDANCE_RECORD_TYPE, subType = HRM_ATTENDANCE_RECORD_IMPORT_SUB_TYPE, bizNo = "0",
            success = HRM_ATTENDANCE_RECORD_IMPORT_SUCCESS)
    public CommonResult<String> importExcel(@Valid HrmAttendanceRecordImportReqVO importReqVO) throws IOException {
        List<HrmAttendanceRecordImportExcelVO> list = ExcelUtils.read(importReqVO.getFile(), HrmAttendanceRecordImportExcelVO.class);
        if (CollUtil.isEmpty(list)) {
            // 记录导入结果汇总，供 @LogRecord 的 success 文案引用
            OperateLogUtils.putImportSummary(0, null, null);
            return success("没有可导入的数据");
        }
        int successCount = 0;
        int createCount = 0; // 新增的记录数
        int updateCount = 0; // 更新的记录数（仅勾选「支持更新」时才会走更新）
        Set<String> missingNames = new LinkedHashSet<>();
        Set<String> duplicateNames = new LinkedHashSet<>();
        Set<String> invalidRows = new LinkedHashSet<>();
        for (HrmAttendanceRecordImportExcelVO item : list) {
            if (item.getDate() == null) {
                invalidRows.add((item.getUserName() == null || item.getUserName().isBlank()) ? "未填姓名的行" : "考勤日期为空(" + item.getUserName().trim() + ")");
                continue;
            }
            if (item.getUserName() == null || item.getUserName().isBlank()) {
                invalidRows.add("考勤日期为 " + item.getDate() + " 但未填员工姓名");
                continue;
            }
            List<HrmEmployeeDO> employees = employeeService.getEmployeeListByName(item.getUserName().trim());
            if (employees.isEmpty()) {
                missingNames.add(item.getUserName().trim());
                continue;
            }
            HrmEmployeeDO employee = employees.get(0);
            // 存在多个同名员工时，用手机号区分
            if (employees.size() > 1) {
                String phone = item.getPhone() != null ? item.getPhone().trim() : null;
                List<HrmEmployeeDO> matchedByPhone = new ArrayList<>();
                if (phone != null && !phone.isEmpty()) {
                    for (HrmEmployeeDO emp : employees) {
                        if (phone.equals(emp.getPhone())) {
                            matchedByPhone.add(emp);
                        }
                    }
                }
                if (matchedByPhone.size() == 1) {
                    employee = matchedByPhone.get(0);
                } else {
                    duplicateNames.add(item.getUserName().trim());
                    continue;
                }
            }
            HrmAttendanceRecordDO record = attendanceRecordService.getAttendanceRecordByUserIdAndDate(employee.getId(), item.getDate());
            if (record == null) {
                record = HrmAttendanceRecordDO.builder()
                        .userId(employee.getId()).deptId(employee.getDeptId()).date(item.getDate())
                        .clockInTime(item.getClockInTime()).clockOutTime(item.getClockOutTime())
                        .clockInType(item.getClockInType()).clockOutType(item.getClockOutType())
                        .location(item.getLocation()).remark(item.getRemark())
                        .dataSource(2).build();
                attendanceRecordService.createImportedRecord(record);
                createCount++;
            } else if (Boolean.TRUE.equals(importReqVO.getUpdateSupport())) {
                record.setClockInTime(item.getClockInTime());
                record.setClockOutTime(item.getClockOutTime());
                record.setClockInType(item.getClockInType());
                record.setClockOutType(item.getClockOutType());
                record.setLocation(item.getLocation());
                record.setRemark(item.getRemark());
                attendanceRecordService.updateImportedRecord(record);
                updateCount++;
            }
            successCount++;
        }
        StringBuilder msg = new StringBuilder("成功导入 " + successCount + " 条");
        if (!missingNames.isEmpty()) {
            msg.append("；以下员工不存在，未能导入：").append(String.join("、", missingNames));
        }
        if (!duplicateNames.isEmpty()) {
            msg.append("；以下员工存在多名同名员工，需补充手机号区分，未能导入：").append(String.join("、", duplicateNames));
        }
        if (!invalidRows.isEmpty()) {
            msg.append("；以下记录数据不完整，未能导入：").append(String.join("、", invalidRows));
        }
        // 记录导入结果汇总，供 @LogRecord 的 success 文案引用
        OperateLogUtils.putImportSummary(createCount, updateCount,
                missingNames.size() + duplicateNames.size() + invalidRows.size());
        return success(msg.toString());
    }

    @GetMapping("/export-excel")
    @Operation(summary = "导出考勤记录 Excel")
    @PreAuthorize("@ss.hasPermission('hrm:attendance:export')")
    @PreAuthorize("@ss.hasPermission('hrm:attendance-record:export')")
    @ApiAccessLog(operateType = EXPORT)
    public void exportAttendanceRecordExcel(@Valid HrmAttendanceRecordPageReqVO pageReqVO,
                                              HttpServletResponse response) throws IOException {