使用钉钉Stream模式和API实现简单的考勤效果

前期准备#

1. 创建企业/组织。通讯录->右上角人型标志->创建或加入企业/团队。教程
2. 组织绑定考勤机。
3. 录入人脸信息。通讯录->更多->智能办公硬件->智能前台->选择对应的考勤机。

为应用接入Stream模式#

重点：官方文档

1. 创建企业内部应用。进入钉钉开放平台->主管理员登录->右上角我的后台->应用开发->钉钉应用->创建应用。
2. 主管理员默认有开发者权限，需由主管理员为其他人员赋予开发者权限。点击上图对应的APP->成员管理->添加角色。申请开发者权限官方教程
3. 开发事件订阅服务，安装Stream模式依赖，使用示例代码。注意示例代码订阅的是群会话修改群名称chat_update_title，我们需要修改为员工打卡信息attendance_check_record，否则信息会被过滤掉。使用Client ID和Client Secret启动示例代码。
4. 在应用管理后台中测试是否连接成功。
5. 连接成功后，勾选考勤事件中的员工打卡信息。
6. 测试是否能够正常接受到员工打卡信息。
7. 编写业务代码，将读取到的信息存储到数据库中。

业务代码编写实现考勤#

1. 获取到考勤机数据后，由于只有员工考勤组信息和打卡事件，缺少打卡的结果。因为调用考勤服务端API-批量获取考勤组详情接口，获取企业考勤组内的排班上下班时间。
2. 获取到排班时间后，我们就可以使用员工所属的考勤信息，注意考勤机返回的是groupKey，虽然他的字段名是groupId，因此需要进行转换才能获取到对应的考勤组信息。groupKey转groupId。
3. 根据考勤组信息，我们可以获取到每天的排班信息，这样我们就可以通过员工打卡的时间和排班的时间进行比较得到员工打卡结果。目前对于简单的考勤规则可以返回正确的打卡结果，但如果考勤规则较为复杂的情况，则可能出现和钉钉结果不一致的情况。
4. 由于需要确定员工打的是那一段的卡和打的是上班卡还是下班的卡，我们还需要维护每个员工的当前状态，因此需要获取组织内所有员工的ID，由于官方的方法只能获取本部门的员工，不获取本部门下子部门的员工，因此需要层次遍历员工，注意需要赋予通讯录的权限。获取部门用户userid列表
5. 对于员工、考勤组、班次信息的变化也做了事件订阅，会根据增加、修改和删除操作进行对应的处理。

钉钉开发文档的坑#

1. 通过Stream订阅的考勤机打卡事件返回的值和开发文档缺少部分参数，主要是经纬度等信息，如果使用手机钉钉蓝牙连接打卡机打卡返回的信息又有所不同。
2. 订阅考勤组新增事件，传递的信息非常少，与开发文档不符合，原来返回的逻辑是先传递新增的考勤组ID等基础信息，详细信息是通过考勤组修改事件传输的，所以要注意考勤组新增信息和修改事件逻辑的编写。
3. 考勤机使用人脸识别打卡时，直接打是上班卡，然后凝视是打下班卡，但是实际考勤机并不会判断上下班卡，而是传递一个打卡时间而已。所以员工打的是上班还是下班卡需要编写逻辑判断。

存在的问题#

1. 当前只能支持员工每天一次上班打卡和一次下班打卡，而钉钉可以设置多段打卡时间且可以打多次下班卡。目前尝试的解决方法是用最早可打卡时间段和最晚可打卡时间段来划分是打什么时间的卡，如果没有设定就用两个事件间隔的中间时间。比如上午8点打卡，下午18点打卡，那么上班9点的最早打卡时间是1点，最晚打卡时间是13点，下班18点的最早打卡时间是13点，最晚打卡时间是1点。
2. 由于是事件订阅模式，只有打卡了才会触发事件，因此没有对缺勤情况进行处理。目前尝试的解决方法是使用定时任务去查询数据库数据判断用户是否缺勤。
3. 系统开始的时候默认员工处于未打卡状态，但是其实可能在系统启动的时候，员工处于其他状态。
4. 钉钉打卡还有很多其他设置可以设置，目前仅实现了最基础的打卡设置。
5. 当设置了下班卡的最早和最迟打卡时间，考勤机虽然显示是打下班卡，但是钉钉后台还是按照上班卡的时间去进行判断。因此考勤机显示是上班和下班是无效的，我们只能自行判断打卡时间和考勤组的对应关系。
6. 我们是否需要按照钉钉的考勤规则定义打卡，还是可以自己确定考勤规则。不用完全按照钉钉的打卡规则。

另外的方向#

目前使用Stream模式订阅事件时效性较好，但是提供的API的结果比较少，需要自己手动实现较多的业务逻辑，难以确定是否与钉钉一致，且所使用的API次数较多。

其他的方法是使用获取打卡结果输入时间范围，获取期间的打卡结果信息，优点是使用API较少，结果准确，需要实现的业务代码少。缺点是实时性不够，需要定时去查询。

、