DooTask 签到打卡全指南:入口、四种签到方式与考勤数据导出

原创2026-10-14 20:32:191,815 阅读
文章标签:后端前端桌面应用协同办公

DooTask 签到打卡全指南:入口、四种签到方式与考勤数据导出

导读

DooTask 将签到打卡作为内置考勤能力打包进主程序,通过应用中心「签到打卡」卡片(系统应用 signin)统一承载:普通成员用它完成每日上下班打卡、查看历史记录、维护个人 MAC 与人脸信息,管理员则可在同一抽屉内进入「签到设置」维护全局考勤规则。读完本文,你将掌握从入口、手动 / WiFi / 定位 / 人脸四种签到方式的完整操作,到提醒机制、数据导出与常见排障的端到端实战方案,并能对照源码理解其底层实现。

功能定位:一个入口,两套身份视图

「签到打卡」是 DooTask 应用中心中的一个系统应用卡片(前端对应系统应用标识 signin),是日常上下班签到的常规入口。点击后弹出右侧抽屉,展示当日签到状态、历史记录、补卡按钮等信息。抽屉按身份自动分流:

身份 抽屉内可见内容
普通成员 当日签到状态与打卡按钮、近 5 天时间线、「查看更多签到数据」日历入口、个人签到设置(人脸 / WiFi Tab)
管理员 除上述内容外,抽屉右上角多出「签到设置」入口,可配置全局规则、查看团队签到并导出数据

从源码看,签到功能的主体(数据表、签到机器人、提醒任务、设置接口)全部内置于主程序,开箱即用,无需单独安装「签到」或「checkin」插件。相关模型与任务可见 UserCheckinRecord、UserCheckinMac、UserCheckinFace 与 CheckinRemindTask。

入口:桌面端、移动端与管理员入口

  • 桌面端:左侧导航「应用」→「签到打卡」卡片(位于「常用」分区);
  • 移动端:底部 Tabbar「应用」→「签到打卡」卡片;
  • 管理员:在签到抽屉右上角可见「签到设置」入口(普通成员看不到)。该入口也支持从管理后台 → 系统设置 → 签到进入;
  • 签到机器人:也可直接在「消息」列表搜索 签到打卡机器人(系统机器人,账号 check-in@bot.system)打开对话完成打卡。

关于入口与权限的边界,文档 签到打卡入口 明确说明:普通成员看不到「签到设置」入口;应用中心卡片本身不会显示当日是否已打卡的角标,当日状态需要点开抽屉查看。

操作步骤:一次完整打卡流程

  1. 进入应用中心,点击「签到打卡」卡片;
  2. 抽屉弹出后查看当日签到状态与可用按钮(如「上班打卡」「下班打卡」);
  3. 按规则提示完成打卡:常规(手动)/ WiFi / 人脸,取决于管理员启用的签到方式;
  4. 历史记录与补卡入口位于同一抽屉内(补卡仅指窗口内补打当下时间,见后文常见问题)。

四种签到方式总览

管理员可在「签到设置 → 签到方式」中勾选启用的方式(参数 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 / 定位 / 手动签到。

手动签到(常规打卡):机器人对话即打卡

入口

桌面端 / 移动端:「应用」→「签到打卡」卡片 → 抽屉内「打开签到机器人」按钮;或直接在「消息」搜索 签到打卡机器人 打开对话。

操作步骤

  1. 打开签到机器人对话框;
  2. 输入框发送任意内容,机器人识别为打卡请求(指令 manual-checkin);
  3. 机器人回复「上班/下班打卡成功」并附带本次打卡时间;
  4. 一天内多次发送会被合并:早上一次记为上班段、晚上一次记为下班段,间隔过短的重复发送会被去重。

字段默认值

  • 签到日期:以服务器当前日期(北京时间)为准;
  • 签到时间:以消息送达时刻为准,精确到分钟;
  • 备注:由管理员在「签到设置 → 手动签到 → 签到备注」自定义提示文案。

手动签到的限制

  • 不能补打过去日期,只能打当下时间;
  • 已生成的签到记录不可撤回 / 删除(只读);
  • 一天最多识别出 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 分钟延迟,属于"连上后路由器下一次上报时打卡"。

成员侧操作

  1. 「应用」→「签到打卡」抽屉 → 滚动到「签到设置」→「WiFi 签到」Tab;
  2. 填入设备 MAC 地址(格式 XX:XX:XX:XX:XX:XX,大小写均可);
  3. 可填写备注(如「工作笔记本」「办公手机」);
  4. 点「添加设备」可继续添加,点输入框右侧 × 删除;
  5. 点「提交」保存。

每位成员最多绑定 3 个 MAC;同一 MAC 全系统唯一,被他人占用时提交会报「已被其他成员设置」。

管理员侧操作

  1. 「签到设置 → WiFi 签到 → 安装说明」处复制 curl ... | sh 一键命令;
  2. 在 OpenWrt 路由器 SSH 终端执行该命令完成安装(脚本写入 /etc/init.d/dootask-checkin-report 并注册每分钟 crontab);
  3. 若关闭再开启签到功能,需要重新安装(每次开启会重新生成 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);
  • 黄色叉号:当天未签到。

日历视图

点击「查看更多签到数据」按钮进入日历:

  1. 默认显示当月,每个日期格内显示当天首签与末签时间;
  2. 顶部可切换月份,最多向前回看 3 个月;
  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)以群外私聊模板消息发送。

管理员导出签到数据

入口

  • 「应用」→「签到打卡」→ 抽屉右上角「签到设置」→ 顶部「导出签到数据」;
  • 管理后台头部下拉菜单 →「导出签到数据」。

操作步骤

  1. 导出成员:从成员选择器勾选要导出的人,单次最多 100 个;
  2. 签到日期:选日期区间,右侧有「上个月」「这个月」快捷选项;
  3. 班次时间:选上下班时间窗口,作为首签 / 末签结果判定基准,快捷选项 8:30-18:00 / 9:00-18:00 / 9:30-18:30;
  4. 点「导出」→ 提示「正在打包,请留意系统消息」。

导出过程与结果

  • 后端接口: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 签到没有「申请补签」工单功能,已生成的签到记录无法修改时间,普通成员不能编辑 / 删除签到记录。可行做法:

  1. 当下立刻补打一次:只要仍在「最晚可延后」窗口内,哪怕已过上班时间仍能签上;
  2. 请假 / 外出审批:通过 approve 插件提交审批,通过后当天不算缺卡,也不再触发缺卡提醒;
  3. 联系管理员说明:管理员只能线下记录,无法改动 DooTask 内的签到记录;
  4. 改用 WiFi / 人脸自动签到,减少漏签概率。

漏签的典型原因包括:超出签到时间窗口(advance / delay 边界外打卡被拒)、MAC / 人脸未匹配、完全忘记打卡、以及节假日不发提醒(但节假日打卡一样会记录)。

不在公司网络 / MAC 不匹配

WiFi 签到依赖办公网路由器扫描并上报,任一环节不通都不会打卡:

  • 不在办公网(在家 / 出差),路由器扫不到设备 MAC;
  • 设备 MAC 未在「签到设置 → WiFi 签到」登记;
  • MAC 已被其他成员占用(报「已被其他成员设置」);
  • 路由器脚本未安装或失效(关闭再开启签到后需重新安装);
  • 路由器非 OpenWrt 系统,脚本装不上;
  • 手机休眠 / 关 WiFi 导致上报间隔变长甚至消失;
  • iOS 14+ / 部分 Android 默认「随机 MAC」导致设备真实 MAC 未上报。

解决顺序:确认连接的是办公 WiFi → 核对 MAC 填写是否正确 → 关闭随机 MAC 使用真实 MAC → 联系管理员确认路由器脚本状态 → 临时切换手动 / 人脸签到。注意 WiFi 签到约 1 分钟延迟,不要期望「秒打卡」;在家办公或出差时请使用手动 / 定位签到。

底层数据与实现要点

数据表结构

核心算法:签到窗口与时段切分

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 自动签到怎么用、个人签到设置怎么改、怎么查看签到记录、怎么导出签到数据、签到规则与全局配置、签到提醒怎么发的、签到是插件还是内置功能。

登录后查看全文
dootask