2.5 KiB
2.5 KiB
快速 Demo 核心契约 V1
冻结日期：2026-07-27
状态：frozen-target
1. 契约边界
Demo 公共 HTTP API 由两部分共同组成：
openapi/platform-api-v1.yaml：已经运行的脚本、稳定版本详情、数据资源和文件编辑锁接口。openapi/demo-core-extension-v1.yaml：第 15 小步冻结、后续小步实现的上下文、Jupyter 票据、稳定版本列表、调度和运行查询接口。
内部 Storage 与 Runtime 接口继续分别以
openapi/storage-api-internal-v1.yaml 和
openapi/runtime-api-internal-v1.yaml 为准。
2. 不可变约束
- 主标识使用 ULID；调度节点只引用不可变的
versions_id。 - 当前认证上下文由
X-User-ID、X-Workspace-ID提供；以后换成 JWT 时不得改变业务 DTO。 - 修改调度方案必须提交
workflow_version，冲突返回412。 - 创建调度、立即运行、启停和取消使用
Idempotency-Key。 schedule_runs.schedule_snapshot固化本次执行 DAG，后续编辑不影响已创建的运行。- 浏览器不能拿到 Jupyter 内部 Token，只能获得短期访问 Cookie。
3. 状态值
- 调度运行：
queued / running / succeeded / failed / cancelled / timed_out - 节点运行：
queued / running / succeeded / failed / skipped / cancelled / timed_out - 失败策略：
stop / continue - 触发类型：
manual / cron / api / retry
4. MySQL Outbox 与 HTTP 推送
| 事件 | 写入方 | 处理方 |
|---|---|---|
schedule.run.requested |
Backend / Cron Dispatcher | Schedule Executor |
job.node.execute |
Schedule Executor | Schedule Executor Worker |
job.node.finished |
Schedule Executor Worker | Schedule Executor |
业务事务先写 outbox_events。Backend 对“立即运行”执行一次内部 HTTP 推送，
Executor 同时轮询 MySQL 作为兜底；consumer_inbox 防止同一事件重复执行。
5. 模块所有权
| 模块 | 拥有的数据与职责 |
|---|---|
| Platform API | 脚本、稳定版本、调度定义、运行查询、Outbox 写入 |
| Runtime Manager | Workspace/Jupyter 生命周期与内部运行态 |
| Nginx | 统一入口、Jupyter HTTP/WebSocket 代理 |
| Schedule Orchestrator | 消费调度请求、解析 DAG、推进节点状态 |
| Job Worker | 读取稳定版本、执行节点、保存日志/结果、报告终态 |
| Storage Service | RustFS 对象元数据与预签名访问 |
模块间不得复制定义 DTO、状态枚举、错误结构或事件字段；契约变更必须先 升级本目录中的版本化文件。