Files
AgentLab/backend/app/db/models_triggers.py
T
ThearchyHelios a1ab3247f9 数据事件触发(后端):待派发事件表、调度循环派发与去抖、防环、{{ event.* }} 模板变量、接口收 trigger_kind / trigger
做了什么:
- 新表 trigger_events(待派发事件)、trigger_deliveries(一个事件派给一个定时任务、等去抖),放在 db/models_triggers.py,
  models.py 末尾整模块导入。事件在发生处、和那件事同一个事务里写一行:上传表格按期累积的新一期启用(table_versions 的
  publish_build / publish_snapshot 切指针那一下,移除、作废、回滚不算)、正式运行成功收尾(runner._finalize 写终态的事务里
  加两行调用 outbox.stage_run_finished)、探查 / 剖析新记了要处理的变化(source_changes.notify_after_job,一个任务一条)。
  发生处不发起运行:事务边界、重复与重启都在派发这边说清,也为第 2 波多进程做准备(认领靠条件 UPDATE)。
- scheduler/outbox.py:调度循环每一拍(fire_due 之后)派发:pending 事件条件 UPDATE 认领成 routed,同一事务里给合条件、启用着的
  事件触发任务写 delivery;窗口从最早一条的发生时刻起算 debounce_s(缺省 60 秒),过了就合成一次触发,内容取最新的那条,
  fire_at 取窗口结束的时刻(同一窗口永远同一个时刻,触发记录唯一约束兜住重复派发);照 fire_once 发起正式运行,ScheduleFire
  kind=event、inputs 写 {event: 事件说明, inputs: 渲染出的输入};上一次没结束记 skipped_overlap;派发太晚(超出补发宽限)
  记 skipped_misfire;任务停用、改了触发条件时等着的标 dropped。AGENTLAB_SCHEDULER 关着时没有这一拍,事件留着,接口照实说。
- scheduler/triggers.py:三种事件的触发条件(table.version 可选只认新增的一期;workflow.finished 可选只认某个应用 / 某种来源;
  source.changed)、核对对象(表格是按期累积的上传表格、上游工作流已发布、应用在)、说法、{{ event.* }} 变量(table、version、
  period、activated_at;workflow_id、run_id、outputs.<字段>;source、counts)、示例事件(预览、立即运行用对象最近一次真实的事件)、
  防环:保存时查 workflow.finished 串成的环(停用的也算,A→B→A、自己触发自己都拒,422 写出经过的工作流),运行时按 origin 里的
  触发深度兜底(超过 5 层记未能发起)。
- service:fire_once / _fire_workflow 接事件(模板按事件种类校验、渲染 {{ event.* }},运行来源 origin.trigger 带种类、对象、
  事件 id、深度、经过的运行和一句说法);check_template / render_inputs / variables 加可选的 event 参数,cron 任务一字不变。
- api/schedules.py:收 trigger_kind(cron 缺省)/ trigger,event 时目标只能是工作流、cron 存空串、下一次触发为空;返回带
  trigger_kind、trigger、trigger_text(也是 description_text)、trigger_state(几条事件在等、去抖到何时、调度开没开);触发
  历史带 event;预览按示例事件渲染;变量清单按事件种类给;新增 GET /api/schedules/trigger-options(各事件能选的对象及不能选的
  原因、来源、应用,界面不自己判);立即运行按示例事件发起;触发方式建好之后不能改。Webhook 照旧可配,通知写「事件触发」那一行。
- 应用页印章的来源(apps/resolve._from_text)照实写「由事件触发:…」。

为什么:总方案 §4 已拍板接这三种事件、不接口径发布,一套定时机制(X4);派发放在调度循环里而不是发生处,事务和重复都说得清。

测试:test_schedule_events.py(三种事件各触发一次、去抖合并与窗口外另起、重叠跳过、停用 / 改条件丢弃、调度关着时事件留着、
超出宽限、触发链深度与上限、模板校验与渲染、期次写法、通知、印章)、test_schedule_events_api.py(建、核对、防环、改、预览、
变量、立即运行、触发状态、可选对象);test_schedules_api.py 的约定键集合补上新加的几项。
2026-10-18 15:53:08 +08:00

85 lines
5.6 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""数据事件触发的待派发事件和去抖等待(docs/design/orchestration-round/00-总方案.md §4)。
由 app/db/models.py 末尾整模块导入,create_all 建表(都是新表,只加不改)。这里不导入 app.db.models:models.py 导入本模块时
自己还没加载完,外键一律按表名写。
**为什么要一张「待派发事件」表,而不是在发生处直接发起运行。** 事件发生在别的事务里:启用上传表格的新版本、正式运行的
收尾、记下数据源的变化。在那里直接发起运行,发起失败要不要回滚那次启用?重复发生、服务重启时发起到一半又算什么?说不清。
改成在发生处、和那件事**同一个事务**里写一行 TriggerEvent(发生了就一定有这一行,没发生就一定没有),调度循环一拍取走、
按各定时任务的触发条件派发:发起运行的规矩(重叠跳过、正式运行只从发布版本发起、触发记录唯一)全部沿用定时任务那一套。
调度关着(AGENTLAB_SCHEDULER)时没人取,事件留在表里,接口照实说有几条在等。第 2 波多进程时,取走靠的是条件 UPDATE,
多个进程也只有一个取得到。
- TriggerEvent 一次事件:种类(table.version / workflow.finished / source.changed)、对象 id、给模板用的事件内容、触发链
的深度和经过的运行、发生时刻。status:pending 还没派发;routed 已经按触发条件派给了 matched 个定时任务(0 个也算派完)。
- TriggerDelivery 一个事件派给一个定时任务、等着去抖:同一个定时任务窗口内(第一条事件发生之后 debounce_s 秒)的几条
合成一次触发,fire_id 是那次触发记录;status:pending 等着、fired 合进了某次触发(发起、跳过、未能发起都算)、dropped
定时任务在等待期间被停用或改了触发条件,不再派发。(定时任务, 事件) 唯一:同一个事件不会派给同一个任务两次。
"""
from __future__ import annotations
from datetime import datetime
from typing import Any
from sqlalchemy import ForeignKey, Index, Integer, String, UniqueConstraint
from sqlalchemy.orm import Mapped, mapped_column
from app.db.base import Base, UTCDateTime, new_id, utcnow
#: 事件种类:上传表格启用了新的一期、工作流的正式运行成功结束、数据源出现要处理的变化
EVENT_KINDS = ("table.version", "workflow.finished", "source.changed")
#: 事件的状态:还没派发、已经派发(派给了 matched 个定时任务)
EVENT_STATUSES = ("pending", "routed")
#: 派给一个定时任务之后的状态:等着去抖、合进了一次触发、不再派发
DELIVERY_STATUSES = ("pending", "fired", "dropped")
class TriggerEvent(Base):
"""一次待派发的事件。payload 只放给输入模板用的值({{ event.* }},见 scheduler/triggers.py),workflow.finished 的
出口字段不复制进来:派发时按 run_id 读那次运行的成果(运行记录已经落库、不会再变)。"""
__tablename__ = "trigger_events"
__table_args__ = (
Index("ix_trigger_events_status", "status", "created_at"),
Index("ix_trigger_events_subject", "event", "subject_id"),
)
id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
event: Mapped[str] = mapped_column(String(30))
#: 对象 id:表格数据源 id(table.version)、工作流 id(workflow.finished)、数据源 id(source.changed)
subject_id: Mapped[str] = mapped_column(String(32), default="")
#: 对象当时的名字(给人看的说法里用;对象之后改名、删除都不影响这一条)
subject_name: Mapped[str] = mapped_column(String(200), default="")
payload: Mapped[dict[str, Any]] = mapped_column(default=dict)
#: 触发链的深度:workflow.finished 时是上游那次运行自己由事件触发了几层(不是事件触发的为 0),别的种类为 0。
#: 派发时新运行的深度是它加 1,超过上限(scheduler/triggers.MAX_DEPTH)不发起
depth: Mapped[int] = mapped_column(Integer, default=0)
#: 经过的运行 id(从最上游起),给记录、排查循环用;只截最近的几条
chain: Mapped[list[Any]] = mapped_column(default=list)
occurred_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow)
status: Mapped[str] = mapped_column(String(20), default="pending")
routed_at: Mapped[datetime | None] = mapped_column(UTCDateTime, default=None)
#: 派给了几个定时任务
matched: Mapped[int] = mapped_column(Integer, default=0)
created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow)
class TriggerDelivery(Base):
"""一个事件派给了一个定时任务,等着去抖、合成一次触发。"""
__tablename__ = "trigger_deliveries"
__table_args__ = (
UniqueConstraint("schedule_id", "event_id"),
Index("ix_trigger_deliveries_waiting", "schedule_id", "status", "occurred_at"),
)
id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id)
schedule_id: Mapped[str] = mapped_column(ForeignKey("schedules.id", ondelete="CASCADE"))
event_id: Mapped[str] = mapped_column(ForeignKey("trigger_events.id", ondelete="CASCADE"))
#: 同事件的发生时刻(去抖窗口按它算)
occurred_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow)
status: Mapped[str] = mapped_column(String(20), default="pending")
#: 合进的那次触发(schedule_fires.id)
fire_id: Mapped[str | None] = mapped_column(String(32), default=None)
created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=utcnow)