时间与考勤管理几乎是每个企业内部系统都绕不开的模块，而它恰恰是前端开发中容易低估的一块硬骨头。看起来只是记录打卡时间、统计工时，实际做起来会发现跨日班次、夏令时、节假日调休、迟到早退判定这些细节层出不穷。本文将以Vue 3为技术底座，按照Kronos这类专业工时管理系统的思路，从前端工程化的角度完整拆解一个考勤模块应该怎么设计与实现。
一、时间数据的统一建模：一切的起点
考勤系统出问题，八成出在时间表示不统一上。有的地方用字符串，有的地方用时间戳，有的地方用Date对象，一旦混用，比较和运算就会出错。工程化的第一步是建立一个统一的时间模型层。推荐使用Day.js作为底层库，它体积小、API友好，而且插件机制可以按需加载isoweek、duration等功能。
考勤领域的时间不是单纯的时间点，而是一个包含语义的对象。一条打卡记录至少要包含原始时间戳、所属逻辑日期、班次ID、打卡类型这几个字段。特别注意逻辑日期这个概念：一个凌晨两点下班的大夜班员工，他的打卡时间戳属于第二天，但逻辑上应该归属前一个考勤日。这个映射关系必须在前端就处理好，否则传给后端的数据就是错的。
import dayjs from 'dayjs'
import isoweek from 'dayjs/plugin/isoweek'
dayjs.extend(isoweek)
// 统一的时间解析工具，所有模块只允许通过这里处理时间
export function parseAttendanceTime(timestamp) {
const d = dayjs(timestamp)
return {
raw: timestamp,
// 凌晨6点前打卡归属前一个考勤日
logicalDate: d.hour() < 6 ? d.subtract(1, 'day').format('YYYY-MM-DD') : d.format('YYYY-MM-DD'),
weekOfYear: d.isoweek(),
isWeekend: d.day() === 0 || d.day() === 6
}
}
// 计算单次工作时长，处理跨日场景
export function calcWorkDuration(startTs, endTs) {
const start = dayjs(startTs)
const end = dayjs(endTs)
// 如果结束时间小于开始时间，说明跨日，需要补一天
const adjusted = end.isBefore(start) ? end.add(1, 'day') : end
return adjusted.diff(start, 'minute')
}这个工具层建好之后，项目里其他地方一律不允许直接new Date或者手写字符串拼接。可以在ESLint里加一条自定义规则强制约束，从工程层面杜绝时间表示混乱的问题。另外时区问题也要在这层处理，如果系统服务于多个地区的员工，建议所有时间戳统一存UTC，只在展示层做本地化转换。
二、考勤日历组件：组合式API的典型实践
考勤界面的核心是日历视图，员工在上面查看每天的出勤状态，管理员在上面排班。Vue 3的组合式API非常适合把这种复杂组件拆成职责清晰的逻辑单元。我们可以把日历拆成三个composable：useCalendarGrid负责生成日历网格数据，useAttendanceStatus负责计算每天的考勤状态，useShiftSelection负责处理班次选择交互。
// useCalendarGrid.js：生成某年某月的日历网格
import { computed } from 'vue'
import dayjs from 'dayjs'
export function useCalendarGrid(year, month) {
const grid = computed(() => {
const firstDay = dayjs(`${year.value}-${month.value}-01`)
// 日历首行前置补齐上个月的日期
const padStart = firstDay.day() === 0 ? 6 : firstDay.day() - 1
const daysInMonth = firstDay.daysInMonth()
const cells = []
for (let i = 0; i < padStart; i++) {
cells.push({ date: null, placeholder: true })
}
for (let i = 1; i <= daysInMonth; i++) {
cells.push({
date: firstDay.date(i).format('YYYY-MM-DD'),
placeholder: false
})
}
return cells
})
return { grid }
}考勤状态的判定逻辑建议用有限状态机的思路来组织。一天的状态可能是正常、迟到、早退、缺卡、请假、休息日等，这些状态之间有优先级关系。比如员工请了假，那这一天的迟到记录就不应该展示。把判定规则收敛到一个纯函数里，输入是打卡记录集合和排班信息，输出是状态枚举值，这样单元测试会非常好写。
// 状态判定纯函数，方便单测覆盖
export function judgeDayStatus(punches, shift, leaveRecords) {
if (leaveRecords.length > 0) return 'LEAVE'
if (!shift) return 'REST_DAY'
if (punches.length === 0) return 'ABSENT'
const firstPunch = punches[0]
const lateThreshold = shift.start + 15 // 允许15分钟弹性
if (firstPunch > lateThreshold) return 'LATE'
const lastPunch = punches[punches.length - 1]
if (lastPunch < shift.end) return 'EARLY_LEAVE'
return 'NORMAL'
}组件层面用ECharts做月度考勤热力图是个不错的补充，员工一眼就能看出哪几个月迟到频繁。图表配置里的颜色映射要和状态枚举绑定，不要写死十六进制色值，而是维护一份状态到主题色的映射表，这样后续换肤或者调整状态种类时只需要改一处。
三、状态管理与数据流：Pinia的考勤实践
考勤模块的状态比想象中复杂：当前选中的月份、员工维度的打卡缓存、排班草稿、审批中的修改申请，这些数据之间有依赖关系。用Pinia来组织最合适，一个store管理考勤域的所有状态，配合getter做派生计算，比如当月总工时、加班总时长这些统计值都可以做成计算属性自动更新。
import { defineStore } from 'pinia'
export const useAttendanceStore = defineStore('attendance', {
state: () => ({
currentMonth: dayjs().format('YYYY-MM'),
records: {}, // 以日期为key的打卡记录缓存
shiftPlans: {}, // 排班数据
statistics: null
}),
getters: {
monthlyWorkMinutes(state) {
return Object.values(state.records).reduce((sum, day) => {
return sum + (day.workMinutes || 0)
}, 0)
},
lateCount(state) {
return Object.values(state.records)
.filter(day => day.status === 'LATE').length
}
},
actions: {
async loadMonth(month) {
this.currentMonth = month
// 带缓存的按月加载，避免重复请求
if (!this.records[month]) {
const data = await fetchAttendanceApi(month)
this.records[month] = groupByDate(data)
}
}
}
})排班功能要注意草稿态和提交态的区分。管理员拖拽调整班次时，这些变更只存在于本地草稿，必须显式点保存才提交。可以在store里单独维护一个draft对象，配合Vue 3的watch做脏检测，页面离开时如果有未保存的草稿要弹窗提醒。打卡接口则要做好防重复提交，前端用节流加请求中标记，后端用幂等键兜底，两边都不能省。
最后提一个容易踩的坑：考勤报表导出时，不要在前端把上万条记录一次性渲染再导出，应该走后端生成文件的下载链接。前端只负责触发和展示进度。整体来说，把时间建模、组件拆分、状态管理这三层做扎实，一个Kronos级别的考勤前端模块就有了可靠的骨架，后续无论是加工时审批还是多地区支持，都能在这个基础上平滑扩展。