flowable-devops/backend/docs/99-最终修正落地方案.md

最终修正落地方案（PM + 架构联合稿）

版本: v1.0 适用范围: 替代/修正 docs/01、docs/02、docs/03 中的关键设计，统一数据库为 MySQL 8.0，并固化 MVP 可落地路径。

—

一、产品与范围（MVP）

• 目标：可视化工作流平台，支持编辑器（ReactFlow）、节点配置（动态表单/字段映射/表达式）、执行、审批。
• 明确不做（MVP）：并行/子流程、定时/Webhook 触发、版本管理、多租户、复杂鉴权/监控、插件市场、AI 辅助。
• 闭环路径：前端构建 JSON → 后端转 BPMN（含条件分支）部署到 Flowable → 同步执行（审批点暂停并恢复）→ 执行/日志/任务可查询。

二、关键技术决策（统一口径）

• 数据库：MySQL 8.0（JSON 类型用于 definition/fields/output_schema/input/output 等），字符集 utf8mb4。
• 表达式：仅采用 Jakarta EL (JUEL)；Map-only 访问，禁用类/方法反射调用；前端不直接执行表达式，仅做占位/静态提示（第二期可加后端沙箱预览）。
• 执行：MVP 同步执行；Flowable 全局异步执行器关闭（async-executor-activate=false）；审批链路天然异步（等待用户完成任务）。
• 条件分支：JSON 模型以 edge.condition（JUEL 表达式）表示；转换层生成 ExclusiveGateway + 条件 SequenceFlow。
• 节点扩展：Spring 插件化（WorkflowNode 接口 + NodeTypeMetadata + outputSchema），NodeTypeRegistry 负责注册/查询。
• HTTP 客户端：WebClient（Spring WebFlux），统一超时与重试策略；不混用 MVC + WebFlux。

三、架构总览（修正摘要）

• 后端：Spring Boot 3.2 + Flowable 7.0.1 + MySQL 8.0 + Redis 7 + Jakarta EL；REST API（/api/workflows、/api/node-types、/api/tasks）。
• 前端：React 18 + TypeScript 5 + ReactFlow 11 + AntD 5 + Zustand + Axios；Vite 构建。
• 部署：Docker Compose（mysql:8、redis:7、backend），Nginx 反向代理（生产）。

四、后端落地清单

1. 依赖与配置

• POM 仅保留 spring-boot-starter-webflux；移除 spring-boot-starter-web；添加 jakarta.el 依赖；数据库驱动改为 mysql-connector-j。
• application.yml：
  • datasource.url=jdbc:mysql://.../workflow_db?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC
  • driver=com.mysql.cj.jdbc.Driver
  • flowable.async-executor-activate=false（MVP 同步）

2. DDL（MySQL 8）

• 将所有 JSONB 改为 JSON；去除 ::jsonb 强制类型转换；示例插入用合法 JSON 字符串。
• 关键表：
  • workflow_definitions(definition JSON, flowable_* 索引列保留)
  • node_types(fields JSON, output_schema JSON)
  • workflow_executions(input JSON)
  • node_execution_logs(input JSON, output JSON)

3. Flowable 集成修正

• ServiceTask 使用 delegateExpression("${genericNodeExecutor}")，由 Spring 托管，保证 @Autowired 生效。
• GenericNodeExecutor 从 execution.getCurrentFlowElement() 的 FieldExtension 读取 nodeType/nodeConfig，不再误用 execution 变量。
• WorkflowConverter：
  • 添加 ExclusiveGateway 与条件 SequenceFlow；对 edge.condition 设置 conditionExpression。
  • 保留 start→first 与 last→end 的连线（无条件）。

4. 表达式引擎（JUEL - Jakarta EL）

• import jakarta.el.*；构建 StandardELContext；注入 nodes/workflow/env 三大命名空间。
• 缓存表达式编译结果（LRU），无 ${} 的字符串走快路径直接返回。
• 安全：黑名单不足以防御，辅以受限 ELResolver（仅 Map/property 解析），禁用方法调用。

5. HTTP 节点

• 实现基于 WebClient：连接/响应超时；可选重试（限定幂等方法）。
• 输入：url/method/headers/body/timeout；输出：statusCode/body/headers/elapsed。

6. 观察性

• 写入 node_execution_logs：status、input、output、错误、时长；为 execution_id、status、时间建立索引。
• 审批与执行历史接口完成：执行详情包含各节点输入/输出摘要（注意脱敏）。

五、前端落地清单

• 字段映射：基于上游节点的 outputSchema 构建树；表达式值统一存储为“完整 ${...}”字符串。
• 表达式括号处理修复：使用正则 /^${|}$/g 去括号；选择时拼接为 \${${val}}。
• Zustand：统一管理 nodes/edges/selectedNode/currentWorkflow；保存时构建规范化 JSON。
• 性能：节点组件 memo、事件节流；避免使用不存在的 ReactFlow 属性。

六、API 与契约（MVP 必备）

• /api/workflows：create/update/get/list/delete/execute、getExecutions、getExecutionDetail。
• /api/node-types：list/get/by-category（返回 NodeTypeMetadata，含 fields/outputSchema）。
• /api/tasks：list/detail/complete/form（审批流）。
• 错误码：4xx（校验/鉴权）、5xx（系统错误）；分页与筛选采用标准 query 参数。

七、验收标准（MVP）

• 功能：
  • 场景 A：HTTP → 审批 → 邮件，端到端成功；审批暂停与恢复链路可见。
  • 场景 B：条件分支生效（200→邮件，否则→另一分支）。
• 性能：10 节点链路 < 500ms（不含审批），表达式评估基准 > 10k QPS，画布 100+ 节点不卡顿。
• 质量：核心模块单测覆盖 > 60%，E2E 场景跑通；关键事件与错误可观测。

八、两周 PoC 计划

• Week 1：
  • 完成 JSON→BPMN（ServiceTask + UserTask + ExclusiveGateway + 条件边）
  • JUEL 上下文与缓存；HTTP 节点（WebClient）
  • NodeTypeRegistry 注册/查询；node_types/definitions 基础表
• Week 2：
  • 审批任务 API（列表/表单/完成）；执行历史与节点日志入库
  • 前端编辑器/配置面板/字段映射；审批中心
  • 样例工作流 A/B 端到端自测并出基准数据

九、风险与缓解

• 转换层复杂：以最小节点集（HTTP/条件/变量/邮件/审批）完成 PoC，随后逐步扩展。
• 表达式安全：Map-only ELResolver + 严格长度/关键字校验；第二期引入后端沙箱预览接口。
• MySQL JSON 性能：关键查询加合适索引；大 JSON 字段只作存储与读取，不进行复杂查询。

十、后续演进（非 MVP）

• 异步执行（队列/线程池/回调）、定时/Webhook 触发、循环/并行/子流程、工作流版本管理、更多节点库、监控大盘、权限与多租户、导入导出、AI 辅助。