orbit/docs/01-functional-spec.md

Orbit 功能说明：Pulse 与公共能力

版本 0.2 · 2026-09-17。Pulse 与 Weave 首版功能范围已确认；标注“建议”的细节待评审。Weave 具体范围另见流程设计。基础、任务执行、调度、资源控制和可靠订阅已实现；批量受理、独立任务核查/人工重试及查询筛选等继续开发，实现状态见持续开发计划。

1. 目标与责任边界

Orbit 统一提供任务调度与流程编排。Pulse 接收一个明确的工作单元，按照时间、容量、权限和重试策略交给业务 Worker 执行，管理可查询、可恢复的执行过程。Weave 将多个工作单元按流程规则连接起来，具体方案见 流程设计。

参与方	职责
Pulse	任务受理、调度、派发、执行权、重试控制、运行记录、结果交付
业务系统 / Worker	业务校验、业务授权、外部调用、业务幂等、业务结果与证据
Weave（内部模块）	研发定义发布、多步骤依赖、分支、汇合、持久化等待、有界重复查询、暂停/继续、人工恢复与流程版本
MySQL 运维	数据持久化与复制配置、备份、故障切换、恢复演练

任务可以是一次文件转换、一次数据准备或一次外部作业结果查询。Pulse 管理任务执行过程，具体业务结果和完成条件由处理器契约定义。

任务类型、参数和标识采用通用模型，不要求平台理解接入方的专用业务概念。

2. 基本概念

概念	含义
应用 / 环境 / 命名空间	接入身份与资源边界；建议一个应用环境对应一个命名空间
队列	任务路由、资源配置与 Worker 消费范围
任务类型与版本	处理器身份及其兼容版本
任务	一项已受理工作，具有稳定的任务 ID
执行尝试	一次派发与执行过程，具有独立尝试 ID 和执行凭据
调度计划	产生任务的时间规则，每次实际触发产生独立任务
业务关联键	由业务方提供的查找、追踪标识
并发控制键	在规定作用域内限制同时有效执行许可的通用标识

自动重试沿用任务 ID，产生新的执行尝试。HTTP 请求重试、任务重试和定时计划的下一次触发是三件不同的事情。

Weave 有界查询的一轮对应一个 Pulse 任务；查询得到“处理中”后，Weave 等待并创建下一轮任务。当前轮请求失败由 Pulse 在原任务下重试，不能通过开启新轮次绕过重试上限。

3. 任务提交与管理

3.1 提交方式

• 立即执行：受理后尽快进入可派发范围，实际开始时间受资源和排队影响。
• 延迟执行：在指定等待时长之后才允许开始。
• 指定时间执行：在指定时间之后才允许开始，不承诺硬实时触发。
• 批量提交：多项普通任务的提交方式；建议逐项返回结果，每项独立幂等，失败项独立补交。

任务至少说明：归属、队列、处理器与版本、参数版本、执行时间、时限、重试规则和提交幂等标识。已受理参数与生效策略保存快照；修改配置不静默改写历史任务。

最晚允许开始时间、单次执行超时、任务总时限分别定义。到期后停止授权新的执行；已经发出的业务请求是否产生效果，需要按处理器的结果确认规则判断。

3.2 操作行为

操作	目标行为
幂等提交	同作用域、同标识、同语义请求返回原任务；同标识不同请求明确冲突
查询	返回当前任务状态、关联计划、执行尝试、错误与结果引用
取消待执行任务	在与开始执行的竞争中原子决定取消是否生效
取消执行中任务	持久化取消意图并通知 Worker，等待停止或最终结果，已有业务效果不自动撤销
人工重试	校验权限、错误类别及业务确认条件，保留原历史，记录操作人和原因
修改业务参数	新建关联任务，原任务参数不变

设计建议：人工重试创建带 retry_of 的新任务。 原任务保留终态及结果，避免外部订阅方已经消费终态后任务又悄悄恢复。业务幂等键应按原操作语义保留；平台新任务 ID 不代表允许重复产生业务副作用。此项在协议冻结前确认。

流程关联任务的人工恢复统一经过 Weave，校验流程版本、步骤归属和当前恢复条件；不能直接从普通任务重试入口生成无人接续的流程任务。

流程暂停的门控建议由 Pulse 通用执行控制承载，阻止关联任务的新领取、开始和执行重试，同时继续收集已授权执行的结果。它与定时计划暂停、队列暂停分别建模；具体规则见 Weave 暂停与继续。

任务成功表示处理器完成约定的这一步。例如“渠道提交已受理”可以是一个处理器的成功结果，最终业务成功应由查询或回执处理任务另行确认。

4. 定时计划

• 支持 Cron、固定间隔、时区、生效与结束边界、启用、暂停、恢复和修改计划。
• 设计建议：首版采用五段 Cron；固定间隔首先定义为按基准时间推进的 fixed-rate。是否增加“完成后再等待”的 fixed-delay 待确认。
• 每个实际触发点具有唯一身份，记录采用的计划版本与原计划时间。
• 计划变更明确生效边界；已生成任务保留原参数与策略快照。
• 暂停计划阻止新的触发，不隐式取消已经生成或正在执行的任务。

创建计划时必须明确以下策略，不能在故障后临时猜测：

情况	可选策略及限制
漏跑	跳过、合并为一次、按次补跑；补跑必须有数量/时间窗口与速率上限
上一轮未完成	允许并行、串行等待、跳过本次；串行等待也必须有积压上限
时区夏令时变化	明确不存在时刻、重复时刻的处理，首版选定并测试后发布
停机期间修改计划	保存版本与生效边界，按明确的历史版本计算漏跑

跳过和合并需留下原因、原计划时间或覆盖范围。业务日历由业务系统决定，Pulse 执行其提交的时间计划。

5. Worker 与执行恢复

• Worker 通过 WSS 主动连接，经过鉴权后声明处理器版本、消费队列及执行容量。
• SDK 封装消息收发、任务去重、租约续期、结果重报、带抖动的重连和优雅退出。
• 同一 Worker 可执行多个任务，网络读写不能被业务处理器阻塞。
• 任务只分配给版本兼容且有容量的 Worker；无兼容 Worker 时可观测地等待，并受时限约束。
• 连接心跳检测通信；任务续租确认具体执行权，两者独立。
• 断线后先核对任务，不直接认定业务失败；无有效租约时 Worker 应停止推进并尝试取消可取消的操作。
• 优雅退出时停止接新任务，给已有任务留出受控完成时间，退出超时按恢复规则处理。

错误至少区分：可安全重试、明确不可重试、需要外部核查、需要人工处理。策略包含退避、抖动、尝试上限或总时限，禁止无限快速重试。

副作用是否发生不明确时，不允许因为“网络错误”自动重复提交业务操作。任务类型必须声明恢复安全等级；声明缺失时采用保守处理。

6. 队列与资源控制

• 支持队列并发、应用配额、速率限制、优先级和项目间公平性。
• 支持按业务提供的并发控制键限制有效执行许可。例如可用资源标识限制同一资源的一类操作。
• 跨节点限制必须由共享状态协调，单节点内存计数只能约束该节点。
• 并发控制不自动提供跨任务严格顺序；需要顺序的业务必须明确顺序协议或交由流程编排。
• 任务数量、参数大小、发送缓冲、事件积压和重试均有有限上限，并提供拒绝/背压行为。

过期 Worker 仍可能在物理上运行。业务资源端还需幂等或执行代次校验，避免旧执行产生额外效果。

7. 多项目、安全与管理

支持应用与环境隔离、可轮换凭据、队列级提交和消费授权、查询权限与管理权限。命名空间和 Worker 标识不能替代身份认证。

管理操作包括暂停队列派发、调整配额、取消、人工重试和计划变更。都应记录操作人、时间、原因和前后状态。暂停派发不等于强制停止运行中的处理器。

参数、结果与日志设置访问控制和脱敏规则。大文件使用业务侧引用；凭据不作为普通任务参数或日志传递。

8. 查询、审计、告警与结果交付

• 通过任务 ID、业务关联键、状态、队列、时间范围查找任务。
• 保存执行尝试和关键状态转换，关联 Worker、版本、错误分类与结果引用。
• 监控任务积压、到期派发延迟、重试、失联、数据库异常、结果通知积压和资源用量。
• 提供可靠结果订阅：事件持久化，接收方处理后确认，未确认可再次交付。
• 运行统计可最终一致；影响派发与终态判断的状态必须按权威状态读取。
• Orbit 运行审计与业务审计通过关联标识衔接，保存策略分别制定。

9. 首版范围与后续扩展

上述生产相关行为属于首版设计范围。首版首先交付 Go SDK、管理 API 与必要运行指标。完整图形化控制台、其他语言 SDK、高级全文检索及跨地域主动写入作为后续扩展评估。

流程依赖、等待及有界查询由平台内的 Weave 承担，已确认范围见 流程功能与设计。审批人员与业务权限规则、专用规则计算由业务系统承担。通用 SQL 查询平台、文件处理平台不纳入 Orbit。

功能是否达标以 生产验收 的结果为依据，不以接口存在或演示运行成功代替。