# 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 推荐用容器启动）。

1) 开发依赖服务（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），不要写入代码或命令行历史

2) 后端（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

3) 前端（frontend/，Vite）
- 安装依赖：
  npm i
- 启动开发服务：
  npm run dev
- 构建生产包：
  npm run build
- 代码检查（ESLint，若已配置）：
  npx eslint .
- 前端 API 基址（示例）：
  - 开发：VITE_API_BASE_URL=http://localhost:8080

三、端到端开发流程（本地）
1) 启动 MySQL/Redis（见上文 Docker 命令）。
2) 启动后端：在 backend/ 执行 mvn spring-boot:run。
3) 启动前端：在 frontend/ 执行 npm run dev（默认 http://localhost:3000）。
4) 在前端编辑器创建/编辑工作流，保存 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 计划与验收标准）