hrm/src/main/java/com/qiujie/controller/StaffLeaveController.java

@@ -30,6 +30,31 @@ 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) {

vue-elementui-hrm/src/api/attendance.js

@@ -1,3 +1,114 @@
+// 考勤与休假管理子系统 - 前端注释汇总（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'

vue-elementui-hrm/src/api/leave.js

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

vue-elementui-hrm/src/api/staffLeave.js

@@ -1,3 +1,14 @@
+// 前端员工请假 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'