本说明书解释“当前代码真正做什么、调用者应如何集成、失败时会留下什么事实”。Workflow 适合审批、会签、条件路由、超时升级和业务状态协同；它不是通用长事务编排器，也不能在缺少业务幂等与恢复设计时替代 Saga。
1. 先判断是否该用 Workflow
| 业务问题 | 建议 |
|---|---|
| 需要人工审批、驳回、转办、会签和轨迹 | 使用 Workflow |
| 需要租户/Office 选择不同审批版本 | 使用部署绑定 |
| 只需单表状态机且无待办/历史 | 优先领域聚合状态机 |
| 需要跨服务补偿与精确一次消息 | 先设计 Saga/Outbox，Workflow 仅承担人工节点 |
| 需要完整 BPMN 2.0 XML 互操作 | 当前引擎不适用 |
2. 阅读地图
| 目标 | 章节 |
|---|---|
| 搞清 Framework、Platform、Host 与 Adapter | 架构与核心概念 |
| 写可执行的节点、边、条件与参与人 | 定义工作流 |
| 使用服务端 Schema、AOT 元数据、修订草稿和路径模拟 | 可视化设计器 |
| 发布版本并理解“灰度”的真实语义 | 部署与版本 |
| 发起、审批、驳回、撤回和控制实例 | 运行实例 |
| 待办、已办、候选人、已读和缓存 | 任务管理 |
| 轨迹、归档、报表和不精确项 | 历史与分析 |
| 旧系统在途导入与指定节点发起 | 迁移与导入 |
| 通知接收人、模板、偏好与失败 | 通知 Pipeline |
| HTTP 路由与错误映射 | API 参考 |
| 在其他产品中嵌入引擎 | 独立嵌入 |
3. 一条实例的真实生命周期
图中状态来自引擎枚举 ProcessInstanceStatus：Running / Completed / Cancelled / Terminated / Suspended——没有 Withdrawn 或 Approved 这样面向业务的枚举值。引擎采用双字段模型：Status 承载上面的机器状态机；撤回映射为 Cancelled，同时 BusinessStatus（字符串）记录业务语义 Draft / InProcess / Active 等；FlowState 用节点前缀加尾字编码完整轨迹（如 ABW 表示 B 节点待审）。业务代码判断”审批是否通过”应看 BusinessStatus == "Active"，而不是枚举值。
每次发起把 DefinitionId、DefinitionVersion、TenantId、OfficeId、StarterId 和 BusinessKey 固化到实例。TokenExecutor 执行节点行为；UserTask 创建待办并挂起 Execution；完成任务后恢复 Execution、选择连线、更新 FlowState/BusinessStatus 并追加活动记录。
4. 最小业务集成
业务模块通常不直接解析 IWorkflowEngine，而是依赖聚焦端口。调用前由业务聚合验证“是否允许送审”，工作流成功后再通过可靠事件或可重试协调更新业务状态。
public async Task<Result<string>> SubmitAsync( MatterIntake matter, string userId, string tenantId, CancellationToken cancellationToken){ // ① 送审前置规则仍由 MatterIntake 聚合拥有：当事人齐备、利冲初筛已通过。 if (!matter.CanSubmitForApproval()) return Result.Failure<string>("Matter.IntakeInvalid");
// ② BusinessKey 用案件编号，保证流程事实与业务事实一一对账。 var started = await transitions.StartAsync( definitionKey: "matter-intake-approval", businessKey: matter.MatterNo, businessType: "MatterIntake", starterId: userId, tenantId: tenantId, officeId: matter.OfficeId, variables: new Dictionary<string, object?> { ["disputeAmount"] = matter.DisputeAmount, ["crossBorder"] = matter.IsCrossBorder }, cancellationToken);
// ③ 当前接口没有客户端 IdempotencyKey；超时后应先按业务键查询对账，再决定重试。 return started.IsSuccess ? Result.Success(started.Value.Id) : Result.Failure<string>(started.Error.Code);}5. 三层授权不能混为一谈
第一层是 HTTP 认证、限流、超时；第二层是 IAuthorizedRequest 的模块/资源/动作授权；第三层是引擎 IFlowDataPermissionChecker 对具体 task/instance 的 View、Operate、Manage 决策。参与人命中只是任务责任，不自动等价于查看全部业务数据。
WorkflowPermissions 常量不是处理器使用的授权事实（实际授权来自 ResourceDescriptor 与 AuthorizationAction）。但 workflow.runtime Feature 已被强制执行：WorkflowRuntimeLicenseGuard 在每次工作流写入和每次后台作业前通过 ILicenseGate 评估它，失败关闭。
6. 成功响应的含义
- 事务内实例、Execution、任务和轨迹写入成功，才返回运行时成功。
- 通知落库已纳入同一事实链：
INotificationChannel实现逐接收人写站内信并进入 CAP Outbox，任一接收人失败会计数并在发送后抛出，分发器记录日志后继续重抛——命令提交成功即可证明通知事实已持久化；跨网络的外部送达仍由 Notifications 模块的消费者异步负责。 - EventDispatcher 的监听器异常不再被静默隔离：记录日志后向上重抛，整个写操作随之失败回滚。监听器一致性因此成为流程正确性的一部分，自定义 Listener 必须按事务语义设计。
- Timer 返回 processed 计数包含失败记录；它统计”遍历过”，不是”动作成功”。
- 批量代批只标记任务完成，不推进流程，这是管理操作而非普通审批。
7. 生产前必做
验证双 ORM 并发、重复完成、并行网关、候选刷新、跨租户拒绝、定义发布竞争、Timer crash window、通知失败、业务回调失败、导入中断、归档孤儿、报表大区间和缓存失效。每项都需要可重现命令、预期错误、数据核对 SQL/Query 和恢复步骤。
8. 当前实现边界
workflow.runtime 已在运行时写入与后台作业前强制校验，不能再把它列为“仅有目录、未执行”的缺口。可视化设计器也已形成 Schema、AOT 业务元数据、乐观并发草稿、校验、模拟和发布闭环。
仍需显式接受的边界包括：旧的直接定义部署入口不会自动执行设计器的完整校验；模拟器只预览一条可达路径；浏览器崩溃快照目前按 tenant + definition key 隔离，不含 user；外部通知投递的送达确认依赖 Notifications 模块的 Outbox 消费，而独立宿主自建 Channel 的持久化强度取决于其自身实现。Timer、导入、归档和复杂并发是否满足具体产品 SLO，应以对应章节和发布候选测试为准，不沿用历史缺口清单。
9. 学习路径
建议先在可视化设计器中用三节点审批定义完成保存、validate、simulate、publish、start、complete 全流程；再增加排他网关；随后测试并行会签、转办与超时；最后做一次通知故障、并发完成和导入中断演练。每一步都同时查看实例、Execution、Task、ActivityRecord 和 TimerJob，而不是只看 HTTP 200。
10. 源码入口
# 引擎内核、平台用例和宿主端点。rg --files src/Framework/BitzOrcas.Workflow src/Platform/Workflow src/Hosts/BitzOrcas.Api/Endpoints/Workflow
# 单元、架构与独立集成测试。rg --files tests | rg 'Workflow|workflow'本章核心导航
- 01/11
Workflow 架构与核心概念
深入解释工作流内核分层、聚焦端口、执行模型、命令/查询存储、事务并发、缓存、租户和宿主组合。
- 02/11
定义与设计工作流
以当前 JSON DSL 讲解节点、连线、表达式、业务绑定、表单字段、参与人、多实例、定时器、监听器、校验与模拟边界。
- 03/11
部署、版本与回滚
讲透定义快照、Checksum 幂等、Office/租户绑定、当前 Grayscale 语义、缓存失效、并发风险与发布 Runbook。
- 04/11
可视化流程设计器
说明当前全页流程设计器的服务端 Schema、AOT 业务元数据、草稿修订、表单字段策略、模拟路径、版本作用域和权限边界。
- 05/11
运行工作流实例
深入说明发起、完成、驳回、撤回、重提、交接、控制、多实例、事务、并发、回调和定时器失败语义。
- 06/11
任务、候选人与待办查询
深入说明 Assigned/Candidate UNION、DataScope、查询降级、分页性能、详情授权、已读幂等、候选刷新和缓存。
- 07/11
历史、归档与分析
说明审批轨迹、实例与业务 Timeline、归档事务、报表计算、查询端口降级、精度缺口和运营验证。
- 08/11
迁移、指定节点发起与旧实例导入
区分 StartAtNode 与 Import，讲解映射、预检、当前非事务/非幂等边界、批次恢复、申请人转交和验收 Runbook。
- 09/11
Workflow 通知 Pipeline
讲解事件分发、接收人、默认模板、偏好、平台通知适配、JobHost 接线、事务性失败语义与外部投递对账。
- 10/11
Workflow HTTP API 参考
按 Definition、Runtime、Task、History、Report、Management 分组说明当前手写与生成路由、授权、限流、超时和错误语义。
- 11/11
独立嵌入 Workflow Engine
在非 BitzOrcas Host 中组合工作流引擎，正确实现持久化、查询、权限、参与人、服务任务、通知、Timer、缓存与运维。