# Orbit 持续开发与回归计划

更新：2026-09-17。此计划对应持续开发目标，由开发过程同步维护。数据库已按用户要求采用无外键设计，迁移 000008 移除历史外键，关联一致性由服务端事务保证。

## 1. 最终交付目标

交付可由多个业务项目接入的 Go + MySQL + HTTP/WebSocket 平台：Pulse 管理任务与调度，Weave 管理持久化流程，业务处理器运行在独立 Worker。研发通过独立 Go SDK 定义和发布流程。

完成标准包括服务端、SDK、迁移及运行工具、Markdown 接口手册、可运行场景示例，以及实际正确性/故障/性能验证记录。完成设计、单机运行或展示一条正常路径，均不等同于完成首版交付。

## 2. 持续推进方式

每个阶段按以下顺序推进：

1. 根据已确认功能细化状态、协议、数据及完成标准。
2. 完成一条可执行的业务无关调用链，同步 SDK 和文档。
3. 运行单元、真实数据库、协议及端到端回归，记录失败与修复。
4. 验证该阶段异常路径、兼容性、授权边界与可恢复性。
5. 更新本计划、接口实现状态、示例和验证报告，再进入下一阶段。

常规技术选择和缺陷修复自主进行。只有确实缺少外部信息或涉及未获授权的操作时才请求用户介入。不能为了让目标显示完成而隐藏未实现项或跳过故障验收。

## 3. 阶段清单

| 阶段 | 开发内容 | 回归与完成标准 | 当前状态 |
| --- | --- | --- | --- |
| P0 基础与数据模型 | Go workspace、独立 SDK module、公共/Pulse/Weave 模型、MySQL 迁移、配置、健康检查 | 编译/竞态/静态检查；真实 MySQL 建表、隔离、唯一性、预算、不可变版本、迁移失败防护；SDK 健康调用 | 已完成并通过阶段回归（见 P0 报告） |
| P1 任务受理闭环 | 应用凭据与作用域权限、队列、幂等提交、查询、待执行取消、受理事件；SDK 客户端 | API/SDK 创建查询闭环；重复键与内容冲突、响应未确认重报、跨命名空间拒绝、参数边界 | 已完成并通过阶段回归（见 P1 报告；真实断路/提交 ACK 丢失注入留后续故障阶段） |
| P2 Worker 执行闭环 | WSS 接入、能力/容量、领取与开始、租约、续租、结果确认、排空与恢复；Worker SDK | 真 Worker 执行；失联/重连/重复确认/旧尝试拒绝；业务效果未知转核查；节点故障接管 | 已完成并通过阶段回归：服务端、自动 SDK、历史查询、完整 Schema 与真实进程强杀恢复；测试拓扑和剩余生产故障矩阵见 P2 验收报告 |
| P3 Pulse 完整能力 | 安全重试、延时、Cron/固定间隔、漏跑策略、计划版本、运行中取消、并发许可、配额/背压、可靠结果订阅、批量受理、独立任务核查/人工重试、查询筛选与事务Outbox接入 | 多实例领取/触发竞争、重试上限、取消竞争、队列隔离、积压恢复、事件重复交付 | 进行中：安全重试、计划调度、运行中取消、队列控制/限速/积压背压、跨命名空间应用配额、显式资源键许可及 SDK 场景已实现并通过全量回归；优先级及节点公平派发已实现并通过全量回归；可靠订阅核心、HTTP/WSS、管理 SDK 和管理示例已实现并回归；消费 SDK、协议示例及两项节点强杀回归已完成；业务 Inbox 场景、COMMIT响应丢失及消费者进程故障回归已完成；批量受理、SDK、接口与部分补交示例已完成全量回归；独立任务核查/人工重试、业务键/时间筛选与事务Outbox接入待完成 |
| P4 Weave 主流程 | SDK 定义构建与发布校验、实例、顺序/分支/结构化并行汇合、信号/定时等待、版本绑定 | 重启接续、早到/重复信号、并行竞争、内部事件重放、发布版本兼容；端到端通用流程 | 待开发 |
| P5 Weave 恢复与查询 | 有界查询、暂停继续、取消、人工核查恢复、控制门控与审计 | 轮次与尝试独立预算；暂停/开始/回执/超时竞争；恢复保留预算；未知结果不盲目重复 | 待开发 |
| P6 生产验证与运维 | 完整监控、凭据轮换、备份恢复、滚动升级、运行手册、可复现负载和故障工具 | 对照生产验收清单执行，报告环境/指标/遗留项；容量、RPO/RTO 按真实拓扑验证 | 待开发 |
| P7 首版交付核对 | SDK 兼容与发布准备、完整 API 手册、场景示例、全量回归及交付清单 | 新接入者按文档跑通全部示例；所有首版能力可追溯到实现与测试；报告实际生产边界 | 待开发 |

SDK、文档与示例随 P1–P5 同步开发，P7 是全量核对，不是最后才开始补文档。

### P3 功能范围核对

可靠订阅链路完成后，重新对照 [原功能范围](01-functional-spec.md) 和 [事务衔接设计](04-reliability-and-data.md)，以下原定首版能力按核对结果逐项补齐。不能只按已实现模块反推P3完成；全部补齐并回归后，再进入完整阶段验收。

| 核对项 | 当前证据与后续交付 |
| --- | --- |
| 批量任务受理 | 已实现[批量API](api/batch-tasks.md)、独立SDK及[补交示例](examples/batch.md)；真实MySQL部分失败与HTTP响应丢失用例已通过，同键并发20轮及全量回归已通过，见[报告](reports/phase-3-batch-tasks.md) |
| 独立任务人工核查与重试 | [重试API](api/retries.md) 仍未提供解除不确定性的核查接口；需证据、权限、版本、审计和历史保留，人工重试身份按关联新任务实现并冻结契约 |
| 任务查询筛选 | [当前ListTasks](../sdk/go/types.go) 仅队列/状态/分页；需按业务关联键及创建时间范围查询，游标绑定所有筛选，保持授权与有界索引扫描 |
| 业务到平台的事务Outbox接入 | [事务Outbox设计](04-reliability-and-data.md#61-业务系统到平台) 尚缺完整接入示例；需业务变更与待发请求同事务、稳定提交身份、响应不明核对和发送恢复，保持核心SDK无ORM/数据库依赖 |

凭据安全重绑、历史清理、全量监控/容量与MySQL故障切换仍按P6执行；Weave的通用执行门控/内部事件接续随P4–P5落实，不将外部结果订阅当作内部流程引擎。


## 4. SDK 与示例交付清单

| 场景 | 预期调用链 | 所属阶段 |
| --- | --- | --- |
| 健康检查 | 创建客户端 → 存活/就绪查询 | P0 |
| 文件转换任务 | 提交幂等任务 → Worker 处理 → 查询结果 | P1–P2 |
| 有限安全重试 | 明确失败 → 持久化退避 → 新尝试 → 查询完整历史 | P3，已实现完整示例 |
| 定期数据同步 | 发布计划 → 触发任务 → 暂停/恢复 → 查看触发记录 | P3，已实现通用快照示例 |
| 运行中取消 | 保存取消意图 → 停止处理器 → 确认结果 → 查询并排空 | P3，已实现完整示例 |
| 队列限速与背压 | 暂停 → 满额拒绝 → 原回执核对 → 释放空间 → 限速执行 | P3，已实现完整示例 |
| 跨命名空间应用配额 | first 受理 → second 全局满额 → 释放 → 原键成功 → 恢复配置 | P3，已实现完整示例 |
| 跨队列共享资源 | 两队列同键 → 一个有效许可 → 递增序号 → 资源端拒绝旧写入 | P3，已实现完整示例 |
| 优先级与应用隔离 | 近同时到期按优先级 → 旧任务等待补偿 → 应用/队列轮转 | P3，已实现完整示例 |
| 可靠结果订阅 | 冻结结果 → 持久化交付 → Inbox 去重 → 确认/补发 → 耗尽后人工重试 | P3，核心、HTTP/WSS、管理及消费 SDK、独立Inbox示例与真实进程故障回归已完成 |
| 批量文件作业受理 | 逐项身份 → 部分结果 → 同键核对 → 释放额度 → 只补交失败项 | P3，已实现完整示例 |
| 并行生成结果 | 发布流程 → 并行执行 → 汇合 → 完成 | P4 |
| 审核与外部回执 | 提交流程 → 等待信号 → 授权信号注入 → 继续 | P4 |
| 外部作业轮询 | 提交一次 → 有界查询处理中状态 → 回执或最终结果 → 超限核查 | P5 |
| 暂停与人工恢复 | 暂停 → 保存结果 → 核查/恢复 → 查看审计 | P5 |
| 故障恢复 | 节点/连接中断 → 相同身份核对 → 恢复或人工核查 | P2–P6 |
| 执行历史核对 | 读取尝试 → 查看冲突/迟到证据 → 对照权威结果 | P2，已实现完整示例 |

每个正式示例需要：前置配置、完整可运行源码、启动命令、输入、预期输出、失败路径、幂等/清理说明。SDK API 尚未实现时，文档只能标为规划，不能给出伪装可运行的代码。

## 5. 回归规则

- 每次模型或迁移变化：执行真实 MySQL 集成测试，验证外键为 0、服务端关联归属、唯一约束与升级数据保留。
- 每次状态或协议变化：更新服务端、SDK、兼容说明与异常场景。
- 每次执行/恢复变化：增加对应断线、超时、重复、迟到、宕机或竞争用例。
- 每次发布候选：全量回归、示例回归、迁移检查、故障和负载报告。
- 验证失败先修复再推进，未执行的项目明确记为未验证。

## 6. 性能与高可用验收边界

不直接用租户总数作为容量结论。P6 先固定硬件、数据库拓扑、消息大小、任务时长、连接数、峰值与积压模型，再记录受理/派发/推进/恢复的吞吐、延迟和资源消耗。

本地多实例与故障注入可以验证恢复逻辑；实际生产复制确认、跨故障域部署、备份介质、RPO/RTO 及峰值余量，需要在对应部署环境复测。所有报告分别标注已验证、未验证和当前限制。

## 7. 文档入口

- [数据模型](07-data-model.md)
- [可靠结果订阅核心](09-result-subscription-core.md)
- [P3 订阅核心回归](reports/phase-3-result-subscription-core.md)
- [P3 订阅通信与管理 SDK 回归](reports/phase-3-result-subscription-transport.md)
- [P3 消费 SDK 与节点故障回归](reports/phase-3-event-consumer-sdk.md)
- [P3 业务 Inbox 与消费者故障回归](reports/phase-3-result-inbox.md)
- [P3 批量任务受理回归](reports/phase-3-batch-tasks.md)
- [接口手册](api/README.md)
- [SDK 接入](sdk/README.md)
- [通用场景示例](examples/README.md)
- [生产验收总清单](05-production-acceptance.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-cancellation.md)
- [P3 队列资源控制回归](reports/phase-3-queue-resources.md)
- [P3 应用共享配额回归](reports/phase-3-application-resources.md)
- [P3 资源键许可回归](reports/phase-3-keyed-concurrency.md)
- [P3 优先级和公平派发回归](reports/phase-3-priority-fairness.md)
- [P2 服务端阶段记录](reports/phase-2-server.md)
- [P2 SDK 协议阶段记录](reports/phase-2-sdk-protocol.md)
- [P2 自动 Worker 运行器记录](reports/phase-2-worker-runtime.md)
- [P2 执行历史与大载荷记录](reports/phase-2-execution-history.md)