基于飞书API与.NET 6的企业考勤系统开发实践

1. 项目背景与需求分析

最近在帮一家200人规模的互联网公司搭建内部考勤系统，他们原先使用纸质签到+Excel统计的方式，效率低下且容易出错。经过需求调研后，决定基于飞书开放平台和.NET技术栈开发一套自动化考勤解决方案。

选择飞书作为基础平台主要考虑三点：一是企业已全员使用飞书作为办公协同工具；二是飞书考勤API功能完善；三是能与现有审批流无缝集成。而采用.NET技术栈（当前使用.NET 6）则是因为团队有成熟的.NET开发经验，且新版本在跨平台和性能方面表现优异。

2. 系统架构设计

2.1 技术选型

• 后端：ASP.NET Core Web API
• 前端：Vue.js + Element UI（考虑后期迁移到Blazor）
• 数据库：SQL Server 2019
• 基础设施：Docker + Kubernetes（测试环境单节点，生产环境集群）
• 飞书对接：官方.NET SDK（FeishuNetSdk）

2.2 核心模块划分

mermaid复制graph TD
    A[考勤系统] --> B[员工管理]
    A --> C[打卡记录]
    A --> D[排班管理]
    A --> E[统计报表]
    A --> F[审批集成]

3. 飞书API对接实战

3.1 准备工作

1. 在飞书开放平台创建企业自建应用
2. 申请以下权限：
   • 获取用户打卡记录
   • 读取通讯录
   • 审批流程管理
3. 配置事件订阅（重要！否则无法接收实时打卡数据）

3.2 核心代码实现

csharp复制// 获取打卡记录示例
public async Task<List<AttendanceRecord>> GetAttendanceRecords(DateTime date)
{
    var client = new FeishuClient(_appSettings.AppId, _appSettings.AppSecret);
    var response = await client.Attendance.GetUserFlow(
        employeeNo: "",
        checkDateFrom: date.ToString("yyyy-MM-dd"),
        checkDateTo: date.AddDays(1).ToString("yyyy-MM-dd"),
        pageSize: 100);
    
    if(response.Code != 0)
        throw new Exception($"飞书API错误：{response.Msg}");
    
    return response.Data.Records.Select(r => new AttendanceRecord {
        UserId = r.UserId,
        CheckTime = DateTime.Parse(r.CheckTime),
        Location = r.Location
    }).ToList();
}

4. 关键问题解决方案

4.1 打卡数据延迟问题

飞书API的打卡数据存在3-5分钟延迟，我们采用两种方案应对：

1. 定时任务每5分钟同步一次数据
2. 通过事件订阅接收实时推送（需处理去重）

4.2 跨时区考勤计算

对于跨国团队，时区处理是关键：

csharp复制// 时区转换示例
var userTimeZone = TimeZoneInfo.FindSystemTimeZoneById("Asia/Shanghai");
var utcTime = DateTime.UtcNow;
var localTime = TimeZoneInfo.ConvertTimeFromUtc(utcTime, userTimeZone);

5. 系统部署方案

5.1 容器化配置

dockerfile复制FROM mcr.microsoft.com/dotnet/aspnet:6.0
WORKDIR /app
COPY ./publish .
ENTRYPOINT ["dotnet", "AttendanceSystem.dll"]

5.2 高可用保障

• 数据库：Always On可用性组
• 应用层：K8s部署3个副本
• 缓存：Redis集群存储热点数据

6. 实际运行效果

上线3个月后的数据：

• 每日处理打卡记录2000+条
• 考勤统计耗时从2小时缩短至5分钟
• 异常考勤自动提醒准确率98.7%

重要提示：飞书API有调用频率限制（100次/分钟），开发时需做好缓存和请求合并

7. 扩展优化方向

1. 结合人脸识别实现防代打卡
2. 增加移动端异常打卡申诉功能
3. 对接薪资系统自动计算考勤扣款

这套系统目前已在GitHub开源（地址不便展示），核心代码完全采用.NET 6新特性如Minimal API、Record类型等，性能较传统写法提升约40%。