novu-design-workflow

工作流设计

适用于任何 Novu 工作流的设计规则——无论你是在 Dashboard（无代码）中创作，还是使用 @novu/framework 编写代码。这里的决策（渠道、严重性、关键通知、摘要、条件）在两种方式中都相同；只有语法不同。

要用代码创作？请将此技能与 framework-integration/ 搭配使用，了解 workflow(...)、step.*、controlSchema 和 Bridge Endpoint 设置。 要在 Dashboard 中或通过 Novu MCP 创作？完成此处的设计后，使用 dashboard-workflows/ 填写步骤内容（主题、正文、editorType、标头、条件）。

何时使用此技能

每当你需要决定工作流应采用什么形式时，都可以使用此技能：

• “设计一个订单确认工作流”
• “支付失败时应该使用哪些渠道发送通知？”
• “将此通知设为关键通知”
• “是否应该将其汇总到摘要中？”
• “为离线订阅者添加备用方案”
• “X 应该使用什么模板？”

不要将此技能用于：触发已有工作流（trigger-notification/）、编写代码封装（framework-integration/），或在 UI 中呈现严重性（inbox-integration/）。

严重性与关键通知

两个相互独立的设置。大多数工作流都不设置。

设置	可选值	默认值	效果
severity	LOW / MEDIUM / HIGH	未设置	在 Inbox 中进行视觉优先级排序（颜色、光晕）；影响摘要跳过规则。
critical	true / false	false	忽略订阅者偏好、跳过摘要、不延迟，并通过所有可用渠道发送。

经验法则：

• 大多数工作流都不设置 severity。仅在需要进行视觉优先级排序时才设置。
• HIGH = “今天就要处理”（支付失败、试用期明天到期）。
• critical: true = “无论偏好如何都要送达”（账号被停用、安全警报、密码重置）。
• critical: true ⇒ 自动跳过摘要，并立即通过渠道发送。

完整行为矩阵以及 readOnly 与 critical 的区别，请参阅 references/severity-and-critical.md。

渠道选择

如果用户指定了渠道

仅使用这些渠道。不要添加备用渠道，也不要添加其他渠道。如果组织尚未配置请求的渠道，也要添加，因为用户已明确提出要求。

“订单发货时发送推送通知” → 一个 push 步骤，不添加其他内容。

如果用户未指定渠道

从组织中已配置的渠道中，按以下优先级选择，最多选择 3 个渠道：

In-App  >  Email  >  Chat  >  Push  >  SMS

渠道	适用场景	跳过条件
In-App	产品内内容的默认渠道。如果用户正在使用你的产品，则始终包含此渠道。	接收者无法查看（重置密码、OTP、注册前）
Email	收据、文档、异步通信。In-App 之后的默认备用渠道。	产品内纯对话式提醒
Chat	已配置且 severity >= MEDIUM 时使用。适用于运维和内部流程中的 Slack/Teams。	营销或低严重性提醒
Push	订阅者离线但需要立即获知时使用的备用渠道。	订阅者在线时（改用 In-App）
SMS	最后的备用渠道。仅在其他渠道都不可用时使用（真正的紧急情况、OTP、监管要求）。	任何适合通过 Email 或 Push 发送的内容

完整的决策树请参阅 references/channel-selection.md。

摘要默认设置

添加摘要步骤时，默认使用：

• type: "regular"
• 回溯时间窗口：5 分钟
• 摘要时间：1 小时
• 键：subscriberId（对话式工作流使用 +threadId）

以下情况跳过摘要：

• severity: HIGH，或
• critical: true

有关摘要键的组成和对话示例，请参阅 references/digest-defaults.md。

用户状态逻辑

根据订阅者是否在线调整路由：

状态	行为
在线	立即发送 In-App。跳过 Push。根据严重性延迟发送 Email/Chat。
离线	使用 Push 或 Chat 引起注意。

默认延迟：

• B2B 应用 → 下一个工作时段
• B2C 应用 → 约 30 分钟

两个界面中，“订阅者离线”的判断条件相同，请参阅 references/step-conditions.md。

工作流模板

根据使用场景选择模板，并参照其结构编写。每个模板都指定严重级别、是否为关键工作流、是否可执行，以及交互类型，还规定了步骤顺序。

#	使用场景	严重级别	是否关键	备注
1	订单确认	none	false	汇总后发送，应用内 + 电子邮件 + 推送（仅离线时）
2	有人评论了你的帖子	none	false	按 subscriberId + threadId 汇总
3	付款失败	HIGH	false	应用内 + 聊天 + 电子邮件 + 推送（离线时）
4	账户已暂停	HIGH	true	所有渠道，不遵循偏好设置，不汇总
5	忘记密码	none	true	仅电子邮件 + SMS，不使用应用内通知
6	试用期将于明天到期	HIGH	false	应用内 + 聊天 + 电子邮件 + 推送（离线时）
7	明确指定渠道	n/a	n/a	仅使用用户指定的渠道
8	Webhook / 外部 API 调用	varies	varies	在渠道步骤后添加 step.http
9	获取数据后发送通知	varies	varies	首先执行 step.http；声明 responseBodySchema

完整的 ASCII 流程和各模板元数据见 references/workflow-templates.md。

步骤条件

条件决定是否执行某个步骤。可用于“仅在订阅者离线时发送”、“仅当应用内通知未被查看时发送电子邮件”等回退场景。

• Dashboard 作者使用 JSON-Logic：{ "==": [{ "var": "subscriber.isOnline" }, "false"] }
• Framework 作者向步骤传入 skip: () => boolean 回调。

两者的语义相同。规范示例以及各作用域中可用的变量见 references/step-conditions.md。

常见问题

1. 不要默认设置严重级别——除非确实需要视觉优先级，否则请留空。
2. critical: true 不等于 readOnly: true——readOnly 只会在 Preferences UI 中隐藏工作流；critical 则会在运行时跳过偏好设置和汇总。参见 references/severity-and-critical.md。
3. 用户指定了渠道时，不要添加回退渠道——明确指定的渠道就是全部渠道。
4. 用户未指定渠道时，渠道数量最多为 3 个。渠道越多只会增加打扰，不会扩大触达范围。
5. 不要将汇总与 critical: true 结合使用——关键工作流必须立即送达。汇总步骤会自动跳过。
6. 对话流程中的汇总键很重要——如果不包含 +threadId，对帖子 A 和帖子 B 的评论会被汇总到一起。
7. 仅在用户离线时发送推送——向在线用户发送推送会与应用内提醒重复。
8. HTTP 步骤需要 responseBodySchema——否则，下游步骤无法通过 {{ steps.<id>.<prop> }} 读取响应属性。

参考资料

• 渠道选择 — 完整决策树和各渠道指南
• 严重级别与关键工作流 — 行为矩阵、偏好设置与汇总的交互，以及 readOnly 与 critical 的区别
• 汇总默认设置 — 时间窗口、键和对话汇总模式
• 步骤条件 — JSON-Logic 示例和 Framework skip 对应写法
• 工作流模板 — 9 个参考流程及其严重级别、关键状态和交互表

另请参阅

• dashboard-workflows/ — 为 Dashboard 或 Novu MCP 工作流编写步骤内容（主题、正文、editorType、标头、条件）
• framework-integration/ — 在代码中实现这些设计（workflow()、step.*、controlSchema、Bridge）
• manage-preferences/ — 了解 critical 如何与订阅者级偏好设置交互
• inbox-integration/ — 了解严重级别如何在 Inbox 中直观呈现
• trigger-notification/ — 触发已设计好的工作流