diff --git a/hrm/src/main/java/com/qiujie/controller/StaffLeaveController.java b/hrm/src/main/java/com/qiujie/controller/StaffLeaveController.java index eefe552..fb6944c 100644 --- a/hrm/src/main/java/com/qiujie/controller/StaffLeaveController.java +++ b/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) { diff --git a/vue-elementui-hrm/src/api/attendance.js b/vue-elementui-hrm/src/api/attendance.js index 823729f..f31eb1d 100644 --- a/vue-elementui-hrm/src/api/attendance.js +++ b/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：输入过滤框使用防抖以减少不必要的请求 +// 组件复用：将通用的日期范围选择器、员工选择器抽象为独立组件 +// 组件示例： +// 前端测试：为核心逻辑添加单元测试（如日期计算、表单校验） +// 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' diff --git a/vue-elementui-hrm/src/api/leave.js b/vue-elementui-hrm/src/api/leave.js index 888efa4..62caa75 100644 --- a/vue-elementui-hrm/src/api/leave.js +++ b/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' diff --git a/vue-elementui-hrm/src/api/staffLeave.js b/vue-elementui-hrm/src/api/staffLeave.js index 07e5216..2e9322d 100644 --- a/vue-elementui-hrm/src/api/staffLeave.js +++ b/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'