From 8d08a2840bfecbcc19e42324c57473666650e5c8 Mon Sep 17 00:00:00 2001 From: 0264408 Date: Sun, 20 Sep 2026 11:45:23 +0800 Subject: [PATCH] docs: sync package layout and REST with current API Host examples and README still described the pre-split packages and omitted optional REST. Co-authored-by: Cursor --- README.md | 21 ++++++++++++++++----- docs/roadmap.md | 1 + docs/usage.md | 18 +++++++++++++++++- 3 files changed, 34 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index a46abc7..b798a00 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Ordo -轻量审批流程引擎。宿主通过 `OrdoEngine` 注册流程定义、发起实例、审批/驳回/转派/撤回/取消，并查询任务、实例与审计历史。引擎不绑定业务表单、用户体系或设计器 UI，当前也不自带 REST；业务数据放在 `ProcessContext` 里。 +轻量审批流程引擎。宿主通过 `OrdoEngine` 注册流程定义、发起实例、审批/驳回/转派/撤回/取消，并查询任务、实例与审计历史。引擎不绑定业务表单、用户体系或设计器 UI。可选 REST（`ordo.rest.enabled`）。业务数据放在 `ProcessContext` 里。 要求 **Java 17+**。当前版本 `0.0.1-SNAPSHOT`。 @@ -30,7 +30,7 @@ - 审计时间线：`ProcessEvent` + `queryHistory` - 扩展点：`AssigneeResolver`、`RoutingCondition`、`ActionHandler`、`NamedCondition`、`NamedAction`、`OrdoEventListener` -开发计划：可选 REST + 目录 SPI。设计器为独立产品（不进本仓库），待 REST 与目录之后。多租户 **暂不在计划中**。见 [docs/roadmap.md](docs/roadmap.md)。 +开发计划：独立设计器（不进本仓库）。多租户 **暂不在计划中**。见 [docs/roadmap.md](docs/roadmap.md)。 详细用法（定义 JSON、扩展点、异常、查询、ACTION/审计语义）见 **[docs/usage.md](docs/usage.md)**。对外行为变更时同步更新该文档。 @@ -45,6 +45,12 @@ ``` ```java +import com.jetlumen.ordo.api.OrdoEngine; +import com.jetlumen.ordo.api.definition.ApprovalStep; +import com.jetlumen.ordo.api.definition.ProcessDefinition; +import com.jetlumen.ordo.api.runtime.ProcessContext; +import com.jetlumen.ordo.core.InMemoryOrdoEngine; + OrdoEngine ordo = new InMemoryOrdoEngine(); ordo.publish(ProcessDefinition.linear("leave-request", "Leave request", List.of( ApprovalStep.single("manager", "Manager approval", "maria"), @@ -83,8 +89,7 @@ ordo.approve(manager.id(), "maria", "ok"); - `kind` 默认 `APPROVAL`；ACTION 用 `"action"` 作为 handler 查找键；`PARALLEL` 用 `branches`（结构化并行块，见 [docs/usage.md](docs/usage.md)）。 - 带 `when` 的边先按 `priority` 匹配，都未命中再走无条件边；`to: null` 表示结束。 -- 代码侧可用 `ProcessDefinitionParser.fromJson(...)`。 -- `replace` 会整体替换同 id 定义；存在 `RUNNING` 实例时拒绝替换。 +- 代码侧可用 `ProcessDefinitionParser.fromJson(...)`（`com.jetlumen.ordo.api.definition`）。 ## Spring Boot @@ -96,7 +101,7 @@ ordo.approve(manager.id(), "maria", "ok"); ``` -需要 `DataSource`。存在 `DataSource` 且 `ordo.enabled` 不为 `false` 时装配 JDBC 引擎。 +需要 `DataSource`。存在 `DataSource` 且 `ordo.enabled` 不为 `false` 时装配 JDBC 引擎。REST 另需宿主的 Web starter，且 `ordo.rest.enabled=true`。 ```yaml ordo: @@ -105,6 +110,11 @@ ordo: dialect: # 可选 postgresql / mysql；空则按 DataSource 探测 definitions: location: classpath*:ordo/*.json # 默认值；启动时 publish 加载 + due: + poll-ms: 0 # >0 时轮询 processDue + rest: + enabled: false + base-path: /ordo ``` 宿主提供 Bean 即可覆盖默认值： @@ -115,6 +125,7 @@ ordo: | `NamedCondition` / `NamedAction` | 可多个；无对应门面时按 key 分发 | | `RoutingCondition` | 无具名 condition 时始终匹配；有则未知 `ref` 为 false | | `ActionHandler` | 无具名 action 时空操作；有则未知 key 抛错 | +| `OrdoCatalog` | REST 打开时从 Named* 投影；`assignees` 空 | | `OrdoEventListener` | 可注册多个，提交后按顺序调用 | ## 运行时约定 diff --git a/docs/roadmap.md b/docs/roadmap.md index c2c2441..d34a0ac 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -20,6 +20,7 @@ - 管理员/系统取消 `cancel` / `CANCELLED` - 可选 REST（autoconfigure 条件装配）+ 目录 SPI `OrdoCatalog` - `NamedAction` / `NamedCondition` 注册与官方 key 分发；默认 Catalog 从具名 Bean 投影 +- API 分包：`api.definition` / `runtime` / `spi` / `util` ## 开发计划（确定要做） diff --git a/docs/usage.md b/docs/usage.md index 713c37f..87d1e4c 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -22,6 +22,18 @@ Ordo 是嵌入宿主进程的审批引擎，入口是 `OrdoEngine`。 | `ordo-spring-boot-starter` | Spring Boot 自动装配 | | `ordo-example` | `LeaveRequestExample` 内存演示 | +Java 包（模块未变）： + +| 包 | 内容 | +|---|---| +| `com.jetlumen.ordo.api` | `OrdoEngine`、`TransactionExecutor` | +| `com.jetlumen.ordo.api.definition` | 图：定义、步骤、边、`when`、PARALLEL | +| `com.jetlumen.ordo.api.runtime` | 实例、任务、事件、ACTION 执行、token、`ProcessRuntime` | +| `com.jetlumen.ordo.api.spi` | `ActionHandler`、`NamedAction`、`RoutingCondition`、`NamedCondition`、`AssigneeResolver`、`OrdoCatalog`、`OrdoEventListener` | +| `com.jetlumen.ordo.api.util` | `Texts`、`Jsons` | +| `com.jetlumen.ordo.api.exception` / `query` / `repository` | 异常、分页查询、存储端口 | +| `com.jetlumen.ordo.core.spi` | `DispatchingActionHandler`、`DispatchingRoutingCondition`、`RegistryOrdoCatalog` | + Starter **不携带** JDBC 驱动。生产按库添加 `org.postgresql:postgresql` 或 `com.mysql:mysql-connector-j`。Spring Boot 4 还需 `spring-boot-starter-flyway`，否则 Flyway 迁移不会执行。 先 `mvn install` 本仓库，宿主再依赖 `0.0.1-SNAPSHOT`。 @@ -85,7 +97,7 @@ ordo: 未提供 `NamedAction` 且未覆盖 `ActionHandler` 时，ACTION 步骤仍会推进流程，但 handler 什么都不做。不要同时提供门面 Bean 与对应 `Named*`（门面优先，具名 Bean 不参与运行时）。 -内存引擎把 `DispatchingRoutingCondition.of(...)` / `DispatchingActionHandler.of(...)` 传入 `InMemoryOrdoEngine` 即可。 +内存引擎把 `com.jetlumen.ordo.core.spi.DispatchingRoutingCondition.of(...)` / `DispatchingActionHandler.of(...)` 传入 `InMemoryOrdoEngine` 即可。 ### 2.3 可选 REST @@ -314,6 +326,10 @@ v1：至少 2 条分支；禁止套娃 PARALLEL；join 固定 ALL；任一分支 **失败不回滚已提交的审批，不阻塞后续步骤，引擎不做重试。** 宿主用 `queryActionExecutions` 或 listener 自行补发。分发器遇到未知 `actionKey` 会抛 `IllegalArgumentException`，记为该次 ACTION `FAILED`。 ```java +import com.jetlumen.ordo.api.runtime.ProcessRuntime; +import com.jetlumen.ordo.api.spi.NamedAction; +import org.springframework.stereotype.Component; + @Component public class LeaveApprovedMail implements NamedAction { @Override