DooTask 管理员数据导出全指南：四大导出类型、操作流程与源码级实现解析

导读

本文面向 DooTask 的系统管理员与二次开发者，系统讲解应用中心「管理员」分区内置的「数据导出」功能：从入口定位、四种导出类型（任务统计 / 超期任务 / 审批数据 / 签到数据）的参数与限制，到导出后如何通过系统机器人获取限时下载链接，再到后端异步导出、Excel 生成与下载令牌的源码实现。读完本文，管理员可独立完成各类运营数据的导出归档，开发者可对照源码理解导出功能的完整调用链。

功能定位：管理员专属的数据打包能力

「数据导出」是 DooTask 主程序内置的管理员应用，普通成员不可见。它把系统内的任务、审批、签到等运营数据按预设字段整理成 Excel/CSV 文件，用于汇报、归档与二次分析。

从知识库概念文档 data-export/overview.md 可以确认该功能的三条关键属性：

• 异步生成：触发后接口立即返回，文件由 Swoole 协程在后台生成（源码中表现为 go(function () {...})），完成后才推送消息；
• 机器人通知：所有导出完成消息均由系统机器人 system-msg 发送到管理员的私聊会话，而非浏览器直接下载；
• 范围限制：每种导出都有成员数 / 日期范围上限，参数校验在接口层完成。

从源码 application.vue 可以看到，应用中心为 exportManage 应用配置了标签「数据导出」，且带 show: this.userIsAdmin 条件——只有管理员账号才会渲染这张卡片，与文档中「普通成员看不到」的描述完全对应。

入口：桌面端与移动端如何打开

根据 apps/admin-apps/export.md 与导航文档 menu-map/data-export/entry.md，入口路径如下：

• 桌面端：左侧栏「应用」→ 下方「管理员」分区 →「数据导出」卡片；
• 移动端竖屏：底部 Tabbar「应用」→「管理员」分区 →「数据导出」。

点击卡片后弹出下拉菜单（不弹抽屉），先选择导出类型，再进入对应的参数对话框。前端源码 application.vue 中定义了该菜单的三个固定子项（导出任务统计、导出超期任务、导出签到数据），选中后通过 emitter.emit('openManageExport', type) 交由 manage.vue 分发到对应弹窗或确认框。

权限校验

「数据导出」卡片仅在 userIsAdmin = true 时渲染；同时，后端每个导出接口都会调用 User::auth('admin') 做二次校验（见 ProjectController.php 与 SystemController.php），防止越权调用。若账号头像下拉菜单顶部没有「系统管理员」徽标，说明当前账号无权限，需由超级管理员在「团队管理」中为账号 identity 追加 admin 后重新登录。

四种导出类型一览

后台「数据导出」实际提供 4 类导出，分别对应不同 API（下表依据 data-export/overview.md 与路由映射 routes/api-map.md）：

菜单项	对应 API	说明
导出任务统计	GET api/project/task/export	按成员 + 时间段导出任务，含负责人 / 工时 / 状态
导出超期任务	GET api/project/task/exportoverdue	全系统未完成且已超期的任务
导出审批数据	GET api/approve/export	按流程分类 + 状态 + 时间段导出审批单（需 approve 插件）
导出签到数据	GET api/system/checkin/export	按成员 + 日期段 + 时间段导出签到记录（需开启签到功能）

四种类型的具体操作步骤、筛选参数与导出字段，详见下文各小节。

导出任务统计（按成员）

完整流程文档见 data-export/project.md，接口实现见 ProjectController.php。

操作步骤

1. 进入「数据导出」→ 选「导出任务统计」；
2. 选择导出成员：单次最多 100 个，超出需分批；
3. 选择时间范围：最长 90 天，弹窗支持「上个月 / 这个月」快捷选择；
4. 选择导出时间类型：
   • 「任务计划时间」（默认，taskTime）：按任务 start_at/end_at 筛选，对无计划时间但在范围内完成的任务，用 complete_at 兜底纳入；
   • 「任务创建时间」（createdTime）：仅按 created_at 筛选；
5. 点击「导出」立即返回，文件由系统机器人 system-msg 私聊推送。

导出字段（固定 17 列）

任务 ID、父级任务 ID、所属项目、任务标题、任务标签、任务开始时间、任务结束时间、完成时间、归档时间、任务计划用时、实际完成用时、超时时间、开发用时、验收/测试用时、负责人、创建人、状态。

源码要点

• 列定义：表头数组在 ProjectController.php 中逐列生成，所有表头经 $doo->translate() 做多语言转换；
• 筛选逻辑：type === 'createdTime' 时仅按创建时间过滤；默认 taskTime 分支额外用 complete_at 兜底（第 1840-1853 行），保证「考核期内无计划时间但已完成任务」不漏导；
• 耗时统计：开发用时 / 测试用时依据 ProjectTaskFlowChange 流程变更记录推算；任务未完成时从最近一次流程变更时间计算至当前时刻；
• 状态判定：flow_item_name 以 end| 开头视为结束态，进一步区分「已完成 / 已取消」；非 end| 但 complete_at 有值视为已完成（兼容无流程或历史数据），未完成任务在 Excel 中以红色字体标出（第 1902-1927 行）；
• 分页流式：通过 ->chunk(100, ...) 分批写出数据，避免大结果集耗尽内存；
• 多 Sheet 组织：每个成员生成一个独立 Sheet，Sheet 标题格式为「序号.成员昵称」，文件名形如「张三等 N 位成员的任务统计_时间戳.xls」。

导出超期任务（全系统）

完整流程文档见 data-export/task.md，接口实现见 ProjectController.php。

操作步骤

1. 进入「数据导出」→ 选「导出超期任务」；
2. 弹出确认框「你确定要导出所有超期任务吗？」→ 确定；
3. 立即返回，文件由系统机器人 system-msg 私聊推送。

导出范围（后端判定）

后端查询条件为 complete_at IS NULL AND end_at IS NOT NULL AND end_at <= NOW()，即：尚未完成、设置了截止时间、且截止时间已经过去的任务，按 end_at 升序排列（最早超期的在前），同样 chunk(100) 分批流式写出。请注意：

• 已完成的延期任务不在导出范围内；
• 没有计划截止时间（end_at 为空）的任务不会被纳入；
• 导出范围为全系统所有项目，不支持按项目 / 成员筛选。

导出字段（固定 11 列）

任务 ID、父级任务 ID、所属项目、任务标题、任务标签、任务开始时间、任务结束时间、任务计划用时、超时时间、负责人、创建人。

与「任务统计」的区别

维度	导出任务统计	导出超期任务
参数	必须选成员 + 时间段 + 时间类型	无参数，全系统
状态覆盖	已完成 / 已归档 / 未完成全部状态	仅当前已超期且未完成
单次上限	100 成员、90 天	无

导出审批数据（需 approve 插件）

完整流程文档见 data-export/approve.md，对应 API 为 GET api/approve/export（限管理员）。

前置条件

• 需要系统管理员权限；
• 已安装 approve 插件（审批微服务）。文档中明确：审批中心内部自带导出由审批模板负责人触发，而这里讲的是管理员后台统一入口，按全公司流程分类拉数据，不挑模板负责人身份。

操作步骤

1. 进入「数据导出」→ 选「导出审批数据」；
2. 选择流程分类（proc_def_name）：必填，单次只能选一类，不能一次导全部分类；
3. 选择状态（state）：0 全部 / 1 审批中 / 2 通过 / 3 拒绝 / 4 撤回；
4. 选择是否完成（is_finished）；
5. 选择日期范围：最多 35 天；
6. 点击「导出」，文件由系统机器人 system-msg 私聊推送。

导出字段

申请编号、标题、申请状态、发起 / 完成时间、发起人工号、User ID、姓名、部门、部门 ID、部门负责人、历史审批人、历史办理人，以及各模板自定义字段。

数据来源与失败处理

后端调用审批微服务的 findAllProcIns 接口拉取流程实例，再翻译成行列写入 Excel。微服务不可用时，机器人会推送错误信息，且不会自动重试，需要管理员处理后重新触发。

导出签到数据（考勤打卡明细）

完整流程文档见 data-export/checkin.md，接口实现见 SystemController.php。

前置条件

系统设置 → 签到设置 →「开启签到功能」必须为开启（checkinSetting.open = 'open'）。接口第一道校验即是读取该配置，未开启直接返回「此功能未开启，请前往系统设置开启」（第 1317-1320 行）。

操作步骤

1. 进入「数据导出」→ 选「导出签到数据」；
2. 选择成员：最多 100 个，必填；
3. 选择日期范围：最多 35 天，必填，支持「上个月 / 这个月」快捷选择；
4. 选择班次时间范围：例如 09:00-18:00，必填（弹窗内置 8:30-18:00 / 9:00-18:00 / 9:30-18:30 三个快捷选项）；
5. 点击「导出」，文件由系统机器人 system-msg 私聊推送。

导出字段（固定 8 列）

签到人、签到日期、班次时间、首次签到时间、首次签到结果、最后签到时间、最后签到结果、参数数据。每个成员一个 Sheet。

结果判定规则（源码级）

• 首次签到：晚于班次开始时间标「迟到」（蓝色 436FF6），无记录标「缺卡」（红色 ff0000）；
• 最后签到：考虑「延后时间」（默认 120 分钟，取自 checkinSetting.delay）支持跨天打卡——末次打卡窗口被扩展为「班次开始时间 + 1 秒 ～ 次日 + delay 秒」（第 1392-1396 行）；
• 当前时间还没到班次开始 / 结束时，对应结果显示 -；
• 末次打卡早于班次结束时间且与首次不同，判定「早退」；
• 每个 Sheet 的 A-H 列按天循环写出（while ($startT < $endT) 逐日推进）。

触发之后：异步任务、机器人推送与限时下载

无论哪一类导出，提交后都会经历同一条链路，这也是理解本功能的核心：

1. 立即返回：接口在 go(function () {...}) 协程中执行耗时任务，同时先给机器人会话推送一条「正在导出…请稍等」的占位消息，接口本身同步返回 ret:1；
2. 后台打包：协程内 Coroutine::sleep(1) 后开始查询与组装数据，生成 Excel 文件后调用 Base::zipAddFiles() 压缩为 zip（任务导出与签到导出均走此流程）；
3. 机器人通知：文件写入 storage/app/temp/{task|checkin}/export/YYYYMM/ 目录后，通过 WebSocketDialogMsg::sendMsg(...) 以 system-msg 机器人身份向管理员私聊推送 file_download 类型卡片（标题如「导出任务统计已完成」），其中携带文件名、大小与下载 URL；
4. 限时下载：下载链接形如 api/project/task/down?key=... / api/system/checkin/down?key=...。key 由 Down.php 的 cache_encode() 生成：将文件路径 base64 编码后以 md5 为键写入 Cache，默认有效期 1 小时；cache_decode() 读取时若缓存已失效，会返回「请求已过期，请重新导出！」。因此下载链接是限时的，缓存失效后需要重新触发导出。

说明：原文档提到「在导出管理列表查看进度并下载结果」，实际源码中导出进度与结果统一由 system-msg 机器人私聊承载，并不存在独立的导出历史页面；「导出管理」卡片只是导出动作的快捷入口（参见 apps/system-apps/export.md）。

底层实现：Excel 如何生成

两类任务导出与签到导出共用了同一套 Excel 生成组件：

• BillExport.php：单个 Sheet 的导出单元，实现 WithHeadings / WithEvents / FromCollection / WithTitle / WithStrictNullComparison 接口，支持设置表头、数据、单元格样式（如加粗、字体颜色）以及下拉列表数据校验；store() 方法通过 Excel::store() 写入 storage，失败时返回「导出错误：…」字符串而非抛异常；
• BillMultipleExport.php：多 Sheet 容器，实现 WithMultipleSheets 接口，sheets() 返回由多个 BillExport 组成的数组——这正是「每个成员一个 Sheet」的实现基础。

导出格式方面：任务统计与超期任务生成 .xls，签到数据生成 .xlsx，均使用 Maatwebsite\Excel（基于 PhpSpreadsheet）驱动。文件命名规则：任务统计为「{首位成员名}等 N 位成员的任务统计_时间戳.xls」，签到为「{成员名}等 N 位成员的签到记录_时间戳.xlsx」；超期任务为「超期任务_时间戳.xls」。

能力边界：明确不支持的场景

根据 apps/admin-apps/export.md 及四个子文档的「不支持」清单，汇总如下：

• 不支持把多类型一次合并导出：任务统计、超期任务、审批、签到须分别导出，每次只能选一种；
• 不支持自定义列：所有导出类型的列固定，无法选择字段或增删列；
• 不支持普通成员自助导出：全部入口与接口均限管理员；
• 导出范围边界：任务统计单次 ≤ 100 成员、≤ 90 天；审批与签到日期范围 ≤ 35 天；签到成员 ≤ 100 人；
• 超期任务：不支持按项目 / 部门 / 成员筛选；
• 审批数据：不支持「全部分类」一次导、不支持超 35 天范围、不支持只导草稿 / 未提交单；
• 签到数据：不支持导出无班次成员、不支持自定义结果判定规则（使用系统全局设置）；
• 主程序不覆盖的导出：工作报告、用户列表、项目列表等不在「数据导出」范围内（详见 data-export/report.md 与 data-export/user.md 的替代方案说明）。

相关文档索引

• 数据导出概览：concept/data-export/overview.md
• 入口导航：menu-map/data-export/entry.md、menu-map/menu-navigation/data-export-mgmt.md
• 导出任务统计：howto/data-export/project.md
• 导出超期任务：howto/data-export/task.md
• 导出审批数据：howto/data-export/approve.md
• 导出签到数据：howto/data-export/checkin.md
• 应用中心导出管理（普通用户侧）：howto/apps/system-apps/export.md
• 管理员应用全集：concept/apps/admin-apps/list.md