Files
AgentLab/backend/app/scheduler/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

543 lines
29 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):触发条件的写法与校验、给人看的说法、输入模板里的
{{ event.* }}、示例事件、防环。
**一套定时机制(X4)。** 事件触发不是另一套调度:它就是一个 trigger_kind=event 的定时任务,目标只能是工作流。认领、重叠跳过、
触发记录、通知、正式运行只从发布版本发起,全部沿用定时任务那一套(scheduler/service.fire_once);不同的只是「什么时候触发」
——不是到点,而是三种数据事件之一(已拍板:不接「口径发布」):
- table.version:一张按期累积的上传表格启用了新的一期(data/table_versions 启用那一下)。可选只认新增的一期(period=new):
重传、替换已有那一期(改错数)的不算;
- workflow.finished:一个工作流的正式运行成功结束。可选只认某个应用(app_id)发起的、某种来源(origin_kind)的;
下游的输入模板能引用这次运行的出口字段({{ event.outputs.<字段> }});
- source.changed:一个数据源出现「要处理」级的变化。按源去抖:同一次探查、剖析产生的一批只记一条事件(data/source_changes)。
trigger 的形状:{event, 对象(source_id / workflow_id / source_id), 过滤(见上), debounce_s(缺省 60)}。同一个定时任务
在 debounce_s 内的几次事件合成一次触发(scheduler/outbox)。
**防环。** workflow.finished 能把工作流串起来:A 跑完触发 B、B 跑完又触发 A 就停不下来。保存时查串联成不成环(find_cycle,
停用的任务也算:启用不该绕过这道检查);运行时按 origin 里记的触发链深度兜底,超过 MAX_DEPTH 层不发起、照实记一次未能发起
(手改过库、经别处间接串成环时还有这一道)。
这里不碰调度循环、不发起运行:派发在 scheduler/outbox.py,发起在 scheduler/service.py。
"""
from __future__ import annotations
from dataclasses import dataclass, field
from datetime import date, datetime, timedelta, timezone
from typing import Any
from sqlalchemy import select
#: 事件种类,顺序即界面上的顺序(和 db/models_triggers.EVENT_KINDS 是同一份)
EVENTS = ("table.version", "workflow.finished", "source.changed")
#: 事件种类的叫法(界面另有一份在 lib/termsTrigger.ts,逐字对照)
EVENT_LABEL = {
"table.version": "上传表格出了新的一期",
"workflow.finished": "上游工作流运行成功结束",
"source.changed": "数据源有要处理的变化",
}
#: 每种事件的对象写在 trigger 的哪个键上、叫什么
SUBJECT_KEY = {"table.version": "source_id", "workflow.finished": "workflow_id", "source.changed": "source_id"}
SUBJECT_LABEL = {"table.version": "上传表格", "workflow.finished": "工作流", "source.changed": "数据源"}
DEFAULT_DEBOUNCE_S = 60
MAX_DEBOUNCE_S = 24 * 3600
#: 触发链最多几层:A 触发 B 是第 1 层,B 再触发 C 是第 2 层……超过就不发起
MAX_DEPTH = 5
#: 「期次规则」:any 新增的一期和替换已有的一期都认(缺省);new 只认新增的一期
PERIOD_RULES = ("any", "new")
PERIOD_RULE_LABEL = {"any": "新增的一期和替换已有的一期都认", "new": "只认新增的一期"}
#: 能发起正式运行的来源:workflow.finished 的「只认某种来源」从这几种里选(问数据、画布试跑、评测发起的都是探索运行,
#: 不会有 workflow.finished)
FORMAL_ORIGINS = ("launcher", "schedule", "app_entry", "app_view", "app_backfill", "hook", "api", "ledger_issue")
#: 来源的叫法(同前端 lib/terms.ts 的 ORIGIN_LABEL)
ORIGIN_LABEL = {
"launcher": "手动正式运行", "schedule": "定时任务", "app_entry": "应用入口", "app_view": "应用视图",
"app_backfill": "应用补算", "hook": "入站钩子", "api": "接口调用", "ledger_issue": "按口径正式出具",
}
#: trigger 里认得的键(多出来的拒收:拼错的过滤条件悄悄不生效,比报错更糟)。subject_name 是保存时记下的对象名(接口不给、
#: 带回来也不认,对象删掉之后说法里用它)
_KEYS = {"event", "source_id", "workflow_id", "period", "app_id", "origin_kind", "debounce_s", "subject_name"}
#: 示例事件里给不出真实值时写的占位说明
EXAMPLE_NOTE = "示例值"
class TriggerError(ValueError):
"""触发条件写错了、对象不在或不合用。str() 是给人看的中文说明,field 是表单上的那一项(缺省 trigger)。"""
def __init__(self, message: str, field: str = "trigger") -> None:
super().__init__(message)
self.field = field
# --------------------------------------------------------------------------
# 写法
# --------------------------------------------------------------------------
def _text(value: Any) -> str | None:
return value.strip() if isinstance(value, str) and value.strip() else None
def normalize(value: Any) -> dict[str, Any]:
"""校验 trigger 的形状并规范化(不碰库):{event, 对象键, debounce_s, 过滤…},没写的过滤不出现。不对抛 TriggerError。"""
if not isinstance(value, dict):
raise TriggerError("事件触发需要写明事件种类和对象,例如 {event: table.version, source_id: …}")
event = value.get("event")
if event not in EVENTS:
labels = "、".join(EVENT_LABEL[e] for e in EVENTS)
raise TriggerError(f"事件种类需要是{labels}之一")
unknown = sorted(k for k in value if k not in _KEYS)
if unknown:
raise TriggerError(f"事件触发的设置里有不认识的项:{'、'.join(unknown)}")
key = SUBJECT_KEY[event]
subject = _text(value.get(key))
if subject is None:
raise TriggerError(f"请选择{SUBJECT_LABEL[event]}")
for other in {"source_id", "workflow_id"} - {key}:
if _text(value.get(other)):
raise TriggerError(f"「{EVENT_LABEL[event]}」只选{SUBJECT_LABEL[event]},不写别的对象")
out: dict[str, Any] = {"event": event, key: subject}
period = value.get("period")
if period not in (None, ""):
if event != "table.version":
raise TriggerError("只有「上传表格出了新的一期」能按期次过滤")
if period not in PERIOD_RULES:
raise TriggerError("期次规则需要是「新增的一期和替换已有的一期都认」或「只认新增的一期」")
if period != "any":
out["period"] = period
for name in ("app_id", "origin_kind"):
raw = value.get(name)
if raw in (None, ""):
continue
if event != "workflow.finished":
raise TriggerError("只有「上游工作流运行成功结束」能按应用、来源过滤")
text = _text(raw)
if text is None:
raise TriggerError("只认的应用、来源需要从列表里选")
if name == "origin_kind" and text not in FORMAL_ORIGINS:
labels = "、".join(ORIGIN_LABEL[o] for o in FORMAL_ORIGINS)
raise TriggerError(f"只认的来源需要是{labels}之一")
out[name] = text
debounce = value.get("debounce_s", DEFAULT_DEBOUNCE_S)
if isinstance(debounce, bool) or not isinstance(debounce, int) or not 0 <= debounce <= MAX_DEBOUNCE_S:
raise TriggerError(f"去抖需要是 0 到 {MAX_DEBOUNCE_S} 之间的整数秒数(最长 1 天)", "debounce_s")
out["debounce_s"] = debounce
return out
def subject_of(trigger: dict[str, Any] | None) -> str:
"""触发条件里的对象 id;不成形的为空串。"""
trigger = trigger if isinstance(trigger, dict) else {}
key = SUBJECT_KEY.get(trigger.get("event") or "")
return str(trigger.get(key) or "") if key else ""
def debounce_of(trigger: dict[str, Any] | None) -> int:
value = (trigger or {}).get("debounce_s", DEFAULT_DEBOUNCE_S) if isinstance(trigger, dict) else DEFAULT_DEBOUNCE_S
return value if isinstance(value, int) and not isinstance(value, bool) and value >= 0 else DEFAULT_DEBOUNCE_S
def matches(trigger: dict[str, Any] | None, event: str, subject_id: str, payload: dict[str, Any] | None) -> bool:
"""这条事件合不合这个触发条件:种类、对象对得上,过滤条件都满足。"""
if not isinstance(trigger, dict) or trigger.get("event") != event or subject_of(trigger) != subject_id:
return False
payload = payload or {}
if event == "table.version" and trigger.get("period") == "new" and payload.get("replaced"):
return False
if event == "workflow.finished":
if trigger.get("app_id") and payload.get("app_id") != trigger["app_id"]:
return False
if trigger.get("origin_kind") and payload.get("origin_kind") != trigger["origin_kind"]:
return False
return True
# --------------------------------------------------------------------------
# 核对对象(建任务、改触发条件时)
# --------------------------------------------------------------------------
@dataclass
class Checked:
"""核对通过的触发条件:对象现在的名字,过滤里的应用名(有的话)。"""
subject_name: str
app_name: str | None = None
async def accumulating(session: Any, source: Any) -> bool:
"""这个上传表格是不是按期累积的:当前版本是累积快照,或者现行配方写的是按期累积(还没导入过第二期的也算)。"""
from app.db.models import SourceSnapshot, TableRecipe
if source.current_snapshot_id:
snap = await session.get(SourceSnapshot, source.current_snapshot_id)
if snap is not None and (snap.mode or "replace") == "accumulate":
return True
if source.current_recipe_id:
recipe = await session.get(TableRecipe, source.current_recipe_id)
if recipe is not None and isinstance(recipe.recipe, dict) and recipe.recipe.get("mode") == "accumulate":
return True
return False
async def check(session: Any, trigger: dict[str, Any]) -> Checked:
"""核对触发条件里的对象(trigger 已经 normalize 过):表格在、是按期累积的上传表格;工作流在、已发布(只有正式运行成功
结束才算事件);数据源在;过滤里的应用在。不对抛 TriggerError。"""
from app.db.models import App, DataSource, Workflow
event, subject = trigger["event"], subject_of(trigger)
if event in ("table.version", "source.changed"):
source = await session.get(DataSource, subject)
if source is None:
raise TriggerError(f"{SUBJECT_LABEL[event]}不存在,可能已被删除")
if event == "table.version":
if (source.origin or "manual") != "upload":
raise TriggerError(f"「{source.name}」不是上传表格:只有上传表格有「出了新的一期」")
if not await accumulating(session, source):
raise TriggerError(f"「{source.name}」不是按期累积的上传表格:每次上传替换整张表的没有「新的一期」。"
"请在导入设置里改为按期累积,或改用「数据源有要处理的变化」")
return Checked(source.name)
workflow = await session.get(Workflow, subject)
if workflow is None:
raise TriggerError("上游工作流不存在,可能已被删除")
if not workflow.published_version:
raise TriggerError(f"上游工作流「{workflow.name}」还没有发布版本:只有正式运行成功结束才算事件,"
"正式运行只能从发布版本发起。请先在编排页发布")
app_name = None
if trigger.get("app_id"):
app = await session.get(App, trigger["app_id"])
if app is None:
raise TriggerError("只认的应用不存在,可能已被删除")
app_name = app.name
return Checked(workflow.name, app_name)
async def find_cycle(session: Any, *, schedule_id: str | None, trigger: dict[str, Any],
target_workflow_id: str) -> list[str] | None:
"""workflow.finished 串成的环:这个任务(A 跑完触发 B)加进去之后,从 B 沿着别的事件触发任务能不能回到 A。成环时返回经过的
工作流 id(A, B, …, A),否则 None。停用的任务也算进去:启用不该绕过这道检查;schedule_id 是正在改的那个任务(它原来的
那条边不算)。"""
if trigger.get("event") != "workflow.finished" or not target_workflow_id:
return None
from app.db.models import Schedule
start, target = subject_of(trigger), target_workflow_id
if start == target:
return [start, start]
edges: dict[str, set[str]] = {}
rows = (await session.execute(select(Schedule.id, Schedule.trigger, Schedule.workflow_id, Schedule.target_kind)
.where(Schedule.trigger_kind == "event"))).all()
for sid, other, workflow_id, kind in rows:
if sid == schedule_id or (kind or "workflow") != "workflow" or not isinstance(other, dict):
continue
if other.get("event") == "workflow.finished" and subject_of(other) and workflow_id:
edges.setdefault(subject_of(other), set()).add(workflow_id)
# 从 B 出发找回 A 的路(广度优先,取最短的一条说给人听)
parent: dict[str, str | None] = {target: None}
queue = [target]
while queue:
node = queue.pop(0)
for nxt in sorted(edges.get(node, ())):
if nxt in parent:
continue
parent[nxt] = node
if nxt == start:
back = [start] # A ← … ← B,倒着记
while back[-1] != target:
back.append(parent[back[-1]] or target)
return [start, *reversed(back)]
queue.append(nxt)
return None
def cycle_text(names: list[str]) -> str:
"""成环时的说明(422):「A」→「B」→「A」,箭头说的是「正式运行成功结束后触发」。"""
chain = "→".join(f"「{n}」" for n in names)
return (f"这样设置会循环触发:{chain}(每个箭头表示前一个工作流的正式运行成功结束后触发后一个),"
"运行会一直接力下去。请去掉其中一环")
# --------------------------------------------------------------------------
# 给人看的说法
# --------------------------------------------------------------------------
def describe(trigger: dict[str, Any], subject_name: str | None, *, app_name: str | None = None) -> str:
"""一个事件触发任务的说法(列表、详情页头、预览,同 cron 任务的 description_text):
「上传表格「门店销售」出了新的一期时触发(只认新增的一期;去抖 60 秒)」。对象不在了写保存时记的名字。"""
event = trigger.get("event")
name = f"「{subject_name}」" if subject_name else ""
if event == "table.version":
head = f"上传表格{name}出了新的一期时触发"
elif event == "workflow.finished":
head = f"工作流{name}的正式运行成功结束时触发"
elif event == "source.changed":
head = f"数据源{name}出现要处理的变化时触发"
else:
return "由事件触发(触发条件无法识别)"
notes: list[str] = []
if trigger.get("period") == "new":
notes.append(PERIOD_RULE_LABEL["new"])
if trigger.get("app_id"):
notes.append(f"只认应用「{app_name}」发起的" if app_name else "只认指定的应用发起的")
if trigger.get("origin_kind"):
notes.append(f"只认来源为「{ORIGIN_LABEL.get(trigger['origin_kind'], trigger['origin_kind'])}」的")
debounce = debounce_of(trigger)
from app.scheduler.service import duration_text
notes.append(f"去抖 {duration_text(debounce)}" if debounce else "不去抖")
return f"{head}({';'.join(notes)})"
def event_text(event: str, subject_name: str, payload: dict[str, Any] | None) -> str:
"""一次事件的说法(触发历史、运行来源、通知):「上传表格「门店销售」出了新的一期(2026-09)」。不写出口字段的值、变化的
内容(可能带着数,通知会推进群里)。"""
payload = payload or {}
name = f"「{subject_name}」" if subject_name else ""
if event == "table.version":
period = payload.get("period") or ""
what = "替换了已有的一期" if payload.get("replaced") else "出了新的一期"
return f"上传表格{name}{what}{f'({period})' if period else ''}"
if event == "workflow.finished":
run = str(payload.get("run_id") or "")
return f"工作流{name}的正式运行成功结束{f'(#{run[:6]})' if run else ''}"
if event == "source.changed":
n = (payload.get("counts") or {}).get("new")
return f"数据源{name}出现要处理的变化{f'(新记 {n} 条)' if isinstance(n, int) and n else ''}"
return "数据事件"
# --------------------------------------------------------------------------
# 输入模板里的 {{ event.* }}
# --------------------------------------------------------------------------
#: 每种事件能用的变量:(变量名, 说明, 示例)。outputs.<字段>、counts.<项> 之下的名字是开放的,见 allowed_path
VARIABLES: dict[str, tuple[tuple[str, str, str], ...]] = {
"table.version": (
("table", "上传表格的名字", "门店销售"),
("version", "启用的版本编号", "3f2a9c…"),
("period", "这一期(整月写 YYYY-MM,整周写 YYYY-Www,单日写 YYYY-MM-DD)", "2026-09"),
("period_start", "这一期的第一天(YYYY-MM-DD)", "2026-09-01"),
("period_end", "这一期的最后一天(YYYY-MM-DD)", "2026-09-30"),
("activated_at", "启用的时间(带时区偏移的 ISO 时间)", "2026-10-08T09:30:00+08:00"),
),
"workflow.finished": (
("workflow", "上游工作流的名字", "门店日报"),
("workflow_id", "上游工作流的编号", "wf…"),
("run_id", "上游那次运行的编号", "run…"),
("finished_at", "上游运行结束的时间(带时区偏移的 ISO 时间)", "2026-10-08T09:30:00+08:00"),
("outputs", "上游运行的出口字段(写 event.outputs.<字段名>)", "{…}"),
),
"source.changed": (
("source", "数据源的名字", "门店库"),
("source_id", "数据源的编号", "ds…"),
("counts", "变化的条数(写 event.counts.new 这次新记的要处理的条数,"
"event.counts.action / warning / info 各级还要人看的条数)", "{…}"),
),
}
#: 开放的那一级:event.outputs.<字段>、event.counts.<项>
_OPEN = {"workflow.finished": "outputs", "source.changed": "counts"}
_COUNT_KEYS = ("new", "action", "warning", "info", "pending")
def names(event: str) -> tuple[str, ...]:
"""这种事件能写在模板里的变量(带 event. 前缀),给报错列出来。"""
out = [f"event.{key}" for key, _, _ in VARIABLES.get(event, ())]
if event == "workflow.finished":
out = [n if n != "event.outputs" else "event.outputs.<字段名>" for n in out]
if event == "source.changed":
out = [n for n in out if n != "event.counts"] + [f"event.counts.{k}" for k in _COUNT_KEYS]
return tuple(out)
def allowed_path(path: str, event: str) -> bool:
"""event.* 的路径合不合这种事件:固定的几个名字,加上 outputs.<字段>(可以再往下取)、counts.<项>。"""
if not path.startswith("event."):
return False
rest = path[len("event."):]
keys = {key for key, _, _ in VARIABLES.get(event, ())}
head, _, tail = rest.partition(".")
if head not in keys:
return False
if head == _OPEN.get(event):
if event == "source.changed":
return not tail or tail in _COUNT_KEYS
return bool(tail.strip())
return not tail
def _zoned(text: Any, tz: str) -> str:
"""存的 UTC ISO 时间换成任务时区、只到秒的 ISO(同 schedule.fire_time 的写法);读不出来的照原样。"""
if not isinstance(text, str) or not text:
return ""
try:
moment = datetime.fromisoformat(text)
except ValueError:
return text
if moment.tzinfo is None:
moment = moment.replace(tzinfo=timezone.utc)
from app.scheduler import cron
try:
return moment.astimezone(cron.zone(tz)).isoformat(timespec="seconds")
except ValueError:
return moment.isoformat(timespec="seconds")
def values(event: str, payload: dict[str, Any] | None, tz: str, *, outputs: dict[str, Any] | None = None,
) -> dict[str, Any]:
"""模板里 event 下面的值(render_inputs 的 ctx["event"])。时间按任务时区写;workflow.finished 的出口字段由派发时读到的
那次运行的成果交进来。"""
payload = payload or {}
if event == "table.version":
return {"table": payload.get("table") or "", "version": payload.get("version") or "",
"period": payload.get("period") or "", "period_start": payload.get("period_start") or "",
"period_end": payload.get("period_end") or "", "activated_at": _zoned(payload.get("activated_at"), tz)}
if event == "workflow.finished":
return {"workflow": payload.get("workflow") or "", "workflow_id": payload.get("workflow_id") or "",
"run_id": payload.get("run_id") or "", "finished_at": _zoned(payload.get("finished_at"), tz),
"outputs": dict(outputs or {})}
if event == "source.changed":
counts = payload.get("counts") if isinstance(payload.get("counts"), dict) else {}
return {"source": payload.get("source") or "", "source_id": payload.get("source_id") or "",
"counts": {k: int(counts.get(k) or 0) for k in _COUNT_KEYS}}
return {}
def variables(event: str) -> list[dict[str, str]]:
"""变量清单接口里 event.* 的那几项:[{name, label, example, note}]。"""
out = []
for key, label, example in VARIABLES.get(event, ()):
name = "event.outputs.<字段名>" if (event, key) == ("workflow.finished", "outputs") else f"event.{key}"
if (event, key) == ("source.changed", "counts"):
name = "event.counts.new"
out.append({"name": name, "label": label, "example": example, "note": ""})
return out
# --------------------------------------------------------------------------
# 期次的写法
# --------------------------------------------------------------------------
def period_label(start: str | None, end: str | None) -> str:
"""这一期写成一个词:整月 2026-09、整季 2026-Q3、整年 2026、ISO 整周 2026-W40、单日 2026-09-30;别的写「起~止」。"""
if not start:
return ""
if not end or end == start:
return start
try:
d0, d1 = date.fromisoformat(start), date.fromisoformat(end)
except ValueError:
return f"{start}~{end}"
last_of_month = (d1 + timedelta(days=1)).day == 1
if d0.day == 1 and last_of_month:
if (d0.year, d0.month) == (d1.year, d1.month):
return f"{d0.year:04d}-{d0.month:02d}"
if d0.year == d1.year and d0.month == 1 and d1.month == 12:
return f"{d0.year:04d}"
if d0.year == d1.year and d0.month in (1, 4, 7, 10) and d1.month == d0.month + 2:
return f"{d0.year:04d}-Q{(d0.month - 1) // 3 + 1}"
if d0.weekday() == 0 and d1 - d0 == timedelta(days=6):
year, week, _ = d0.isocalendar()
return f"{year}-W{week:02d}"
return f"{start}~{end}"
# --------------------------------------------------------------------------
# 示例事件(预览、立即运行)
# --------------------------------------------------------------------------
@dataclass
class Sample:
"""按对象现在的情况凑出的一次事件:real 为假时是示例值(对象还没发生过这种事件),立即运行不拿它发起用到 event.* 的运行。"""
event: str
subject_id: str
subject_name: str
payload: dict[str, Any]
outputs: dict[str, Any] = field(default_factory=dict)
real: bool = True
async def sample(session: Any, trigger: dict[str, Any]) -> Sample:
"""预览、立即运行用的事件:上传表格取当前版本里最近的一期,上游工作流取最近一次成功的正式运行,数据源取现在的变化计数。
对象不在、还没有过这种事件时给示例值(real=False)。"""
from app.db.models import DataSource, Run, SourceSnapshot, TableImport, Workflow
event, subject = trigger.get("event") or "", subject_of(trigger)
if event in ("table.version", "source.changed"):
source = await session.get(DataSource, subject) if subject else None
name = source.name if source is not None else ""
if event == "source.changed":
if source is None:
return Sample(event, subject, name, {"source": name or EXAMPLE_NOTE, "source_id": subject,
"counts": {"new": 2, "action": 2}}, real=False)
from app.data import source_changes
got = await source_changes.counts(session, subject)
by = got.get("by_severity") or {}
return Sample(event, subject, name, {"source": name, "source_id": subject, "counts": {
"new": int(by.get("action") or 0), "action": int(by.get("action") or 0),
"warning": int(by.get("warning") or 0), "info": int(by.get("info") or 0),
"pending": int(got.get("pending") or 0)}})
snap = await session.get(SourceSnapshot, source.current_snapshot_id) \
if source is not None and source.current_snapshot_id else None
imports = list((await session.execute(select(TableImport).where(TableImport.id.in_(
[str(x) for x in snap.imports or []])))).scalars()) if snap is not None else []
latest = max(imports, key=lambda i: (i.period_end or "", i.seq or 0), default=None)
if snap is None or latest is None:
return Sample(event, subject, name, {"table": name or EXAMPLE_NOTE, "version": "", "period": "2026-09",
"period_start": "2026-09-01", "period_end": "2026-09-30",
"activated_at": ""}, real=False)
return Sample(event, subject, name, table_payload(
name, snapshot_id=snap.id, period_start=latest.period_start, period_end=latest.period_end,
activated_at=snap.activated_at or snap.created_at, replaced=False, seq=latest.seq))
workflow = await session.get(Workflow, subject) if subject else None
name = workflow.name if workflow is not None else ""
query = select(Run).where(Run.workflow_id == subject, Run.run_class == "formal", Run.status == "succeeded")
if trigger.get("app_id"):
query = query.where(Run.app_id == trigger["app_id"])
if trigger.get("origin_kind"):
query = query.where(Run.origin_kind == trigger["origin_kind"])
run = (await session.execute(query.order_by(Run.finished_at.desc()).limit(1))).scalars().first() if subject else None
if run is None:
return Sample(event, subject, name, {"workflow": name or EXAMPLE_NOTE, "workflow_id": subject, "run_id": "",
"finished_at": ""}, real=False)
return Sample(event, subject, name, run_payload(run), outputs=dict(run.output or {}))
def table_payload(name: str, *, snapshot_id: str, period_start: str | None, period_end: str | None,
activated_at: datetime | None, replaced: bool, seq: int | None) -> dict[str, Any]:
"""table.version 的事件内容(发生处和示例共用一份写法)。"""
return {"table": name, "version": snapshot_id, "period": period_label(period_start, period_end),
"period_start": period_start or "", "period_end": period_end or "",
"activated_at": _iso(activated_at), "replaced": bool(replaced), "seq": seq}
def run_payload(run: Any) -> dict[str, Any]:
"""workflow.finished 的事件内容:不含出口字段(派发时按 run_id 读成果)。"""
return {"workflow": run.workflow_name or "", "workflow_id": run.workflow_id or "", "run_id": run.id,
"finished_at": _iso(run.finished_at), "app_id": run.app_id, "origin_kind": run.origin_kind,
"version": run.version}
def _iso(moment: datetime | None) -> str:
if moment is None:
return ""
if moment.tzinfo is None:
moment = moment.replace(tzinfo=timezone.utc)
return moment.astimezone(timezone.utc).isoformat()
def uses_event(template: dict[str, str] | None) -> bool:
"""输入模板里有没有用到 {{ event.* }}(立即运行拿示例值时据此决定能不能发起)。"""
from app.scheduler.service import _TEMPLATE_RE
for text in (template or {}).values():
for match in _TEMPLATE_RE.finditer(text if isinstance(text, str) else ""):
if match.group(1).split("|")[0].strip().startswith("event."):
return True
return False