从零构建企业微信打卡签到系统：API实战演练

1. 引言

打卡签到系统要验收的是：人在规定窗口内完成一次有效打卡，结果写进考勤表，异常能通知到当事人。第一天不要上人脸、位置围栏、全员群播报。能证伪的最小命题：一次打卡事件，能不能只落一条记录，并且该员工自己的会话里收到已审回执。

2. 状态机先于界面

待打卡、已打卡、缺卡、补卡申请，四态。重复提交同一窗口，应返回已成功，而不是再插一行。补卡是另一张单，不要覆盖原缺卡证据。

通知和记考勤是两件事。记成功后再发回执。先发后记，崩溃窗口里人看见成功、表里没有，对账会崩。

3. 实战顺序

1. 用测试员工打一次，只写库
2. 再打开该员工会话看回执原文
3. 同一窗口连点，库中仍一条、会话仍一条
4. 过了窗口再打，记为无效或转补卡，不改已关闭窗口的成功记录

def check_in(device, staff, window_id, db, enqueue):
    key = f"att:{staff}:{window_id}"
    if not db.try_insert(key):
        return "already"
    db.write_att(staff, window_id, "ok")
    enqueue(device, staff, "今日打卡已记录。")
    return "ok"

4. 不要用全员群当回执

回执打到部门大群，当事人以为没打上。地址用该员工会话。需要主管汇总，另做一条给主管的任务，业务键不同。

定时催未打卡必须带时区。错过上午催办，中午不要把原文再灌一遍。号不在线停在存活，不要狂重试把缺卡刷成已打卡。

5. 验收

测试员工独立按文档完成一次打卡，库和会话一致；跨天窗口互不影响；测试数据不得写入生产考勤汇总。

6. 总结

打卡签到从零构建，先幂等落库，再精准回执。群播报和模型分析都是下一期，第一期只证明「一次窗口一次成功」。