5.6 KiB
5.6 KiB
WARP.md
This file provides guidance to WARP (warp.dev) when working with code in this repository.
一、概览
- 当前仓库以设计文档为主（docs/），目标是实现一个可视化工作流平台（前端 ReactFlow，后端 Spring Boot + Flowable 7，数据库 MySQL 8）。
- 计划中的代码结构（以文档为准）：
- backend/（Spring Boot 3 + WebFlux + Flowable + Jakarta EL）
- frontend/（React 18 + TypeScript + Vite + AntD + Zustand）
- docs/（架构/后端/前端/落地方案等文档）
- 统一技术决策（MVP）：数据库 MySQL 8；表达式引擎 Jakarta EL（JUEL）；执行策略为“同步执行”（关闭全局异步执行器），审批节点自然暂停等待；条件分支通过 ExclusiveGateway + 条件边实现。
二、常用命令（按子项目执行）
- 先决条件
- Java 17+、Node 18+、Docker（本地 MySQL/Redis 推荐用容器启动）。
- 开发依赖服务（MySQL + Redis）
- 使用外部 MySQL（不使用 Docker）：
- 数据库地址：172.22.222.111:3306
- 数据库名称：flowable-devops
- 用户名：root（如不同请按实际填写）
- 密码：请通过环境变量安全注入（SPRING_DATASOURCE_PASSWORD），不要写入代码或命令行历史
- 使用外部 Redis（不使用 Docker）：
- 地址：172.22.222.111:6379
- 数据库：db5（spring.redis.database=5）
- 密码：请通过环境变量安全注入（SPRING_REDIS_PASSWORD），不要写入代码或命令行历史
- 后端（backend/，Maven）
- 安装依赖并构建（跳过测试）： mvn -q -DskipTests package
- 运行开发服务（读取 application.yml）： mvn spring-boot:run
- 运行全部测试： mvn -q test
- 仅运行单个测试类： mvn -q -Dtest=ExpressionEngineTest test
- 仅运行单个测试方法： mvn -q -Dtest=ExpressionEngineTest#testSimpleExpression test
- 常用环境变量（示例）：
- SPRING_DATASOURCE_URL=jdbc:mysql://172.22.222.111:3306/flowable-devops?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=UTC
- SPRING_DATASOURCE_USERNAME=root
- SPRING_DATASOURCE_PASSWORD=<请在本地安全设置该环境变量>
- SPRING_REDIS_HOST=172.22.222.111
- SPRING_REDIS_PORT=6379
- SPRING_REDIS_PASSWORD=<请在本地安全设置该环境变量>
- SPRING_REDIS_DATABASE=5
- 前端（frontend/，Vite）
- 安装依赖： npm i
- 启动开发服务： npm run dev
- 构建生产包： npm run build
- 代码检查（ESLint，若已配置）： npx eslint .
- 前端 API 基址（示例）：
- 开发：VITE_API_BASE_URL=http://localhost:8080
三、端到端开发流程（本地）
- 启动 MySQL/Redis（见上文 Docker 命令）。
- 启动后端：在 backend/ 执行 mvn spring-boot:run。
- 启动前端：在 frontend/ 执行 npm run dev（默认 http://localhost:3000）。
- 在前端编辑器创建/编辑工作流，保存 JSON；后端将 JSON 转 BPMN 并部署 Flowable；执行时在审批节点暂停，审批完成后继续。
四、关键架构速览（帮助快速理解大图）
- 前端
- 画布：ReactFlow；节点面板 + 配置面板（动态表单 + 字段映射 + 表达式输入）。
- 字段映射：基于上游节点的 outputSchema 构建字段树；表达式统一为 ${...} 字符串。
- 主要页面：工作流列表、工作流编辑、执行历史、审批中心。
- 后端
- 控制器：/api/workflows（创建/更新/执行/历史）、/api/node-types（类型/元数据）、/api/tasks（审批）。
- 转换层：JSON → BPMN，生成 ServiceTask（delegateExpression 指向 ${genericNodeExecutor}）、UserTask、ExclusiveGateway + 条件 SequenceFlow。
- 执行：GenericNodeExecutor 读取当前 ServiceTask 的 FieldExtension（nodeType/nodeConfig），调用对应节点实现（WorkflowNode），并将节点输入/输出写入流程变量 nodes 与日志表。
- 表达式：Jakarta EL（JUEL），仅 Map 属性访问；上下文包含 nodes/workflow/env；无 ${} 字符串走快路径。
- 数据：
- Flowable ACT_* 表（引擎自建）
- 业务表（MySQL）：workflow_definitions(definition JSON)、node_types(fields/output_schema JSON)、workflow_executions(input JSON)、node_execution_logs(input/output JSON)
- 执行策略
- MVP 同步执行；审批（User Task）自然暂停/恢复；后续迭代再引入全局异步与队列。
五、对未来在仓库内协作的注意事项（Agent 关键提示）
- 仅使用 Jakarta EL（JUEL）；不要切换为 JavaScript 表达式引擎。
- ServiceTask 一律使用 delegateExpression（${genericNodeExecutor}），不要使用 ImplementationType.CLASS，避免失去 Spring 注入能力。
- edge.condition 使用 JUEL 表达式；转换层需在 BPMN 中为条件边设置 conditionExpression。
- 节点扩展：实现 WorkflowNode 接口，并在 NodeTypeRegistry 注册；确保提供 outputSchema 供前端字段映射使用。
- 观察性：将每个节点的输入/输出/耗时/状态写入 node_execution_logs，便于问题定位与验收性能指标。
- 数据库相关：MySQL 8；JSON 字段仅用于存储与读取，不做复杂查询；字符集统一 utf8mb4。
六、文档索引（优先阅读）
- docs/01-架构总览.md（统一到 MySQL + JUEL 的大图）
- docs/02-后端技术设计.md（Flowable 集成要点、条件分支与执行器修正、MySQL DDL）
- docs/03-前端技术设计.md（字段映射/表达式一致性）
- docs/04-数据模型设计.md（JSON Schema：WorkflowDefinition/Node/Edge/NodeTypeMetadata 等）
- docs/05-API契约.md（/api/workflows、/api/node-types、/api/tasks 的请求/响应）
- docs/99-最终修正落地方案.md（PM + 架构联合终版，含 PoC 计划与验收标准）