feat: persist workflow admission and initial execution graph
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# Weave 流程编排功能与设计
|
||||
|
||||
> 版本 0.3 · 2026-09-18。首版功能范围已确认。定义结构、发布校验与不可变版本已实现，见[定义格式](api/workflow-definition-format.md)和[发布API](api/workflow-definitions.md)；已补[步骤决策与内部结果交付](10-workflow-engine-core.md)，下述实例存储推进、等待、查询与管理仍待P4–P5实现验收。
|
||||
> 版本 0.3 · 2026-09-18。首版功能范围已确认。定义结构、发布校验与不可变版本已实现，见[定义格式](api/workflow-definition-format.md)和[发布API](api/workflow-definitions.md)；已补[步骤决策与内部结果交付](10-workflow-engine-core.md)，[实例受理与元数据查询存储](11-workflow-admission.md)已实现；事件消费、等待运行器、公共API/SDK与管理仍待P4–P5实现验收。
|
||||
|
||||
## 1. 职责与边界
|
||||
|
||||
|
||||
@@ -191,3 +191,8 @@ delay_ms是普通/批量提交命令字段，首次事务以同一个数据库
|
||||
## P4 内部结果快照
|
||||
|
||||
000017_workflow_result_inbox为InboxEvent增加SourceTaskID、SourceActivationID、SourceRevision、Snapshot四个直接字段；当前35个实体、293个直接声明持久化字段，均有中文注释，无外键或级联。有效待处理记录要求来源齐全；历史缺少快照的未处理记录隔离为QUARANTINED，保留旧代次而不重建结果。内部快照独立于对外结果日志保留期，和Pulse权威结果同事务提交。见[执行决策及交付边界](10-workflow-engine-core.md)与[回归进展](reports/phase-4-engine-core.md)。
|
||||
|
||||
|
||||
## 实例受理与等待身份（000018）
|
||||
|
||||
Wait新增SignalName和PayloadVersion两个中文注释字段；correlation_key转为VARBINARY(764)，新受理仍限制512字节，兼容历史191个四字节字符而不截断。实例business_key使用utf8mb4_0900_bin保留精确尾部空格；仍无外键和级联。35个实体，含公共Record的295个直接持久化字段声明均有中文注释。内部`$root`步骤作为实例级待续检查点，不属于定义静态节点或公共步骤列表。具体初始事务、预算和未接通的运行边界见[实例受理](11-workflow-admission.md)。
|
||||
|
||||
@@ -28,7 +28,7 @@
|
||||
| P1 任务受理闭环 | 应用凭据与作用域权限、队列、幂等提交、查询、待执行取消、受理事件；SDK 客户端 | API/SDK 创建查询闭环；重复键与内容冲突、响应未确认重报、跨命名空间拒绝、参数边界 | 已完成并通过阶段回归（见 P1 报告；真实断路/提交 ACK 丢失注入留后续故障阶段） |
|
||||
| P2 Worker 执行闭环 | WSS 接入、能力/容量、领取与开始、租约、续租、结果确认、排空与恢复；Worker SDK | 真 Worker 执行；失联/重连/重复确认/旧尝试拒绝；业务效果未知转核查；节点故障接管 | 已完成并通过阶段回归：服务端、自动 SDK、历史查询、完整 Schema 与真实进程强杀恢复；测试拓扑和剩余生产故障矩阵见 P2 验收报告 |
|
||||
| P3 Pulse 完整能力 | 安全重试、延时、Cron/固定间隔、漏跑策略、计划版本、运行中取消、并发许可、配额/背压、可靠结果订阅、批量受理、独立任务核查/人工重试、查询筛选与事务Outbox接入 | 多实例领取/触发竞争、重试上限、取消竞争、队列隔离、积压恢复、事件重复交付 | 已完成平台功能阶段验收：[原范围逐项核对](reports/phase-3.md)、[本轮完整回归](reports/phase-3-delay-recovery.md)。补齐相对延迟、改参数关联示例和四种重试全停恢复场景；20个可运行示例全部通过。全平台生产门槛及SDK首版交付剩余项仍按P6–P7推进 |
|
||||
| P4 Weave 主流程 | SDK 定义构建与发布校验、实例、顺序/分支/结构化并行汇合、信号/定时等待、版本绑定 | 重启接续、早到/重复信号、并行竞争、内部事件重放、发布版本兼容；端到端通用流程 | 定义格式/词法类型校验、不可变发布、独立SDK及六类节点定义例子已实现，已通过[子项验收](reports/phase-4-definitions.md)；已补[有限决策器及内部结果交付](reports/phase-4-engine-core.md)；实例存储适配、事件消费推进与持久化等待仍待实现 |
|
||||
| P4 Weave 主流程 | SDK 定义构建与发布校验、实例、顺序/分支/结构化并行汇合、信号/定时等待、版本绑定 | 重启接续、早到/重复信号、并行竞争、内部事件重放、发布版本兼容；端到端通用流程 | 定义格式/词法类型校验、不可变发布、独立SDK及六类节点定义例子已实现，已通过[子项验收](reports/phase-4-definitions.md)；已补[有限决策器及内部结果交付](reports/phase-4-engine-core.md)；[实例受理及首批事务](reports/phase-4-admission.md)已实现；事件消费推进、持久化等待运行器和实例公共API/SDK仍待实现 |
|
||||
| P5 Weave 恢复与查询 | 有界查询、暂停继续、取消、人工核查恢复、控制门控与审计 | 轮次与尝试独立预算；暂停/开始/回执/超时竞争；恢复保留预算；未知结果不盲目重复 | 待开发 |
|
||||
| P6 生产验证与运维 | 完整监控、凭据轮换、备份恢复、滚动升级、运行手册、可复现负载和故障工具 | 对照生产验收清单执行，报告环境/指标/遗留项；容量、RPO/RTO 按真实拓扑验证 | 待开发 |
|
||||
| P7 首版交付核对 | SDK 兼容与发布准备、完整 API 手册、场景示例、全量回归及交付清单 | 新接入者按文档跑通全部示例；所有首版能力可追溯到实现与测试；报告实际生产边界 | 待开发 |
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Weave 执行决策与内部结果交付
|
||||
|
||||
状态：P4 内部基础已实现。已接通Pulse结果到Weave持久化Inbox，并提供有限步骤决策器；**实例启动、实例存储适配、Inbox消费推进、定时/信号运行器及对应公共SDK尚未实现**。不能把本页能力解释成流程已经可以端到端执行。
|
||||
状态：P4 内部基础已实现。已接通Pulse结果到Weave持久化Inbox，并提供有限步骤决策器；[实例受理和首批存储适配](11-workflow-admission.md)已补齐。**Inbox消费推进、定时/信号运行器及实例公共API/SDK尚未实现**。不能把本页能力解释成流程已经可以端到端执行。
|
||||
|
||||
## 1. 为什么结果要独立持久化
|
||||
|
||||
@@ -74,7 +74,7 @@ v16及以前的未处理记录缺少冻结来源，升级后统一标为QUARANTI
|
||||
|
||||
## 4. 后续存储适配必须满足的条件
|
||||
|
||||
此处是尚待实现的要求，不能按纯单测宣称已完成：
|
||||
以下是存储运行器的完整要求；第1项初始事务已实现并按[受理报告](reports/phase-4-admission.md)验证，其余消费/运行要求尚未完成，不能按纯单测宣称已完成：
|
||||
|
||||
1. 启动时认证、固定不可变版本/输入和策略、校验全部队列、计算实例截止，并在同事务创建实例、门控、首批激活/任务及审计回执。相同身份返回原实例。
|
||||
2. 消费者领取内部事件后核对命名空间、来源任务版本、激活/轮次及当前步骤版本；消费确认、步骤变化、后续任务或持久化待续记录同事务提交。
|
||||
@@ -82,6 +82,6 @@ v16及以前的未处理记录缺少冻结来源，升级后统一标为QUARANTI
|
||||
4. AllowNew来自权威实例状态、控制版本、取消、总截止和门控。程序参数本身不是权限证明。任务deadline不得超过实例或查询节点绝对截止。
|
||||
5. 数据库时间驱动真实等待与超时，按可靠受理时间裁决信号/结果，原截止和预算在恢复时保持。单轮重试与查询轮次不能互相补充次数。
|
||||
6. 完成实例前核对所有活动工作结清和未知效果；失败/取消需要停止新派发并收集在途结果。人工恢复通过新激活保留历史。
|
||||
7. 增加流程来源查询、实例/步骤/信号/操作HTTP和独立SDK、可运行端到端场景、真实节点强杀和竞争回归。以上均属于P4–P5剩余工作。
|
||||
7. 增加流程来源查询、实例/步骤/信号/操作HTTP和独立SDK、可运行端到端场景、真实节点强杀和竞争回归。其中未完成项继续属于P4–P5剩余工作。
|
||||
|
||||
当前测试夹具通过SQL构造流程关联，只验证结果事务边界；它不代表公共实例API或运行器已经存在。纯决策器的JSON往返测试验证可从快照重算，也不等同于真实进程恢复验收。
|
||||
本页的结果交付专用测试夹具通过SQL构造流程关联，只验证结果事务边界；后续[受理测试](reports/phase-4-admission.md)已使用真实内部Start创建实例，两者均不代表公共实例API或完整运行器已经存在。纯决策器的JSON往返测试验证可从快照重算，也不等同于真实进程恢复验收。
|
||||
|
||||
62
docs/11-workflow-admission.md
Normal file
62
docs/11-workflow-admission.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# Weave 实例受理与首批工作
|
||||
|
||||
状态：内部Go服务与MySQL存储适配已实现实例Start/Get/Steps、固定版本、首批决策落库和可靠结果交付。**尚未开放实例HTTP路由、启动SDK或命令行入口；后台Inbox消费、待续扫描和等待运行器尚未接通。** Weave相关公开SDK目前仅支持定义发布。不能将首批任务可执行解释成整个流程已能自动完成。
|
||||
|
||||
## 1. 受理事务
|
||||
|
||||
内部入口为`weave/instance.Service`，存储由`WorkflowInstanceStore`实现。一个Start事务按以下顺序执行：
|
||||
|
||||
1. 验证凭据和`workflows:start`；取得应用额度排他锁，保留现有认证共享锁。
|
||||
2. 以命名空间、`workflow.start`、幂等键冻结完整请求；同键不同定义、版本、输入或业务键冲突。
|
||||
3. 读取并验证指定定义和不可变版本的原文摘要。所有被引用队列按ID排序，核对当前范围并直接取得排他锁；有业务任务时还需要`tasks:submit`。
|
||||
4. 原回执在用量限制检查前返回。当前权限和固定版本归属仍需有效，重报不重算截止、输入、版本或首批工作。
|
||||
5. 校验实例输入和未终结实例上限，解析最多32个初始变更；以数据库时间固定总截止。
|
||||
6. 同事务创建门控、实例、全部静态步骤、内部根步骤，以及初始激活、任务/等待/轮次或待续记录，写入事件、审计及受理回执。
|
||||
|
||||
任何后续写入或额度预占失败都回滚整个图，包括首批中已经创建的任务。队列满额可用原身份重试；同一应用的多个队列共享原Pulse额度。队列暂停允许受理，由既有Worker门控阻止领取/开始。
|
||||
|
||||
流程推进不延长总截止。普通任务的实际deadline为自身任务时限与实例绝对截止的较早者；POLL任务还受查询节点绝对截止限制。冻结的单次尝试和重试策略不因剩余时限变短而重写，由Pulse在实际截止处终止授权。
|
||||
|
||||
## 2. 首批节点如何持久化
|
||||
|
||||
| 节点 | 受理时保存的内容 |
|
||||
| --- | --- |
|
||||
| TASK | 当前激活、精确输入、所属Pulse任务、流程门控及`workflow_activation`所有者 |
|
||||
| BRANCH | 首次选择的case索引；未选中节点分批SKIPPED，不创建业务激活 |
|
||||
| PARALLEL | 父激活、独立分支初始工作；完成汇合仍需要后续消费推进 |
|
||||
| SIGNAL | WAITING激活、信号名称/内容版本/精确业务关联、固定截止；不分配Worker |
|
||||
| TIMER | WAITING激活和数据库时间计算的等待截止；不生成业务任务 |
|
||||
| POLL | 固定输入、查询状态、首轮记录和唯一当前任务；used_rounds=1；可选最终信号等待与查询截止一致 |
|
||||
|
||||
所有关系由事务按namespace核验，不使用外键。TASK激活的task_id直接指向任务；POLL激活不占用该字段，查询任务通过轮次归属。真实Worker完成首批任务时，上一阶段的原子结果交付会写入该实例的Inbox。
|
||||
|
||||
空流程可在受理事务内完成并保存输出，完成门控关闭；纯等待流程进入WAITING。包含活动TASK/POLL或尚有待续变更的流程保持RUNNING。第一次持久化决策将实例版本从内部创建时的1推进到2，Start回执通常为revision="2"；调用者不得假设起始版本或自行递增版本。
|
||||
|
||||
## 3. 有限推进和查询
|
||||
|
||||
定义仍最多128个静态节点，每次Plan最多32个变更。存储额外建立不可由研发定义的`$root`/JOIN步骤，保存实例级根状态及当前激活。预算耗尽时，以根步骤ID、当前步骤版本和schema_version=1检查点写入`weave_pending_advances`，不能只依赖内存唤醒。
|
||||
|
||||
根步骤是内部记录，不出现在Steps查询中。Steps最多返回128项元数据及同一读取边界的实例revision，包含节点、状态、当前激活和直接任务引用；不把全部步骤输入/输出拼成大响应。读取核验固定定义和当前激活归属，缺失或错误关联不会降级为有效结果。
|
||||
|
||||
Get返回当前实例视图；Start重报返回受理时冻结的原始视图，两者语义不同。查询需要`workflows:read`以及固定版本涉及的全部队列范围。定义发布权限不会自动授予实例执行或读取权限；当前bootstrap的`--workflow-access`仍仅授予定义权限。
|
||||
|
||||
## 4. 运行边界和模型演进
|
||||
|
||||
| 项目 | 当前边界 |
|
||||
| --- | --- |
|
||||
| 请求输入 | 最多256 KiB；按固定定义严格类型校验，精确数字、显式null与缺失分别处理 |
|
||||
| 业务键 | 最多191个Unicode字符，精确保留尾部空格；不提供执行幂等 |
|
||||
| 活跃实例 | 每个namespace最多10000个RUNNING/WAITING/CANCELLING/NEEDS_REVIEW实例；终态不计入；满额仍可恢复原受理回执 |
|
||||
| 信号关联 | 新受理最多512字节；数据库兼容旧191字符最长764字节，升级不截断历史 |
|
||||
| 截止 | 数据库时间生成；任务、查询与等待均不超过实例总截止 |
|
||||
| 自动运行 | 本阶段尚未实现Inbox消费、待续扫描、信号消费、定时到期处理或后续轮询 |
|
||||
|
||||
迁移000018为Wait增加signal_name和payload_version两个带中文注释的可空字段；NULL仅表示TIMER或尚未核实的历史元数据，未来消费者不得把历史NULL自动解释为有效的新信号等待。correlation_key转为精确字节存储；实例business_key改为utf8mb4_0900_bin。35个实体、含公共Record的295个直接持久化字段声明，全部有中文注释，继续保持零外键。
|
||||
|
||||
## 5. 下一步接入
|
||||
|
||||
1. 锁定实例、核验来源快照/当前激活，消费确认与后续步骤/任务/待续记录同事务；处理重复、迟到、旧轮次和未知结果。
|
||||
2. 实现有界待续扫描与数据库时间驱动的等待，恢复时保留原截止和次数；开始扫描前补齐暂停/截止/凭据所属应用停用的判定。
|
||||
3. 接通实例公共HTTP、独立SDK、来源查询和可运行端到端场景，同时实施真实节点退出与接管回归。
|
||||
|
||||
本阶段验证见[实例受理回归记录](reports/phase-4-admission.md)。纯受理测试不是流程运行验收，P4–P7仍按[完整计划](08-development-plan.md)推进。
|
||||
59
docs/reports/phase-4-admission.md
Normal file
59
docs/reports/phase-4-admission.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# P4 进展：实例受理与首批事务
|
||||
|
||||
日期：2026-09-18。本阶段实现实例内部服务/存储Start/Get/Steps，以及初始最多32个变更的原子落库。未开放实例HTTP/SDK；Inbox消费与等待运行器仍未实现，不能按首批任务执行证明整个流程闭环。
|
||||
|
||||
## 实现
|
||||
|
||||
- 显式版本、输入契约、当前队列权限、独立启动/读取权限、命名空间未终结实例上限。
|
||||
- 原身份回执恢复；固定版本/门控/全部静态步骤/首批任务或等待/轮次/检查点/事件/审计同事务。
|
||||
- 六类节点持久化，任务和POLL截止受父绝对截止限制；内部根步骤支持有限推进检查点。
|
||||
- 元数据步骤查询核验固定定义与当前激活，实例查询核验输入及冻结策略。
|
||||
- 新迁移000018保留旧等待的完整UTF8关联和尾部空格，补齐信号名称及契约版本；无外键，字段提供中文注释。
|
||||
|
||||
## 验证状态
|
||||
|
||||
环境为macOS arm64、Go 1.27.1、隔离Docker MySQL 8.4.10；所有数据库为一次性测试库。
|
||||
|
||||
| 用例 | 当前证据 |
|
||||
| --- | --- |
|
||||
| 并发受理 | 12个同键Start只创建一份实例及任务；精确数字、固定版本、原截止和同键冲突验证通过 |
|
||||
| 真实首批Worker | 服务真实创建任务，Worker开始并完成后恰好一条内部结果；普通任务取消接口不能绕过流程所有权 |
|
||||
| 六类节点 | TASK/BRANCH/PARALLEL/SIGNAL/TIMER/POLL初始记录、未选中路径、等待不占Worker、512字节关联、128字符名称、轮次和父截止通过 |
|
||||
| 事务故障与背压 | 队列只能容纳2个但首批需要3个时全部回滚，原键扩容后成功；步骤、等待、任务和审计注入失败均无半套图或额度泄漏 |
|
||||
| 权限及读取 | 范围撤销后原键和查询拒绝，跨namespace不可见；损坏当前激活和冻结策略的查询拒绝通过 |
|
||||
| 有限检查点和升级 | 114个静态步骤的32变更首批边界、根检查点及v17等待完整升级通过；相关存储/升级/零外键定向回归连续3轮通过，共59.628秒 |
|
||||
| 完整检查 | make fmt/test/vet/build通过；完整隔离脚本退出0，存储、SDK、21个示例及进程故障通过；临时容器已清理 |
|
||||
| 查询关联补强 | 完整脚本运行期间补充Steps直接任务的所有者、门控及固定队列核对，新增损坏owner/queue用例；最新实例受理组race连续3轮通过，共12.673秒，随后完整make检查再次通过 |
|
||||
|
||||
完整脚本测试组耗时如下（秒）；最后的只读实例查询补强以上方专门回归为验证证据，未重新运行无关SDK/进程组：
|
||||
|
||||
| 测试组 | 耗时 |
|
||||
| --- | ---: |
|
||||
| MySQL存储全量 | 119.723 |
|
||||
| Worker连接及运行SDK | 91.108 |
|
||||
| 计划 / 队列资源SDK | 5.651 / 4.479 |
|
||||
| 批量受理 / 任务查询SDK | 1.378 / 1.412 |
|
||||
| 订阅管理 / 事件SDK | 33.434 / 52.879 |
|
||||
| 人工恢复 / 定义发布SDK | 3.406 / 1.356 |
|
||||
| 独立Inbox / Outbox | 35.611 / 34.673 |
|
||||
| 应用额度SDK | 1.521 |
|
||||
| SDK进程故障 | 93.931 |
|
||||
|
||||
共运行19个SDK例子和独立Inbox/Outbox的2个示例，10个SDK进程故障父用例及两个独立模块的进程故障用例通过。它们验证既有Pulse/定义发布链路，不能充当Weave后续自动运行的证据。
|
||||
|
||||
复现入口：
|
||||
|
||||
```sh
|
||||
make fmt test vet build
|
||||
make integration
|
||||
```
|
||||
|
||||
本次通过GO参数选择Go 1.27.1、DOCKER参数选择本机Docker。脚本自行建库并清理，普通测试在数据库环境变量缺失时会跳过集成用例，不能代替实际integration结果。
|
||||
|
||||
首轮数据库回归发现实例字段均未变化时MySQL返回affected_rows=0，不能据此判断实例丢失。已改为每次持久化决策递增实例revision并校验旧版本，首批回执为revision="2"。同时修正测试定义的POLL任务/节点/最终信号时限不一致；生产发布校验保持严格。
|
||||
|
||||
直接查询完整回归临时数据库：外键数量为0，业务表字段空COMMENT数量为0。代码扫描核对含公共Record共295个持久化字段声明，中文注释无遗漏；808个本地文档链接、53个JSON块及git diff --check通过。
|
||||
|
||||
## 尚待完成
|
||||
|
||||
当前测试中的实例由真实内部受理服务创建，首批任务走真实Pulse执行与内部交付；Get不会隐式消费Inbox。尚无流程后继自动推进、定时/信号/轮询恢复或流程进程强杀验收。公共API、SDK启动例子和完整运行器在后续阶段接入。生产容量、跨节点拓扑、清理和运维继续属于P6–P7。
|
||||
Reference in New Issue
Block a user