- 后端
- 前端
- 协同办公
- 即时通讯
- 企业应用
【免费下载链接】dootask
DooTask是一款开源在线项目任务管理工具，提供各类文档协作工具、在线思维导图、在线流程图、项目管理、任务分发、即时IM，文件管理等工具；同时消息功能使用非对称加密技术让你的沟通更安全。
DooTask 的 routes/api-map.md 是一份由命令行自动生成的"API 路由对照表"，覆盖了当前仓库全部 329 个 HTTP 接口，把每一个 URL 精确映射到对应的控制器方法。本篇文章以这份对照表为骨架，结合 routes/web.php、InvokeController.php 与 DocApiMap.php 的源码实现，讲清楚三件事：DooTask 的 API 为何采用"URL 段即方法名"的动态路由、这张表是如何被自动生成并保持与代码同步的，以及面对这张表时如何快速定位、调试与二次开发你自己的接口。
一、这份文档是什么：自动生成的 API 路由对照表
api-map.md是 DooTask 项目内部维护的接口索引文档，其定位有三个鲜明特征：
- 自动生成：文件头部明确标注"此文件由
php artisan doc:api-map生成，勿手改"，说明它是构建/发布流程的产物，而非手写文档； - 全局覆盖：以"接口总数：329"开头，按控制器维度分节，覆盖用户、项目、对话、文件、上传、汇报、搜索等全部 API 模块；
- 一眼定位：每一行都是
URL | 方法名 | HTTP 方法 | 说明的四列结构，方便开发者在看到某个接口调用时立刻反查其控制器实现。
对于开发者来说，这份表既是接口总清单，也是调试排错的起点——前端报错时，先按 URL 在表中定位控制器与方法名，再去app/Http/Controllers/Api/目录下阅读对应实现即可。
二、路由规则：URL 段如何映射为控制器方法
2.1 三种映射规则
对照表开头的"路由规则"一节给出了 DooTask API 路由的核心约定，其根因在 routes/web.php 中可以看到：所有 API 统一挂在api前缀 +webapi中间件之下，用Route::any('{controller}/{method}', Controller::class)这种单控制器单路由的方式注册，而不是为每个方法单独注册一条路由。URL 与控制器方法的对应关系如下：
| URL 形态 | 映射目标 | 示例 |
|---|---|---|
api/{controller}/{method} | 控制器上的{method}()方法 | api/project/lists→ProjectController::lists() |
api/{controller}/{method}/{action} | {method}__{action}()方法（双下划线连接） | api/project/invite/join→ProjectController::invite__join() |
| 固定 method 的三级路由 | {fixed_method}__{action}() | api/file/dav/status→FileDavController::dav__status() |
2.2 路由的落地执行：__invoke 与 __before
动态路由最终由控制器基类 InvokeController.php 的__invoke方法统一接管（L21-L39）：
public function __invoke($method, $action = '') { $app = $method ?: 'main'; if ($action) { $app .= "__" . $action; } // 接口不存在（仅 public 方法可作为端点，protected/private 为内部方法，不暴露为路由） if (!method_exists($this, $app) || !(new \ReflectionMethod($this, $app))->isPublic()) { $msg = "404 not found (" . str_replace("__", "/", $app) . ")."; return Base::ajaxError($msg); } $res = $this->__before($method, $action); if ($res === true || Base::isSuccess($res)) { return $this->$app(); } else { return is_array($res) ? $res : Base::ajaxError($res); } }关键细节：
- URL 中的
{method}、{action}两段在__invoke内被拼成{method}__{action}的方法名，再动态调用； - 权限与前置校验的钩子是
__before($method, $action)（L46-L49），基类默认直接返回true，各业务控制器可重写它做登录态、权限、参数预处理，返回true才放行到真正的业务方法； - 只有 public 方法才会被暴露为接口，
protected/private方法即使能被method_exists找到，也会因ReflectionMethod::isPublic()检查而被拒绝，返回404 not found (xxx/yyy).——这既是安全边界，也是"方法名最多一个双下划线"这一限制的根源：URL 只有两段，拼接后的方法名结构天然只能含一个__。
2.3 特殊形态：固定 method 路由与自定义 __invoke
对照表中的file/dav模块（FileDavController）是一个特例。在 routes/web.php 中，它注册为：
Route::any('file/dav/{action}', FileDavController::class)->defaults('method', 'dav');该路由固定了method为dav，URL 中只透出{action}一段。因此它的接口命名遵循dav__{action}的规律，例如api/file/dav/status对应dav__status()、api/file/dav/conflicts对应dav__conflicts()。由于 Laravel 在调用动态控制器时传入参数的顺序与本路由的默认值位置不同，FileDavController.php 重写了__invoke来调整参数顺序：
public function __invoke($action, $method = 'dav') { return parent::__invoke($method, $action); }这解释了为何对照表中file/dav一节的方法名都带dav__前缀，也提醒我们：表格中的方法名就是你在源码里搜索的准确标识符。
2.4 HTTP 方法与"any"的含义
对照表中每行第三列标注 HTTP 方法（get/post/any）。由于routes/web.php用的是Route::any(...)，理论上任何 HTTP 动词都能命中路由；表格中的get/post实际来自控制器方法 docblock 中的@api {get}/@api {post}注释，而没有写@api注释的方法则统一显示为any（如api/project/task/ai_generate、api/system/setting/ai、api/dialog/msg/ai_generate等，见 DocApiMap.php 的解析逻辑）。因此：
any并不意味着"任意方法都能安全调用"，而是"该方法未在注释中声明 HTTP 动词"；- 若要给接口补充语义，应在方法 docblock 中补写
@api {get} api/xxx/yyy 说明。
三、自动生成机制：doc:api-map 命令的完整原理
既然文件头部声明"勿手改"，那么它必然有可靠的重生成途径。生成器是 DocApiMap.php，一条命令即可让表格与代码永远同步：
php artisan doc:api-map成功执行后终端会输出：
已生成: routes/api-map.md（控制器 N 个，接口 329 个）整个生成管线分四步：
- 收集控制器映射（collectControllers，L44-L67）：遍历 Laravel 已注册路由表
Route::getRoutes()，用正则匹配api/{prefix}/{method}形态的 URI，从路由动作中取出控制器类名；同时识别带defaults['method']的固定 method 路由（如file/dav）； - 反射扫描方法（collectMethods，L75-L105）：对每个控制器做
ReflectionClass反射，只保留"本类声明、非静态、非__开头"的 public 实例方法——这与__invoke的运行时校验规则（public 才暴露）完全一致，保证表格与真实可访问接口一一对应； - 解析接口注释（parseApiDoc，L112-L119）：用正则
@api\s+\{(\w+)}\s+(\S+)(?:[ \t]+(.+))?从方法 docblock 提取 HTTP 动词与标题，缺省时兜底为['any', '']； - 渲染 Markdown（renderHeader / renderSection，L124-L162）：按
api/{prefix}/{urlMethod}拼接完整 URL（__会被替换回/），最终写入routes/api-map.md。
值得注意的是，整个流程不依赖手写清单，而是直接反射运行时的路由与控制器，因此新增一个 public 方法、改一个@api注释，重新执行一次命令，表格即自动更新——这也是它敢写"勿手改"的原因：手改的痕迹在下一次生成时会被覆盖。
四、对照表逐模块导读：329 个接口都干了什么
以下按表格章节梳理各控制器职责与代表性接口，方便按业务域检索。
4.1 users（UsersController）——账号与个人中心
覆盖登录注册（login、login/qrcode、reg/needinvite）、验证码（login/needcode、login/codeimg、login/codejson）、资料密码（info、editdata、editpass）、会员管理与批量导入（lists、operation、createuser、import/preview、import、import/template）、部门管理（department/list、department/add、department/adddeputy、department/sync）、签到（checkin/get、checkin/save、checkin/list）、设备与安全（device/list、device/logout、delete/account、key/client）以及近年新增的个人化能力：个性标签（tags/lists、tags/add、tags/recognize）、任务浏览历史（task/browse、task/browse_save、task/browse_clean）、最近访问（recent/browse、recent/delete）、收藏（favorites、favorite/toggle、favorite/remark）、个人应用排序（appsort、appsort/save）。其中login接口同时承担登录与注册（通过type参数区分），info/managed_departments用于负责人视角切换，是 DooTask 多负责人机制的前端入口。
4.2 project（ProjectController）——项目与任务核心
这是全表体量最大的模块，涵盖：
- 项目生命周期：
lists、one、add、update、transfer（移交）、adddeputy/deldeputy（任命/罢免项目管理员）、archived（归档）、remove、exit、top（置顶）、sort（任务排序）、permission/permission/update（权限设置）； - 任务列表（列）：
column/lists、column/add、column/update、column/remove、column/one； - 任务 CRUD 与扩展：
task/lists、task/easylists、task/one、task/add、task/addsub（子任务）、task/upgrade（子任务升级）、task/update、task/copy、task/move、task/archived、task/remove、task/dialog（创建/获取任务聊天室）、task/content、task/content_history、task/files、task/filedown； - 导出与模板：
task/export、task/exportoverdue、task/down（限管理员），task/template_list、task/template_visible（跨项目模板）、task/template_save、task/template_sort、task/template_default； - 工作流与标签：
flow/list、flow/save、flow/delete，tag/save、tag/sort、tag/delete、tag/list； - AI 能力：
task/ai_generate、ai/generate、task/ai_apply（采纳 AI 建议）、task/ai_dismiss（忽略 AI 建议）； - 邀请与日志：
invite、invite/info、invite/join，log/lists。
task/addsub、task/related（关联任务）与task/related/delete对应任务间的父子、关联关系；task/resetfromlog（根据日志重置任务）则体现了 DooTask "操作留痕、可回溯"的设计。
4.3 projecttaskhandoff（ProjectTaskHandoffController）——任务流转
lists（流转记录）、options（指派人员与权限）、assign（指派负责人并附带留言）三个接口构成任务交接闭环，后端实现在 ProjectTaskHandoffService.php，并有 ProjectTaskHandoffTest.php 与 ProjectTaskHandoffFeatureTest.php 两组测试保障。
4.4 dashboard（DashboardController）——负责人视角
team/stats（统计）与team/tasks（任务列表）支撑"负责人视角"看板，与 users 模块的info/managed_departments遥相呼应，测试见 DashboardTeamTest.php。
4.5 system（SystemController）——系统设置与通用能力
- 设置类：
setting（全局设置）、setting/email、setting/meeting、setting/ai、setting/aibot、setting/checkin、setting/apppush、setting/thirdaccess、setting/file（均限管理员）； - 运维类：
version、get/info、get/ip、get/cnip、get/updatelog、license、demo、prefetch（预加载资源）； - 通用能力：
imgupload、imgview、fileupload（上传/浏览图片与文件）、email/check（邮件测试）、checkin/export、checkin/down（签到导出）、column/template（创建项目模板）、microapp_menu（自定义应用菜单）、priority（任务优先级）。
4.6 license（LicenseController）——在线授权
email/send、login、login/confirm、trial（试用）、status、refresh、logout一套完整的授权生命周期接口，对应 OnlineLicense.php 与命令 OnlineLicenseRenew.php。
4.7 dialog（DialogController）——即时消息（IM）
DooTask 的 IM 能力全部集中于此，是全表接口最密集的模块之一：
- 会话：
lists、beyond、search、search/tag、one、user、todo、top、hide、tel、open/user、open/event、config、config/save； - 消息收发：
msg/list、msg/latest、msg/one、msg/sendtext、msg/sendnotice、msg/sendtemplate、msg/sendapprove（审批卡片）、msg/sendrecord/msg/convertrecord（语音）、msg/sendfile/msg/sendfiles/msg/sendfileid、msg/sendtaskid、msg/sendanon（匿名）、msg/sendbot（机器人）、msg/send_ai_assistant、msg/sendlocation、msg/stream（通知成员监听）； - 消息操作：
msg/read、msg/unread、msg/dot、msg/withdraw（撤回）、msg/forward/msg/mergeforward（转发/合并转发）、msg/emoji、msg/tag（标注）、msg/todo/msg/todolist/msg/todoremind/msg/done（待办）、msg/mark、msg/silence（免打扰）、msg/top（置顶）、msg/color、msg/readlist、msg/detail、msg/download、msg/voice2text、msg/translation（翻译）、msg/wordchain（接龙）、msg/vote（投票）； - 群组：
group/add、group/edit、group/adduser、group/deluser、group/transfer、group/adddeputy/group/deldeputy、group/disband、group/searchuser； - AI 会话：
session/create、session/list、session/open、session/rename。
其中msg/sendfile、msg/sendfiles属于上传入口，而upload/*模块则是大文件分片上传的统一通道（见 4.9）。msg/webhookmsg2ai与sticker/search（在线表情）则是与外部系统打通的能力点。
4.8 file（FileController / FileDavController）——文件与 WebDAV
文件模块同时承载两套协议：
- 业务 API（FileController）：
collaboration/lists、collaboration/download（协作文件），lists、one、search、add、copy、move、remove（文件/文件夹 CRUD），content、content/save、content/history、content/restore（内容与历史），office/token、content/office（在线 Office 编辑），share、share/update、share/out（共享），link（链接）、download/pack（打包下载）、fetch（按路径取文本内容）； - WebDAV 管理（FileDavController）：
dav/status、dav/credentials、dav/create、dav/revoke、dav/delete、dav/adminsetting、dav/adminstatus、dav/conflicts、dav/conflictrename、dav/userrevoke，配合 routes/web.php 中独立的dav/{path?}协议入口（PROPFIND/PUT/MOVE/LOCK 等）使用，设计细节可参考 docs/webdav-design.md。
4.9 upload（UploadController）——分片上传
init（启动会话，支持秒传/续传命中）、chunk（上传分片）、merge（合并入库）、cancel（取消会话）四段式流程，是文件消息、任务附件、图片等所有场景的大文件统一通道。其 docblock 注释（见 UploadController.php）写明：小于 10MB 的小文件不走此接口，前端直接调用各场景老接口，实现透明降级。会话元数据存于 Redis，cancel会清理分片目录与索引。
4.10 report（ReportController）——工作汇报
my（我发送的）、receive（我接收的）、store（保存并发送）、template（模板生成）、detail、mark、share（分享到消息）、last_submitter、unread、read（批量已读），以及 AI 能力analysave（保存汇报 AI 分析）。
4.11 其余模块
- public（PublicController）：仅
checkin/install、checkin/report两个无需登录的开放端点（签到打卡场景）； - assistant（AssistantController）：AI 助手授权与能力接口——
auth（生成授权码）、models（AI 模型）、match_elements（元素向量匹配）、log/search（知识库检索日志）、feedback/save（反馈）、operation/dispatch与operation/result（页面操作派发）、session/list、session/save、session/delete； - complaint（ComplaintController）：
lists、submit、action构成举报投诉处理闭环； - search（SearchController）：
contact、project、task、file、message五个维度打通全局智能搜索（后端配合 Manticore 同步，见 SyncMsgToManticore.php 等命令）； - apps（AppsController）：
badge/set（应用密钥鉴权设置角标）、badge/clear（当前用户 token 鉴权清除角标）、badge/list（拉取角标）； - test（TestController）：测试专用端点，表中仅保留节标题。
五、@api 注释：表格的"数据源"与 apiDoc 兼容
对照表中每一行的 HTTP 方法与说明，源头是控制器方法 docblock 里的@api注释，例如 UsersController.php 的登录接口：
/** * @api {get} api/users/login 登录、注册 * * @apiVersion 1.0.0 * @apiGroup users * @apiName login * * @apiParam {String} type 类型 * - login:登录（默认） * - reg:注册 * @apiParam {String} email 邮箱 * @apiParam {String} password 密码 * @apiParam {String} [code] 登录验证码 * @apiParam {String} [code_key] 验证码通过key验证 * @apiParam {String} [invite] 注册邀请码 * * @apiSuccess {Number} ret 返回状态码（1正确、0错误） * @apiSuccess {String} msg 返回信息（错误描述） * @apiSuccess {Object} data 返回数据（同"获取我的信息"接口） */ public function login()这套注释完全兼容 apiDoc 规范：仓库内 apidoc.md 提供了@api、@apiBody、@apiParam、@apiSuccess等全部标签的速查说明，apidoc.json 是 apiDoc 的工程配置（name: API、title: APP接口、version: 1.0.0）。此外 apidoc.php 是一个维护脚本，可为各控制器@api注释统一追加/移除两位宽度的顺序编号（01.、02.…），只处理 get/post 注释且跳过已有编号，便于 apiDoc 输出稳定的接口排序。
理解这条数据链路后，"如何新增一个接口并让它出现在对照表中"的答案就清晰了：在控制器里新增 public 方法并写好@api注释，然后执行php artisan doc:api-map重新生成表格。
六、实践指南：用好这张表进行开发与排错
6.1 新增接口的标准流程
- 在
app/Http/Controllers/Api/下对应控制器中新增public方法（或{method}__{action}形态的复合方法），并在 docblock 中按@api {get|post} api/xxx/yyy 说明的格式声明接口； - 若接口需要登录、权限或参数预处理，重写/复用基类的
__before($method, $action)钩子（见 InvokeController.php）； - 执行
php artisan doc:api-map刷新 routes/api-map.md，确认新接口出现在对应分节； - 前端直接按
api/{method}/{action}的 URL 调用即可，无需在 routes 中新增路由（routes/web.php中每个控制器只注册两行通配路由）。
6.2 排查 404 的三种典型原因
当接口返回404 not found (xxx/yyy).时，按以下顺序检查：
- 方法可见性：目标方法是否为 public？
protected/private方法不会被__invoke暴露（InvokeController.php）； - 方法名与 URL 的对应：
{method}/{action}会拼接为{method}__{action}，URL 中多余的/段会导致方法名不匹配——这也是"路由最多两段、方法名最多一个双下划线"约束的由来； - 控制器归属：URL 第一段必须对应
routes/web.php中已注册的控制器前缀，且该方法存在于该控制器内（api/project/xxx只会去ProjectController找）。
6.3 作为接口文档的三种用法
- 前端联调：按 URL 定位方法名 → 阅读源码中的
@apiParam确认入参 → 参照@apiSuccess处理返回（ret为 1 成功、0 失败，data为业务数据）； - 权限审查：表格中标注"限管理员"的接口（如
users/lists、system/setting/email、project/task/export）在源码中均有对应鉴权逻辑，可作为安全巡检清单； - 版本比对：
php artisan doc:api-map生成的接口总数（329）可作为版本间的接口增量基线，升级时对比新旧表格即可发现变更。
结语
DooTask 的 API 设计有一个贯穿始终的思路：用统一约定代替海量路由注册。api/{controller}/{method}[/{action}]的 URL 结构、{method}__{action}的方法命名、@api注释驱动的文档生成，三者环环相扣，让"接口总数 329"的庞大体系依然保持"新增接口零路由成本、文档永远与代码同步"的维护体验。这张 api-map.md 既是导航地图，也是理解整个后端控制层架构的最佳切入点——读懂它，你就能在 DooTask 的代码库中快速找到任何一个功能的实现入口。
- 后端
- 前端
- 协同办公
- 即时通讯
- 企业应用
【免费下载链接】dootask
DooTask是一款开源在线项目任务管理工具，提供各类文档协作工具、在线思维导图、在线流程图、项目管理、任务分发、即时IM，文件管理等工具；同时消息功能使用非对称加密技术让你的沟通更安全。
相关推荐
Redoc中的动态路由：根据API自动生成路由
Redoc中的动态路由：根据API自动生成路由 引言 在现代API开发中，动态路由是一个关键功能，它能够根据API规范自动生成导航结构，极大地提升了API文档的
API设计文档前端Antigravity-Manager 模型重映射链路深度解析：静态路由与动态账号回退机制
Antigravity Manager 模型重映射链路深度解析：静态路由与动态账号回退机制 本篇技术指南以 docs/model remapping logic
LLM 网关API网关AI 应用后端UI-Router动态路由生成：从API获取路由配置实现
UI Router动态路由生成：从API获取路由配置实现 你是否遇到过这样的困扰：在开发单页应用时，路由配置写死在代码中，每次新增页面都要修改路由并重新部署？特
前端路由
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
