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 <cursoragent@cursor.com>
This commit is contained in:
0264408
@@ -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");
|
||||
</dependency>
|
||||
```
|
||||
|
||||
需要 `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` | 可注册多个，提交后按顺序调用 |
|
||||
|
||||
## 运行时约定
|
||||
|
||||
@@ -20,6 +20,7 @@
|
||||
- 管理员/系统取消 `cancel` / `CANCELLED`
|
||||
- 可选 REST（autoconfigure 条件装配）+ 目录 SPI `OrdoCatalog`
|
||||
- `NamedAction` / `NamedCondition` 注册与官方 key 分发；默认 Catalog 从具名 Bean 投影
|
||||
- API 分包：`api.definition` / `runtime` / `spi` / `util`
|
||||
|
||||
## 开发计划（确定要做）
|
||||
|
||||
|
||||
+17
-1
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user