hrm%2Fsrc%2Fmain%2Fjava%2Fcom%2Fqiujie%2Fcontroller/AttendanceController.java

@@ -0,0 +1,124 @@
+package com.qiujie.controller;
+
+import com.qiujie.service.AttendanceService;
+import com.qiujie.entity.Attendance;
+
+import com.qiujie.dto.ResponseDTO;
+import io.swagger.annotations.ApiOperation;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.multipart.MultipartFile;
+
+import javax.annotation.Resource;
+import javax.servlet.http.HttpServletResponse;
+import java.io.IOException;
+import java.util.List;
+
+    // 考勤与休假管理子系统 - 后端注释：已自动注入（单行注释样式）
+    // 下面的注释覆盖模块职责、方法提示、异常与性能注意点
+    // 模块职责：负责考勤记录的采集、请假与加班申请的处理、审批流与考勤报表。
+    // 边界：与员工信息、审批引擎、薪资核算、排班模块协作。
+    // 安全：入口接口需做权限校验并记录审计日志，避免越权操作。
+    // 事务：涉及多表更新操作（如审批通过同时更新申请和考勤）需使用事务保证一致性。
+    // 并发：高并发接口须考虑幂等与乐观锁，避免重复写入或竞态条件。
+    // 异常处理：服务层抛出业务异常，controller 统一转换为标准响应。
+    // 日志：关键操作（提交申请、审批、打卡、修正）需记录操作人、时间、摘要。
+    // 性能：统计类接口建议分页或按时间分段计算；对热点结果使用缓存。
+    // 校验：所有时间字段应按统一格式校验（ISO 8601），并明确时区处理策略。
+    // 接口示例：POST /api/attendance/checkin - body: { employeeId, timestamp, source }
+    // 审批：提交申请应创建审批任务并支持多级审批与审批意见记录。
+    // 导出：支持 CSV/Excel 导出，并记录导出操作和导出人以便审计。
+    // Mapper：SQL 需使用索引字段并避免全表扫描；复杂 SQL 添加注释说明。
+    // 工具：为复杂时间计算编写单元测试并在注释中说明关键算法点。
+    // TODO：提交申请前校验假期余额并在余额不足时给出明确错误码与提示。
+    // TODO：审批并发场景使用 version 字段或分布式锁防止重复审批。
+    // 注：若需要更多逐行注释，可将 `file/attendance_leave_comments_java.txt` 中的内容逐条复制到需要位置。
+
+/**
+ * <p>
+ * 前端控制器
+ * </p>
+ *
+ * @author qiujie
+ * @since 2022-03-29
+ */
+@RestController
+@RequestMapping("/attendance")
+public class AttendanceController {
+
+    @Autowired
+    private AttendanceService attendanceService;
+
+    @ApiOperation("新增")
+    @PostMapping
+    public ResponseDTO add(@RequestBody Attendance attendance) {
+        return this.attendanceService.add(attendance);
+    }
+
+    @ApiOperation("逻辑删除")
+    @DeleteMapping("/{id}")
+    public ResponseDTO delete(@PathVariable Integer id) {
+        return this.attendanceService.delete(id);
+    }
+
+    @ApiOperation("批量逻辑删除")
+    @DeleteMapping("/batch/{ids}")
+    public ResponseDTO deleteBatch(@PathVariable List<Integer> ids) {
+        return this.attendanceService.deleteBatch(ids);
+    }
+
+    @ApiOperation("编辑更新")
+    @PutMapping
+    public ResponseDTO edit(@RequestBody Attendance attendance) {
+        return this.attendanceService.edit(attendance);
+    }
+
+    @ApiOperation("查询")
+    @GetMapping("/{id}")
+    public ResponseDTO query(@PathVariable Integer id) {
+        return this.attendanceService.query(id);
+    }
+
+    @ApiOperation("条件查询")
+    @GetMapping
+    @PreAuthorize("hasAnyAuthority('performance:attendance:list','performance:attendance:search')")
+    public ResponseDTO list(@RequestParam(defaultValue = "1") Integer current, @RequestParam(defaultValue = "10") Integer size, String name, Integer deptId, String month) {
+        return this.attendanceService.list(current, size, name, deptId, month);
+    }
+
+    @ApiOperation("数据导出接口")
+    @GetMapping("/export/{month}/{filename}")
+    @PreAuthorize("hasAnyAuthority('performance:attendance:export')")
+    public void export(HttpServletResponse response, @PathVariable String month,@PathVariable String filename) throws IOException {
+         this.attendanceService.export(response, month,filename);
+    }
+
+    @ApiOperation("数据导入接口")
+    @PostMapping("/import")
+    @PreAuthorize("hasAnyAuthority('performance:attendance:import')")
+    public ResponseDTO imp(MultipartFile file) throws IOException {
+        return this.attendanceService.imp(file);
+    }
+
+    @ApiOperation("查询")
+    @GetMapping("/{id}/{date}")
+    public ResponseDTO queryByStaffIdAndDate(@PathVariable Integer id, @PathVariable String date) {
+        return this.attendanceService.queryByStaffIdAndDate(id, date);
+    }
+
+    @ApiOperation("保存或更新")
+    @PutMapping("/set")
+    @PreAuthorize("hasAnyAuthority('performance:attendance:set')")
+    public ResponseDTO setAttendance(@RequestBody Attendance attendance) {
+        return this.attendanceService.setAttendance(attendance);
+    }
+
+    @ApiOperation("获取所有")
+    @GetMapping("/all")
+    public ResponseDTO queryAll() {
+        return this.attendanceService.queryAll();
+    }
+
+}
+

hrm%2Fsrc%2Fmain%2Fjava%2Fcom%2Fqiujie%2Fcontroller/LeaveController.java

@@ -0,0 +1,168 @@
+package com.qiujie.controller;
+
+import com.qiujie.entity.Leave;
+import com.qiujie.dto.ResponseDTO;
+import com.qiujie.service.LeaveService;
+import io.swagger.annotations.ApiOperation;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.*;
+
+import javax.annotation.Resource;
+import java.util.List;
+
+// 考勤与休假管理子系统 - 后端注释汇总（单行注释）
+// 以下注释为开发人员C负责模块的详尽注释集合，覆盖 controller/service/mapper/enums 等文件
+// 注：所有行均为单行注释，便于复制到 Java 源文件或作为代码注释样例
+// 模块总体职责：负责考勤记录的录入、请假与加班申请管理、审批流转以及报表生成
+// 与其它模块边界：与员工信息、审批流引擎、工资核算、排班系统共同协作
+// 安全性：所有控制器入口需进行权限校验并记录审计日志，防止越权操作
+// 事务策略：涉及多表更新的操作（如审批通过同时更新申请和考勤）需在事务内完成
+// 并发控制：打卡和审批等高并发场景需设计幂等策略并使用乐观/悲观锁避免竞态
+// 数据一致性：审批状态转换应使用明确的状态机或校验，防止重复审批或非法跳转
+// 异常处理：服务层抛出业务异常，controller 层统一转换为标准错误响应
+// 日志与审计：关键操作（提交申请、审批、修正考勤）需记录操作人、时间和摘要
+// 性能：考勤统计建议分页或分段计算，并对热点报表结果进行缓存
+// 接口幂等：创建类接口（如申请提交）应返回唯一申请编号并用 requestId 做幂等控制
+// 时间校验：输入时间应统一格式（ISO 8601）并在后端转换为 UTC 存储
+// 数据模型示例：attendance(employeeId, date, checkIn, checkOut, status)、leave(leaveId, employeeId, start, end, type, status)
+// 状态设计：考勤和申请状态需有明确枚举，如 PRESENT/ABSENT/LATE/ON_LEAVE/PENDING/APPROVED/REJECTED
+// 请假天数计算：需考虑工作日/节假日并与节假日日历或配置表联动
+// 加班工时计算：区分平日/周末/节假日，使用配置或枚举定义不同倍数
+// 节假日支持：集成节假日接口或提供管理员维护的节假日表
+// 接口限流：对打卡、批量导入类接口加入限流保护以防止滥用
+// 字段校验：对文本与时间字段设置合理长度与格式校验，防止注入攻击
+// 国际化：错误码与提示信息应支持 i18n，以便多语言环境显示友好文本
+// 健康检查：提供轻量健康检查接口便于监控考勤服务可用性
+// 监控指标：记录请求量、错误率、审批延迟、统计耗时等作为关键指标
+// 扩展设计：考虑支持人脸/指纹/外勤定位等多种打卡来源字段
+// 数据归档：历史考勤数据量大时应考虑归档策略以保持查询性能
+// Mapper 性能：SQL 设计时注意索引使用，避免全表扫描，复杂 SQL 添加注释解释
+// DTO 设计：避免在 API 返回中暴露多余或敏感字段，仅返回必要展示字段
+// 冲突校验：提交请假或加班前应校验是否与已批准或待审批的申请冲突
+// 时间区间判断：使用一致的闭/半开区间规则实现重叠判断函数
+// 打卡来源标识：区分设备打卡、APP 打卡、管理员补签等来源字段
+// 批量操作：批量审批或导入需做好事务边界控制并记录每条处理结果
+// 统一返回结构：建议使用 { code, message, data } 的统一响应格式
+// 错误码规范：为考勤子系统定义独立错误码段，便于定位问题
+// 并发审批：审批并发时使用乐观锁 version 字段或数据库行锁保证一致性
+// 异步计算：耗时统计任务可采用异步或消息队列方式减轻同步接口压力
+// 审批超时策略：支持自动超时流转或提醒机制避免申请长期挂起
+// 通知机制：审批结果可通过站内信/邮件/SMS 等方式通知申请人
+// 补卡申请：支持员工提交补卡并由管理员/主管审核，记录补卡理由与凭证
+// 补卡审查：对补卡的真实性做规则校验（如定位/凭证）以减少欺诈
+// 幂等键：使用客户端请求 id 或服务端生成的业务序列作为幂等键
+// 审批日志：保存审批人意见、时间和操作类型用于审计
+// 角色模型：建议至少区分 HR、管理员、主管、普通员工 四类角色并设计权限粒度
+// 前端过滤：为前端提供灵活的筛选参数（员工、部门、时间、状态）
+// 查询优化：复杂过滤使用索引字段与分页策略避免慢查询
+// SQL 注入防护：使用参数化查询并避免拼接用户输入的动态 SQL
+// Mapper 命名：使用语义化方法名，如 selectByEmployeeAndDateRange
+// DTO 校验：使用注解（如 @NotNull/@Size）在 controller 层进行参数校验
+// 时间格式：API 返回统一时间格式，前端负责本地化展示
+// 数据补偿：提供补偿流程以修复系统故障导致的丢失打卡或错误统计
+// 对外接口：对外部系统回调进行签名校验并实现幂等处理
+// 删除策略：数据删除使用软删除并保留审计信息，必要时管理员可执行硬删除
+// 员工离职：离职员工的未处理申请自动关闭或转交至指定处理人
+// 问题场景：处理跨年/闰年/夏令时切换等边界时间问题
+// SSO 集成：与 SSO 联合使用时需要在 token 中获取当前用户并做权限校验
+// 幂等示例：if (existsByRequestId(requestId)) return existingResult;
+// 加密：敏感字段传输使用 HTTPS，存储层根据合规要求进行脱敏/加密
+// 枚举国际化：为枚举提供 locale 映射以便不同语言环境展示
+// 备份恢复：定期备份关键表并验证恢复流程
+// 文档注释：为每个公开方法编写 javadoc 以生成开发文档
+// 方法注释示例：/** 计算请假天数；参数：start,end；返回：工作日天数 */
+// SQL 优化：对慢查询使用 explain 分析并优化索引或重写 SQL
+// 事件驱动：关键变更通过事件总线广播以实现模块解耦
+// 统计并发：统计作业应避免与写入路径冲突，可在非高峰期运行或使用 MVCC
+// 灰度发布：新规则上线先灰度测试一部分用户，再全量放开
+// 公共工具：将通用时间处理、节假日判断、工时计算封装为工具类
+// API 合同：更改返回字段需更新 swagger 并通知前端
+// 审批回调重试：对第三方回调做有限重试并记录失败原因
+// 批处理窗口：夜间批处理尽量避开业务高峰以减少对线上影响
+// 加班导出字段：员工、日期、时长、类型、审批状态、审批人、审批时间
+// 请假导出字段：员工、类型、开始、结束、天数、状态、审批人
+// 打卡导出字段：员工、打卡时间、来源、定位/设备信息、异常标记
+// 设备同步：支持从多厂商设备拉取数据并标注设备来源
+// 宽限策略：上下班时间设置可配置的宽限期用于迟到/早退判断
+// 宽限配置：管理员可在配置页调整迟到/早退阈值
+// 审批链配置：支持动态配置审批链以适配不同部门流程
+// 数据修复工具：提供脚本修复异常数据并生成修复报告
+// UI 合同：列表页接口应返回 total 以供前端分页组件使用
+// 可扩展性：设计扩展点以支持未来新增考勤规则
+// 说明：可将 `file/attendance_leave_comments_java.txt` 中更多注释按需复制到各方法前
+
+
+/**
+ * <p>
+ * 请假表 前端控制器
+ * </p>
+ *
+ * @author qiujie
+ * @since 2022-03-27
+ */
+@RestController
+@RequestMapping("/leave")
+public class LeaveController {
+    @Autowired
+    private LeaveService leaveService;
+
+    @ApiOperation("新增")
+    @PostMapping
+    public ResponseDTO add(@RequestBody Leave leave) {
+        return this.leaveService.add(leave);
+    }
+
+    @ApiOperation("逻辑删除")
+    @DeleteMapping("/{id}")
+    public ResponseDTO delete(@PathVariable Integer id) {
+        return this.leaveService.delete(id);
+    }
+
+    @ApiOperation("批量逻辑删除")
+    @DeleteMapping("/batch/{ids}")
+    public ResponseDTO deleteBatch(@PathVariable List<Integer> ids) {
+        return this.leaveService.deleteBatch(ids);
+    }
+
+    @ApiOperation("编辑更新")
+    @PutMapping
+    public ResponseDTO edit(@RequestBody Leave leave) {
+        return this.leaveService.edit(leave);
+    }
+
+    @ApiOperation("查询")
+    @GetMapping("/{id}")
+    public ResponseDTO query(@PathVariable Integer id) {
+        return this.leaveService.query(id);
+    }
+
+
+    @ApiOperation("获取")
+    @GetMapping("/{deptId}/{typeNum}")
+    public ResponseDTO queryByDeptIdAndTypeNum(@PathVariable Integer deptId, @PathVariable Integer typeNum) {
+        return this.leaveService.queryByDeptIdAndTypeNum(deptId, typeNum);
+    }
+
+    @ApiOperation("设置假期")
+    @PostMapping("/set")
+    @PreAuthorize("hasAnyAuthority('system:department:setting')")
+    public ResponseDTO setLeave(@RequestBody Leave leave) {
+        return this.leaveService.setLeave(leave);
+    }
+
+
+    @ApiOperation("查询")
+    @GetMapping("/dept/{id}")
+    public ResponseDTO queryByDeptId(@PathVariable Integer id) {
+        return this.leaveService.queryByDeptId(id);
+    }
+
+    @ApiOperation("获取所有")
+    @GetMapping("/all")
+    public ResponseDTO queryAll() {
+        return this.leaveService.queryAll();
+    }
+
+}
+

hrm%2Fsrc%2Fmain%2Fjava%2Fcom%2Fqiujie%2Fcontroller/StaffLeaveController.java

@@ -0,0 +1,164 @@
+package com.qiujie.controller;
+
+import com.qiujie.service.StaffLeaveService;
+import com.qiujie.entity.StaffLeave;
+
+import com.qiujie.dto.ResponseDTO;
+import io.swagger.annotations.ApiOperation;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.multipart.MultipartFile;
+
+import javax.servlet.http.HttpServletResponse;
+import java.io.IOException;
+import java.util.List;
+
+
+/**
+ * <p>
+ * 前端控制器
+ * </p>
+ *
+ * @author qiujie
+ * @since 2022-04-05
+ */
+@RestController
+@RequestMapping("/staff-leave")
+public class StaffLeaveController {
+
+    @Autowired
+    private StaffLeaveService staffLeaveService;
+
+    // 考勤与休假管理子系统 - 后端注释（单行注释样式）
+    // 该注释块为开发人员C负责模块的详细说明，包含业务职责、边界、校验与 TODO 提示
+    // 模块职责：考勤记录录入、请假/加班申请提交与审批、统计报表生成与导出
+    // 边界与集成：与用户中心获取员工信息、与审批引擎交互生成审批任务、与薪资系统推送计薪数据
+    // 权限控制：员工只能操作本人申请，主管/Hr/管理员按职责查看与审批
+    // 事务边界：审批通过需在事务内同时更新申请表、审批日志与相关统计表
+    // 并发安全：审批/撤回/修改等操作应使用乐观锁或分布式锁防止并发冲突
+    // 输入校验：时间区间需合法（start < end），文本长度设限，防止注入
+    // 时间处理：服务端统一使用 UTC 存储，前端在展示时转换为本地时区
+    // 请假计算：计算天数时需考虑工作日与节假日规则，并支持小时制请假
+    // 加班计算：区分普通工作日、周末与法定节假日，计算不同的补偿倍数
+    // 审批流程：支持多级审批、会签与并行审批场景，并记录审批意见
+    // 审批日志：每次审批记录审批人、时间、操作、意见与状态快照
+    // 导出与审计：导出数据时记录导出人、时间与导出条件以便审计
+    // 异常处理：服务层抛出业务异常，controller 层统一捕获并返回标准错误码
+    // 性能注意：统计类接口应分页返回或使用预聚合表提高查询效率
+    // 缓存策略：热点报表可缓存并设置合理的过期策略与手动刷新接口
+    // 批量导入：提供预校验接口并返回错误详情，导入时按批次写入并记录失败行
+    // 补卡流程：员工补卡需提供凭证并记录补卡来源以便人工核实
+    // 幂等实现：提交申请时使用 requestId 保证幂等，审批更新使用受影响行数判断并发
+    // Mapper 优化：对常用查询字段（employeeId,date）建立联合索引
+    // 日志埋点：记录每次关键操作的上下文（用户、IP、请求参数摘要）以便追踪
+    // TODO：添加审批超时处理策略并发送提醒到待审批人
+    // TODO：在导入失败时生成可下载的错误明细供用户修正
+    // 说明：如需更详细的逐行注释，可从 `file/attendance_leave_comments_java.txt` 引入到具体方法前
+    @ApiOperation("新增")
+    @PostMapping
+    public ResponseDTO add(@RequestBody StaffLeave staffLeave) {
+        return this.staffLeaveService.add(staffLeave);
+    }
+
+    @ApiOperation("逻辑删除")
+    @DeleteMapping("/{id}")
+    public ResponseDTO delete(@PathVariable Integer id) {
+        return this.staffLeaveService.delete(id);
+    }
+
+    @ApiOperation("批量逻辑删除")
+    @DeleteMapping("/batch/{ids}")
+    public ResponseDTO deleteBatch(@PathVariable List<Integer> ids) {
+        return this.staffLeaveService.deleteBatch(ids);
+    }
+
+    @ApiOperation("编辑更新")
+    @PutMapping
+    public ResponseDTO edit(@RequestBody StaffLeave staffLeave) {
+        return this.staffLeaveService.edit(staffLeave);
+    }
+
+
+    @ApiOperation("查询")
+    @GetMapping("/{id}")
+    public ResponseDTO query(@PathVariable Integer id) {
+        return this.staffLeaveService.query(id);
+    }
+
+
+    /**
+     *
+     * @param current
+     * @param size
+     * @param name
+     * @param deptId
+     * @param code 用户工号
+     * @return
+     */
+    @ApiOperation("分页条件查询")
+    @GetMapping
+    @PreAuthorize("hasAnyAuthority('performance:leave:list','performance:leave:search')")
+    public ResponseDTO list(@RequestParam(defaultValue = "1") Integer current, @RequestParam(defaultValue = "10") Integer size, String name, Integer deptId,String code) {
+        return this.staffLeaveService.list(current, size, name,deptId,code);
+    }
+
+    @ApiOperation("数据导出接口")
+    @GetMapping("/export/{filename}")
+    @PreAuthorize("hasAnyAuthority('performance:leave:export')")
+    public void export(HttpServletResponse response,@PathVariable  String filename) throws IOException {
+         this.staffLeaveService.export(response,filename);
+    }
+
+    @ApiOperation("数据导入接口")
+    @PostMapping("/import")
+    @PreAuthorize("hasAnyAuthority('performance:leave:import')")
+    public ResponseDTO imp(MultipartFile file) throws IOException {
+        return this.staffLeaveService.imp(file);
+    }
+
+    @ApiOperation("分页")
+    @GetMapping("/staff")
+    public ResponseDTO queryByStaffId(@RequestParam(defaultValue = "1") Integer current, @RequestParam(defaultValue = "10") Integer size, Integer id) {
+        return this.staffLeaveService.queryByStaffId(current, size, id);
+    }
+
+    @ApiOperation("获取所有")
+    @GetMapping("/all")
+    public ResponseDTO queryAll() {
+        return this.staffLeaveService.queryAll();
+    }
+
+    @ApiOperation("申请请假")
+    @PostMapping("/apply/{code}")
+    public ResponseDTO apply(@RequestBody StaffLeave staffLeave,@PathVariable String code) {
+        return this.staffLeaveService.apply(staffLeave,code);
+    }
+
+    @ApiOperation("拾取请假任务")
+    @PostMapping("/claim/{code}")
+    @PreAuthorize("hasAnyAuthority('performance:leave:claim')")
+    public ResponseDTO claim(@RequestBody StaffLeave staffLeave,@PathVariable String code) {
+        return this.staffLeaveService.claim(staffLeave,code);
+    }
+
+    @ApiOperation("归还请假任务")
+    @PostMapping("/revert/{code}")
+    public ResponseDTO revert(@RequestBody StaffLeave staffLeave,@PathVariable String code) {
+        return this.staffLeaveService.revert(staffLeave,code);
+    }
+
+
+    @ApiOperation("完成任务")
+    @PostMapping("/complete/{code}")
+    public ResponseDTO complete(@RequestBody StaffLeave staffLeave, @PathVariable String code) {
+        return this.staffLeaveService.complete(staffLeave,code);
+    }
+
+    @ApiOperation("撤销请假")
+    @PostMapping("/cancel")
+    public ResponseDTO cancel(@RequestBody StaffLeave staffLeave){
+        return this.staffLeaveService.cancel(staffLeave);
+    }
+}
+

vue-elementui-hrm%2Fsrc%2Fapi/attendance.js

@@ -0,0 +1,194 @@
+// 考勤与休假管理子系统 - 前端注释汇总（JS 风格单行注释）
+// 该文件包含前端 api、views、components、store 的注释示例，便于开发人员C在前端代码中粘贴
+// 注：全部使用单行注释，覆盖接口说明、参数说明、返回值说明、前端校验、错误提示与 UX 建议
+// 文件：src/api/attendance.js - 说明：考勤记录相关的 API 封装
+// 方法：getAttendanceRecords(params) - 说明：按时间/员工/状态查询打卡记录
+// 参数说明：params={ employeeId, startDate, endDate, page, size }
+// 返回说明：{ code, message, data: { total, list } }
+// 错误处理：网络或服务器错误应在页面展示友好提示并支持重试
+// UX 提示：分页切换时应保留过滤条件并支持快速导出当前查询结果
+// 方法：checkIn(payload) - 说明：员工端打卡接口，payload 包含 timestamp, source
+// 校验：前端应确保 timestamp 为合法时间且不早于系统允许的最早打卡时间
+// 备注：打卡成功后应即时反馈状态并同步更新本地考勤视图
+// 组件职责：展示员工每天的考勤状态、支持点击日查看详情
+// 组件输入：props: { year, month, employeeId }
+// 组件输出：事件 dayClick(day) 当用户点击某天时触发
+// 组件 UX：异常日期以警告色显示并支持快速发起修正或申请
+// store 模块：src/store/modules/attendance.js - 说明：全局考勤状态管理
+// state 示例：{ records: [], stats: {}, loading: false }
+// action 示例：fetchAttendanceRecords({ commit }, params) - 说明：调用 attendance API 并 commit 结果
+// mutation 示例：setRecords, setStats, setLoading
+// 页面职责：提供多维度筛选、分页、导出功能与行级操作（如修正/详情）
+// 表格列建议：员工姓名、日期、上班时间、下班时间、状态、异常标识、操作
+// 校验提示：申请提交前在 UI 提示预计天数与可能的审批耗时
+// 错误展示：对常见错误（如余额不足、时间冲突）提供明确的用户提示
+// 前端表单校验：使用 form rules 校验必填项、时间范围与长度限制
+// 提示文案示例："开始时间不能晚于结束时间"、"请填写请假理由（至少 10 字）"
+// 提交态 UX：提交后按钮置为 loading，防止重复提交
+// 撤回申请：提供撤回入口并在撤回前弹出二次确认
+// 审批状态展示：用颜色区分 PENDING/APPROVED/REJECTED
+// 审批意见：在详情页显示审批人、审批时间与审批意见
+// 前端权限：前端仅做展示与控制，核心权限校验由后端完成
+// API 错误处理：统一在 request.js 中处理错误码并抛出友好错误提示
+// request.js 注释：封装 axios，处理 token 注入、重试与错误拦截
+// request.js 建议：对 401 做登出并跳转到登录页，对 429 提示限流并重试
+// 前端缓存：对静态枚举如假期类型可在 localStorage 缓存以减少请求
+// 列表组件：在表格中添加批量操作复选框以支持批量审批（HR 视图）
+// 导出功能：提供导出进度提示并在后台完成后提供下载链接
+// 表单提示：对关键字段添加 hover 帮助文案说明其含义与限制
+// 国际化：前端提示文本使用 i18n，避免硬编码中文
+// Accessibility：关键操作按钮需有 aria-label 属性提高可访问性
+// Loading 状态：对长时间接口使用 skeleton 或 loading spinner 提升体验
+// debounce：输入过滤框使用防抖以减少不必要的请求
+// 组件复用：将通用的日期范围选择器、员工选择器抽象为独立组件
+// 组件示例：<EmployeeSelect :department="deptId" v-model="selectedEmployee" />
+// 前端测试：为核心逻辑添加单元测试（如日期计算、表单校验）
+// E2E 测试：编写用户场景测试，如提交请假 -> 审批 -> 状态变更
+// 兼容性：在低版本浏览器上测试日期控件与文件导出功能
+// 打卡页面 UX：在网络不佳时允许离线打卡并在恢复网络后同步
+// 离线打卡注意：需要前端生成加密的本地记录以便验证真伪
+// 打卡定位提示：提示用户允许定位权限以便展示外勤位置信息
+// 打卡异常提示：当连续多次打卡失败提示用户联系管理员
+// 年假余额展示：在申请表单中实时展示员工剩余年假
+// 表格性能：对大数据使用虚拟滚动或分页减轻渲染压力
+// 组件懒加载：按需加载重型组件如大量图表或导出组件
+// 图表组件：使用 ECharts 或类似库展示月度出勤趋势
+// 图表数值来源：优先使用已聚合的统计接口而不是前端自行计算
+// 公共样式：考勤异常使用统一颜色变量，放在 `_variable.scss` 中维护
+// 日期工具：使用 utils/date.js 统一处理日期格式化与计算
+// date.js 方法示例：formatDate(date, format), diffInDays(start, end), isWorkday(date)
+// 权限前端校验：在展示操作按钮前判断用户角色并隐藏不可用的操作
+// 前端路由：将考勤相关页面放到 `/attendance` 路径下便于管理
+// 面包屑：在页面顶部展示导航以便用户快速返回父级页面
+// 响应式设计：确保考勤日历在移动端也能友好展示
+// 列表过滤：支持按状态、时间、员工、部门等组合过滤
+// 复核功能：为 HR 提供批量复核入口并记录复核结果
+// 交互示例：点击异常项弹出详情对话框并提供修正/补卡入口
+// 错误码映射：将后端错误码映射为前端友好提示文案
+// retry 策略：对偶发的网络错误可在 request.js 中实现自动重试
+// token 失效处理：全局拦截 401，提示重新登录并清理本地缓存
+// 文件示例：src/api/attendance.js
+// UI 错误提示示例：this.$message.error('提交失败：开始时间不能晚于结束时间')
+// Form 提示示例：{ required: true, message: '请选择请假类型', trigger: 'change' }
+// 前端分页注意：使用 total 字段做分页控件的总数，避免后端分页偏差
+// 组件通信：使用事件与 prop 传递，避免过度使用全局状态
+// store 性能：避免在 state 中存放大量不可变的大数组，可在需要时按需加载
+// 复用 API：对于相似查询使用通用方法并在参数中传入区分字段
+// 前端缓存失效：在关键配置更新后主动清理本地缓存以保持一致
+// 认证方式：前端使用 token 放入 header 并定期刷新 token
+// 文件大小限制：上传请假附件时对单个文件大小限制在 10MB 内
+// 前端分页大小建议：默认为 10/20/50 可供选择
+// 视觉提示：审批流中的通过/拒绝使用明显颜色区分以提升可读性
+// 权限提示：当用户没有权限执行操作时展示禁用状态与原因提示
+// 前端测试建议：使用 Jest 或 Vue Test Utils 编写单元测试
+// E2E 场景建议：使用 Cypress 或 Nightwatch 覆盖用户提交申请与审批流程
+// 国际化示例：this.$t('attendance.applySuccess') 在语言包中维护文案
+// 表单自动保存：在填写申请表单时周期性保存草稿防止意外丢失
+// 草稿功能：支持恢复草稿并在提交后删除草稿记录
+// 细节提示：若为长时间假期，前端应提醒用户核对开始与结束日期
+// 时间输入控件：采用带时分的日期时间选择器以提高精度
+// 前端导入：提供模板下载并在导入前做严格校验反馈错误行
+// UX 建议：在审批通过/拒绝时提供可复制的审批编号以便沟通
+// 组件加载策略：对于图表类组件采用动态 import 提升首屏速度
+// API 兼容策略：在后端返回字段新增时前端应采用安全访问方式如 data?.newField
+// 错误回退：在关键接口失败时提供降级显示而非整页报错
+// 前端日志：收集前端异常并上报以便定位问题（不要上报敏感数据）
+// 可配置化：将常量（如假期类型、审批角色）放到配置中心或接口下发
+// 国际化注意：日期格式化需根据 locale 进行展示转换
+// 安全提示：前端避免在日志或错误上打印完整 token
+// 表单自动校验：在用户填写关键字段时实时进行校验并给出友好建议
+// 性能监控：使用前端监控工具跟踪慢接口并建立告警
+// 前端缓存策略示例：枚举缓存 24h，用户数据缓存 5 分钟
+// 请求防抖：对于模糊查询输入使用防抖以减少请求量
+// Accessibility：表单控件需支持键盘导航与屏幕阅读器
+// 代码示例：async function applyLeave(payload) { /* ... */ }
+// 在前端页面上显示审批历史时，建议按时间倒序展示最新审批在顶端
+// 表格导出示例：点击导出时先调用后台导出接口并轮询导出任务状态
+// 导出成功后在页面展示下载链接并记录导出日志
+// 批量审批 UX：提供预览并显示每条的审批建议与可能问题
+// 错误示例提示："该时间段已有已批准的请假，请先撤销或联系 HR"
+// 如果需要我把这些注释直接插入到其它前端文件（如 src/api/leave.js），请告知。
+
+import request from '../utils/request'
+
+const url = '/attendance'
+
+/**
+ * 添加
+ * @param data
+ * @returns {AxiosPromise}
+ */
+export const add = (data) => {
+  return request({
+    url: url, method: 'post', data
+  })
+}
+
+/**
+ * 逻辑删除
+ * @param id
+ * @returns {AxiosPromise}
+ */
+export const del = (id) => {
+  return request({
+    url: url + '/' + id, method: 'delete'
+  })
+}
+
+export const deleteBatch = (ids) => {
+  return request({
+    url: url + '/batch/' + ids, method: 'delete'
+  })
+}
+
+export const edit = (data) => {
+  return request({
+    url: url, method: 'put', data
+  })
+}
+
+// 查询所有
+export const queryAll = () => {
+  return request({
+    url: url + '/all'
+  })
+}
+
+// 得到一条数据
+export const query = (id) => {
+  return request({
+    url: url + '/' + id
+  })
+}
+
+export const queryByStaffIdAndDate = (id, date) => {
+  return request({
+    url: url + '/' + id + '/' + date
+  })
+}
+
+// 查询
+export const list = (params) => {
+  return request({
+    url: url, method: 'get', params
+  })
+}
+
+export const setAttendance = (data) => {
+  return request({
+    url: url + '/set', method: 'put', data
+  })
+}
+export const exp = (month, filename) => {
+  return request({
+    url: url + '/export/' + month + '/' + filename,
+    method: 'get',
+    responseType: 'blob'
+  })
+}
+
+// 得到一条数据
+// 数据导入
+export const getImportApi = () => {
+  return process.env.VUE_APP_HOST + ':' + process.env.VUE_APP_PORT + url + '/import'
+}

vue-elementui-hrm%2Fsrc%2Fapi/leave.js

@@ -0,0 +1,42 @@
+// 前端考勤与休假子系统注释（自动注入）
+// 该注释为前端 API 文件提供说明：方法、参数、返回、校验与 UX 建议
+// 方法：queryByDeptIdAndTypeNum(deptId,typeNum) - 查询指定部门与类型的请假规则
+// 方法：setLeave(data) - 管理端设置请假类型与规则，需要管理员权限
+// 方法：queryByDeptId(deptId) - 查询某部门的请假规则
+// 方法：queryAll() - 查询所有请假类型用于前端下拉展示
+// 前端校验：在提交设置时校验名称唯一性、最大天数为非负整数
+// 错误处理：统一通过 request.js 的拦截器处理错误并弹出友好提示
+// UX：设置页面应在保存成功后提示并刷新下拉缓存
+
+import request from '../utils/request'
+
+const url = '/leave'
+
+// 得到
+export const queryByDeptIdAndTypeNum = (deptId, typeNum) => {
+  return request({
+    url: url + '/' + deptId + '/' + typeNum
+  })
+}
+
+export const setLeave = (data) => {
+  return request({
+    url: url + '/set',
+    method: 'post',
+    data
+  })
+}
+
+// 得到
+export const queryByDeptId = (deptId) => {
+  return request({
+    url: url + '/dept/' + deptId
+  })
+}
+
+// 查询所有请假类型
+export const queryAll = () => {
+  return request({
+    url: url + '/all'
+  })
+}

vue-elementui-hrm%2Fsrc%2Fapi/staffLeave.js

@@ -0,0 +1,115 @@
+// 前端员工请假 API 注释（自动注入）
+// 说明：该文件封装员工请假相关接口，包括提交申请、查询、撤回与审批任务操作
+// apply(data, code) - 员工提交请假申请，返回申请编号与初始状态
+// claim(data, code) - 审批人拾取任务进行审批处理
+// revert(data, code) - 审批人归还任务，供他人拾取
+// complete(data, code) - 审批人完成审批任务并写入审批意见
+// cancel(data) - 员工撤销请假申请，需校验当前审批进度是否允许撤销
+// 前端校验示例：检查 startTime < endTime、理由长度、年假余额等
+// 提交后 UX：展示申请编号并提示预计审批时间
+// 错误处理：统一在 request.js 中拦截并展示友好提示
+
+import request from '../utils/request'
+
+const url = '/staff-leave'
+
+/**
+ * 添加
+ * @param data
+ * @returns {AxiosPromise}
+ */
+export const add = (data) => {
+  return request({
+    url: url, method: 'post', data
+  })
+}
+
+/**
+ * 逻辑删除
+ * @param id
+ * @returns {AxiosPromise}
+ */
+export const del = (id) => {
+  return request({
+    url: url + '/' + id, method: 'delete'
+  })
+}
+
+export const deleteBatch = (ids) => {
+  return request({
+    url: url + '/batch/' + ids, method: 'delete'
+  })
+}
+
+export const edit = (data) => {
+  return request({
+    url: url, method: 'put', data
+  })
+}
+
+export const list = (params) => {
+  return request({
+    url: url, method: 'get', params
+  })
+}
+
+export const queryByStaffId = (params) => {
+  return request({
+    url: url + '/staff', method: 'get', params
+  })
+}
+
+// 获得所有
+export const queryAll = () => {
+  return request({
+    url: url + '/all'
+  })
+}
+
+export const exp = (filename) => {
+  return request({
+    url: url + '/export/' + filename,
+    method: 'get',
+    responseType: 'blob'
+  })
+}
+
+// 数据导入
+export const getImportApi = () => {
+  return process.env.VUE_APP_HOST + ':' + process.env.VUE_APP_PORT + url + '/import'
+}
+
+// 请假
+export const apply = (data, code) => {
+  return request({
+    url: url + '/apply/' + code, method: 'post', data
+  })
+}
+
+// 拾取任务
+export const claim = (data, code) => {
+  return request({
+    url: url + '/claim/' + code, method: 'post', data
+  })
+}
+
+// 归还任务
+export const revert = (data, code) => {
+  return request({
+    url: url + '/revert/' + code, method: 'post', data
+  })
+}
+
+// 完成任务
+export const complete = (data, code) => {
+  return request({
+    url: url + '/complete/' + code, method: 'post', data
+  })
+}
+
+// 撤销请假
+export const cancel = (data) => {
+  return request({
+    url: url + '/cancel', method: 'post', data
+  })
+}