All Known Implementing Classes:: InMemoryFlowRepository, JdbcFlowRepository

public interface FlowRepository

Unified persistence contract for the flow engine; backed by either InMemoryFlowRepository (tests / demos) or JdbcFlowRepository (production, S4). 流程引擎的统一持久化契约；后端可由 InMemoryFlowRepository （测试 / 演示）或 JdbcFlowRepository（生产，S4）实现。

Concurrency model (v4 §8.0):

updateInstance(FlowInstance) and updateTask(Task) use optimistic locking: their SQL carries WHERE version = ?; a return value of 0 indicates a concurrent modification.
casIncrementAddsignDepth(String, int, int) performs a CAS update guarded by both version and addsign_depth < maxDepth; callers must re-read to distinguish "version conflict" from "depth exceeded".
History rows are append-only (appendHistory(HistoryRecord) and query methods only).

并发模型（v4 §8.0）：

updateInstance(FlowInstance) / updateTask(Task) 使用乐观锁：SQL 带 WHERE version = ?，返回 0 即并发冲突。
casIncrementAddsignDepth(String, int, int) 同时校验 version 与 addsign_depth < maxDepth；调用方需重新读取以区分"版本冲突"与"超深"两种情况。
history 表为追加写（仅 appendHistory(HistoryRecord) 与查询）。

Since:: JDK 25, opencode-base-flow V1.0.5
Author:: Leon Soo

Method Summary

Modifier and Type

Method

Description

void

appendHistory(HistoryRecord record)

Appends a new history row.

int

cancelAllTasksForStep(String instanceId, String stepId)

Bulk-transitions every task under (instanceId, stepId) whose current status is not TaskStatus.CANCELED into the TaskStatus.CANCELED state — including DONE / REJECTED rows from a prior approval round.

int

cancelOtherPendingTasks(String instanceId, String stepId, String exceptTaskId)

Bulk-cancels every other TaskStatus.PENDING task on the same step (excluding exceptTaskId), respecting optimistic-lock version.

int

casIncrementAddsignDepth(String instanceId, int expectedVersion, int maxDepth)

Compare-and-set: UPDATE addsign_depth = addsign_depth + 1, version = version + 1 WHERE id = ? AND version = ? AND addsign_depth < maxDepth.

Optional<FlowDefinition>

findActiveDefinition(String flowKey)

Returns the single FlowStatus.ACTIVE definition for the given business key, if any.

Optional<FlowDefinition>

findDefinitionById(String id)

Looks up a definition by its primary id.

List<FlowDefinition>

findDefinitionVersions(String flowKey)

Lists every persisted version of the given business key, in version ascending order.

List<HistoryRecord>

findHistoryByInstance(String instanceId)

Lists every history row for an instance in chronological order (earliest first).

Optional<HistoryRecord>

findHistoryByTaskId(String taskId)

Looks up a history row by its related task id (one-to-one for terminal task actions such as approve / reject).

List<HistoryRecord>

findHistoryByUser(String userId, int page, int size)

Paginated history query for the given user (matched on HistoryRecord.operatorId()).

Optional<FlowInstance>

findInstanceById(String id)

Looks up an instance by id.

List<FlowInstance>

findInstancesByInitiator(String userId, int page, int size)

Lists instances started by the given user, paginated.

Optional<Task>

findTaskById(String id)

Looks up a task by id.

List<Task>

findTasksByInstance(String instanceId)

Lists every task (any status) under the given instance.

List<Task>

findTasksByInstanceAndStatus(String instanceId, TaskStatus status)

Lists tasks that belong to the given instance and currently sit in the given status.

List<Task>

findTodoByUser(String userId, int page, int size)

Paginated todo-list query for the given user (status = TaskStatus.PENDING only).

List<VoteRecord>

findVotesByTask(String taskId)

Lists every vote recorded against the given task, in vote order.

void

recordVote(String taskId, String voterId, VoteOpinion opinion)

Records a single vote at a StepType.VOTE step.

void

runInTransaction(Runnable action)

Run the supplied action atomically.

FlowDefinition

saveDefinition(FlowDefinition def)

Persists a new flow definition.

FlowInstance

saveInstance(FlowInstance inst)

Persists a new flow instance.

Task

saveTask(Task task)

Persists a new task.

void

updateDefinitionStatus(String id, FlowStatus newStatus)

Mutates the lifecycle status of a definition (ACTIVE / DEPRECATED).

int

updateInstance(FlowInstance inst)

Optimistic-lock UPDATE; returns the number of affected rows (0 indicates version conflict).

int

updateTask(Task task)

Optimistic-lock UPDATE; returns affected rows (0 = version conflict).

Method Details
- saveDefinition
  
  FlowDefinition saveDefinition(FlowDefinition def)
  
  Persists a new flow definition. The returned record reflects the stored state (including any engine-assigned fields). 持久化一份新的流程定义。返回已存储的视图。
  
  Parameters:
  
  def - the definition to persist — 待持久化的定义
  
  Returns:
  
  the persisted definition — 已持久化的定义
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- findDefinitionById
  
  Optional<FlowDefinition> findDefinitionById(String id)
  
  Looks up a definition by its primary id. 根据主键 ID 查找定义。
  
  Parameters:
  
  id - definition id — 定义 ID
  
  Returns:
  
  the definition wrapped in an Optional — 定义（Optional）
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- findActiveDefinition
  
  Optional<FlowDefinition> findActiveDefinition(String flowKey)
  
  Returns the single FlowStatus.ACTIVE definition for the given business key, if any. 返回指定业务 key 当前唯一启用的（FlowStatus.ACTIVE）定义。
  
  Parameters:
  
  flowKey - business flow key — 业务 key
  
  Returns:
  
  the active definition — 启用中的定义
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- findDefinitionVersions
  
  List<FlowDefinition> findDefinitionVersions(String flowKey)
  
  Lists every persisted version of the given business key, in version ascending order. 返回给定业务 key 所有版本（按版本号升序）。
  
  Parameters:
  
  flowKey - business flow key — 业务 key
  
  Returns:
  
  all definition versions — 全部版本
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- updateDefinitionStatus
  
  void updateDefinitionStatus(String id, FlowStatus newStatus)
  
  Mutates the lifecycle status of a definition (ACTIVE / DEPRECATED). 修改某定义的生命周期状态（ACTIVE / DEPRECATED）。
  
  Parameters:
  
  id - definition id — 定义 ID
  
  newStatus - the new status — 新状态
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- saveInstance
  
  FlowInstance saveInstance(FlowInstance inst)
  
  Persists a new flow instance. 持久化新的流程实例。
  
  Parameters:
  
  inst - the instance to persist — 待持久化的实例
  
  Returns:
  
  the persisted instance — 已持久化的实例
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- findInstanceById
  
  Optional<FlowInstance> findInstanceById(String id)
  
  Looks up an instance by id. 根据 ID 查找实例。
  
  Parameters:
  
  id - instance id — 实例 ID
  
  Returns:
  
  the instance wrapped in an Optional — 实例（Optional）
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- findInstancesByInitiator
  
  List<FlowInstance> findInstancesByInitiator(String userId, int page, int size)
  
  Lists instances started by the given user, paginated. 分页列出指定发起人启动的实例。
  
  Parameters:
  
  userId - initiator user id — 发起人 userId
  
  page - zero-based page index — 页码（0 起）
  
  size - page size — 每页大小
  
  Returns:
  
  instances on the requested page — 该页实例
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- updateInstance
  
  int updateInstance(FlowInstance inst)
  
  Optimistic-lock UPDATE; returns the number of affected rows (0 indicates version conflict). 乐观锁 UPDATE；返回 affected rows（0 表示版本冲突）。
  
  Parameters:
  
  inst - the instance to update — 待更新的实例
  
  Returns:
  
  affected rows — 影响行数
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- casIncrementAddsignDepth
  
  int casIncrementAddsignDepth(String instanceId, int expectedVersion, int maxDepth)
  
  Compare-and-set: UPDATE addsign_depth = addsign_depth + 1, version = version + 1 WHERE id = ? AND version = ? AND addsign_depth < maxDepth. Returns affected rows (0 = conflict or depth exceeded). Callers must re-read the instance to distinguish the two cases. CAS：UPDATE addsign_depth + 1, version + 1 WHERE id = ? AND version = ? AND addsign_depth < maxDepth。返回 affected rows（0 表示冲突或超深）。调用方需复读 instance 区分两种情况。
  
  Parameters:
  
  instanceId - instance id — 实例 ID
  
  expectedVersion - expected current version — 期望的当前版本
  
  maxDepth - configured max addsign depth — 配置的加签链上限
  
  Returns:
  
  affected rows — 影响行数
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- saveTask
  
  Task saveTask(Task task)
  
  Persists a new task. 持久化新任务。
  
  Parameters:
  
  task - the task to persist — 待持久化的任务
  
  Returns:
  
  the persisted task — 已持久化的任务
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- findTaskById
  
  Optional<Task> findTaskById(String id)
  
  Looks up a task by id. 根据 ID 查找任务。
  
  Parameters:
  
  id - task id — 任务 ID
  
  Returns:
  
  the task wrapped in an Optional — 任务（Optional）
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- findTasksByInstanceAndStatus
  
  List<Task> findTasksByInstanceAndStatus(String instanceId, TaskStatus status)
  
  Lists tasks that belong to the given instance and currently sit in the given status. 列出指定实例下、指定状态的任务。
  
  Parameters:
  
  instanceId - owning instance id — 所属实例 ID
  
  status - task status filter — 任务状态
  
  Returns:
  
  matching tasks — 符合条件的任务
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- findTasksByInstance
  
  List<Task> findTasksByInstance(String instanceId)
  
  Lists every task (any status) under the given instance. 列出指定实例下所有任务（不限状态）。
  
  Parameters:
  
  instanceId - owning instance id — 所属实例 ID
  
  Returns:
  
  all tasks — 所有任务
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- findTodoByUser
  
  List<Task> findTodoByUser(String userId, int page, int size)
  
  Paginated todo-list query for the given user (status = TaskStatus.PENDING only). 分页查询某用户的待办（仅 TaskStatus.PENDING）。
  
  Parameters:
  
  userId - assignee user id — 承接人 userId
  
  page - zero-based page index — 页码（0 起）
  
  size - page size — 每页大小
  
  Returns:
  
  tasks on the requested page — 该页任务
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- updateTask
  
  int updateTask(Task task)
  
  Optimistic-lock UPDATE; returns affected rows (0 = version conflict). 乐观锁 UPDATE；返回 affected rows（0 表示版本冲突）。
  
  Parameters:
  
  task - the task to update — 待更新的任务
  
  Returns:
  
  affected rows — 影响行数
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- cancelOtherPendingTasks
  
  int cancelOtherPendingTasks(String instanceId, String stepId, String exceptTaskId)
  
  Bulk-cancels every other TaskStatus.PENDING task on the same step (excluding exceptTaskId), respecting optimistic-lock version. Returns the number of tasks that were successfully canceled. 批量取消同节点其他 PENDING 任务（不含 exceptTaskId），遵守乐观锁；返回成功取消的条数。
  
  Parameters:
  
  instanceId - owning instance id — 所属实例 ID
  
  stepId - step id — 节点 ID
  
  exceptTaskId - the task id to keep — 保留的任务 ID
  
  Returns:
  
  number of canceled tasks — 成功取消条数
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- cancelAllTasksForStep
  
  int cancelAllTasksForStep(String instanceId, String stepId)
  
  Bulk-transitions every task under (instanceId, stepId) whose current status is not TaskStatus.CANCELED into the TaskStatus.CANCELED state — including DONE / REJECTED rows from a prior approval round. Used by RejectOperation when rolling back to a previously visited step so that StepEvaluator only ever observes tasks from the new batch. 批量将 (instanceId, stepId) 下所有非 CANCELED 状态的任务（含上一轮的 DONE / REJECTED）置为 TaskStatus.CANCELED。 RejectOperation 在回退到已访问节点时调用此方法，确保 StepEvaluator 只看见新一轮批次的任务。
  Invariant: each step has at most one active batch of tasks at any given time. Reject re-entry must enforce this by calling this method for every affected step before creating fresh PENDING rows.
  
  不变式：任意时刻每个 step 最多有一批活跃 task；reject 重入前必须对所有受影响 step 调用本方法。
  
  Parameters:
  
  instanceId - owning instance id — 所属实例 ID
  
  stepId - step id — 节点 ID
  
  Returns:
  
  number of affected rows — 影响行数
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- appendHistory
  
  void appendHistory(HistoryRecord record)
  
  Appends a new history row. History is append-only — once written, rows are never updated or deleted. 追加一条历史记录。历史表仅追加，写入后不可更新或删除。
  
  Parameters:
  
  record - the history row to append — 待追加的历史
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- findHistoryByInstance
  
  List<HistoryRecord> findHistoryByInstance(String instanceId)
  
  Lists every history row for an instance in chronological order (earliest first). 按时间升序列出指定实例的所有历史记录。
  
  Parameters:
  
  instanceId - owning instance id — 所属实例 ID
  
  Returns:
  
  chronological history — 时间升序的历史
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- findHistoryByUser
  
  List<HistoryRecord> findHistoryByUser(String userId, int page, int size)
  
  Paginated history query for the given user (matched on HistoryRecord.operatorId()). 分页查询某用户的历史记录（按 HistoryRecord.operatorId() 匹配）。
  
  Parameters:
  
  userId - operator user id — 操作人 userId
  
  page - zero-based page index — 页码（0 起）
  
  size - page size — 每页大小
  
  Returns:
  
  history rows on the requested page — 该页历史
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- findHistoryByTaskId
  
  Optional<HistoryRecord> findHistoryByTaskId(String taskId)
  
  Looks up a history row by its related task id (one-to-one for terminal task actions such as approve / reject). 按关联任务 ID 查找历史（approve / reject 等终态任务动作一对一）。
  
  Parameters:
  
  taskId - related task id — 关联任务 ID
  
  Returns:
  
  the history row wrapped in an Optional — 历史（Optional）
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- recordVote
  
  void recordVote(String taskId, String voterId, VoteOpinion opinion)
  
  Records a single vote at a StepType.VOTE step. Append-only. 在 StepType.VOTE 节点记录一票。追加写。
  
  Parameters:
  
  taskId - related task id — 关联任务 ID
  
  voterId - voter user id — 投票人
  
  opinion - vote opinion — 投票意见
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- findVotesByTask
  
  List<VoteRecord> findVotesByTask(String taskId)
  
  Lists every vote recorded against the given task, in vote order. 列出关联任务的所有投票（按投票顺序）。
  
  Parameters:
  
  taskId - related task id — 关联任务 ID
  
  Returns:
  
  votes in submission order — 投票（按提交顺序）
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5
- runInTransaction
  void runInTransaction(Runnable action)
  
  Run the supplied action atomically.
  
  JDBC implementations open a single connection with autoCommit=false, bind it via a thread-local so every repo method called by action reuses it, then commit (or roll back on any thrown exception).
  
  The in-memory implementation runs the action under a reentrant lock to provide best-effort atomicity for tests / demos (compute-blocks already provide per-row CAS).
  
  The contract is best-effort: a RuntimeException thrown from within action aborts the transaction (rollback on JDBC) and is re-raised to the caller. Nested calls are allowed and join the outer transaction without re-opening one. 原子执行给定动作：
  
  JDBC 实现：取一个 autoCommit=false 连接绑入 ThreadLocal，期间所有仓储方法复用此连接，结束时 commit；动作抛异常则 rollback。
  
  InMemory 实现：用可重入锁保证测试 / 演示场景的最佳努力原子性（compute-block 已保证单行 CAS）。
  
  嵌套调用安全：内层不会重开事务，自动并入外层。
  
  Parameters:
  
  action - the action to run atomically — 待原子执行的动作
  
  Since:
  
  JDK 25, opencode-base-flow V1.0.5

Interface FlowRepository

Method Summary

Method Details

saveDefinition

findDefinitionById

findActiveDefinition

findDefinitionVersions

updateDefinitionStatus

saveInstance

findInstanceById

findInstancesByInitiator

updateInstance

casIncrementAddsignDepth

saveTask

findTaskById

findTasksByInstanceAndStatus

findTasksByInstance

findTodoByUser

updateTask

cancelOtherPendingTasks

cancelAllTasksForStep

appendHistory

findHistoryByInstance

findHistoryByUser

findHistoryByTaskId

recordVote

findVotesByTask

runInTransaction