Appearance
jeeflow 引擎规范（Spec）
本规范是 jeeflow 工作流引擎的唯一事实来源。所有语言实现（八语言引擎：Java / Go / Python / Node.js / PHP / Rust / MoonBit / C#）必须对齐本文档定义的语义。规范只陈述"必须怎么做"——设计动机与决策论证见 设计原理（Concepts） 系列。 ⚠ 例外口径：事务与事件这两章允许各语言用自己的机制（语言特性不同），规范只钉可判定的行为， 见 12 · 事务契约 §12.1 与各栈机制映射表。
术语
| 术语 | 说明 |
|---|---|
| 流程定义 (Process Define) | 流程模板，包含节点和边的 LogicFlow JSON |
| 流程实例 (Process Instance) | 一次流程执行，绑定一个操作人 |
| 流程任务 (Process Task) | 实例中的审批节点，绑定参与者 |
| 参与者 (Actor) | 任务的审批人，存储在 wf_process_task_actor |
规范分卷
| 分卷 | 内容 | 设计原理对应 |
|---|---|---|
| 01 · 数据模型 | 5 张核心表 + 3 张扩展表结构 | 架构总览 |
| 02 · 流程定义格式 | 顶层结构 / 节点 properties / 参与者解析 / 决策表达式 / 完整示例 | 执行引擎 |
| 03 · 状态机 | 流程实例状态 / 任务状态转换 | 领域模型 |
| 04 · 引擎核心操作 | 启动 / 完成 / 系统代执行 / 驳回 / 跳转 / 会签 / 流程变量约定 / 聚合根方法清单 | 执行引擎 · 领域模型 |
| 05 · SPI 接口 | IProcessRepository 全签名 / 可选 SPI / 事务约定 / 扩展仓储 / SurrogateInterceptor | SPI 设计 · 管理扩展与门面 |
| 06 · 统一门面 | flow(action, map) 契约 / 40+ 个 action 清单 / deploy / execute 分发 / 用户搜索钩子 | 管理扩展与门面 · 契约约定 |
| 07 · 元数据能力 | 枚举字典（7 个 key）/ SPI 实现清单（HandlerRegistry） | 引擎元数据 |
| 08 · 合规测试 | 22 条跨语言合规场景（合并 v1.0~v1.4.0 全部） | — |
| 09 · 业务数据通用入库 | 引擎无关 DynamicTableWriter + 入库拦截器 PersistPostInterceptor（persist） | 扩展机制 |
| 10 · 元数据驱动的动态写入/读取 | FieldMeta / TableMeta / StorageType + MetaTableReader（persist-meta） | 引擎元数据 |
| 11 · 事件契约 | 事件码表 1..9（10+ 预留）/ 触发时机（落库后 fire）/ 载荷键 / 订阅形状与异常隔离 / 不发清单 / 码值迁移 | 扩展机制 |
| 12 · 事务契约 | 原子面（哪些动作必须原子）/ 覆盖面（含扩展仓储与 persist 腿）/ 归属面（调用作用域，禁进程级句柄槽）/ 副作用面（监听器隔离·拦截器连坐）/ 三档行为判据（原子·归属·空转 + 阳性对照） | SPI 设计 |
各语言实现位置速查
| 层 | Java | Go | Python | Node.js | PHP | Rust | MoonBit | C# |
|---|---|---|---|---|---|---|---|---|
| 引擎核心 | jeeflow-core | engine/ | jeeflow/engine.py | src/engine.ts | packages/core/src | jeeflow-core/src/ | core/ | src/Mldong.Jeeflow.Core/ |
| 聚合根 | domain/ProcessInstance.java | model/ | jeeflow/model.py | src/model.ts | packages/core/src/Domain/ProcessInstance.php | jeeflow-core/src/model.rs | core/model/aggregate.mbt | src/Mldong.Jeeflow.Core/ProcessInstance.cs + ProcessTask.cs |
| 仓储 SPI | spi/IProcessRepository.java | spi/spi.go | jeeflow/spi.py | src/spi.ts | packages/core/src/Spi/ProcessRepositoryInterface.php | jeeflow-core/src/spi.rs | core/spi/repository.mbt | src/Mldong.Jeeflow.Core/Spi/IProcessRepository.cs |
| JDBC 参考实现 | jeeflow-repository-jdbc | repository/jdbc/ | jeeflow/repository/base.py | src/jdbc/shared.ts | packages/repository-pdo | jeeflow-repository-sqlx/src/lib.rs | repository-mysql/ | src/Mldong.Jeeflow.Repository.MySql/Repo/MySqlRepository.cs |
| 门面 | facade/JeeflowFacade.java | facade/facade.go | jeeflow/facade.py | src/facade.ts | packages/web-contract/src/JeeflowFacade.php | jeeflow-facade/src/lib.rs | facade/facade.mbt | src/Mldong.Jeeflow.Facade/JeeflowFacade.cs |
| 元数据 | metadata/ + enums/IDictEnum | metadata/ | jeeflow/metadata.py | src/metadata.ts + src/registry.ts | packages/core/src/Metadata/ | jeeflow-core/src/metadata.rs | core/metadata/metadata.mbt | src/Mldong.Jeeflow.Core/Metadata/Metadata.cs |