核心用法
feishu-attendance 是一款面向企业行政管理的飞书考勤监控工具，通过调用飞书开放平台 API 实现自动化考勤异常检测与通知。核心流程包括：读取当日考勤数据 → 比对标准工时 → 识别迟到/早退/旷工 → 向员工推送提醒 → 向管理员汇总报告。
命令行交互
node index.js check：执行当日考勤检查（默认模式）node index.js check --date YYYY-MM-DD：回溯指定日期node index.js check --dry-run：模拟运行，仅输出日志不发送消息，适合测试配置
依赖服务
- 飞书开放平台：需申请
attendance:report:readonly、contact:user.employee:readonly、im:message:send_as_bot三类权限 - timor.tech 假日 API：用于自动识别中国大陆法定节假日与调休，避免假日误报
---
显著优点
1. 假日智能感知：接入第三方假日 API，自动跳过节假日和周末，减少无效监控与员工骚扰
2. 故障安全设计：假日 API 异常时自动进入 Safe Mode，暂停用户通知，防止因数据源故障导致的批量误发
3. 缓存优化：用户列表 24 小时 TTL 缓存，假日数据本地缓存，降低 API 调用频次与_rate limit_风险
4. 富媒体报告：向管理员推送飞书交互式卡片，支持多维度数据可视化
5. 低侵入部署：纯命令行工具，无需改造现有飞书组织架构，即配即用
---
潜在缺点与局限性
| 维度 | 说明 |
|------|------|
| **外部依赖风险** | timor.tech 为非官方假日数据源，稳定性与长期维护存疑；API 下线或返回异常将触发 Safe Mode，导致监控中断 |
| **地域覆盖有限** | 假日 API 默认指向中国大陆节假日，海外办公室或特殊行业排班（如大小周）需额外定制 |
| **权限粒度较粗** | 需申请用户通讯录读取权限，涉及员工隐私数据，在强合规场景下可能触发安全审批 |
| **无实时同步** | 基于定时任务（cron）触发，非实时流式处理，考勤数据延迟取决于飞书 API 同步周期 |
| **扩展性约束** | 当前仅支持 Node.js 运行时，无容器化/Serverless 原生支持，大规模并发需自行优化 |
---
适合人群
- 中小型企业行政：50-500 人规模，已使用飞书考勤模块，需自动化异常提醒替代人工筛查
- HR SaaS 集成开发者：作为飞书考勤数据下游处理节点，对接 BI 或薪酬系统
- 内部工具团队：希望快速搭建零成本考勤监控，避免采购商业 HR 系统
---
常规风险
- 数据隐私：员工考勤记录与通讯录属于敏感个人信息，需确保飞书应用授权范围最小化，日志脱敏存储
- API 限流：飞书开放平台对
attendance接口有频率限制，大规模企业需评估并发或申请提额 - 误通知风险：Safe Mode 虽能降低假日 API 故障影响，但无法覆盖飞书考勤数据本身的同步延迟或错误
- 第三方依赖：建议为 timor.tech 配置降级方案（如本地节假日配置表），避免单点故障