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