🎯 项目概述
🏗️ 核心架构
- 后端框架: FastAPI (Python)
- 数据库: SQLite + SQLAlchemy ORM
- 任务调度: APScheduler 定时任务
- API集成: 飞书开放平台 SDK (lark-oapi)
- 部署方式: Docker + Docker Compose
🔧 主要功能
1. 审批事件处理
- 事件订阅: 支持飞书审批状态变更回调 (v1/v2)
- 审批类型: 请假审批 + 外出审批
- 状态识别: 自动识别审批通过状态，触发后续处理流程
- 去重处理: 防止重复处理同一审批实例
2. 用户状态管理
- 状态更新: 审批通过后自动设置用户状态为"请假中"/"外出中"
- 状态重置: 审批结束后自动恢复用户正常状态
- 跨应用支持: 支持 open_id 和 user_id 两种用户标识
3. 日历事件管理
- 个人日历: 使用 Calendar v4 timeoff_event 创建请假日程
- 公共日历: 创建公司级共享日历，支持请假/外出分类显示
- 颜色区分: 请假使用红色，外出使用蓝色进行视觉区分
- 自动清理: 定时任务自动删除过期的日历事件
4. 智能时长计算
- 显式时长优先: 优先使用审批表单中的明确时长字段
- 时间差计算: 基于开始/结束时间计算实际时长
- 半天识别: 支持上午/下午半天假期的智能识别
- 工作日计算: 排除周末和节假日，精确计算工作日时长
5. 群聊通知系统
- 智能模板: 根据审批类型自动选择通知模板
- 术语区分: 外出使用"外出事由"/"外出时间"，请假使用"请假原因"/"请假时间"
- 安全签名: 支持群机器人签名验证，确保消息安全
- 详细信息: 包含员工姓名、审批类型、时间范围、时长、原因等完整信息
6. 历史数据同步
- CoreHR集成: 支持从飞书CoreHR系统同步历史请假记录
- 增量同步: 基于检查点机制，避免重复同步
- 批量处理: 支持批量创建历史日历事件和通知
- 预览模式: 提供同步预览功能，支持干运行测试
7. 定时任务调度
- 过期事件清理: 自动清理已过期的日历事件
- CoreHR同步: 定时同步最新的请假审批记录
- 可配置间隔: 支持自定义调度间隔 (默认30分钟)
- 详细日志: 提供完整的任务执行日志和统计信息
8. 配置管理
- 环境变量: 支持通过环境变量配置API密钥、日历名称等
- 颜色配置: 可自定义请假/外出日历的颜色主题
- 功能开关: 支持启用/禁用特定功能 (如事件删除、公共日历等)
- 审批类型映射: 支持自定义审批类型的中文名称映射
🔄 业务流程
请假审批流程:
- 接收回调 → 2. 验证签名 → 3. 解析事件 → 4. 设置用户状态 → 5. 创建个人日历 → 6. 创建公共日历 → 7. 发送群聊通知 → 8. 记录处理状态
外出审批流程:
- 接收回调 → 2. 验证签名 → 3. 解析事件 → 4. 设置用户状态 → 5. 创建公共日历 → 6. 发送群聊通知 → 7. 记录处理状态
🛠️ 技术特性
高可用性
- 异常处理: 完善的异常捕获和错误处理机制
- 重试机制: 支持API调用失败时的自动重试
- 日志记录: 详细的日志记录，便于问题排查和监控
扩展性
- 模块化设计: 各功能模块独立，便于扩展和维护
- 配置驱动: 通过配置文件控制功能开关和行为
- API接口: 提供RESTful API接口，支持外部系统集成
安全性
- 签名验证: 支持飞书回调签名验证
- 权限控制: 基于飞书应用权限的访问控制
- 数据保护: 敏感信息通过环境变量管理
📊 监控与运维
健康检查
- API端点: 提供 /health 健康检查接口
- 状态监控: 实时监控系统运行状态
- 性能统计: 记录API调用次数和响应时间
调试支持
- 调试接口: 提供多个调试和测试接口
- 日志级别: 支持不同级别的日志输出
- 测试工具: 内置测试脚本，便于功能验证
🎨 用户界面
- API文档: 自动生成的Swagger API文档
- 管理界面: 通过 /docs 访问完整的API管理界面
- 实时反馈: 通过群聊机器人提供实时的审批状态通知
📈 应用场景
- 企业考勤管理: 自动化处理员工请假和外出申请
- 团队协作: 通过公共日历让团队成员了解同事状态
- 流程优化: 减少人工处理审批的重复性工作
- 数据统计: 为HR部门提供请假/外出数据统计和分析
效果展示：
自行准备：
飞书企业账号（个人版不行）
公网服务器（2 核 2G 够，我远程部署）
公司现有 HR 系统（能接飞书 API）
我包什么：
现成部署包（不用写代码）
远程帮你部署到服务器（含群聊推送配置）
原创声明：本文章为原创内容，所有文章均由博主亲自撰写，严格遵循原创原则。我们承诺不使用任何人工智能生成的内容，所发布的每一篇文章都经过深思熟虑，旨在为读者提供真实、有价值的观点和信息。我们坚信原创才是知识分享的根本，致力于为广大读者呈现最具真实性和独特性的文章。感谢您的支持与关注，欢迎持续关注我们的原创内容。