88 lines
21 KiB
Markdown
88 lines
21 KiB
Markdown
# Orbit 开发约定
|
||
|
||
- Orbit 是通用平台。代码、文档和示例不得包含接入方项目名称或行业定制规则。
|
||
- 服务端分为公共能力、Pulse 与 Weave；SDK 是独立 Go module，不引用服务端模型或存储实现。
|
||
- 新增或修改数据模型必须提供中文注释，覆盖模型职责及每个持久化字段的含义。明确单位、可空语义、版本/幂等/租约/预算等约束，避免仅重复字段名。
|
||
- SQL 数据表和字段同步维护中文 COMMENT；已应用的迁移不得回改，后续演进新增前向迁移。
|
||
- 数据库禁止外键及级联删除。关联关系由服务端在同一事务中按命名空间校验；保留查询索引、唯一约束和 CHECK。历史外键由 000008 前向移除，后续迁移不得重新引入，真实 MySQL 回归必须断言外键为 0。
|
||
- Pulse 涉及用量的事务先锁应用额度再锁队列，恢复和调度遵守同一顺序；不得在已锁队列后新增应用额度锁。应用额度与身份行分离，不能升级认证共享锁。
|
||
- 优先级冻结为 0–9，每级30秒排序优势；dispatch_at 是数据库生成排序字段，不能替代 available_at 的实际就绪检查。节点按认证应用与队列轮转领取，内存轮转/空探测缓存不得授予执行权或改变持久化配额。
|
||
- 状态变更、租约、门控、许可、事件及审计必须按设计的事务边界实现，不用内存状态代替持久化确认。
|
||
- 研发任务持续更新 docs/08-development-plan.md。接口、SDK、可运行示例和对应回归随功能同步交付。
|
||
- 模型/迁移变更运行真实 MySQL 集成测试；执行和恢复变更覆盖竞争、重复、迟到及故障场景。以实际测试报告判断完成，不把设计文档当作已实现能力。
|
||
- 编译和基础回归入口是 make test、make vet、make build；隔离数据库端到端回归入口是 make integration。
|
||
|
||
- 结果日志的序号在独立命名空间流行锁下分配，与任务状态及原事件同事务提交；禁止用最大事件ID或时间戳推断提交水位。生产者不得锁订阅行。
|
||
- 创建订阅先锁队列再锁流行；消费按订阅→交付持锁，不能再取得任务、队列、额度或流行锁。ACK只验证最近代次及证明，过期未被替代的证明仍可确认；重复确认不能再次扣减pending_count。
|
||
- 可靠订阅已完成核心、HTTP/WSS、管理及消费SDK、独立业务Inbox示例、节点及消费者进程故障回归。批量受理已提供逐项幂等与未知结果分类。独立任务核查/人工重试已实现，任务查询已支持业务键、创建时间及直接来源（普通/人工重试/计划固定版本），业务事务Outbox独立示例已实现并通过全量链路回归；P3已完成原功能范围核对与全量阶段回归（docs/reports/phase-3.md），相对延迟及四种重试全停恢复一并验证；P4/P5功能范围另按阶段报告验收，A04已补精确故障证据；继续P6/P7的生产验证和实际文件转换示例等未完成项，不能把P3阶段验收当作全平台交付。
|
||
|
||
- 批量受理最多32项、512 KiB；每项复用单项身份与事务，未知结果必须原键核对。任务提交按认证→应用额度→提交幂等身份→队列持锁，禁止恢复为先抢提交唯一键后等待额度锁；原回执仍须先于配额上限检查返回。
|
||
|
||
- 独立任务核查必须显式声明所有历史执行已结束，并提交原因、证据和版本；NEEDS_REVIEW只转SUCCEEDED/FAILED。核查不改写旧尝试或迟到证据。人工重试仅无所有者且无未知效果的FAILED/CANCELLED任务，创建retry_of关联新任务，每个原任务最多一个直接后继；继续重试沿后继推进。
|
||
- tasks:review、tasks:retry、tasks:audit:read是显式管理权限，普通提交/Worker凭据不自动获得。核查结果流锁最后获取，审计/回执/额度与状态同事务；恢复不得绕过Weave/计划所有权、门控及现有额度限制。
|
||
|
||
- 任务列表队列必填，business_key精确匹配（包含尾部空格），created_from包含/created_before不包含。v2游标绑定所有筛选，不能因网络或游标错误删筛选降级；旧游标仅兼容旧查询。四种固定索引覆盖状态/业务键组合，禁止全量取回后内存过滤。业务键仅Go空字符串映射NULL。
|
||
|
||
- 任务来源通过独立只读路由查询，tasks:read仅授予当前任务的有限来源引用；计划定义仍需schedules:read。显式核对命名空间、队列、计划、触发与固定版本，悬空/错误/未实现所有者不得默认为DIRECT；不依赖外键，也不向派发路径加入来源查询。
|
||
|
||
- 业务事务Outbox示例使用独立module和业务数据库，核心SDK不得引入SQL驱动。业务记录/待发命令同事务；原请求、操作ID、目标及提交键冻结，HTTP在事务外，确认按最新租约代次与业务关联同事务。24小时/100次预算内原键核对，禁止换键、重置预算或把ACCEPTED解释成业务成功；REVIEW保留待核查数据。
|
||
|
||
- 相对延迟delay_ms只在首次受理事务按数据库时间计算；原时长参与摘要，零值omitempty保持旧摘要。重报先返回原回执，禁止重算执行时间；总时限包含等待。计划模板拒绝非零delay_ms，人工重试不自动继承首次等待。
|
||
|
||
- P4定义发布使用schema_version=1有限结构，词法作用域禁止跨分支/前向读取，任务策略显式冻结；SDK类型独立。发布按认证→应用额度→操作身份→定义→排序队列持锁；原键与同版本去重仍校验当前权限。定义/版本/revision/审计/回执同事务；同版本不同内容不得覆盖。保留精确数字，校验存储原文与结构摘要；不得把发布通过或DSL支持误称为实例执行已实现。
|
||
|
||
- P4定义子项已通过真实MySQL、HTTP丢回执、独立SDK和全量回归（docs/reports/phase-4-definitions.md）。实例启动/固定版本/首批任务同事务的内部存储已补齐；内部事件消费、顺序与组合推进及根接续已接入；TIMER与后续POLL时钟已接入，SIGNAL及最终查询竞争已接入，内部控制与停止结清已接入，等待恢复已接入，实例公共API/SDK已接入，流程任务来源已接入，已接入有界历史查询，实例分页已接入，已接入状态事件时间线，独立轮询/恢复示例已接入，W06/W09/W14/W15已补实际事务竞争和公共SDK全停回归；P4/P5平台功能阶段已按原范围验收，见docs/reports/phase-4-5.md；P6/P7及全平台交付仍未完成。
|
||
|
||
- 内部结果交付使用workflow_activation所有者并固定激活ID，TASK经activation.task_id、POLL经轮次校验归属；weave_inbox来源及独立快照与Pulse结果同事务，先于外部结果流行锁，不在结果路径反锁实例/步骤/订阅。迁移000017隔离缺快照历史，禁止用当前任务重建旧事件。
|
||
- weave/engine仅计算有限决策；实例受理、Inbox消费与根接续已接入，等待和停止结清运行器已接入，内部核查/TASK恢复已接入，等待恢复已接入内部服务，公共API/SDK已接入，流程任务来源已接入，有界历史已接入，实例分页已接入，已接入状态事件时间线，独立轮询/恢复示例已接入，W06/W09/W14/W15已补实际事务竞争和公共SDK全停回归。Plan最多32个变更，More必须持久化待续；耗尽变更预算仍须遍历其他已活动分支，不能误判在途工作不可达。冻结分支选择，精确数值，不以PENDING查询结果完成POLL。后续消费确认/当前激活校验/新任务或检查点必须同事务，不能把纯快照往返测试当作真实进程恢复。
|
||
|
||
- 实例内部受理已实现，信号内部运行器已接入，公共实例/信号HTTP及独立SDK已接入；结果消费和根待续扫描已接入后台。Start按认证→应用额度→原身份→排序队列建立门控/固定版本/全部步骤/首批工作，所有失败同事务回滚。首批推进递增revision至2，原键返回冻结回执且仍核验当前权限，不重算截止。
|
||
- 实例根步骤`$root`/JOIN不属于用户定义，Steps查询排除它；More对应根步骤版本化持久检查点。TASK直接关联激活task_id，POLL通过轮次关联，实际任务截止必须受实例/查询绝对截止限制。Wait名称及契约版本冻结，旧NULL等待须核实，不能盲目解释；新关联512字节、存储兼容历史764字节。
|
||
|
||
- 结果消费按身份→应用额度→排序队列→实例→门控→步骤/Inbox持锁，禁止先锁Inbox再锁父资源。来源使用独立冻结快照，旧激活/低版本留痕；数据库故障不归类为业务失败。消费确认、步骤、后继或根待续、事件及审计同事务。
|
||
- 后继满额用SAVEPOINT回滚整轮新工作，保留已接受结果和待续；恢复必须重读持久图。多次根推进使用独立系统审计操作身份；迟到证据也递增实例历史版本，禁止复用已有workflow.advanced唯一身份。
|
||
- 本轮消费运行器和真实Orbit强杀/双节点接管已验证，见docs/reports/phase-4-runtime.md。TIMER到期与POLL后续轮次已接入，见docs/13-workflow-clock.md；SIGNAL及最终信号竞争已接入（docs/14-workflow-signals.md）；内部FAIL_AFTER_SETTLED分支结清与控制已接入（docs/15-workflow-controls.md）；公共控制API和实例SDK已接入，流程任务来源已接入，实例列表已接入，状态事件时间线已接入，独立轮询/恢复示例已接入，W01/W13提交切点和W16最终信号竞争已补，P4/P5功能阶段核对见docs/reports/phase-4-5.md；生产数据库故障、容量和运维继续P6/P7。
|
||
|
||
- TIMER/POLL复用weave_pending_advances及到期索引，时钟固定激活ID；迁移000019只回填原等待/查询时钟，不改截止和预算。后续POLL只由已确认POLL_PENDING开启，首轮精确输入/资源键冻结，每轮Pulse尝试独立计数；满额/暂停不消耗轮数。截止遇到已落库结果先等待Inbox，仍在途则关闭门控但保留ACTIVE和当前任务，许可由Pulse结清；不得由时钟假定外部请求已结束。
|
||
|
||
- SIGNAL受理要求显式workflows:signal、固定目标步骤/激活代次/内容契约/精确关联及原因；每实例全部历史信号上限1024，原键先返回冻结回执。accepted_at/expires_at及摘要与不可变审计核验；available_at只用于到期检查退避。
|
||
- 最终信号与当前查询按原受理/事件时间裁决，PENDING不争夺终结权；保存信号赢家后复用Pulse取消规则，在途任务保留许可直至真实结果。未知/冲突结果转核查，已有核查不得自动清除。迁移000020隔离旧PENDING身份并保留历史原文，不引入外键。
|
||
|
||
- 流程控制使用显式workflows:control和独立control_revision；后台结果只改变通用revision。控制标记、门控、原操作回执、根接续、事件与审计同事务，原键恢复仍核对当前权限。RESUME不解除核查或停止意图。
|
||
- StopKind/StopRequestedAt冻结首次CANCEL或FAILURE目标，后来的用户取消不覆盖原失败目标。结清复用ROOT，每事务最多一个Pulse取消、32项步骤收尾；结果流锁取得后不能再锁另一任务。终态前校验全部历史任务的双向归属、未结束尝试和未释放许可，UNKNOWN不得终结。迁移000021恢复旧停止意图，不添加外键。
|
||
|
||
- 人工核查使用显式workflows:recover、当前实例revision、步骤/任务版本及激活身份，必须有原因和证据；执行结论、步骤结论、解除核查分别确认。新决定拒绝PENDING/QUARANTINED Inbox，原键回执仍核验权限。核查回执/额度/双审计/结果流同事务，结果流锁最后取得。
|
||
- TASK人工重试保留首次绝对截止和精确输入，以新激活/关联任务继续消耗原max_attempts；激活数也受该上限限制，不能无限制造零尝试任务。成功步骤、未知执行、原停止意图或预算耗尽均不得重试。Continue不解除paused、重置预算或撤销停止。POLL跨激活恢复已实现（docs/17-workflow-poll-recovery.md），等待恢复已接入内部服务，公共HTTP/SDK已接入，流程任务来源已接入，实例列表已接入，状态事件时间线已接入，独立轮询/恢复示例已接入，已完成P5功能范围核对，恢复与生产负载/运维边界见docs/reports/phase-4-5.md。
|
||
|
||
- POLL人工恢复以新激活重查同一业务轮，FirstRound/FirstRoundAttemptsUsed保留原轮次和已用尝试；实际尝试行、retry_of链和冻结参数必须相符。同轮任务数也受原max_attempts限制，PENDING不得人工重查绕过轮次上限。查询截止按首次激活、请求截止按该轮首任务，不允许重计时；下一业务轮才获得完整单轮策略。
|
||
- POLL恢复的最终信号等待保留原契约/关联/截止并更换代次，旧winner和已消费信号只留历史；存在当前代次PENDING信号时拒绝重建。迁移000022无外键，新增2个中文注释字段。公共HTTP/SDK已接入，有界历史查询已接入，实例列表已接入，状态事件时间线已接入，生产验收继续推进。
|
||
|
||
- 核查将UNKNOWN请求确认成成功PENDING时，当前RetryStep仍拒绝重查同轮；ContinuePoll显式恢复原等待，必须核验当前SUCCEEDED/PENDING任务、已处理Inbox及不可变来源。新审计固定来源事件/版本、原间隔与截止，时钟/最终信号核验证明后才推进；不改写旧Inbox处置，ReviewTask不自动解除核查。
|
||
|
||
- RearmWait仅重建独立SIGNAL/TIMER，显式wait_verified及最新步骤/激活/实例版本，连续激活上限32。旧WAITING激活/等待关闭，新代次保留首次输入、契约、关联及截止；PENDING信号、已有赢家、停止意图及过期均拒绝。TIMER运行和成功核查按首次激活计时，恢复后仍须Continue；无新持久化字段或外键。
|
||
|
||
- 公共流程API包括实例启动/读取、最多128项步骤元数据、单步当前输入输出/预算/等待、控制、信号、六类恢复和流程资源操作审计。当前激活代次同时进入Steps、详情和新恢复回执；旧冻结回执缺字段时只能另读当前详情，不改写历史回执。Pulse流程来源已交付；历史激活/轮次/等待/信号及信号审计已接入；实例列表已接入，状态事件时间线已接入，独立轮询/恢复示例已接入，原功能范围及提交故障已核对，P6/P7生产验收继续推进。
|
||
- 恢复请求的匿名嵌入结构按扁平精确JSON字段解析，继承字段也拒绝别名/重复/未知字段，保留显式null例外与必填确认。bootstrap先验证权限集合；工作流执行/控制/信号/恢复/审计分别显式授予，旧workflow-access仅定义发布。
|
||
|
||
- 任务来源WORKFLOW只返回已授权任务的固定流程/版本/步骤/历史激活及POLL轮次；tasks:read不授予完整流程和其他队列权限。核对正反向关联、固定定义及门控，恢复父任务须为前一激活且POLL同轮。TASK恢复的retry_of位于workflow对象内，后续POLL新轮无父任务。不能改指当前激活、递归展开历史或将来源查询加入派发路径；无外键。
|
||
|
||
- 历史读取按固定实例及所有队列授权，明确步骤/激活/信号归属，不依赖外键；摘要分页20/100，游标绑定种类和父资源。指定激活详情的Step是当前视图、Activation是历史视图，不自动改代次；POLL轮次限定单个激活，恢复同轮任务不可与下一业务轮混淆。信号列表保留未核验旧身份，正文单条读取；信号审计用显式workflows:audit:read，不能按全局审计ID越权。000023只增加分页索引；全量回归必须保留零外键与旧数据/索引断言。
|
||
|
||
- 实例列表按固定定义全部队列在SQL中筛选，再校验原定义/摘要、范围、策略及关联；不能用已执行任务推断权限。000024增加不可变范围索引与7个列表索引，无外键；发布与范围同事务，旧DSL常量中的queue_id不纳入范围。游标绑定命名空间/全部筛选/规范化队列权限，跨页不承诺快照，limit只限制返回候选量。先排序锁整页队列，不在实例锁之后追加队列锁。
|
||
|
||
- 状态时间线只读取已存workflow/workflow_step/workflow_signal事件，排除$root；两条路由均显式workflows:audit:read并核对固定版本全部队列及实际子资源。000025派生只读索引不授予权限、不改历史原文、不补造旧信号转换，无外键；新信号状态和事件同事务，批量拒绝32条一批且失败整笔回滚。时间/ID排序与资源revision均不是提交水位；Pulse可靠消费仍走持久订阅。旧写节点停止后迁移，不能承诺混合版本无历史缺口。
|
||
|
||
- 独立workflow-poll示例验证2轮3次请求与2轮耗尽核查；workflow-recovery实际提交后断线，只提交一次，按证据依次ReviewTask/ResolveStep/Continue，再显式RESUME，旧UNKNOWN和原截止保持。受控内存渠道不是持久生产证据。W06实际版本后继、W09三方竞争、W14暂停竞争和W15暂停全停已补，见docs/reports/phase-4-5-races.md；P4/P5功能阶段验收见docs/reports/phase-4-5.md，P6/P7生产及交付门槛继续保留。
|
||
|
||
- 竞争回归通过performance_schema确认参与者实际进入数据库锁等待，禁止将请求已发出或sleep当作并发证据。W09以原数据库截止自然到达放行；PAUSE以后不得新建任务/尝试或授权，已授权结果仍需收集。公共SDK暂停全停场景须在全部旧节点Wait确认退出后才启动新节点；保留原回执、等待身份、版本、查询轮次与截止。普通SIGNAL竞争不能替代最终查询/回执/下一轮的独立故障边界；COMMIT不明和A04已补独立故障工具及真实回归；生产HA与容量等继续按P6/P7验收。
|
||
|
||
- 版本/暂停竞争本批已通过21个真实存储子场景、公共SDK两旧节点全停及两新节点恢复、23个SDK示例/2个业务模块的标准全量回归。证据见docs/reports/phase-4-5-races.md；A04/W01/W13/W16精确故障也已补，见docs/reports/phase-6-fault-boundaries.md；进程观测基础已实现，下一批按docs/08-development-plan.md继续持久积压/阶段延迟与发送队列，再做凭据轮换，不重复将上述已验证场景列为未做。全平台目标继续保持，不能以本批通过替代观测、凭据轮换、归档/备份、生产拓扑和发布交付。
|
||
|
||
- A04须截留真实task.assign并独立确认LEASED/未授权，再强杀旧节点、Wait确认退出、新节点等原租约自然到期；不能把已送达未开始替代未送达。COMMIT故障工具只在测试二进制：BEFORE阻止COMMIT，AFTER核验真实MySQL成功包后丢确认；独立连接回读，原身份/候选恢复，禁止在生产增加故障开关或将HTTP丢回执替代数据库提交不明。
|
||
- W16下一轮时钟只能在PENDING结果已保存等待后存在，三方竞争中的结果参与者是旧结果重放；新结果/未知/冲突另有在途查询回归。保持原受理时间、事件时间、截止与预算，不能凭有限入队顺序声称穷尽线程交错。
|
||
|
||
- P6进程观测使用internal/observability固定指标目录，拒绝未知名称、类型和动态标签，不能引入任务/租户/业务键/凭据维度。ORBIT_METRICS_ADDR默认空（关闭），显式启用独立采集监听；业务端口不得暴露全局指标。渲染和网络I/O不持有全局记录锁，每个直方图局部快照保持桶/count/sum一致，最多2个并发抓取。启用指标后的5秒后台采样使用000026–000028固定索引读取任务、交付、流程状态、固定事件类别和终态耗时，每个状态或事件最多10000条、事件窗口5分钟、900ms数据库截止；采样失败保留最后成功状态并独立记录错误/超时，不能影响业务事务或把有限样本当全局精确数。
|
||
- HTTP成功升级在Hijack完成时记录握手，WS处理器存续计入独立连接指标；保持1xx临时响应、Flush、Hijack与原panic行为。DB池取本地Stats，抓取不查询业务库；后台批次success不是业务任务成功量。观测丢样或失败不得改变权威事务及恢复决定。
|
||
- 进程指标、固定状态采样、格式验证、告警规则和标准回归证据见docs/reports/phase-6-observability.md及docs/reports/phase-6-business-observability.md。仍须补受理/授权/完成与流程推进延迟、持久吞吐/积压的全局聚合、重试/核查/恢复量、发送队列、实际采集告警及负载开销，不能把进程观测通过写成P6已完成。普通清理仍须保护有效幂等、未确认事件、未知结果和未终结流程。
|
||
- 凭据轮换保留credential_id及订阅/Worker授权绑定，在同一事务替换摘要、固定到期时间、幂等回执和管理审计；新令牌必须重新建立会话，认证路径每次重新核对凭据状态。撤销必须让认证失效并保留原任务、订阅、交付、会话和审计证据，允许在应用或命名空间停用后执行；重复应用同一固定操作幂等返回。管理CLI先把固定操作文件写成0600，再提交；提交不明时保留文件并用原文件重放，不能重新生成秘密。日志、审计摘要、指标和业务表不得保存秘密原文或摘要。不要把轮换同一凭据ID解释成历史令牌仍有效，也不得级联删除订阅、任务或事件。
|