20 KiB
消息渠道设计:站内信之外,同一句话送到邮箱与群机器人
对应缺口:docs/oa-capability-review.md §3「消息只有站内信」。
落脚:backend/app/service/channels.py(入队 + 投递 + 重试)、backend/app/api/notify_channels.py(配置接口)、
backend/app/engine/engine.py::notify(唯一写通知的入口)、
frontend/src/views/oa/NotifyChannelView.vue(/settings/notify-channels,权限 system:notify)、
验收 backend/tests/oa_platform.py(SMTP 桩 + 机器人桩,都在测试进程内起)。
0. 一句话结论
站内信的问题是它只在人已经打开 OA 的时候才有用——待办提醒的价值恰恰在人没看系统的那一刻。
这一版把写通知收敛成一个入口 engine.notify():站内信照旧落库(一条都不少),
同一个事务里再按配置给每个渠道排一条投递,后台线程慢慢发。业务代码里没有任何一行"发邮件"。
配置面压到三格:发到哪(SMTP 账号或机器人地址)、发什么事(勾事件)、以什么身份发(口令 / 加签密钥)。 没有第四格,因为第四格通常是"收件人规则",而那一格一旦开放就会出现"配了渠道却不知道发给谁"。
唯一的例外是 hub_wecom 那一格的收件人标识:它不改"发给谁"(还是站内信那批人),
只说"向统一身份要到这个人时按哪一列报名字"。这不是收件人规则,是寻址方式,
所以开放它不会长出"配了渠道却不知道发给谁"那张脸。
1. 支持哪些渠道
models.NotifyChannel.KINDS,界面上是六个选项:
| 种类 | 传输 | 要填的东西 | 典型用法 |
|---|---|---|---|
email 邮件 |
SMTP(ssl / starttls) |
服务器、端口、加密、账号、口令、发件人 | 给每个人发到自己邮箱 |
dingtalk 钉钉群机器人 |
群机器人 Webhook | 地址 + 加签密钥 | 财务群、部门群提醒 |
feishu 飞书群机器人 |
群机器人 Webhook | 地址 + 加签密钥 | 同上 |
wecom 企业微信群机器人 |
群机器人 Webhook | 地址 | 同上 |
webhook 自定义 HTTP |
POST JSON | 地址 + 签名密钥 | 自建企业微信应用、内部短信网关、值班系统 |
hub_wecom 企业微信应用消息 |
交给统一身份 Hub 代发 | 形态(卡片 / 纯文字)、标题额度、收件人标识(按哪一列认人) | 推到个人手机 + 点开直接批那张单 |
第五种是留的口子,不是凑数:内部短信网关这类需要企业级凭证与各自的 token 换取流程,
把它们各做成一种内置渠道,等于把几套外部账号体系搬进配置页。
webhook 渠道发出去的是一封结构固定的 JSON(event / title / body / person / job / url),
中间转换交给对方那半公里。
第六种是"转发型"渠道,跟前五条不一样:前三条群机器人只能发到群里(谁都能看见、也
可以谁都不理),"工作通知"要发到个人手机上还得点开就是自己那条待办,这需要企微应用凭证、
access_token、可信 IP 一整套。这一套统一身份 Hub 已经替所有下游系统做了,所以本系统
不再持有第二把企微密钥,只调 Hub 一次 HTTP;点开那张卡片回到的是已经跑通的免登回调。
口径、逐人失败语义与前提清单见 docs/hub-integration.md §15(对接文档 9.6),
方案沿革见 docs/wecom-app-notification-plan.md。
Hub 只认两种收件人标识:user_id(users.hub_user_id,人员主键)与 account
(users.account,登录账号)。用哪一种、按什么顺序退回,是渠道上的 config.receiver,
界面上是四档并排的选择,旁边写着每一档能覆盖多少个在职账号;投递记录用
oa_notify_delivery.target_field 记住每一串标识是按哪一列取的。口径见
docs/hub-integration.md §15.3。
2. 事件
channels.EVENTS 七项,取值与 oa_notification.type 一致——同一个"新的待办"在站内信和
邮箱里必须是同一件事,两套取值迟早对不上。只有一档例外:rerouted 在站内仍旧是 control
(挂起 / 恢复 / 改数据 / 改道共用站内那一类留痕,不该拆成四档),只有往外发的那一路单独立一个名,
好让渠道能只勾「流程被干预改道」而不必把整类 control 都推出去:
| 事件 | 含义 |
|---|---|
task |
新的待办 |
press |
催办提醒 |
read |
抄送 / 分享 / 评论 |
completed |
办结结果 |
expire |
待办超时 |
meeting |
会议提醒 |
rerouted |
流程被干预改道(站内那条是 control;存量渠道的 events 里没这个值,默认一句都不往外推,要谁勾谁) |
渠道上勾事件,不勾就一条不发。全局还有一个总开关(系统设置 → notify_channels_enabled),
关掉之后站内信照写、渠道一条不入队——入队前先看开关,所以关掉它不会给办结、提交这些热路径
留任何额外查询。
3. 收件人从哪来
不做配置项。 engine.notify(identities, …) 已经知道这句话该对谁说(待办处理人、被催办的人、
被抄送的人),渠道就发给同一批人:
- 邮件:从用户账号上取
email,格式不对当没有; - 群机器人:发往渠道自己填的那个地址;
- Hub 企业微信:按渠道上
config.receiver给的顺序认人——默认先取users.hub_user_id(统一身份的人员主键),取不到退回users.account;一种都取不到才落skipped。 押账号上是会坏事的——账号会被企业微信那边同步改写,所以它只配当退路;但主键不可信的 环境(同步回来的 id 与目录对不上、账号全是本地自建)可以把它调成主位,甚至只认账号。 顺序是渠道上可配的一格,四档与覆盖人数见docs/hub-integration.md§15.3。
拿不到收件人不静默丢,落一条 skipped 并写明原因("这个账号没有邮箱,去「组织人员」里补上之后可以重发")。
这条与失败分开统计——没邮箱不是系统坏了,混在失败里会让运维天天去看根本不存在的故障。
补完邮箱之后那条记录还能就地重发。
Hub 企业微信一人一条
hub_wecom 不进上面那段合并:卡片点开是"我的那条待办",收件人必须在一条消息里唯一确定,
而且逐人失败原因(谁没绑企微、谁不在可见范围)得有个地方记,合并成一条就没处记了,
自动补发也就无从谈起。三个人的会签 = 三条独立卡片 + 三行投递记录。
顺带一件同样只有"一人一条"才做得了的事:/todo/<task> 只发给这条待办的持有人。
notify() 对整批收件人只传一个 task=("外部审批那一环超时"会连兜底管理员一起知会),
合并成一条时这种差别根本没法落进链接;一人一条之后入队时按人核一次归属
(channels.hub_task_links),不是持有人的就把 task 抹掉,深链退回 /work/<job>。
群机器人一批发一条
notify() 一次可能带三个处理人(会签)。一人一条发到群里 = 群里三条一模一样的"您有一张待办",
两天就能把这个群熬成免打扰。所以邮件保持一人一封,机器人和自定义回调按批合并成一条,
收件人名字并进 person_name 与正文(提醒:张三、李四、王五)。投递记录里那一行记的是
"这一批",重发也就是一次重发一条群消息,不会重发三遍。
4. 投递链路
engine.notify() ──同一事务──▶ oa_notification(站内信)
└▶ oa_notify_delivery(pending,每人 × 每渠道一行)
└─提交那一刻─▶ 叫醒调度线程(service/wake.py,跨副本发一条 Redis 广播)
后台调度线程 ──▶ claim() 认领 ──▶ 真发 ──▶ success / failed(退避) / dead(喊人)
oa_notify_delivery 一张表同时是留痕和重试队列(与写回发件箱同一套底线,
见 docs/outbound-integration-design.md §5):
- 退避
60s → 5min → 30min,次数用满进dead,死信在界面上能就地重发; claim()认领互斥:一条UPDATE ... WHERE status='pending'把行锁给自己,多副本时 同一封邮件只有一个进程发得出去(配合docs/multi-worker-deployment.md的调度租约,双保险);- 卡在
sending的会被捞回来:进程死在发送途中,下一轮recover_stuck()把它放回队列, 不会永远停在"正在发送"; - 可重试与不可重试分得很清:连不上、超时、5xx 算可重试;SMTP 口令被拒、收件人被拒、 机器人返回业务错误码(钉钉/飞书/企微连不上时报的往往是 HTTP 200 + errcode≠0)直接进死信—— 重试一百次也不会变成成功,只会把日志刷满;
- 入队当场发,不等轮询:投递记录随
notify()那次事务提交,提交的那一刻由service/wake.py把调度线程叫醒(写回、渠道、事件三条路共用;跨副本走同一条 Redis 广播)。这一条是必需的而不是 锦上添花——叫醒原本只有写回发件箱有,本部署oa_notify_delivery上量得出来:一条企微推送从create_time到sent_at等了 28 / 35 / 55 / 60 秒,而ms那一格写着真发只用了 1 秒。 轮询(下一条)退回"叫不醒也要发出去"的兜底,钉住它的是scripts/check_notify_wake.py; - 调度周期自适应:
main.py::_scheduler_tick_seconds()发现发件箱 / 渠道 / 事件队列里有到点的 活,就把 60 秒收紧到 15 秒;没活时不空转; - 一轮有 20 秒的时间预算:
channels.run_due()发满就收工,剩下没认领的行状态一动没动, 下一轮(或被新消息叫醒的那一轮)接着发。否则一个慢 SMTP 网关把 40 条各顶满超时,刚排上的那条 提醒就算被叫醒也要排在别人后面等完。
每条记录都留 attempts / response / ms / last_error。"消息丢了"必须看得见,
排错时第一个问题永远是"到底发出去没有、对方说了什么"。
5. 正文
留空用系统默认文案(标题 + 正文 + 单据链接),填了就用模板,可替换
{title} {body} {url} {person} {time} {type}。正文进邮件和机器人时截 1000 字——
机器人有长度墙,而且消息不该变成第二份表单,详情让人点链接进去看。
链接取「系统设置 → 站点信息 → 系统访问地址」拼 /work/<job>,没配就只留相对路径。
6. 密钥与权限
- 配置里的
password/secret/token只进不出:回显只说"已设置",保存时没改动就沿用旧值 (scrub_config/merge_config,与数据源、AI 服务商一个口径); - 机器人地址里带
access_token,投递记录里一律打码(mask_target); - 改渠道要
system:notify,看投递记录也要——那里面有收件人邮箱; - 测试发送只发给点按钮的人自己:邮件发到他自己邮箱,群里发一条明写「测试」的消息。
配渠道的人必须先在自己身上验过,而不是配完等用户来报"没收到"。他自己没邮箱就当场直说。
Hub 那一路额外带一条
target_path=/todo的深链——点开那一跳(Hub 认人 +redirect) 是这条链路上最容易配错的一段,测试发送得一起验掉; hub_wecom的密钥不在渠道上:它跟「系统设置 → 统一身份」的hub_integration_key是同一把,与免登换票、目录导出共用。渠道上没有可泄露的东西,scrub_config那套 "只进不出"对它不适用(它压根没有密钥格)。
7. 明确不做
- "在群里直接同意":要企业应用回调 + 对方平台后台配置 + 一套身份回查,
属于"接进企业微信/钉钉工作台"那一档工程,不是消息渠道该顺手做的。
("卡片 + 点开直达待办"这一半已经随
hub_wecom做了:卡片上没有按钮, 同意/退回在点开之后的页面里做,docs/wecom-app-notification-plan.md§10.4 说的是同一件事;) - 个人级消息偏好(我自己只要邮件不要群消息):等有真实诉求再加,先让管理员统一配, 避免"渠道配了但每个人都能关"这种排查噩梦;
- 免打扰时段 / 摘要合并:
expire与press的量都很小,先不上; - 短信渠道:走
webhook那一条接内部短信网关; - 回执(已读 / 送达):邮件与机器人给不了可信回执,不假装能。
hub_wecom是个例外的一半:Hub 给的是逐人投递结果(送到企微了没有)而不是已读, 界面上有个「回查送达」按钮按msg_key去问一次,仍然不承诺"他看过了"。
8. 站内信自己的生命周期:事项办完,提醒就该退
渠道那一层管"同一句话怎么再送一份出去",这一节管站内信这一份在本系统里活多久。 用户报的是最直白的一种现象:待办全部办完,右上角铃铛里那叠通知还挂着四条 「您有新的待办」,小红点不灭;按了「全部已读」,列表照旧摆在原处。
根因不在界面,在库:oa_notification 只在写进去的那一刻有人看。engine.notify()
发完就不管,接口只有「点开算已读」与「全部已读」两个手动口子;而待办本身是会消失的
——_complete_task 直接删行、或签把同级一起结掉、转办与交接换持有人、终止与办结清空整单,
每一条都不回头动站内信。于是这张表变成一份只进不出的流水,越堆越厚。
判据只有一句:一条提醒值不值得摆着,看它指向的那件事还在不在收件人自己手上。
落在 app/service/notify_settle.py::settle(),两条 UPDATE:
| 类型 | 什么时候收尾 |
|---|---|
task / press / expire |
那条待办(oa_notification.task)已经不在收件人名下——办完、转走、被或签结掉、整单终止都算。没记待办号的老数据退一步按「这一单上还有没有我的待办」判 |
read |
这一单上已经没有收件人的待阅(mark_read 与办结搬档都是删行) |
completed / control / meeting / integration / check |
永远不收:说的是已经发生的一件事,不指向任何要办的东西。终止那句「待办已终止」就是 control,它是新消息而不是过期提醒 |
三处取值与判据的对应关系值得记一下:这三类正好是 channels.HUB_TASK_EVENTS
(点开落待办页、要人办事的那一族),而 EVENTS 里除 rerouted 之外的事件名与
oa_notification.type 一字不差——同一件"新的待办"在站内信、邮箱、企微里必须是同一件事,
两套取值迟早对不上。rerouted 那一条例外见 §2。
收尾挂在读出口,不挂在写出口。 待办消失有七八条路子(办结、或签自动结、转办、
交接、退回、撤回、终止、管理员改派),在引擎里逐处挂钩子等于留七八个"漏挂一处就再报一次"
的坑,而且升级前那些早就该退的存量通知一条也补不回来。收在 GET /notification、
GET /notification/unread/count、GET /statistics/workbench 三个出口,
一条 UPDATE 判完,八条路子连历史数据一起管住。代价是"读一次库会写一次已读",
换来的是列表、角标、工作台那个数字永远是同一份账;没未读时那条 COUNT 直接回 0,
一条 UPDATE 都不许多跑(这颗角标 15 秒问一次)。
收尾是标已读(补 read_time),不是删行:投递记录 oa_notify_delivery.notification
要能回查对应的那条站内信,"谁在什么时候收到过什么"也不该因为事项办结就从库里蒸发。
界面这一侧跟着收一次口径:铃铛下拉、手机版通知弹层、首页那张通知卡片只摆没读过的。 这一屏是"还有什么没告诉你",不是历史归档——读过一条就退场,事项办完的那条由后端收尾; 要翻旧账去待办 / 已办 / 待阅 / 单据详情。以前这里连着已读的一起摆, 「全部已读」按下去列表纹丝不动,正是截图那一张的观感。
9. 验收
原本挂在 backend/tests/oa_platform.py 的那一整套(SMTP 桩 + 机器人桩)随测试目录一起
在 2026-10 清掉了,留着是说明这一层原本验到哪:事件订阅过滤、没邮箱落 skipped 并说明原因、
钉钉加签可复算、HTTP 200 + errcode 非 0 算失败、退避重试、重试用满进死信、人工重发、
卡住回收、claim() 多进程互斥、测试发送的收件人、权限拦截,以及同一批收件人只发一条群消息。
眼下真能跑的是 backend/scripts/check_notify_hub.py:进程内起一台假 Hub,不连库、
不碰真 Hub,把 hub_wecom 这一路钉住——收件人标识按渠道配的那一列认(默认主键优先、
只勾一种就不退回、串和列表都洗成一种写法、人没了才回落记录里 target_field 那一列)、msg_key 跨重试稳定而
人工补发换世代、深链只发站内相对路径、标题/正文/markdown 三档字节预算、逐人原因分档
(重试 / 跳过 / 死信)、请求级 401/403/400 判死与 409/5xx 退避、duplicate 算成功、
回查按 receiver 回显对齐到人、入队一人一条且待办深链只给持有人、免登落地只认站内 redirect、
Hub 缺 home_url 时摘掉深链降级成纯提醒而其它 400 不瞎降级、Hub 的零值 sent_at 不当发送时间。
接口那一层另有一条 check_notify_hub_api.py:连开发库、起真 TestClient,只把 Hub
指到进程内那台假 Hub,验 notify/meta 报底细、保存校验形态与额度、换种类不留上一档参数、
收件人标识的四种写法与非法值、覆盖人数随渠道列表回一份、测试发送真发给本人并带 /todo 深链、
回查与补发的键怎么算、投递记录的权限收口。
界面那一半由 frontend/src/views/oa/NotifyChannelView.receiver.spec.ts 钉:列表说得出
当前按哪一列认人、编辑框摊开四档并选中库里那一档、每一档带覆盖人数、换档保存出去的是
config.receiver 那根数组、投递记录里的标识带着它是哪一列取的。
投递记录的分页由 frontend/src/views/oa/NotifyChannelView.pagination.spec.ts 钉。
这一屏以前是 GET /notify/deliveries?limit=80 一刀切:跳过和失败动辄几百行堆在这儿,
第 81 条往后压根翻不到,而"上周那批为什么没发出去"恰恰在第 81 条往后。现在和待办、
操作日志一个口径——page / page_size 进,total / pages 出(serializers.page)。
钉住的是:分页器念得出后端给的总数、点第几页就带 page=几 去要(不是把到手的一页切一切)、
换任何筛选(状态 / 渠道 / 关键词)都回第 1 页、每页条数换档传的是 page_size、
补发之后仍留在当前这一页。顺带修掉「全部」那一格永远是 0:它读的是 counts 里 ''
那一项——当前筛选下的总数,counts 跟着渠道 / 类型 / 关键词走,但不跟着状态走,
否则选中的那一档永远等于「全部」。
点卡片回来的落地那一跳由 check_notify_landing.py(后端:真路由 + 假 Hub 的验票接口)
与 frontend/src/views/auth/SsoCallbackView.landing.spec.ts(前端:换到会话之后落哪一页)
一家一半钉住,口径见 docs/hub-integration.md §15。
cd backend && PYTHONPATH=. python3 scripts/check_notify_hub.py
cd backend && PYTHONPATH=. python3 scripts/check_notify_hub_api.py # 这条要连开发库
cd backend && PYTHONPATH=. python3 scripts/check_notify_settle.py # §8 站内信生命周期(内存 sqlite,不碰生产库)