Notion 与 Temporal 分布式长周期工作流引擎及人工审批(Human-in-the-Loop)状态机协同实战:从超时重试、Signal 审批回传到 Formula 2.0 SLA 门禁闭环

2026 年 11 月 19 日

一、为什么跨天/跨周的企业级长周期审批不能只靠普通 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 与自动化集成实战,可按以下五步构建高可靠的人机协同状态机:

  1. 定义不可变业务键 Workflow_ID 与信号契约:所有业务实例在发起 Temporal client.workflow.start() 时,必须使用确定性业务主键(如 wf-release-20261119-008)作为 workflowId,并设置 WorkflowIdReusePolicy 防止重复启动。
  2. Temporal Activity 创建 Notion 人工审批单并挂起等待:当工作流推进到人工关卡时,调用 Activity 向 DB_Human_Approval_Tasks 写入待审批记录,随后在 Workflow 中调用 condition(() => approvalDecision !== null, '48 hours') 进入零资源占用的持久化等待。
  3. 打通 Notion 审批操作至 Temporal Signal 网关:利用 Notion Automations 自动化触发器详解 或数据库按钮(当 审批决策 变更为 批准放行 / 驳回终止 时发送 Webhook 至企业内部网关),由网关校验签名后向对应 workflowId 投递 Signal,并回写 信号已投递 = true 防止重复提交。
  4. 部署带 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 },
    },
  });
}
  1. 打通 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 退避

❓ 常见问题与答疑 (FAQ)

高频疑难解析与避坑指南
A

完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。