98 lines
6.2 KiB
Markdown
98 lines
6.2 KiB
Markdown
# 最终修正落地方案（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 辅助。
|