禅道企业微信消息推送改造实战：如何让群消息自动@指定成员（附源码修改）

禅道与企业微信深度集成：打造智能@提醒的自动化消息推送系统

在项目管理工具与企业通讯平台的融合应用中，消息推送的智能化程度直接影响团队协作效率。禅道作为国内广泛使用的项目管理软件，与企业微信的对接虽然提供了基础通知功能，但在实际工作场景中，简单的消息推送往往无法满足精准触达的需求。本文将深入探讨如何通过源码级改造，实现禅道与企业微信的深度集成，打造具备智能@提醒、完整上下文展示的专业级消息推送系统。

1. 系统集成基础环境搭建

实现禅道与企业微信的高级消息推送功能，首先需要完成基础环境配置。这一阶段的工作将为后续的定制开发奠定技术基础。

企业微信机器人创建流程：

1. 登录企业微信客户端，进入目标群聊界面
2. 点击右上角群设置菜单，选择"添加群机器人"
3. 为机器人设置易于识别的名称（如"禅道通知助手"）
4. 创建成功后，系统将生成唯一的Webhook地址，格式为：

   https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

安全提示：Webhook地址相当于机器人密钥，需严格保密，避免泄露到公开渠道

禅道侧配置步骤：

1. 使用管理员账号登录禅道系统后台
2. 导航至"后台→通知→Webhook"设置页面
3. 点击"添加Webhook"按钮，填写以下关键信息：
   • 名称：企业微信通知
   • URL：粘贴之前获取的Webhook地址
   • 内容类型：选择application/json
4. 保存配置后，在"触发条件"选项卡中勾选需要推送的事件类型（如任务创建、Bug指派等）

// 禅道Webhook配置示例（zentao/config/my.php） $config->webhook->default = array( 'url' => 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx', 'secret' => '', );

完成基础配置后，建议通过创建测试任务验证基础连通性。如果配置正确，企业微信群内应能收到禅道发送的基础通知消息。这个阶段的消息内容较为简单，通常只包含任务标题和链接，缺乏上下文信息和定向提醒功能。

2. 消息模板深度定制开发

默认的推送消息往往信息量不足，团队成员需要反复点击链接查看详情才能了解任务全貌。通过修改禅道源码，我们可以构建包含完整上下文的信息推送模板。

关键源码文件定位：

• 主处理逻辑文件：./zbox/app/zentao/module/webhook/model.php
• 消息模板文件：./zbox/app/zentao/module/webhook/ext/model/wechat.php

原始消息生成代码通常采用简单的字符串拼接方式：

$text = $title . ' ' . "[#{$objectID}::{$object->$field}](" . $host . $viewLink . ")";

这种实现方式存在三个明显缺陷：

1. 缺乏项目/产品上下文信息
2. 遗漏任务备注等重要附加信息
3. 无法直观显示任务负责人

增强型消息模板改造：

我们通过数据库查询获取附加信息，重构消息生成逻辑：

// 获取产品名称 $productName = $this->dao->select('name')->from(TABLE_PRODUCT) ->where('id')->eq($action->product)->fetch('name'); // 获取负责人真实姓名 $assignedToName = $this->dao->select('realname')->from(TABLE_USER) ->where('account')->eq($object->assignedTo)->fetch('realname'); // 构建富文本消息体 $text = "【{$productName}】\n"; $text .= "📌 {$title}\n"; $text .= "🔗 [#{$objectID}::{$object->$field}](".$host.$viewLink.")\n"; $text .= "👤 负责人: {$assignedToName}\n"; $text .= "📝 备注: {$action->comment}";

改造后的消息推送效果对比如下：

开发注意：修改核心文件前建议创建备份，所有数据库查询应添加错误处理逻辑

3. 智能@提醒功能实现方案

在企业微信群聊中，单纯的文字提及往往无法有效提醒目标成员。通过实现精准的@功能，可以确保相关负责人第一时间收到通知。

企业微信@功能实现原理： 企业微信机器人API支持通过mentioned_mobile_list参数指定需要@的成员，被@成员的手机号必须与企业微信账号绑定手机号完全匹配。

关键实现步骤：

1. 从禅道用户表中查询负责人的手机号信息
2. 将手机号添加到消息体的指定参数中
3. 确保消息文本中包含@提醒文本

// 获取负责人手机号 $assignedToMobile = $this->dao->select('mobile')->from(TABLE_USER) ->where('account')->eq($object->assignedTo)->fetch('mobile'); // 构建企业微信API请求体 $message = array( "msgtype" => "text", "text" => array( "content" => $text, "mentioned_mobile_list" => [$assignedToMobile] ) ); // 发送请求 $response = $this->post($webhookUrl, json_encode($message));

常见问题排查表：

对于需要@多个成员的特殊场景（如跨部门协作任务），可以通过扩展查询逻辑实现：

// 多成员@实现 $ccList = explode(',', $object->mailto); $mobileList = $this->dao->select('mobile')->from(TABLE_USER) ->where('account')->in($ccList)->fetchPairs('mobile'); $message['text']['mentioned_mobile_list'] = array_values($mobileList);

4. 高级功能扩展与优化

基础功能实现后，我们可以进一步优化消息推送系统的用户体验和功能性。

消息卡片化展示： 企业微信支持markdown格式的消息卡片，通过改造消息格式可以显著提升可读性：

$markdown = "### [{$productName}] {$title}\n"; $markdown .= "---\n"; $markdown .= "- **任务编号**: #{$objectID}\n"; $markdown .= "- **负责人**: @{$assignedToName}\n"; $markdown .= "- **优先级**: {$object->pri}\n"; $markdown .= "- **备注**: \n> {$action->comment}\n"; $markdown .= "[查看详情](".$host.$viewLink.")"; $message = array( "msgtype" => "markdown", "markdown" => array("content" => $markdown) );

条件性@提醒策略： 并非所有消息都需要@成员，可以通过判断条件实现智能提醒：

$shouldAt = in_array($action->action, ['assigned', 'resolved']) || $object->status == 'active'; if ($shouldAt) { $message['text']['mentioned_mobile_list'] = [$assignedToMobile]; }

消息推送日志系统： 为便于排查问题，可以添加消息推送日志记录功能：

// 在model.php中添加日志记录 $this->dao->insert(TABLE_WEBHOOKLOG)->set(array( 'url' => $webhookUrl, 'data' => json_encode($message), 'response' => $response, 'datetime' => helper::now() ))->exec();

性能优化建议：

1. 对频繁调用的数据库查询添加缓存机制
2. 使用队列异步处理消息推送
3. 合并相同任务的连续变更通知

5. 企业微信API深度集成技巧

要实现更高级的集成效果，需要深入了解企业微信机器人API的特性。

消息类型选择指南：

安全增强措施：

1. 在禅道配置中加密存储Webhook URL
2. 实现IP白名单验证（企业微信支持设置可信IP）
3. 添加消息签名验证
4. 限制高频推送

// 签名验证示例 $timestamp = time(); $nonce = rand(100000, 999999); $signature = sha1(implode('', [$timestamp, $nonce, $secret])); $headers = [ "Content-Type: application/json", "Timestamp: {$timestamp}", "Nonce: {$nonce}", "Signature: {$signature}" ];

批量任务处理优化： 对于可能触发大量通知的批量操作（如迭代计划创建），应该实现消息合并功能：

// 批量任务消息合并 if ($action->action == 'batchcreate') { $text = "批量创建了".count($objectIDs)."个任务\n"; $text .= "👉 [查看详情](".$host.helper::createLink('task','browse',"projectID={$action->project}").")"; // 延迟发送以避免频繁打扰 $this->loadModel('queue')->send($webhookUrl, $text, time()+300); }

通过以上深度定制，禅道与企业微信的集成将不再局限于基础通知，而是进化为一个智能、高效的团队协作枢纽，显著提升项目管理的实时性和响应速度。