DooTask「导出管理」系统应用完全指南：二级菜单、四种导出动作与异步导出原理

导读

本文围绕 DooTask 应用中心的「导出管理」（exportManage）系统应用展开，完整讲解其卡片入口、二级菜单的四种导出动作（任务统计、超期任务、审批数据、签到数据）以及背后的异步导出与系统机器人通知机制。读完本文，你将掌握如何在桌面端与移动端快速触发导出、每种导出的参数含义与范围上限，并理解导出文件如何由 Swoole 协程后台生成、经系统机器人私聊下发、再通过限时下载链接取回的全过程。

什么是「导出管理」应用

「导出管理」是 DooTask 内置的 exportManage 系统应用。它不是一个独立的页面，而是一张位于应用中心的快捷入口卡片：点击后弹出二级菜单，提供四种常用导出动作；每种动作内部再走对应的导出流程（生成文件 / 触发下载 / 进异步队列），见原始文档 导出管理入口。

在前端实现中，这张卡片有独立的点击逻辑：应用中心页面 application.vue 对 card.system.value === 'exportManage' 的卡片单独绑定了 openExportMenu 方法（排序模式下不响应点击），而非走通用的 handleCardClick。openExportMenu 通过 Vuex 的 menu/operation 弹出下拉菜单，选中后由 handleExport 通过事件总线发出 openManageExport 事件（application.vue），主框架页 manage.vue 中的 openManageExport 再按类型分发到对应的导出弹窗或方法。

从应用注册表看，exportManage 卡片被放置在「管理员应用」分区（application.vue 中 type: 'admin'、show: this.userIsAdmin），且所有导出接口均以 User::auth('admin') 校验管理员身份（见下文各接口），因此实际操作上只有管理员可以使用。

入口与操作路径

• 桌面端：左侧导航「应用」→ 找到「导出管理」卡片并点击；
• 移动端：底部 Tabbar「应用」→「导出管理」卡片。

点击卡片后弹出二级菜单，菜单项即四种导出动作（原始文档的映射关系如下）：

菜单选项	触发动作
导出任务统计	openManageExport / task
导出超期任务	openManageExport / overdue
导出审批数据	openManageExport / approve
导出签到数据	openManageExport / checkin

需要说明的是：从当前仓库源码看，openManageExport 的 switch 分支已完整实现 task（打开任务导出弹窗）、overdue（直接调用超期任务导出接口）、checkin（打开签到导出弹窗）三种；「导出审批数据」的实际入口落在管理员区「数据导出」菜单中，对应 GET api/approve/export，详见 管理员侧导出审批数据。

操作步骤：

1. 进入应用中心，点击「导出管理」卡片；
2. 在二级菜单中选择导出类型；
3. 弹出导出配置对话框，按需选择时间范围 / 成员 / 其他筛选条件；
4. 提交后，系统按数据量同步下载或异步生成（数据量较大时一律走异步队列，完成后由系统机器人通知）。

四种导出动作详解

导出任务统计（task）

对应弹窗组件 TaskExport.vue，表单字段如下：

• 导出成员：通过 UserSelect 多选，最多 100 人（前端与后端双重限制）；
• 时间范围：DatePicker 日期区间，提供「上个月 / 这个月」快捷选择；
• 导出时间类型：单选 taskTime（任务计划时间，默认）或 createdTime（任务创建时间）。

提交时调用 GET api/project/task/export，后端接口 task__export 的参数与校验如下：

参数	类型	说明
userid	Array	指定成员 ID 列表，如 [1, 2]，最多 100 个，超出返回「导出成员限制最多100个」
time	Array	时间范围，如 ['2020-12-12', '2020-12-30']，两端必须是合法日期/时间，且跨度不得超过 90 天
type	String	createdTime 按创建时间筛选；taskTime（默认）按任务计划时间筛选

数据查询逻辑上，接口会 JOIN project_task_users（owner = 1 取负责人）并按导出时间类型筛选：createdTime 仅按创建时间范围筛选；taskTime 优先用任务计划时间筛选，同时对“无计划时间（start_at/end_at 为空）但在考核期内已完成（complete_at 落在区间内）”的任务做了兜底纳入，避免漏掉考核期内完成的任务（ProjectController.php）。数据按 100 条一批 chunk 处理，内存可控。

导出 Excel 的列定义（按负责人分 Sheet）包括：任务ID、父级任务ID、所属项目、任务标题、任务标签、任务开始时间、任务结束时间、完成时间、归档时间、任务计划用时、实际完成用时、超时时间、开发用时、验收/测试用时、负责人、创建人、状态（ProjectController.php）。其中「状态」判定规则为：flow_item_name 以 end| 开头视为结束态并区分“已完成 / 已取消”，非 end| 但 complete_at 有值则视为已完成；未完成行状态列红色标出，已完成但超期的行以蓝色标出。开发/测试用时则基于 ProjectTaskFlowChange 流程变更记录中 test/end 前缀的流转时间差累计计算。

导出超期任务（overdue）

该动作无需配置弹窗：点击菜单后直接弹出确认框“你确定要导出所有超期任务吗？”（manage.vue），确认后调用 GET api/project/task/exportoverdue。

后端接口 task__exportoverdue 不带参数，查询条件为：complete_at 为空、end_at 非空且 end_at <= 当前时间 的全部任务，按 end_at 升序分批导出。导出列包括：任务ID、父级任务ID、所属项目、任务标题、任务标签、任务开始时间、任务结束时间、任务计划用时、超时时间、负责人（含 ID）、创建人（含 ID）。若无数据，机器人会推送“没有任何数据”的红色提示。

导出审批数据（approve）

审批导出走管理员区「数据导出」入口，对应 GET api/approve/export（限管理员）。操作要点（见 管理员侧导出审批数据）：

• 流程分类（proc_def_name）必填，单次只能选一类，不能一次导全部分类；
• 状态（state）：0 全部 / 1 审批中 / 2 通过 / 3 拒绝 / 4 撤回；
• 可选「是否完成（is_finished）」；
• 日期范围最多 35 天。

导出字段覆盖申请编号、标题、申请状态、发起/完成时间、发起人工号、User ID、姓名、部门、部门 ID、部门负责人、历史审批人、历史办理人以及各模板自定义字段。后端通过审批微服务的 findAllProcIns 接口拉取流程实例后转写为 Excel；微服务不可用时，机器人会推送错误信息。

导出签到数据（checkin）

对应弹窗组件 CheckinExport.vue，表单字段如下：

• 导出成员：最多 100 人；
• 签到日期：日期区间，提供「上个月 / 这个月」快捷选择；
• 班次时间：TimePicker 时间区间，提供 8:30-18:00、9:00-18:00、9:30-18:30 三个常用班次快捷选项。

提交时调用 GET api/system/checkin/export，后端接口 checkin__export 的参数与校验如下：

参数	类型	说明
userid	Array	成员 ID 列表，最多 100 个
date	Array	日期范围，如 ['2020-12-12', '2020-12-30']，跨度不得超过 35 天
time	Array	班次时间范围，如 ['09:00', '18:00']

此外接口要求签到功能已开启（读取 checkinSetting 配置，open !== 'open' 时拒绝），并读取 delay 延后打卡配置（默认 120 分钟，用于跨天打卡导出的收尾统计）。导出按成员每人一个 Sheet，列定义包括：签到人、签到日期、班次时间、首次签到时间、首次签到结果、最后签到时间、最后签到结果、参数数据；结果判定中“缺卡”以红色标注、“迟到”以蓝色标注。下载接口为 GET api/system/checkin/down，通过 key 参数换取文件。

异步导出与结果通知机制

所有导出动作都不是同步返回文件，而是“立即返回 success + 后台协程生成 + 机器人私聊通知”三步走（见 数据导出概览）：

1. 触发即返回：接口先做参数校验（成员数、日期范围等），随后用 Swoole 协程 go(function () {...}) 把真正的导出逻辑丢到后台，先 Coroutine::sleep(1) 等待，再执行查询与文件生成；同时通过 WebSocketDialogMsg::sendMsg 给用户私聊窗口推送一条“正在导出…，请稍等…”的占位消息；
2. Excel 生成：文件组装依赖 BillExport.php（单 Sheet：标题、表头、数据、单元格样式、可配置下拉校验）与 BillMultipleExport.php（多 Sheet 容器），底层基于 Maatwebsite/Excel（PhpSpreadsheet）；
3. 打包与限时下载：生成的 .xls 存放在 storage/app/temp/<类型>/export/<Ym>/ 目录，随后用 Base::zipAddFiles 压缩为 zip；下载地址通过 Down::cache_encode 生成携带密钥的 api/project/task/down?key=...（签到为 api/system/checkin/down），并用 file_download 类型消息推送到与系统机器人 system-msg 的私聊会话，用户点击即可下载。由于密钥缓存在服务端，链接有时效，过期后文件无法再取回。

与管理员区「数据导出」的区别

维度	应用中心「导出管理」（本文主题）	管理员区「数据导出」
可见范围	应用中心内的快捷卡片（源码中注册于管理员分区，见上）	仅管理员可见
组织方式	按动作分类的一键导出，点击卡片弹二级菜单	覆盖更多导出类型与导出参数的高级配置入口
典型动作	任务统计、超期任务、签到数据等常用动作	任务、审批、签到等全量管理导出，见 数据导出入口

两者共用同一套底层导出接口与机器人通知机制，区别主要在于入口位置、菜单组织方式和参数深度。

常见限制与注意事项

• 一次只能导出一种类型：不支持把多种导出动作合并为一次操作，每次需在二级菜单中单选；
• 卡片不是历史记录页：点击卡片只是触发导出动作，卡片本身不展示历史导出记录或下载列表；历史下载入口在系统机器人私聊消息中；
• 成员上限：任务统计、签到导出的成员选择上限均为 100 人；
• 时间范围上限：任务统计按时间筛选时跨度最多 90 天；签到数据、审批数据的日期范围最多 35 天；
• 权限要求：导出接口均限管理员（User::auth('admin')），涉及全局数据（如审批数据）的导出还会在后台再次校验管理员权限；
• 下载链接有时效：机器人消息中的下载地址通过服务端缓存密钥生成，过期后需重新发起导出。

以上实现细节均可在仓库对应源码中验证：前端入口见 application.vue 与 manage.vue，导出弹窗见 TaskExport.vue 与 CheckinExport.vue，后端接口见 ProjectController.php 与 SystemController.php。