Python自动化考勤工时计算系统开发指南

1. 项目概述

考勤工时计算是企业管理中的一项基础但重要的工作。传统的手工计算方式不仅效率低下，还容易出错。这个Python项目通过自动化处理打卡数据，实现了高效、准确的工时计算。

核心功能包括：

• 自动读取员工打卡记录Excel文件
• 计算每日实际出勤工时
• 智能扣除午休和晚餐时间
• 生成横向月报和纵向明细两种报表

这个工具特别适合需要处理大量员工考勤数据的企业HR部门使用，可以节省大量手工计算时间，同时避免人为计算错误。

2. 核心算法解析

2.1 工时计算逻辑

项目的核心算法基于以下公式：

code复制出勤工时 = 取整后下班时间 - 取整后上班时间 - 实际覆盖的午休时间 - 实际覆盖的晚餐时间

这里有几个关键点需要注意：

1. 时间取整：采用15分钟阈值，将打卡时间四舍五入到最近的半小时
2. 午休扣除：只有当工时区间覆盖了午休时段才扣除，覆盖多少扣多少
3. 晚餐扣除：同理，只扣除实际覆盖的晚餐时段

2.2 时间处理函数

项目中定义了几个关键的时间处理函数：

python复制def parse_datetime(date_str, time_str):
    """将日期和时间字符串合并为Timestamp对象"""
    return pd.to_datetime(f"{date_str} {time_str}", errors="coerce")

def round_to_half_hour(ts):
    """将时间戳四舍五入到最近的半小时"""
    if pd.isna(ts):
        return ts
    minutes = ts.hour * 60 + ts.minute
    rounded = ((minutes + 15) // 30) * 30
    return ts.normalize() + pd.Timedelta(minutes=int(rounded))

注意：parse_datetime函数中的errors="coerce"参数很重要，它能自动处理格式错误的日期时间字符串，避免程序崩溃。

2.3 重叠时间计算

计算两个时间区间重叠分钟数的函数是项目的核心算法之一：

python复制def overlap_minutes(a_start, a_end, b_start, b_end):
    """计算两个时间区间的重叠分钟数"""
    start = max(a_start, b_start)
    end = min(a_end, b_end)
    if end <= start:
        return 0
    return int((end - start).total_seconds() // 60)

这个函数通过比较两个时间段的开始和结束时间，计算出它们的重叠部分，返回重叠的分钟数。在实际应用中，我们用它来计算工作时间与午休/晚餐时间的重叠部分。

3. 详细实现步骤

3.1 数据准备

首先需要准备打卡记录的Excel文件，文件应包含以下字段：

• 工号
• 姓名