# Orbit · 星轨设计文档

- 文档版本：0.2
- 整理日期：2026-09-17
- 阶段：P0–P2 已通过阶段验收；P3 安全重试、计划调度、运行中取消、队列资源控制和应用共享配额已通过回归，资源键许可及真实进程恢复已通过全量回归，优先级/节点公平派发及真实隔离场景已通过全量回归，批量任务受理已实现，数据库已改为无外键，P3–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) | 开发、测试回归、阶段验收与最终交付目标 |
| [接口手册](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、独立消息队列或独立协调服务 |
| 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) |
| 人工重试的任务身份 | 建议创建关联的新任务，自动重试保持原任务 ID | [功能](01-functional-spec.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) 为准；早期设计稿中的“未实现”描述保留其编写阶段语境。