58 lines
2.7 KiB
Markdown
58 lines
2.7 KiB
Markdown
# 快速 Demo 核心契约 V1
|
|
|
|
冻结日期：2026-07-27
|
|
状态：`frozen-target`
|
|
|
|
## 1. 契约边界
|
|
|
|
Demo 公共 HTTP API 由两部分共同组成：
|
|
|
|
1. `openapi/platform-api-v1.yaml`：已经运行的脚本、稳定版本详情、数据资源和文件编辑锁接口。
|
|
2. `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. Redis Streams 路由
|
|
|
|
| Stream | Consumer Group | 事件 | 生产者 | 消费者 |
|
|
|---|---|---|---|---|
|
|
| `stream:scheduler:commands` | `schedule-orchestrator` | `schedule.run.requested` | Platform API / Cron Dispatcher | Schedule Orchestrator |
|
|
| `stream:jobs:execute` | `job-workers` | `job.node.execute` | Schedule Orchestrator | Job Worker |
|
|
| `stream:jobs:results` | `schedule-results` | `job.node.finished` | Job Worker | Schedule Orchestrator |
|
|
|
|
交付语义为至少一次。业务事务先写 `outbox_events`，发布成功后更新
|
|
Outbox；消费者处理前以 `consumer_inbox` 去重，业务更新与 Inbox 写入同一
|
|
MySQL 事务。只有业务事务提交成功后才确认 Redis 消息。
|
|
|
|
## 5. 模块所有权
|
|
|
|
| 模块 | 拥有的数据与职责 |
|
|
|---|---|
|
|
| Platform API | 脚本、稳定版本、调度定义、运行查询、Outbox 写入 |
|
|
| Runtime Manager | Workspace/Jupyter 生命周期与内部运行态 |
|
|
| Nginx | 统一入口、Jupyter HTTP/WebSocket 代理 |
|
|
| Schedule Orchestrator | 消费调度请求、解析 DAG、推进节点状态 |
|
|
| Job Worker | 读取稳定版本、执行节点、保存日志/结果、报告终态 |
|
|
| Storage Service | RustFS 对象元数据与预签名访问 |
|
|
|
|
模块间不得复制定义 DTO、状态枚举、错误结构或事件字段；契约变更必须先
|
|
升级本目录中的版本化文件。
|