DooTask 签到打卡全指南:入口、四种签到方式与考勤数据导出
DooTask 签到打卡全指南:入口、四种签到方式与考勤数据导出
导读
DooTask 将签到打卡作为内置考勤能力打包进主程序,通过应用中心「签到打卡」卡片(系统应用 signin)统一承载:普通成员用它完成每日上下班打卡、查看历史记录、维护个人 MAC 与人脸信息,管理员则可在同一抽屉内进入「签到设置」维护全局考勤规则。读完本文,你将掌握从入口、手动 / WiFi / 定位 / 人脸四种签到方式的完整操作,到提醒机制、数据导出与常见排障的端到端实战方案,并能对照源码理解其底层实现。
功能定位:一个入口,两套身份视图
「签到打卡」是 DooTask 应用中心中的一个系统应用卡片(前端对应系统应用标识 signin),是日常上下班签到的常规入口。点击后弹出右侧抽屉,展示当日签到状态、历史记录、补卡按钮等信息。抽屉按身份自动分流:
| 身份 | 抽屉内可见内容 |
|---|---|
| 普通成员 | 当日签到状态与打卡按钮、近 5 天时间线、「查看更多签到数据」日历入口、个人签到设置(人脸 / WiFi Tab) |
| 管理员 | 除上述内容外,抽屉右上角多出「签到设置」入口,可配置全局规则、查看团队签到并导出数据 |
从源码看,签到功能的主体(数据表、签到机器人、提醒任务、设置接口)全部内置于主程序,开箱即用,无需单独安装「签到」或「checkin」插件。相关模型与任务可见 UserCheckinRecord、UserCheckinMac、UserCheckinFace 与 CheckinRemindTask。
入口:桌面端、移动端与管理员入口
- 桌面端:左侧导航「应用」→「签到打卡」卡片(位于「常用」分区);
- 移动端:底部 Tabbar「应用」→「签到打卡」卡片;
- 管理员:在签到抽屉右上角可见「签到设置」入口(普通成员看不到)。该入口也支持从管理后台 → 系统设置 → 签到进入;
- 签到机器人:也可直接在「消息」列表搜索 签到打卡机器人(系统机器人,账号
check-in@bot.system)打开对话完成打卡。
关于入口与权限的边界,文档 签到打卡入口 明确说明:普通成员看不到「签到设置」入口;应用中心卡片本身不会显示当日是否已打卡的角标,当日状态需要点开抽屉查看。
操作步骤:一次完整打卡流程
- 进入应用中心,点击「签到打卡」卡片;
- 抽屉弹出后查看当日签到状态与可用按钮(如「上班打卡」「下班打卡」);
- 按规则提示完成打卡:常规(手动)/ WiFi / 人脸,取决于管理员启用的签到方式;
- 历史记录与补卡入口位于同一抽屉内(补卡仅指窗口内补打当下时间,见后文常见问题)。
四种签到方式总览
管理员可在「签到设置 → 签到方式」中勾选启用的方式(参数 modes),支持从 face / auto / locat / manual 中多选。源码中对 modes 的白名单过滤位于 SystemController::setting__checkin。
| 方式 | 参数值 | 依赖 | 入口形态 |
|---|---|---|---|
| 手动签到 | manual |
无 | 签到机器人对话发指令 |
| WiFi 签到 | auto |
OpenWrt 路由器脚本 | 连办公网自动打卡 |
| 定位签到 | locat |
地图 Key(百度 / 高德 / 腾讯三选一),仅移动端 | 签到机器人对话发位置 |
| 人脸签到 | face |
face 插件(应用市场「Face check-in」)+ 人脸识别硬件 | 外接考勤机刷脸 |
依赖边界:手动与 WiFi 签到零插件依赖;定位签到仅需地图 Key;只有人脸签到强制依赖 face 插件——卸载 face 插件不影响 WiFi / 定位 / 手动签到。
手动签到(常规打卡):机器人对话即打卡
入口
桌面端 / 移动端:「应用」→「签到打卡」卡片 → 抽屉内「打开签到机器人」按钮;或直接在「消息」搜索 签到打卡机器人 打开对话。
操作步骤
- 打开签到机器人对话框;
- 输入框发送任意内容,机器人识别为打卡请求(指令
manual-checkin); - 机器人回复「上班/下班打卡成功」并附带本次打卡时间;
- 一天内多次发送会被合并:早上一次记为上班段、晚上一次记为下班段,间隔过短的重复发送会被去重。
字段默认值
- 签到日期:以服务器当前日期(北京时间)为准;
- 签到时间:以消息送达时刻为准,精确到分钟;
- 备注:由管理员在「签到设置 → 手动签到 → 签到备注」自定义提示文案。
手动签到的限制
- 不能补打过去日期,只能打当下时间;
- 已生成的签到记录不可撤回 / 删除(只读);
- 一天最多识别出 2 段时间(首签 + 末签),中间多次发送均归入这两段。
源码侧:机器人如何处理打卡
机器人消息路由在 BotReceiveMsgTask 中按 check-in@bot.system 命中后调用 UserBot::checkinBotQuickMsg('manual-checkin', ...)。核心逻辑在 UserBot::checkinBotQuickMsg:先检查签到功能是否开启(checkinSetting.open === 'open')、手动签到是否在 modes 白名单内,随后调用 checkinBotCheckin() 生成记录;每次调用带 1 秒级防抖(Cache 键 UserBot::checkinBotQuickMsg:{userid}),超频会返回「操作频繁!」。
WiFi 签到:OpenWrt 路由器定时上报 MAC
原理
WiFi 签到并非「手机一连 WiFi 就立刻打卡」。其机制是:办公网路由器(OpenWrt)安装一个定时脚本,约每 1 分钟扫描局域网内已连接设备的 MAC 地址并上报到 DooTask 服务端;服务端匹配「该 MAC 已被某成员登记」后自动生成签到记录。因此存在约 ±1 分钟延迟,属于"连上后路由器下一次上报时打卡"。
成员侧操作
- 「应用」→「签到打卡」抽屉 → 滚动到「签到设置」→「WiFi 签到」Tab;
- 填入设备 MAC 地址(格式
XX:XX:XX:XX:XX:XX,大小写均可); - 可填写备注(如「工作笔记本」「办公手机」);
- 点「添加设备」可继续添加,点输入框右侧 × 删除;
- 点「提交」保存。
每位成员最多绑定 3 个 MAC;同一 MAC 全系统唯一,被他人占用时提交会报「已被其他成员设置」。
管理员侧操作
- 「签到设置 → WiFi 签到 → 安装说明」处复制
curl ... | sh一键命令; - 在 OpenWrt 路由器 SSH 终端执行该命令完成安装(脚本写入
/etc/init.d/dootask-checkin-report并注册每分钟 crontab); - 若关闭再开启签到功能,需要重新安装(每次开启会重新生成
key)。
源码侧:安装脚本与上报接口
安装脚本由 PublicController::checkin__install 动态生成:脚本通过 awk 解析 /proc/net/arp 中 0x2 状态(已连接)设备 MAC,拼接 {"key":..., "mac":..., "time":...} 后 curl -4 -X POST 上报到 api/public/checkin/report,随后写入 cron 每分钟执行。上报接口 PublicController::checkin__report 会校验 key 与 modes 是否包含 auto,再进入 UserBot::checkinBotCheckin() 落库。该接口也复用于考勤机(type=face,使用独立的 face_key 校验)。
定位签到:移动端发位置打卡
定位签到仅支持移动端 App:在「签到机器人」对话中发送位置(指令 locat-checkin),落在管理员配置的允许半径内即打卡成功。管理员需在「签到设置」中选择百度 / 高德 / 腾讯其中一种地图服务并填写 Key,同时配置允许签到坐标点与半径(50–5000 米)。源码 SystemController::setting__checkin 保存时会校验:开启 locat 必须填写对应地图 Key 且坐标点需含 lng / lat / radius。服务端处理逻辑位于 UserBot::checkinBotQuickMsg,对 type(baidu / amap / tencent)做校验后调用 checkinBotCheckin('locat-{userid}', ...)。
人脸签到:外接考勤机 + face 插件
人脸签到通过外接人脸识别设备(考勤机)扫脸完成:考勤机将识别结果以 type=face 上报服务端(使用 face_key 校验),服务端按 face-{userid} 生成签到记录。该方式依赖 face 插件(应用市场搜「Face check-in」)与配套硬件,未安装插件时人脸上传与现场刷脸都会失败。个人侧上传人脸图片由 UserCheckinFace::saveFace 实现:先调用 Apps::isInstalledThrow('face') 校验插件安装状态,再将图片 base64 后 POST 到插件后端 http://face:7788/user 完成注册;删除人脸时调用 /user/delete(backupnum=50 表示删除图片)。
个人签到设置:MAC 与人脸自助维护
入口
「应用」→「签到打卡」卡片 → 抽屉滚动到下半部「签到设置」即可(个人侧只有「人脸签到」与「WiFi 签到」两个 Tab)。
能改什么
- 人脸签到 Tab:上传 / 替换 / 删除本人人脸图片(仅 1 张);
- WiFi 签到 Tab:增删自己的 MAC 地址列表(最多 3 个)并给每条加备注(≤ 50 字,前端展示 ≤ 100 字)。
切换 Tab 时点「提交」只保存当前 Tab 的内容,另一 Tab 的修改会丢失,需要分别提交。
权限控制
管理员关闭「允许修改」后,对应 Tab 提交会报错「未开放修改权限」。源码侧由 UsersController::checkin__save 控制:type=face 要求 checkinSetting.face_upload === 'open';type=mac 要求 checkinSetting.edit === 'open'。MAC 保存走 UserCheckinMac::saveMac,事务内校验唯一性并删除未在提交列表中的旧记录;超过 3 个 MAC 直接返回「最多只能添加3个MAC地址」。
不支持
- 没有「签到提醒时间」「上下班时间」等个人级配置——这些是全局参数,仅管理员可改;
- 不能在此页面查看团队其他成员的签到设置。
查看签到记录:时间线与日历视图
抽屉时间线
「签到打卡」抽屉顶部时间线展示最近 5 个工作日的打卡情况:
- 蓝色对勾:当天已签到,下方列出每段时间区间(如
09:01 - 18:32); - 黄色叉号:当天未签到。
日历视图
点击「查看更多签到数据」按钮进入日历:
- 默认显示当月,每个日期格内显示当天首签与末签时间;
- 顶部可切换月份,最多向前回看 3 个月;
- 工作日无签到的日期标记为缺勤。
数据来源与聚合规则
- 后端接口:
GET api/users/checkin/list?ym=YYYY-MM&before=N(见 UsersController::checkin__list,before最大取 3); - 时间段切分:单次打卡间隔超过 1 小时会被切成新时段(
UserCheckinRecord::atSection默认diff = 3600秒,见 UserCheckinRecord.php),所以一天通常看到「上班段 + 下班段」两组时间; - 当天多次打卡时,每段时间只显示最早和最晚两个时间点。
边界
- 只能查看自己的记录;管理员查看团队签到走「签到设置 → 会员签到设置」;
- 个人无导出入口,批量导出仅管理员可用;
- 不支持回看 3 个月以前的日历数据。
签到规则与全局配置(管理员)
配置存储在系统设置项 checkinSetting,主要字段如下(默认值可从源码 SystemController::setting__checkin 确认):
| 字段 | 含义 | 默认值 |
|---|---|---|
open |
功能开关 | close |
time |
上下班时间 [上班, 下班] |
["09:00", "18:00"] |
advance |
上班前最早可提前打卡分钟数 | 120 |
delay |
下班后最晚可延后打卡分钟数 | 120 |
remindin |
上班前 N 分钟推「打卡提醒」 | 5 |
remindexceed |
上班后 N 分钟推「缺卡提醒」 | 10 |
modes |
启用的签到方式(face / auto / locat / manual) |
[] |
edit |
是否允许成员自行修改 MAC | close |
face_upload |
是否允许成员自行上传人脸 | close |
子方式额外配置:
- 人脸签到:签到备注(
face_remark)+ 重复打卡提醒开关(face_retip); - WiFi 签到:路由器一键安装命令(
cmd,由key动态生成,客户端版本 ≥ v0.34.67 时返回 base64 编码); - 定位签到:百度 / 高德 / 腾讯三选一地图 Key + 允许签到坐标 + 半径(50–5000 米);
- 手动签到:签到备注(
manual_remark)。
源码在保存时会做多项校验:跨天班次支持(time[1] < time[0] 时按 +24 小时计算班次时长);advance + delay 与班次时长重叠校验,超限报「提前和延后时间设置存在重叠」;开启 face 时必须已安装 face 插件;关闭功能时会重新生成 key 与 face_key。
规则限制
- 不支持按部门 / 角色配置不同上下班时间,全员一套;
- 不支持自定义节假日,由内置接口
Extranet::isHoliday()判断(仅自动跳过提醒); - 不支持多班次 / 排班;
- 修改设置即时生效,但已生成的签到记录不会回溯调整。
签到提醒机制:机器人私聊推送
两种提醒
| 类型 | 触发时机 | 文案 |
|---|---|---|
| 打卡提醒(in) | 上班时间前 remindin 分钟 |
「快到上班时间了,别忘了打卡哦~」 |
| 缺卡提醒(exceed) | 上班时间后 remindexceed 分钟 |
「上班时间到了,你还没有打卡哦~」 |
提前 / 延后值可在「签到设置」修改,设为 0 则关闭对应提醒。
触发与筛选逻辑
CheckinRemindTask 每分钟运行一次(由 app/Tasks/CheckinRemindTask.php 实现),仅在工作日窗口内当日推送一次(Cache 键 CheckinRemindTask:remind-{type} 当日去重)。推送对象筛选条件(全部命中才推送):
- 当天还没有
UserCheckinRecord(已打卡不推); - 过去 3 天内有过签到记录(排除新入职 / 长期不打卡者);
- 没有正在生效的请假 / 外出审批(依赖 approve 插件的
ApproveProcInstHistory::userIsLeave); - 在职(
bot = 0且未禁用)非机器人成员; - 非节假日(
Extranet::isHoliday()命中全员不推)。
提醒由签到机器人(check-in@bot.system)以群外私聊模板消息发送。
管理员导出签到数据
入口
- 「应用」→「签到打卡」→ 抽屉右上角「签到设置」→ 顶部「导出签到数据」;
- 管理后台头部下拉菜单 →「导出签到数据」。
操作步骤
- 导出成员:从成员选择器勾选要导出的人,单次最多 100 个;
- 签到日期:选日期区间,右侧有「上个月」「这个月」快捷选项;
- 班次时间:选上下班时间窗口,作为首签 / 末签结果判定基准,快捷选项
8:30-18:00 / 9:00-18:00 / 9:30-18:30; - 点「导出」→ 提示「正在打包,请留意系统消息」。
导出过程与结果
- 后端接口:
GET api/system/checkin/export(见 SystemController::checkin__export),由管理员调用、异步打包(Swoole 协程); - 日期范围限制最大 35 天;导出任务完成后由「系统消息 / 文件助手」机器人(
system-msg)发送带下载链接的卡片; - 文件名自动按
{成员名}/等{N 位成员}的签到记录命名(多成员时加"等 N 位"); - 下载链接走
api/system/checkin/down?key=...,登录后访问; - Excel 字段:签到人、签到日期、班次时间、首次签到时间 / 首次签到结果(正常 / 迟到 / 缺卡)、最后签到时间 / 最后签到结果(正常 / 早退 / 缺卡)、参数数据(时段明细)。
导出判定逻辑源码可见 SystemController.php#L1392-L1428:首签落在 [当日班次开始, 当日班次结束) 区间内判定,末签窗口扩展到次日 delay 分钟以支持跨天打卡(凌晨打卡归属前一日);超过首签时间点即标「迟到」,末签早于下班时间点即标「早退」,无记录标「缺卡」。
导出限制
- 单次最多 100 个成员,更多需分批;
- 不支持按部门一键全选;
- 不导出原始多次打卡明细,只导首签与末签两个时间点。
常见问题:漏签 / 迟到与 MAC 不匹配
漏签 / 迟到怎么办
DooTask 签到没有「申请补签」工单功能,已生成的签到记录无法修改时间,普通成员不能编辑 / 删除签到记录。可行做法:
- 当下立刻补打一次:只要仍在「最晚可延后」窗口内,哪怕已过上班时间仍能签上;
- 请假 / 外出审批:通过 approve 插件提交审批,通过后当天不算缺卡,也不再触发缺卡提醒;
- 联系管理员说明:管理员只能线下记录,无法改动 DooTask 内的签到记录;
- 改用 WiFi / 人脸自动签到,减少漏签概率。
漏签的典型原因包括:超出签到时间窗口(advance / delay 边界外打卡被拒)、MAC / 人脸未匹配、完全忘记打卡、以及节假日不发提醒(但节假日打卡一样会记录)。
不在公司网络 / MAC 不匹配
WiFi 签到依赖办公网路由器扫描并上报,任一环节不通都不会打卡:
- 不在办公网(在家 / 出差),路由器扫不到设备 MAC;
- 设备 MAC 未在「签到设置 → WiFi 签到」登记;
- MAC 已被其他成员占用(报「已被其他成员设置」);
- 路由器脚本未安装或失效(关闭再开启签到后需重新安装);
- 路由器非 OpenWrt 系统,脚本装不上;
- 手机休眠 / 关 WiFi 导致上报间隔变长甚至消失;
- iOS 14+ / 部分 Android 默认「随机 MAC」导致设备真实 MAC 未上报。
解决顺序:确认连接的是办公 WiFi → 核对 MAC 填写是否正确 → 关闭随机 MAC 使用真实 MAC → 联系管理员确认路由器脚本状态 → 临时切换手动 / 人脸签到。注意 WiFi 签到约 1 分钟延迟,不要期望「秒打卡」;在家办公或出差时请使用手动 / 定位签到。
底层数据与实现要点
数据表结构
user_checkin_records:每天每次签到记录,含userid、mac、date、times(时间数组)、report_time(上报时间戳);建表见 2022_12_11_214409_create_user_checkin_records_table.php,date字段由 2022_12_13_092619_add_date_times_user_checkin_records.php 补充,组合索引idx_user_checkin_records_userid_mac_date见 2025_12_26_000000_add_indexes_to_web_socket_dialog_msgs.php;user_checkin_macs:成员 MAC 绑定(userid、mac、remark),见 2022_12_11_214403_create_user_checkin_macs_table.php;user_checkin_faces:成员人脸图片(仅 1 张),见 2024_09_27_135805_create_user_checkin_faces_table.php;- 全局参数存于系统设置项
checkinSetting。
核心算法:签到窗口与时段切分
UserBot::checkinBotCheckin 是全部签到方式的落库入口:按 time<a href="https://link.gitcode.com/i/1b42e99547aaec967f0fccbbc8b7fe8a" target="_blank">0] 与 time[1] 构造当天有效窗口 [上班时间 - advance, 下班时间 + delay],并处理凌晨跨天打卡(早于当天最早可签时刻时,若落在前一天延后窗口内则归属前一日下班段)。记录写入时按 (userid, mac, date) 聚合,times 追加本次时间;成功后由签到机器人私聊发送「上班/下班打卡成功,打卡时间: HH:mm」模板消息,并按类型附带每日开心 / 心灵鸡汤内容。时段切分由 [UserCheckinRecord::atSection 完成:相邻打卡间隔超过 3600 秒即切为新段。
签到方式标识
落库时各方式以 mac 字段区分:路由器上报真实 MAC 地址;手动 / 定位 / 人脸分别写 manual-{userid}、locat-{userid}、face-{userid}(见 UserBot.php#L422-L443),备注取对应全局配置(manual_remark / locat_remark / face_remark),方便导出与统计时追溯来源。
小结
DooTask 的签到打卡是一个"内置能力 + 插件增强"的组合:主程序自带数据模型、签到机器人、提醒任务与设置 / 导出接口,任何成员都可开箱即用;WiFi 签到依赖 OpenWrt 路由器脚本,定位签到依赖地图 Key,人脸签到依赖 face 插件,三者按需叠加。管理员通过「签到设置」控制全局开关、时间窗口、提醒与权限,普通成员则通过应用中心抽屉完成打卡、维护设备信息与查看记录。理解其「入口卡片 + 抽屉 + 机器人 + 设置项」的分层结构后,即可在团队中快速落地这套考勤方案,并借助管理员导出能力完成月度考勤统计。
相关文档索引:签到打卡入口、签到规则配置入口、普通签到怎么做、WiFi 自动签到怎么用、个人签到设置怎么改、怎么查看签到记录、怎么导出签到数据、签到规则与全局配置、签到提醒怎么发的、签到是插件还是内置功能。