DooTask 消息提醒规则详解:强提醒 / 弱提醒 / 无提醒三层判定与免打扰配置

原创2026-10-14 13:37:291,666 阅读
文章标签:后端前端桌面应用协同办公

DooTask 消息提醒规则详解:强提醒 / 弱提醒 / 无提醒三层判定与免打扰配置

DooTask 的即时消息模块(messenger)将「是否打扰用户」抽象为一套可预测的提醒规则:服务端在推送时先为每条消息计算 silence 标志,客户端再叠加用户的会话免打扰状态,最终决定弹窗、红点还是仅累积未读。本文以官方概念文档 消息提醒规则 为骨架,结合仓库源码(WebSocketDialogMsg.php、WebSocketDialogMsgTask.php、DialogController.php)逐层拆解这套机制,帮助你回答“谁会被提醒、为什么收不到通知、如何精确控制打扰”三类问题。

一句话模型:消息属性 + 用户偏好 + 系统通道

DooTask 的消息提醒由「消息属性 + 用户偏好 + 系统通道」三层共同决定:

  1. 消息属性:这条消息本身是什么(普通文本、@ 提及、@所有人、通知/模板消息、是否显式标记 silence=yes)。
  2. 用户偏好:用户在某个会话上是否开了免打扰(web_socket_dialog_users.silence)。
  3. 系统通道:桌面端 / 移动端各自的系统通知开关,以及系统级禁言/静默策略。

服务端推送时先打上 silence 标志,客户端收到推送后,再根据用户自己的免打扰、勿扰状态决定是否弹窗。也就是说,同一消息对不同用户可能呈现完全不同的提醒强度。

三档提醒强度定义

级别 行为表现 典型触发场景
强提醒 弹出系统通知 + 红点 + 数字未读 普通文本 / 文件 / 语音 / 会议消息、@ 提及、@所有人
弱提醒 仅累计未读 + 红点,不弹窗 会话免打扰、消息带 silence=yes、notice/template 类消息
无提醒 静默写入,连未读都不增加 系统重发、内部刷新、修改/撤回类 update 推送

三个档位的区别不只是“弹不弹窗”,而是是否产生未读计数。弱提醒虽然不打扰用户,但依然会在会话列表上形成红点与未读数字,用户进入会话即可看到;只有无提醒消息不会影响任何未读统计。

关键消息属性如何影响提醒

1. @ 提及(mention):最高优先级,免打扰也强制弹窗

被 @ 的用户无论会话是否开了免打扰,都会被强制降级为强提醒。这一逻辑在推送任务中实现:

// app/Tasks/WebSocketDialogMsgTask.php
$mention = array_intersect([0, $userid], $mentions) ? 1 : 0;
$silence = $mention ? false : $silence;   // 被提及则强制不静默

对应地,每条消息的接收记录 web_socket_dialog_msg_reads 中会单独记录 mention 字段(是否被提及),前端据此展示“提及我”的未读分类。被 @ 的成员如果不在当前会话内,还会被自动拉入会话(msgJoinGroup,仅限群聊且发送者是群主或群内无群主时)。

2. @所有人:群广播,所有成员强提醒

@所有人属于群广播,群内每个成员都会被当作强提醒对象处理——前提是成员本身没有被会话免打扰之外的全局策略压制(系统管理员配置的全局静默策略除外)。

3. 消息标记 silence=yes:以弱提醒入库

调用发消息 API 时可通过 silence=yes|true|1 显式声明静默。服务端解析逻辑如下:

// app/Http/Controllers/Api/DialogController.php
$silence = in_array(strtolower(trim(Request::input('silence'))), ['yes', 'true', '1']);

该标志会一路传递到 WebSocketDialogMsg::sendMsg 的 $push_silence 参数,最终写入推送任务。典型的应用场景是 AI 流式增量消息:例如 AI 任务建议模块先用 push_silence=true 发送一版消息,再通过 change-{msg_id} 更新为最终内容(见 AiTaskSuggestion.php),全程不打扰用户。

4. 通知 / 模板 / 系统消息(type=notice/template):默认弱提醒

WebSocketDialogMsg::sendMsg 对 push_silence 的默认值做了类型判定:

// app/Models/WebSocketDialogMsg.php
if ($push_silence === null) {
    $push_silence = !in_array($type, ["text", "file", "record", "meeting"]);
}

即只有文本、文件、语音、会议这四类消息默认强提醒,其余类型(notice、template 及系统消息)默认弱提醒——静默入库、不触发响铃/振动,但正常累积未读。这是很多用户“通知没声音”的直接原因。

用户级配置:免打扰开关怎么生效

会话级免打扰:api/dialog/msg/silence

单会话免打扰走 dialog/msg/silence 接口(DialogController.php),参数为 dialog_id + type=set|cancel:

  • set:将该会话置为免打扰,并且把当前所有未读消息批量标记为已读(通过 WebSocketDialogMsgRead::onlyMarkRead 分批处理),保证开启免打扰后未读数不再累积;
  • cancel:恢复强提醒。

会话免打扰状态存储在 web_socket_dialog_users.silence(0 否 / 1 是,见 WebSocketDialogUser.php)。

重要限制:只有普通自建群(type=group 且 group_type=user)和单聊以外的会话才能设免打扰?源码恰恰相反:

if ($dialogData->type === 'group' && $dialogData->group_type !== 'user') {
    return Base::retError("此会话不允许设置免打扰");
}

即普通自建群(group_type=user)允许设免打扰,而项目群、任务群、部门群、全员群等系统群不允许(对话类型说明)。同时单聊(type=user)在源码层面也不走会话免打扰通道,因此单聊静默只能依赖客户端通知开关。

推送任务的合并逻辑

会话免打扰最终在推送任务中与消息级 silence 合并:

// app/Tasks/WebSocketDialogMsgTask.php
$silence = $this->silence || $silences[$userid];   // 消息静默 或 会话免打扰 → 静默
...
if ($item['userid'] != $msg->userid && !$item['silence'] && !$this->silence) {
    $umengUserid[] = $item['userid'];              // 只有强提醒才走 App 推送
}

被合并为 silence=1 的用户不会收到友盟(Umeng)App 推送,只会收到 WebSocket 的 mode=add 更新(前端仅累积未读)。@ 提及在此处再次生效:$silence = $mention ? false : $silence,所以被 @ 时 App 推送照发不误。

前端如何消费 silence 标志

客户端收到 WebSocket 消息后,在 actions.js 中解构 {mode, silence, data}:

  • 未读计数逻辑照常执行(unread + 1,被提及再 mention + 1);
  • 但 emitter.emit('dialogMsgPush', {silence, data}) 会把 silence 一并广播给界面组件,由各端(桌面端 / 移动端)决定是否弹系统通知、是否响铃振动。

所以“免打扰”在服务端的语义是压制弹窗与 App 推送,但绝不吞掉未读。

全局系统配置:默认静默策略

管理员可在「系统设置 → 消息设置」中配置三个全局字段(SystemController.php):

字段 含义 默认值
user_private_chat_mute 私聊默认静默策略 open
user_group_chat_mute 个人群聊默认静默策略 open
all_group_mute 全员群禁言 open

注意 user_private_chat_mute / user_group_chat_mute 在源码中实际承担的是**禁言(能否发言)**职责,由 WebSocketDialog::checkMute 在发消息前按会话类型路由判定(WebSocketDialog.php):配置为 close 时普通成员发消息会收到「个人会话禁言 / 个人群组禁言 / 当前会话全员禁言」错误,管理员与机器人不受限。完整配置说明见 群组与私聊禁言设置。它与“提醒强弱”是两个独立维度:一个是“能不能发”,一个是“发了怎么提醒”。

桌面端 / 移动端各自的系统通知开关则位于客户端设置中,属于最后一层用户主动控制。

三层决策的完整流程

一条消息从发送到呈现,完整链路如下:

  1. 发送端:调用 dialog/msg/send 等接口,可选传 silence=yes;WebSocketDialogMsg::sendMsg 根据类型确定默认 push_silence(text/file/record/meeting 为 false,其余为 true)。
  2. 入库:消息写入 web_socket_dialog_msgs,每个接收人写入 web_socket_dialog_msg_reads(含 mention、silence、dot 字段)。
  3. 推送任务:WebSocketDialogMsgTask 遍历会话成员,合并「消息级 silence ∨ 会话免打扰」,再被 @ 强制解除;强提醒用户进入 Umeng App 推送队列。
  4. 客户端:WebSocket 收到 mode=add 推送,silence=1 时不弹窗不响铃,仅累计未读 + 红点;silence=0 时弹系统通知并响铃振动。

常见排查:为什么收不到通知

对照三层模型,逐项检查:

  1. 会话免打扰是否开启:进入会话查看是否有免打扰状态(web_socket_dialog_users.silence=1);注意设置免打扰时会把历史未读一并标记已读,可能让你“感觉消息丢失”。
  2. 消息类型:notice / template / 系统消息默认就是弱提醒,本就无响铃振动;AI 流式消息带 silence=yes 同理。
  3. 客户端系统通知开关:桌面端 / 移动端的系统通知是否被系统级关闭(属于客户端设置,服务端无法覆盖)。
  4. 全局禁言策略:管理员将 user_private_chat_mute / user_group_chat_mute / all_group_mute 置为 close 时,普通成员无法发言,自然“没有通知”;管理员与机器人不受限。
  5. 是否被 @:未被 @ 且会话免打扰 → 弱提醒;被 @ → 强制强提醒(App 推送照发)。

当前版本不支持的能力

为保证预期管理,文档明确列出以下不支持项(版本以仓库 last_verified 为准):

  • 不支持按时间段定时静默(如 22:00–08:00 勿扰),只支持按会话开关,也没有后台定时任务做时段压制;
  • 不支持自定义提醒铃声,使用系统默认声音;
  • 不支持把单聊设免打扰(dialog/msg/silence 只对普通自建群开放),单聊静默只能依赖客户端通知开关;
  • 弱提醒(含免打扰)仅压制弹窗通知,未读数仍然累计——这是刻意设计,防止消息被静默吞掉。

理解了“消息属性 + 用户偏好 + 系统通道”三层模型之后,无论是配置团队静默策略、排查收不到通知,还是理解 AI 流式消息为何安静,都能一眼定位到对应的源码层级。

登录后查看全文
dootask