codingapi · xlorne · Aug 8, 2026 · Aug 8, 2026 · Aug 8, 2026 · Aug 8, 2026
diff --git a/docs/Integration/README.md b/docs/Integration/README.md
@@ -0,0 +1,79 @@
+# Flow Engine 集成手册（后端）
+
+> 面向业务项目的后端集成指南。本文档以仓库实际代码为依据，介绍 Flow Engine 工作流引擎允许下游（业务方）集成与扩展的全部能力，包括：**流程用户体系、流程默认脚本、流程事件机制、仓储抽象与持久化、Spring Boot 自动配置、REST API、Mock 模式、节点/动作/策略配置**等。
+
+## 模块结构
+
+| 模块 | 说明 | 集成角色 |
+|------|------|----------|
+| `flow-engine-framework` | 核心引擎：节点/动作/策略/脚本/服务/仓储接口（Spring 无关的领域核心） | 只读，一般不改动 |
+| `flow-engine-starter` | Spring Boot 自动配置入口，把引擎单例与 Spring 容器打通 | 直接依赖 |
+| `flow-engine-starter-infra` | JPA 持久化实现（11 张 `t_flow_*` 表 + 11 个仓储实现） | 可直接依赖；也可自行实现仓储接口替换 |
+| `flow-engine-starter-api` | 命令 REST API（发起/审批/撤销/催办/删除 + 流程设计 CRUD） | 可选依赖 |
+| `flow-engine-starter-query` | 查询 REST API（待办/已办/抄送/全部列表） | 可选依赖 |
+| `flow-engine-example` | 下游集成范本（用户体系、事件订阅、脚本仓储、安全） | 参考实现 |
+
+## 下游必须提供的能力（概览）
+
+集成方**必须**在自身应用中提供以下 Spring Bean / 实现，否则引擎自动配置启动失败：
+
+| # | 必须提供 | 说明 | 对应文档 |
+|---|----------|------|----------|
+| 1 | `FlowOperatorGateway` | 对接应用用户体系的防腐层（`get(id)` / `findByIds(ids)`） | [流程用户体系](./user-integration.md) |
+| 2 | `IFlowOperator` 实现类 | 用户实体/DTO，实现 `getUserId/getName/isFlowManager/forwardOperator` | [流程用户体系](./user-integration.md) |
+| 3 | `NodeViewJavaScriptRepository` | 节点视图 JS 持久化（infra 不提供，需自建） | [仓储抽象](./repository-integration.md) |
+| 4 | 脚本持久化：`GroovyScriptRepository`、`TempGroovyScriptRepository` | Groovy 脚本落库（外部 starter-script 的 SPI） | [仓储抽象](./repository-integration.md) |
+| 5 | 11 个仓储接口（仅当不引入 `flow-engine-starter-infra` 时） | 自行实现存储 | [仓储抽象](./repository-integration.md) |
+
+## 文档目录
+
+| 文档 | 内容 |
+|------|------|
+| [快速开始](./quick-start.md) | 最小集成步骤：引入依赖 → 提供 Bean → 编写流程 → 发起流程 |
+| [流程用户体系](./user-integration.md) | `FlowOperatorGateway` / `IFlowOperator` / `GatewayContext` / 线程缓存 / 当前登录人 |
+| [流程默认脚本](./script-integration.md) | 12 种脚本类型、`GroovyScriptRequest` 完整 API、`$bind`、默认脚本替换、脚本生命周期 |
+| [流程事件机制](./event-integration.md) | 7 种事件、`EventPusher`、`IHandler` 订阅、异步分发管道、事务变体、推送时机 |
+| [仓储抽象与持久化](./repository-integration.md) | `IRepositoryHolder`、12 个仓储接口、JPA 实现、脚本仓储、锁机制 |
+| [Spring Boot 自动配置](./auto-configuration.md) | `AutoConfiguration` 8 个 Bean、4 个 Register、必选/可选 Bean 清单 |
+| [REST API](./rest-api.md) | 4 个 Controller、`mockKey`/`operatorId` 分流机制、请求/响应结构 |
+| [Mock 模式](./mock-mode.md) | 全内存沙箱 `MockInstance`、15 分钟过期、接入方式 |
+| [节点/动作/策略扩展](./extension-points.md) | 19 种节点 × 8 种动作 × 15 种节点策略 × 2 种流程策略，扩展方式 |
+| [编程式 API](./programmatic-api.md) | `WorkflowBuilder`/`FlowFormBuilder` 构建流程、`FlowService` 服务编排、查询服务 |
+
+## 核心架构速览
+
+### 单例上下文家族（框架层，无 Spring 注解）
+
+引擎核心以「静态单例 + Setter 注入」模式运作，Spring 集成由 starter 的 `*Register`（`InitializingBean`）在启动时把 Bean 「灌入」单例：
+
+| 单例 | 作用 | 注入来源 |
+|------|------|----------|
+| `GatewayContext` | 操作人网关持有者（带线程缓存） | `GatewayContextRegister` |
+| `RepositoryHolderContext` | 资源持有者（7 个仓储/服务） | `RepositoryHolderContextRegister` |
+| `FlowScriptContext` | 脚本 `$bind` 上下文（`IBeanFactory`） | `FlowScriptContextRegister` |
+| `FlowIDGeneratorGatewayContext` | ID 生成器（可替换扩展点） | 默认内建，可选替换 |
+| `NodeViewJavaScriptCacheContext` | 节点视图 JS 缓存（15 分钟） | `NodeViewJavaScriptCacheContextRegister` |
+| `FlowOperatorLocalThreadCache` | 操作人线程缓存 | 引擎内部使用 |
+| `FlowRuntimeScriptLocalCache` | 脚本快照线程缓存 | 引擎内部使用 |
+| `MockInstanceFactory` | Mock 沙箱工厂 | api 模块调用 |
+
+### 执行链路
+
+```
+REST 请求 → FlowRecordController
+  （mockKey 分流 Mock / 生产；operatorId 覆盖当前用户）
+  → FlowService（@Transactional，清线程缓存）
+    → FlowXxxService（create / action / revoke / delete / urge / detail）
+      → FlowSession（不可变会话）→ 节点 handle → 动作 run → 策略执行
+      → repositoryHolder.saveRecords（落库）
+      → EventPusher.push（推送事件，异步）
+```
+
+## 版本约定
+
+- 引擎版本：`0.1.0-SNAPSHOT`（根 pom `revision`）
+- 外部框架依赖（根 pom `codingapi.framework.version = 3.4.55`）：
+  - `com.codingapi.springboot:springboot-starter` —— 事件体系（`EventPusher`/`IHandler`）、`UserContext`、`LocaleMessageException`
+  - `com.codingapi.springboot:springboot-starter-script` —— Groovy 脚本引擎（`GroovyScript`/注解/仓储 SPI）
+  - `com.codingapi.springboot:springboot-starter-data-fast` —— `FastRepository`（JPA 仓储基类）
+- Java 17、Spring Boot 3.5.9
diff --git a/docs/Integration/auto-configuration.md b/docs/Integration/auto-configuration.md
@@ -0,0 +1,95 @@
+# Spring Boot 自动配置
+
+`flow-engine-starter` 通过 Spring Boot 自动配置把引擎单例与 Spring 容器打通。注册入口见 `flow-engine-starter/src/main/java/com/codingapi/flow/AutoConfiguration.java`。
+
+## 1. 注册方式
+
+双注册文件（Boot2 / Boot3 兼容）：
+
+- `META-INF/spring.factories` → `EnableAutoConfiguration=com.codingapi.flow.AutoConfiguration`
+- `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` → `com.codingapi.flow.AutoConfiguration`
+
+`AutoConfiguration` 为 `@Configuration`，**无 `@ConditionalOnMissingBean`、无条件注解** —— 构造函数依赖的 Bean 缺失将导致启动失败。
+
+## 2. 注册的 Bean 全清单
+
+| @Bean | 依赖 | 作用 |
+|---|---|---|
+| `NodeViewJavaScriptCacheContextRegister` | **`NodeViewJavaScriptRepository`** | 构造器内执行 `NodeViewJavaScriptCacheContext.getInstance().setNodeViewJavaScriptRepository(repo)`（15 分钟缓存上下文） |
+| `GatewayContextRegister` | **`FlowOperatorGateway`** | 把操作人网关灌入 `GatewayContext` 单例（`InitializingBean`） |
+| `FlowScriptContextRegister` | `ApplicationContext` + **`FlowOperatorGateway`** + `FlowRecordRepository` | 给 `FlowScriptContext` 单例设置 `IBeanFactory`（转发 Spring 容器，脚本 `$bind` 依赖） |
+| `RepositoryHolderContextRegister` | `WorkflowService` + `FlowRecordService` + 5 个仓储 + `GatewayContextRegister` | 把 7 个依赖灌入 `RepositoryHolderContext` 单例（`InitializingBean`） |
+| `FlowRecordService` | `FlowTodoRecordRepository` + `FlowTodoMergeRepository` + `FlowRecordRepository` | 记录服务 Bean |
+| `WorkflowService` | `WorkflowVersionRepository` + `WorkflowRepository` + `WorkflowRuntimeRepository` | 流程设计服务 Bean |
+| `FlowService` | `RepositoryHolderContextRegister`（仅保证顺序） | `new FlowService(RepositoryHolderContext.getInstance())`，业务入口 |
+| `FlowDelayTaskRunner` | `RepositoryHolderContextRegister` | `ApplicationRunner + DisposableBean`：启动时 `DelayTaskManager.getInstance().start(...)` 加载延迟任务，销毁时 `close()` |
+
+## 3. Register 类（单例注入）
+
+全部位于 `flow-engine-starter/src/main/java/com/codingapi/flow/register/`，均实现 `InitializingBean`：
+
+```java
+// GatewayContextRegister
+@Override
+public void afterPropertiesSet() {
+    GatewayContext.getInstance().setFlowOperatorGateway(flowOperatorGateway);
+}
+
+// RepositoryHolderContextRegister
+@Override
+public void afterPropertiesSet() {
+    RepositoryHolderContext.getInstance().register(
+            workflowService, flowRecordService,
+            parallelBranchRepository, delayTaskRepository,
+            urgeIntervalRepository, flowOperatorAssignmentRepository,
+            subProcessRepository);
+}
+
+// FlowScriptContextRegister
+@Override
+public void afterPropertiesSet() {
+    FlowScriptContext.getInstance().setBeanFactory(new IBeanFactory() {
+        // getBean/getBeans 转发 Spring 容器
+        // getRecordById 走 flowRecordRepository.get
+        // getOperatorById/findOperatorsByIds 走 flowOperatorGateway
+    });
+}
+```
+
+## 4. api / query 模块装配
+
+| 模块 | 装配 |
+|---|---|
+| `flow-engine-starter-api` | `@Configuration @ComponentScan("com.codingapi.flow.api")`。`WorkflowController` 注入 `FlowOperatorGateway` + `WorkflowRepository` 用于创建 Mock 实例；当前用户经 `UserContext.getInstance().current()` 强转 `IFlowOperator` |
+| `flow-engine-starter-query` | `@Configuration @ComponentScan("com.codingapi.flow.query")` + `@Bean FlowRecordQueryService(FlowRecordEntityRepository, FlowTodoRecordEntityRepository)` → `FlowRecordQueryServiceImpl`（直接依赖 infra 的 JPA 仓储） |
+
+## 5. 必选 / 可选实现清单
+
+### 必须提供（缺失即启动失败）
+
+| # | 接口/Bean | 说明 | 注入通道 |
+|---|---|---|---|
+| 1 | `FlowOperatorGateway` | 对接应用用户体系（`get`/`findByIds`） | `GatewayContextRegister` → `GatewayContext`；同时被 `FlowScriptContextRegister`、api Controller 依赖 |
+| 2 | `IFlowOperator` 实现类 | 用户实体/DTO | 由 Gateway 返回，经 `FlowOperatorLocalThreadCache` 缓存 |
+| 3 | `NodeViewJavaScriptRepository` | 节点视图 JS 持久化（infra 无实现） | `NodeViewJavaScriptCacheContextRegister` 构造器 |
+| 4 | 11 个仓储接口实现 | 引入 `flow-engine-starter-infra` 则自动提供；否则自行实现 | `RepositoryHolderContextRegister` / `FlowRecordService` / `WorkflowService` |
+| 5 | `GroovyScriptRepository` + `TempGroovyScriptRepository` | 脚本持久化 SPI（外部 starter-script） | 自注册到对应 `*RepositoryContext` 单例 |
+
+### 可选（有默认实现 / 按需替换）
+
+| # | 扩展点 | 默认行为 | 替换方式 |
+|---|---|---|---|
+| 1 | `FlowIDGeneratorGateway` | 随机字母数字（18/10 位）；`generateRecordId()` 默认返回 0（依赖 DB 自增） | `FlowIDGeneratorGatewayContext.getInstance().setFlowIDGeneratorGateway(...)` |
+| 2 | `WorkflowRepository.lockById` | default 空实现 | 持久化实现应使用数据库行锁（多实例部署） |
+| 3 | 当前登录用户 | — | `UserContext.getInstance().setCurrent(...)`（配合安全框架） |
+| 4 | 默认脚本 | `DefaultScriptRegistry` | `ScriptRegistryContext.getInstance().setRegistry(...)` |
+| 5 | 事件事务分发 | `SpringDefaultEventHandler`（发布即分发） | `codingapi.framework.event.transaction.enable=true` → 事务提交后分发 |
+
+## 6. 配置项
+
+| 配置前缀 | 作用 |
+|---|---|
+| `codingapi.script.tempValidTime` | 临时脚本有效期（默认 15 分钟） |
+| `codingapi.script.shellMaxCacheSize` | 脚本编译缓存上限（默认 10240） |
+| `codingapi.framework.handler-thread-pool-size` | 异步事件线程池大小（默认 20） |
+| `codingapi.framework.event.transaction.enable` | 事件事务提交后分发开关（默认 false） |