Notion 与 Temporal 分布式长周期工作流引擎及人工审批(Human-in-the-Loop)状态机协同实战:从超时重试、Signal 审批回传到 Formula 2.0 SLA 门禁闭环
一、为什么跨天/跨周的企业级长周期审批不能只靠普通 Webhook 与 Cron 轮询? #
在企业级 SaaS 订单履约、大额合同法务审批、云资源超配申请与跨部门发布窗口(Release Train)管控中,一个业务流程往往会跨越数小时甚至十几天,期间需要串联多个外部微服务调用、定时等待窗口期以及多轮人工介入确认(Human-in-the-Loop)。如果只用传统的“普通 Webhook + 定时 Cron 轮询数据库”来驱动 Notion 业务流程,很快就会踩中三大可靠性陷阱:
- 长周期等待极易在服务端重启或超时后“状态丢失”:无代码自动化工具或普通 HTTP Serverless 函数通常有 30 秒至 15 分钟的执行超时限制,无法原生挂起等待法务或财务主管 72 小时后的审批点击;一旦中间服务重启,流程上下文就会彻底中断。
- Webhook 乱序到达与人工重复点击引发“双重放行/重复扣款”:审批人在 Notion 界面快速双击了两次“同意”,或上游系统并发推送了状态变更事件,普通脚本缺乏确定性状态机(Deterministic State Machine)与幂等信号锁,极易触发重复建单或重复打款。
- 人工审批节点长期无人响应时,缺乏自动升级与补偿回滚(Saga Compensation)机制:审批卡在某位休假负责人名下 5 天无人问津,既没有自动发送二次催办并切换替补审批人,也无法在整体超时后自动回滚已预占的云资源或库存配额。
Temporal 作为工业级持久化执行(Durable Execution)工作流引擎,擅长在代码层原生挂起等待数周、精确管理指数退避重试与 Saga 补偿回滚;而 Notion 则是业务团队、法务与管理层最顺手的可视化任务与审批操作台。两者结合即可形成“Temporal 管可靠编排与超时补偿 + Notion 管人工决策与审计呈现”的高可用闭环:
| 评估维度 | 自建数据库 + Cron 轮询状态机 | 传统无代码 Webhook 串联平台 | Notion + Temporal 持久化协同中枢 |
|---|---|---|---|
| 长周期挂起与重启容灾 | 需手工维护状态表与锁机制,极易产生僵尸任务 | 单次运行受限于平台超时上限,跨天等待需拆分多条孤立流 | Temporal Workflow 原生持久化执行栈,宕机重启零丢失 |
| 人工审批(Human-in-the-Loop) | 审批按钮与后端代码割裂,状态易失步 | 审批通过后常因瞬时 502 导致后续动作漏发 | Notion 状态变更触发 Temporal Signal,精准唤醒挂起协程 |
| 局部失败补偿(Saga 回滚) | 失败半截状态极难清理,需 DBA 手工修数 | 基本无原生分布式回滚能力,只能靠人工收尾 | 任一 Activity 耗尽重试后自动按逆序执行 Saga 补偿并回写 Notion |
| 审批超时升级与 SLA 治理 | 靠堆叠大量定时扫描 SQL 实现超时催办 | 缺少精细的动态 SLA 倒计时与升级路由 | Temporal Timer 自动触发催办升级,Formula 2.0 实时亮灯门禁 |
二、Notion 长周期业务流程与 Temporal 人工审批三表数据库架构 #
建议在 Notion 中建立“工作流实例主台账 + 人工审批节点工单 + 异常补偿审计流水”三表联动模型,使每一次 Temporal 编排的推进与人工干预都有据可查(多表关联与属性规范可参阅 关系和汇总官方指南 与 数据库架构速查表):
| 数据库名称 | 核心属性(字段名与类型) | 角色职责与权威来源(SSOT) |
|---|---|---|
DB_Workflow_Instances(工作流实例主台账) | Workflow_ID (Title,如 wf-release-20261119-008)、业务类型 (Select:大额合同审批/云资源扩容/生产发布窗口)、Temporal_Run_ID (Text)、当前编排阶段 (Status:运行中/等待人工审批/已完成/已触发Saga回滚/执行失败)、发起人 (Person)、关联审批节点 (Relation -> DB_Human_Approval_Tasks)、关联补偿流水 (Relation -> DB_Workflow_Compensation_Logs)、流程启动时间 (Date)、流程健康门禁 (Formula 2.0) | 映射每一个 Temporal Workflow 实例的全生命周期状态,是全局跟踪唯一入口 |
DB_Human_Approval_Tasks(人工审批节点工单) | Task_UID (Title,如 APR-wf-release-008-stage2)、关联工作流 (Relation -> DB_Workflow_Instances)、审批阶段名 (Text,如 安全负责人复核)、指定审批人 (Person)、审批决策 (Select:待审批/批准放行/驳回终止/超时自动转审)、审批截止时间 (Date)、审批批注 (Text)、信号已投递 (Checkbox) | 承接业务人员在 Notion 中的实际审批交互,状态落库后向 Temporal 发送 Signal |
DB_Workflow_Compensation_Logs(Saga 补偿审计流水) | Comp_UID (Title,如 COMP-wf-release-008-step1)、关联工作流 (Relation -> DB_Workflow_Instances)、补偿动作名 (Text,如 释放预占GPU配额)、补偿结果 (Select:补偿成功/补偿失败需人工介入)、触发原因 (Text)、执行时间 (Date) | 记录任何环节失败或审批驳回后 Temporal 自动逆序回滚的完整审计证据 |
三、五步实现 Notion 状态流转触发 Temporal Signal 与幂等进度回写闭环 #
结合 创建 Notion API 集成指南、Notion API 速率限制与容错实战 与 Notion Webhook 与自动化集成实战,可按以下五步构建高可靠的人机协同状态机:
- 定义不可变业务键
Workflow_ID与信号契约:所有业务实例在发起 Temporalclient.workflow.start()时,必须使用确定性业务主键(如wf-release-20261119-008)作为workflowId,并设置WorkflowIdReusePolicy防止重复启动。 - Temporal Activity 创建 Notion 人工审批单并挂起等待:当工作流推进到人工关卡时,调用 Activity 向
DB_Human_Approval_Tasks写入待审批记录,随后在 Workflow 中调用condition(() => approvalDecision !== null, '48 hours')进入零资源占用的持久化等待。 - 打通 Notion 审批操作至 Temporal Signal 网关:利用 Notion Automations 自动化触发器详解 或数据库按钮(当
审批决策变更为批准放行/驳回终止时发送 Webhook 至企业内部网关),由网关校验签名后向对应workflowId投递 Signal,并回写信号已投递 = true防止重复提交。 - 部署带
429退避与幂等键校验的 Node.js 双向协同处理器(人工确认编排逻辑亦可与 Notion 与 Pipedream / Relay.app 自动化引擎深度集成实战 或 Notion 与企业微信深度集成与双向协同实战 互补使用):
import { setTimeout as sleep } from 'node:timers/promises';
const NOTION_TOKEN = process.env.NOTION_TOKEN;
const WORKFLOWS_DB_ID = process.env.NOTION_TEMPORAL_WORKFLOWS_DB_ID;
const TASKS_DB_ID = process.env.NOTION_TEMPORAL_TASKS_DB_ID;
async function notionRequest(path, method, payload) {
for (let i = 0; i < 5; i++) {
const res = await fetch(`https://api.notion.com/v1${path}`, {
method,
headers: {
Authorization: `Bearer ${NOTION_TOKEN}`,
'Notion-Version': '2022-06-28',
'Content-Type': 'application/json',
},
body: payload ? JSON.stringify(payload) : undefined,
});
if (res.status === 429) {
const waitSec = Number(res.headers.get('retry-after') || '2');
await sleep(waitSec * 1000);
continue;
}
if (!res.ok) {
throw new Error(`Notion API ${res.status}: ${await res.text()}`);
}
return res.json();
}
throw new Error('Notion API 重试次数耗尽');
}
// 1. Temporal Activity:在 Notion 挂起创建人工审批单(幂等防重)
export async function upsertApprovalTaskInNotion(params) {
const wfRow = await notionRequest(`/databases/${WORKFLOWS_DB_ID}/query`, 'POST', {
filter: { property: 'Workflow_ID', title: { equals: params.workflowId } },
page_size: 1,
});
let workflowPageId = wfRow.results?.[0]?.id;
if (!workflowPageId) {
const createdWf = await notionRequest('/pages', 'POST', {
parent: { database_id: WORKFLOWS_DB_ID },
properties: {
Workflow_ID: { title: [{ text: { content: params.workflowId } }] },
业务类型: { select: { name: params.bizType } },
Temporal_Run_ID: { rich_text: [{ text: { content: params.runId } }] },
当前编排阶段: { status: { name: '等待人工审批' } },
流程启动时间: { date: { start: params.startedAtIso } },
},
});
workflowPageId = createdWf.id;
await sleep(350);
} else {
await notionRequest(`/pages/${workflowPageId}`, 'PATCH', {
properties: {
Temporal_Run_ID: { rich_text: [{ text: { content: params.runId } }] },
当前编排阶段: { status: { name: '等待人工审批' } },
},
});
await sleep(350);
}
const existingTask = await notionRequest(`/databases/${TASKS_DB_ID}/query`, 'POST', {
filter: { property: 'Task_UID', title: { equals: params.taskUid } },
page_size: 1,
});
if (existingTask.results?.length === 0) {
await notionRequest('/pages', 'POST', {
parent: { database_id: TASKS_DB_ID },
properties: {
Task_UID: { title: [{ text: { content: params.taskUid } }] },
关联工作流: { relation: [{ id: workflowPageId }] },
审批阶段名: { rich_text: [{ text: { content: params.stageName } }] },
审批决策: { select: { name: '待审批' } },
审批截止时间: { date: { start: params.deadlineIso } },
信号已投递: { checkbox: false },
},
});
}
}
// 2. Notion Webhook 网关:将审批决策安全转发给 Temporal Signal 并锁定标记
export async function forwardNotionDecisionToTemporal(temporalClient, payload) {
const decision = payload.decision;
if (decision !== '批准放行' && decision !== '驳回终止') return;
const taskPage = await notionRequest(`/pages/${payload.taskPageId}`, 'GET');
if (taskPage.properties?.['信号已投递']?.checkbox === true) {
return; // 幂等拦截重复投递
}
const handle = temporalClient.workflow.getHandle(payload.workflowId);
await handle.signal('humanApprovalSignal', {
taskUid: payload.taskUid,
approved: decision === '批准放行',
reviewer: payload.reviewerEmail,
comment: String(payload.comment || '').slice(0, 500),
});
await sleep(350);
await notionRequest(`/pages/${payload.taskPageId}`, 'PATCH', {
properties: {
信号已投递: { checkbox: true },
},
});
}
- 打通 Saga 补偿与超时自动转审闭环:当 Temporal 的
condition等待超时未收到人工 Signal 时,自动调用升级 Activity 将 Notion 中的审批决策改写为超时自动转审并 @ 替补负责人;若最终触发驳回或下游执行异常,则逆序执行已注册的 Saga 补偿动作,并将每一步补偿结果同步写入DB_Workflow_Compensation_Logs。
四、Formula 2.0 工作流超时预警与人工审批 SLA 阻断门禁公式 #
在 DB_Workflow_Instances 中新增 Formula 2.0 属性 流程健康门禁(语法细节可参考 Notion 公式核心指南 与 Formula 2.0 实战速查表),自动扫描关联审批节点是否临近或突破 审批截止时间、是否存在信号投递失败或 Saga 补偿异常:
lets(
stage, prop("当前编排阶段"),
tasks, prop("关联审批节点"),
pendingTasks, tasks.filter(current.prop("审批决策") == "待审批"),
overduePending, pendingTasks.filter(
!empty(current.prop("审批截止时间")) && current.prop("审批截止时间") < now()
).length(),
decidedButUnsent, tasks.filter(
(current.prop("审批决策") == "批准放行" || current.prop("审批决策") == "驳回终止")
&& !current.prop("信号已投递")
).length(),
failedComps, prop("关联补偿流水").filter(
current.prop("补偿结果") == "补偿失败需人工介入"
).length(),
ifs(
failedComps > 0,
style("🛑 Saga 补偿失败 (" + failedComps + " 项) · 需工程师立即介入", "red", "bold"),
stage == "执行失败",
style("🚨 工作流执行异常中止 · 请核查 Temporal 堆栈", "red", "bold"),
decidedButUnsent > 0,
style("⚠️ 有 " + decidedButUnsent + " 条审批已决策但 Signal 未投递", "orange", "bold"),
overduePending > 0,
style("⏳ 人工审批已超 SLA (" + overduePending + " 项) · 触发自动升级", "orange", "bold"),
stage == "已触发Saga回滚",
style("↩️ 已驳回并完成 Saga 逆序补偿归档", "gray"),
stage == "已完成",
style("🟢 编排闭环交付", "green"),
pendingTasks.length() > 0,
style("🔵 挂起等待人工审批 (" + pendingTasks.length() + " 项进行中)", "blue"),
style("⚡ Temporal 协程运行中", "blue")
)
)
五、Temporal 与 Notion 长周期审批协同常见故障排查清单 #
| 常见故障现象 | 根本原因 | 标准化工程修复方案 |
|---|---|---|
| Temporal Activity 因网络波动重试时,在 Notion 生成了 3 条一模一样的审批工单 | Activity 未执行“先按 Task_UID 查重再建行”的幂等校验,且 Temporal 默认至少一次(At-least-once)投递 | 在 Activity 中强制以 APR-{workflowId}-{stage} 查询防重,存在则直接跳过或仅做字段 PATCH |
| 审批人在 Notion 点击“批准放行”后连改两次下拉框,导致工作流收到重复 Signal | 未在网关和 Notion 侧建立投递锁,重复 Webhook 唤醒了后续不相干阶段 | 引入 信号已投递 复选框门禁,同时在 Temporal Signal Payload 中携带 taskUid 由工作流内校验匹配才放行 |
| 工作流已完成并关闭,审批人几天后才在 Notion 修改旧工单触发 Webhook 报 404/WorkflowNotFound | Temporal 已结束的工作流默认不再接收普通 Signal,网关未捕获 WorkflowNotFoundError 导致死循环重试 | 网关捕获 Temporal WorkflowNotFoundError 时直接返回 200 OK 并向 Notion 批注“流程已过期终止”,禁止无限重投 |
大促或批量发布窗口同时拉起上百条审批,回写 Notion 密集出现 429 | Temporal Worker 并发度过高且未限制写 Notion Activity 的速率上限 | 为写 Notion 的专属 Task Queue 配置 Temporal MaxTaskQueueActivitiesPerSecond = 2,并在脚本层保留 Retry-After 退避 |
- 工作流编排与故障排查延伸阅读:如需配合第三方线上告警与值班调度协同,请参阅 Notion 与 Sentry / PagerDuty 线上故障应急响应及复盘闭环实战;遇到 Notion API 速率限制、Webhook 校验失败或数据库性能卡顿时,请查阅 Notion 常见报错与故障诊断手册。
核心手册与速查工具矩阵
高频速查手册与生产力工具直达常见问题与答疑 (FAQ)
高频疑难解析与避坑指南完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。