docs: add workflow schedule and run env plans
This commit is contained in:
parent
46c762384c
commit
197d2d86d0
@ -0,0 +1,129 @@
|
||||
# 工作流小时/天调度与运行时间戳环境变量设计
|
||||
|
||||
**背景**
|
||||
|
||||
当前平台已经具备基础的周期执行能力,但实现仍然停留在“按秒间隔轮询”层面:
|
||||
|
||||
- 工作流顶层 `schedule` 结构中实际生效的是 `interval`
|
||||
- 前端编辑器只暴露“调度间隔(秒)”
|
||||
- worker 只根据 `schedule.interval` 和 `workflow.lastRunAt` 决定是否创建下一次 `scheduled run`
|
||||
|
||||
这套模型能覆盖简单轮询,但无法稳定表达下面两类更接近业务使用方式的调度:
|
||||
|
||||
- 从启用时刻开始,每 `N` 小时执行一次
|
||||
- 每 `N` 天在固定 `HH:mm` 执行一次
|
||||
|
||||
同时,当前节点执行环境里已经注入了 `RUN_ID`、`WORKFLOW_ID`、`NODE_ID` 等基础变量,但还没有“上一轮 / 本轮工作流运行时间戳”这类便于做增量窗口、时间分片和幂等判断的运行时变量。
|
||||
|
||||
**目标**
|
||||
|
||||
实现并验收下面这组能力:
|
||||
|
||||
- 工作流“周期执行”支持三种模式:
|
||||
- 兼容已有的按秒间隔
|
||||
- 每 `N` 小时
|
||||
- 每 `N` 天在 `HH:mm`
|
||||
- 所有模式都能在 worker 里稳定计算下一次触发时间,不因运行时长而漂移
|
||||
- 每次 workflow run 创建时,固化“上一轮 / 本轮运行时间戳”
|
||||
- 这两个时间戳会注入到该 workflow 的所有算子节点环境变量
|
||||
- 在工作流编辑器的节点环境变量区域对这两个系统变量做只读回显
|
||||
|
||||
**设计**
|
||||
|
||||
1. `schedule` 从单一间隔扩展为“兼容旧字段 + 新模式字段”。
|
||||
|
||||
- 保留现有 `schedule.interval`,专门服务历史工作流与秒级轮询。
|
||||
- 新增:
|
||||
- `schedule.mode`
|
||||
- `schedule.intervalHours`
|
||||
- `schedule.dayInterval`
|
||||
- `schedule.timeOfDay`
|
||||
- `schedule.anchorAt`
|
||||
- `schedule.timezone`
|
||||
- `schedule.mode` 可选值:
|
||||
- `interval_seconds`
|
||||
- `every_hours`
|
||||
- `every_days_at_time`
|
||||
- 旧工作流如果只有 `interval > 0` 且没有 `mode`,继续按 `interval_seconds` 解释。
|
||||
|
||||
2. 三种调度模式分别定义清楚触发语义。
|
||||
|
||||
- `interval_seconds`
|
||||
- 完全保持现状
|
||||
- worker 继续按 `interval` 秒判断是否到期
|
||||
- `every_hours`
|
||||
- 开启该模式时写入 `anchorAt`
|
||||
- 后续所有触发点都按 `anchorAt + k * intervalHours` 计算
|
||||
- 不再用“上一轮 run 实际结束时间”当锚点,避免漂移
|
||||
- `every_days_at_time`
|
||||
- 使用 `anchorAt` 的启用日期作为周期起点
|
||||
- 使用 `timeOfDay` 与 `timezone` 计算每天的固定触发时刻
|
||||
- 如果启用当天尚未到 `HH:mm`,当天先跑一次
|
||||
- 如果启用当天已经过了 `HH:mm`,则顺延到 `N` 天后的 `HH:mm`
|
||||
|
||||
3. worker 统一改成“按计划触发点”而不是“按上次 run 时间差”判断。
|
||||
|
||||
- `interval_seconds` 仍可沿用当前逻辑
|
||||
- `every_hours` 与 `every_days_at_time` 由 worker 计算最近应触发的时间槽
|
||||
- worker 每轮最多补一个新的 `scheduled run`
|
||||
- 不追补停机期间错过的多轮窗口,避免恢复后瞬间堆积大量 run
|
||||
- 仍然沿用已有 `maxConcurrentRuns` 限流逻辑
|
||||
|
||||
4. run 创建时固化“上一轮 / 本轮运行时间戳”,不在节点执行时临时推导。
|
||||
|
||||
- 当前 `workflow.lastRunAt` 在创建 run 时就会被覆盖,因此不能在节点执行阶段再去反推“上一轮”
|
||||
- 需要在 `CreateRun(...)` 时:
|
||||
- 读取 workflow 当前的 `lastRunAt`
|
||||
- 把它作为本次 run 的“previous run timestamp”
|
||||
- 把本次触发时刻作为“current run timestamp”
|
||||
- 然后再更新 workflow 的 `lastRunAt`
|
||||
- 这样手动运行、周期运行、重试运行三种触发方式都可以用统一模型处理
|
||||
|
||||
5. 节点环境变量增加两个只读系统变量。
|
||||
|
||||
- 建议新增:
|
||||
- `WORKFLOW_PREVIOUS_RUN_TIMESTAMP`
|
||||
- `WORKFLOW_CURRENT_RUN_TIMESTAMP`
|
||||
- 格式统一为“Unix 秒级时间戳字符串”
|
||||
- 首次运行时:
|
||||
- `WORKFLOW_PREVIOUS_RUN_TIMESTAMP=0`
|
||||
- 选择 Unix 秒级字符串的原因:
|
||||
- `0` 能作为首轮缺省值,格式与正常值一致
|
||||
- Python / Shell / Go 都容易消费
|
||||
- 不依赖展示时区格式
|
||||
|
||||
6. 前端回显放在“工作流编辑器的节点配置面板”,而不是 Operators 管理页。
|
||||
|
||||
- 这两个变量是 workflow run 上下文,不属于算子定义本身
|
||||
- 因此:
|
||||
- Operators 页继续只管理算子自定义 `hyperparams`
|
||||
- WorkflowEditor 的节点详情里,在现有“超参配置 (K8s Job Env)”下新增只读块:
|
||||
- `系统注入环境变量`
|
||||
- 展示上面两个变量名、说明、格式说明、首轮值规则
|
||||
|
||||
7. `cron` 字段本轮不启用。
|
||||
|
||||
- 领域模型里已经存在 `schedule.cron`
|
||||
- 但“每 N 天从启用日开始锚定到固定时间”并不适合直接退化成 cron
|
||||
- 本轮需求不应引入半套 cron 语义,以免调度模型混乱
|
||||
|
||||
**边界与约束**
|
||||
|
||||
- `timezone` 默认固定为 `Asia/Shanghai`,先不在 UI 暴露
|
||||
- `every_hours` 的语义明确为“从启用时刻起,每 `N` 小时”
|
||||
- `every_days_at_time` 的语义明确为“按启用日期锚定,每 `N` 天在 `HH:mm`”
|
||||
- 运行时间戳 env 面向所有 workflow trigger:
|
||||
- `manual`
|
||||
- `scheduled`
|
||||
- `retry`
|
||||
|
||||
**验收标准**
|
||||
|
||||
- 工作流配置页可以稳定保存并重新加载三种调度模式
|
||||
- 历史只含 `schedule.interval` 的工作流不回归
|
||||
- worker 能正确创建“每 N 小时”与“每 N 天固定时刻”的 `scheduled run`
|
||||
- 首次运行时节点可读到:
|
||||
- `WORKFLOW_PREVIOUS_RUN_TIMESTAMP=0`
|
||||
- `WORKFLOW_CURRENT_RUN_TIMESTAMP=<unix-seconds>`
|
||||
- 非首次运行时,两个变量值按 workflow 级运行顺序正确滚动
|
||||
- WorkflowEditor 节点侧能够只读回显这两个系统环境变量
|
||||
@ -0,0 +1,265 @@
|
||||
# 工作流小时/天调度与运行时间戳环境变量 Implementation Plan
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** 为工作流周期执行增加“每 N 小时”和“每 N 天在 HH:mm”两种调度模式,并向该 workflow 的所有算子节点注入上一轮 / 本轮运行时间戳环境变量。
|
||||
|
||||
**Architecture:** 后端保留旧 `schedule.interval` 兼容历史工作流,同时扩展结构化调度字段;worker 按模式计算下一次触发点并在创建 run 时固化前后两轮时间戳;前端工作流编辑器增加小时/天调度表单,并在节点环境变量区域只读回显系统注入变量。
|
||||
|
||||
**Tech Stack:** Go API/store/worker, React workflow editor, Mongo/Memory store, Node test runner
|
||||
|
||||
---
|
||||
|
||||
### Task 1: 为新调度模式和运行时间戳补失败测试
|
||||
|
||||
**Files:**
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/internal/api/server_test.go`
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/internal/worker/runtime_test.go`
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/internal/worker/executor_test.go`
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/tests/frontend/template-settings.test.mjs`
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/tests/frontend/scan-workflows.test.mjs`
|
||||
|
||||
**Step 1: 写 API 失败测试**
|
||||
|
||||
- 覆盖 `schedule.mode=every_hours`
|
||||
- 覆盖 `schedule.mode=every_days_at_time`
|
||||
- 验证非法 `HH:mm`、`dayInterval < 1`、`intervalHours < 1` 会被拒绝
|
||||
- 验证旧 `schedule.interval` 仍可保存
|
||||
|
||||
**Step 2: 跑后端测试确认失败**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
go test ./internal/api -run 'Test.*Schedule' -v
|
||||
```
|
||||
|
||||
Expected: FAIL,因为新字段和校验尚未实现。
|
||||
|
||||
**Step 3: 写 worker 调度失败测试**
|
||||
|
||||
- `every_hours`:验证从 `anchorAt` 开始按小时触发
|
||||
- `every_days_at_time`:验证按启用日期锚定和固定 `HH:mm`
|
||||
- 验证 worker 不会一次补多个 overdue run
|
||||
|
||||
**Step 4: 写 executor 环境变量失败测试**
|
||||
|
||||
- 验证节点环境变量里包含:
|
||||
- `WORKFLOW_PREVIOUS_RUN_TIMESTAMP`
|
||||
- `WORKFLOW_CURRENT_RUN_TIMESTAMP`
|
||||
- 验证首轮 previous 为 `0`
|
||||
|
||||
**Step 5: 写前端失败测试**
|
||||
|
||||
- 验证编辑器可编辑并保留三种模式
|
||||
- 验证节点详情里会只读展示两个系统环境变量
|
||||
|
||||
### Task 2: 扩展领域模型与前后端 schedule 类型
|
||||
|
||||
**Files:**
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/internal/domain/types.go`
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/src/types.ts`
|
||||
|
||||
**Step 1: 增加调度模式字段**
|
||||
|
||||
- 在 `WorkflowSchedule` 中新增:
|
||||
- `mode`
|
||||
- `intervalHours`
|
||||
- `dayInterval`
|
||||
- `timeOfDay`
|
||||
- `anchorAt`
|
||||
- `timezone`
|
||||
|
||||
**Step 2: 增加 run 级时间戳字段**
|
||||
|
||||
- 在 `RunRecord` 中新增:
|
||||
- `PreviousRunAt`
|
||||
- `CurrentRunAt`
|
||||
|
||||
**Step 3: 跑最小编译检查**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
go test ./internal/domain/... ./internal/api/... ./internal/worker/... -run '^$'
|
||||
npm test -- --help >/dev/null 2>&1 || true
|
||||
```
|
||||
|
||||
Expected: 通过编译阶段;测试本身此时仍可能失败。
|
||||
|
||||
### Task 3: 在 store CreateRun 链路里固化前后两轮时间戳
|
||||
|
||||
**Files:**
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/internal/store/store.go`
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/internal/store/memory.go`
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/internal/store/mongo.go`
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/internal/store/memory_test.go`
|
||||
|
||||
**Step 1: 扩展 store 侧 run 创建逻辑**
|
||||
|
||||
- 在创建新 run 前先读取 workflow 当前 `LastRunAt`
|
||||
- 将其写入新 run 的 `PreviousRunAt`
|
||||
- 将本次触发时刻写入新 run 的 `CurrentRunAt`
|
||||
- 最后更新 workflow 的 `LastRunAt`
|
||||
|
||||
**Step 2: 补 store 单测**
|
||||
|
||||
- 首轮 run:`PreviousRunAt=""`
|
||||
- 第二轮 run:`PreviousRunAt` 等于首轮 `CurrentRunAt`
|
||||
|
||||
**Step 3: 跑 store 测试**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
go test ./internal/store -v
|
||||
```
|
||||
|
||||
### Task 4: 在 API 里增加调度模式校验与兼容归一化
|
||||
|
||||
**Files:**
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/internal/api/server.go`
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/internal/api/data_platform.go`
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/internal/api/server_test.go`
|
||||
|
||||
**Step 1: 增加 schedule 校验 helper**
|
||||
|
||||
- `interval_seconds` 允许现有 `interval`
|
||||
- `every_hours` 要求 `intervalHours >= 1`
|
||||
- `every_days_at_time` 要求:
|
||||
- `dayInterval >= 1`
|
||||
- `timeOfDay` 匹配 `HH:mm`
|
||||
- `timezone` 缺省补 `Asia/Shanghai`
|
||||
|
||||
**Step 2: 增加兼容归一化**
|
||||
|
||||
- 老 payload 只有 `interval > 0` 且无 `mode` 时,保存为 legacy 秒级模式
|
||||
- 手动模式关闭时,清理新模式字段到一致状态
|
||||
|
||||
**Step 3: 跑 API 测试**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
go test ./internal/api -v
|
||||
```
|
||||
|
||||
### Task 5: 重写 worker 调度判断为模式化计算
|
||||
|
||||
**Files:**
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/internal/worker/runtime.go`
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/internal/worker/runtime_test.go`
|
||||
|
||||
**Step 1: 提取 schedule due-time helper**
|
||||
|
||||
- 为三种模式分别计算“当前是否到期”
|
||||
- `every_hours` 依据 `anchorAt + k * intervalHours`
|
||||
- `every_days_at_time` 依据 `anchorAt` 日期、`dayInterval`、`timeOfDay`、`timezone`
|
||||
|
||||
**Step 2: 保持单轮最多创建一个 scheduled run**
|
||||
|
||||
- 若 workflow 已经过期多个窗口,也只 enqueue 一个 run
|
||||
- 继续遵守并发限制
|
||||
|
||||
**Step 3: 跑 worker 测试**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
go test ./internal/worker -run 'TestEnqueueStreamingWorkflows|TestBuildNodeEnv' -v
|
||||
```
|
||||
|
||||
### Task 6: 给所有节点注入运行时间戳环境变量
|
||||
|
||||
**Files:**
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/internal/worker/executor.go`
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/internal/worker/executor_test.go`
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/docs/operator-authoring.md`
|
||||
|
||||
**Step 1: executor 注入新变量**
|
||||
|
||||
- 新增:
|
||||
- `WORKFLOW_PREVIOUS_RUN_TIMESTAMP`
|
||||
- `WORKFLOW_CURRENT_RUN_TIMESTAMP`
|
||||
- 值统一转成 Unix 秒级字符串
|
||||
- `PreviousRunAt` 为空时,注入 `0`
|
||||
|
||||
**Step 2: 文档同步**
|
||||
|
||||
- 在 `operator-authoring.md` 中补充这两个系统环境变量说明
|
||||
|
||||
**Step 3: 跑 executor 测试**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
go test ./internal/worker -run 'TestBuildNodeEnv' -v
|
||||
```
|
||||
|
||||
### Task 7: 更新 WorkflowEditor 调度 UI 与系统变量只读回显
|
||||
|
||||
**Files:**
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/src/pages/WorkflowEditor.tsx`
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/src/lib/scan-workflows.js`
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/tests/frontend/scan-workflows.test.mjs`
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/tests/frontend/template-settings.test.mjs`
|
||||
|
||||
**Step 1: 调度表单支持三种模式**
|
||||
|
||||
- `按秒`
|
||||
- `按小时`
|
||||
- `按天`
|
||||
|
||||
**Step 2: 对应展示字段**
|
||||
|
||||
- `按秒`:`interval`
|
||||
- `按小时`:`intervalHours`
|
||||
- `按天`:`dayInterval + timeOfDay`
|
||||
|
||||
**Step 3: 节点环境变量区新增只读块**
|
||||
|
||||
- 标题:`系统注入环境变量`
|
||||
- 展示:
|
||||
- `WORKFLOW_PREVIOUS_RUN_TIMESTAMP`
|
||||
- `WORKFLOW_CURRENT_RUN_TIMESTAMP`
|
||||
- 标注:
|
||||
- `Unix 秒级时间戳`
|
||||
- `首次运行 previous=0`
|
||||
- `运行时自动注入`
|
||||
|
||||
**Step 4: 跑前端测试**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
node --test tests/frontend/scan-workflows.test.mjs tests/frontend/template-settings.test.mjs
|
||||
```
|
||||
|
||||
### Task 8: 做全链路验证并补文档
|
||||
|
||||
**Files:**
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/docs/operations.md`
|
||||
- Modify: `/Users/longtaowu/workspace/droboticflow/docs/api.md`
|
||||
- Modify as needed during fix loop
|
||||
|
||||
**Step 1: 更新运行与 API 文档**
|
||||
|
||||
- 说明新 schedule 模式
|
||||
- 说明两个系统 env 变量
|
||||
|
||||
**Step 2: 跑本地回归**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
go test ./internal/api ./internal/store ./internal/worker -count=1
|
||||
node --test tests/frontend/scan-workflows.test.mjs tests/frontend/template-settings.test.mjs
|
||||
npm run build
|
||||
```
|
||||
|
||||
**Step 3: 如失败则修复后重复执行,直到通过**
|
||||
|
||||
**Step 4: 输出验收结论**
|
||||
|
||||
- 给出小时模式与按天模式的最终行为
|
||||
- 给出两个系统环境变量的最终命名和格式
|
||||
Loading…
x
Reference in New Issue
Block a user