7.4 KiB
7.4 KiB
Orbit · 星轨设计文档
- 文档版本：0.2
- 整理日期：2026-09-17
- 阶段：P0–P2 已通过阶段验收；P3 安全重试、计划调度、运行中取消和队列资源控制已通过回归，数据库已改为无外键，P3–P7 继续推进，尚未完成全平台生产验收
- 适用范围：Orbit 统一平台，包含 Pulse 任务调度模块、Weave 流程编排模块与公共能力。平台面向多个业务系统复用。
阅读顺序
| 文档 | 内容 |
|---|---|
| 01 功能说明 | 平台职责、Pulse 与公共能力、操作行为与责任边界 |
| 02 技术方案 | 组件、部署、调度与派发、MySQL 使用方式、SDK |
| 03 HTTP 与 WebSocket 协议 | 接口草案、消息结构、确认、重连、鉴权与兼容性 |
| 04 可靠性与数据模型 | 状态机、事务、租约、幂等、调度一致性、恢复 |
| 05 生产验收 | 故障场景、性能指标、上线门槛与验证证据 |
| 06 Weave 流程设计 | 已确认的首版功能、研发定义发布、持久化等待、有界查询、暂停恢复与模块协作 |
| 07 数据模型 | 当前 Go 实体、数据库约束、存储约定与实现边界 |
| 08 持续开发计划 | 开发、测试回归、阶段验收与最终交付目标 |
| 接口手册 | 实际接口状态、调用说明与后续接口规划 |
| SDK 与场景 | 可运行示例、接入方法及分阶段 SDK 交付 |
已确认的决策
| 项目 | 决策 |
|---|---|
| 产品定位 | 通用任务调度与流程编排平台，支持多个业务项目复用 |
| 名称与目录 | Orbit · 星轨，目录 orbit/ |
| 项目与部署 | 一个统一项目，内部保留 Pulse 与 Weave；平台独立于业务系统部署，业务方通过 SDK 接入 |
| 开发语言 | Go |
| 持久化 | MySQL 为任务、执行、计划、流程及结果的权威存储 |
| 数据库关联 | 禁止外键及级联删除，关联存在性与归属由服务端事务验证；保留必要索引、唯一约束和 CHECK |
| 通信方向 | HTTP + WebSocket；生产使用 HTTPS / WSS |
| HTTP 职责 | 任务提交、流程启动与信号、查询、计划管理、配置与管理操作 |
| WS 职责 | Worker 接入、能力与容量上报、任务派发、续租、结果上报、取消通知 |
| 执行位置 | 业务处理器位于业务项目自己的 Worker 中 |
| 外部依赖范围 | 首版以 MySQL 为必需的外部存储依赖；运行不要求 Redis、独立消息队列或独立协调服务 |
| Pulse 与公共功能范围 | 任务管理、定时计划、Worker 与恢复、资源控制、多项目权限、审计可观测、SDK 与运维 |
| Weave 定位与定义方式 | 同一平台内承担流程编排，研发通过 Go SDK 描述并发布版本，业务处理器仍在业务 Worker 中运行 |
| Weave 首版流程能力 | 顺序、条件分支、有限并行与汇合、等待信号、定时等待、有界重复查询 |
| Weave 首版管理能力 | 暂停与继续、取消、人工核查与恢复、版本固定、全程追踪 |
Orbit 不内置特定行业规则；Pulse 管理执行，Weave 管理步骤依赖、分支和等待等流程语义。二者通过模块接口及共享事务协作，不要求相互通过 HTTP / WS 调用。
如何理解文档中的约束
- 已确认：上表的平台方向、Pulse 与 Weave 首版功能范围及研发定义发布方式已在讨论中确认。
- 设计要求：为实现已确认的生产目标提出的可靠性约束，后续代码与测试应共同遵守。
- 设计建议 / 草案：本次整理补充的具体实现选择，仍需协议或架构评审。
- 待定：没有足够依据的参数或选择，不代表已批准或已实现。
本文中的“必须”描述目标行为，不代表当前已经具备该能力。示例 ID、接口与 JSON 均为设计示例。
需要继续确认的事项
| 事项 | 当前建议 / 处理方式 | 关联文档 |
|---|---|---|
| HTTP / WS 的最终字段、路径、错误码 | 以本稿作为协议草案，评审后冻结 v1 | 协议 |
| Weave 技术细则 | 功能范围已确认；SDK/定义 Schema、暂停门控与计时、查询预算、并行失败策略、人工恢复身份仍需评审 | 流程 |
| WS 库及后续依赖版本 | 当前基础使用 Go 1.27.1、MySQL 8.4+ 与显式 SQL；WS 已锁定 coder/websocket v1.8.15，后续依赖需单独验证 | 模型基线 |
| 人工重试的任务身份 | 建议创建关联的新任务，自动重试保持原任务 ID | 功能 |
| Cron、固定间隔与夏令时细节 | 已实现五段 Cron、fixed-rate；缺失时刻跳过、重复时刻按 UTC 分开；时区快照随版本冻结 | 计划接口 |
| 批量大小、消息上限、心跳、租约、扫描周期 | 均需设置有限上限；数值通过原型与压测确定 | 验收 |
| 幂等、事件、审计的保留周期 | 按恢复与业务追溯要求确定，不能仅随任务清理 | 数据 |
| 数据库高可用与恢复目标 | 明确故障模型、复制确认、RPO / RTO 及运维责任 | 验收 |
| 容量与可用性目标 | 根据峰值提交、活跃任务、连接数和积压建立负载模型 | 验收 |
| 多分区与全局配额细节 | 明确路由与配额一致性范围后实现，首版不承诺跨库原子操作 | 技术 |
上述事项中影响执行安全、兼容和容量验收的内容，必须在生产发布前关闭。不能将“待定”参数直接作为生产默认值。
文档维护规则
- 功能文档定义使用者看到的行为；协议文档定义通信；数据文档定义权威状态与不变量，其他文档通过链接引用。
- 修改状态、幂等、重试、租约或确认语义时，同时更新协议、恢复场景和验收项。
- 改变已确认决策时记录原因、影响与迁移方式，不静默替换旧约定。
- 设计建议不应被描述为已验证的性能或生产保证。
- 当前已在 Orbit 目录初始化独立 Git 并开始代码实现；服务端、SDK、文档与测试同步维护，不修改目录外的历史项目。
决策更新
2026-09-17，用户明确禁止数据库外键：通过 000008 前向迁移移除全部历史外键，同步服务端关联校验、启动检查及真实数据库回归；详见 模型约定 和 验证记录。
2026-09-17，文档更新至 0.2：用户确认研发定义发布流程及 Weave 首版功能，明确纳入有界重复查询和暂停/继续等生产管理能力。技术细则与参数继续按建议或待定标注，未将功能确认等同于实现或验收通过。
持续开发目标已建立。当前实现和验收进度以 开发计划、P0 报告、P1 报告 与 P2 阶段验收 、P3 安全重试报告 和 P3 计划调度报告 为准；早期设计稿中的“未实现”描述保留其编写阶段语境。