|
| 1 | +# 流程编排系统 — 前端开发计划 |
| 2 | + |
| 3 | +## 一、目标与范围 |
| 4 | + |
| 5 | +- **目标**：在现有后端接口（engine 相关 Controller）基础上，完成可用的前端：应用与标签、数据源（端点）、插件（节点）维护、流程编排器、执行与指标、插件市场。 |
| 6 | +- **范围**：仅前端（nexus-admin）；接口以 `@/services/engine` 为准，不涉及后端改动。 |
| 7 | +- **依赖关系（前端视角）** |
| 8 | + - 流程编排依赖「可编排的节点」→ 节点与「插件」对应 → 需先有**插件/节点维护**（含可选市场）。 |
| 9 | + - 部分节点（如 DB）依赖「数据源」→ 需先有**数据源/端点维护**。 |
| 10 | + - 流程挂在「应用」下 → 需先有**应用管理**（含标签）。 |
| 11 | + |
| 12 | +因此推荐顺序：**应用 → 数据源(端点) → 插件(节点) → 流程编排 → 执行与指标 → 插件市场（可选）**。 |
| 13 | + |
| 14 | +--- |
| 15 | + |
| 16 | +## 二、阶段总览 |
| 17 | + |
| 18 | +| 阶段 | 模块 | 产出 | 依赖 | |
| 19 | +|------|------|------|------| |
| 20 | +| 1 | 应用与标签 | 应用列表/表单、标签管理、绑定解绑 | 无 | |
| 21 | +| 2 | 数据源（端点） | 端点列表/表单、测试连接、端点类型配置（可选） | 无 | |
| 22 | +| 3 | 插件（节点）维护 | 可用节点列表、Schema 预览、可选市场安装 | 无（市场可选） | |
| 23 | +| 4 | 流程编排器 | 画布、节点面板、连线、节点配置、草稿/发布、版本与路由状态 | 阶段 1/2/3 | |
| 24 | +| 5 | 执行与指标 | 执行列表、Trace 详情、死信、指标图表 | 阶段 4 已可发布 | |
| 25 | +| 6 | 插件市场（可选） | 市场浏览、安装/卸载、评价 | 阶段 3 | |
| 26 | + |
| 27 | +--- |
| 28 | + |
| 29 | +## 三、分阶段开发计划 |
| 30 | + |
| 31 | +### 阶段 1：应用与标签管理 |
| 32 | + |
| 33 | +**目的**：能创建/管理「应用」和「标签」，为流程编排提供“按应用选流程”的入口。 |
| 34 | + |
| 35 | +**页面与功能**： |
| 36 | + |
| 37 | +1. **应用列表页**（建议路由如 `/engine/apps`） |
| 38 | + - 列表：名称、类型、状态、标签、操作（编辑/删除）。 |
| 39 | + - 筛选：名称、类型、状态、标签。 |
| 40 | + - 操作：新增应用、编辑、删除（二次确认）。 |
| 41 | + - 接口：`appService.getApps(AppQuery)`、`appService.createApp`、`appService.updateApp`、`appService.deleteApp`。 |
| 42 | + |
| 43 | +2. **应用表单（新增/编辑）** |
| 44 | + - 字段：名称、类型、图标、状态、优先级、日志级别、备注等（与 `EngineApp` 一致）。 |
| 45 | + - 提交：调用 `createApp` / `updateApp`。 |
| 46 | + |
| 47 | +3. **标签管理**（可独立页或弹窗/抽屉） |
| 48 | + - 列表：按类型筛选，展示标签名、类型、操作。 |
| 49 | + - 操作：新增标签、编辑、删除。 |
| 50 | + - 绑定/解绑：选择应用后，勾选标签保存 → 调用 `tagService.bindTags`；解绑 → `tagService.unbindTag`。 |
| 51 | + - 接口：`tagService.listTags`、`tagService.createTag`、`tagService.updateTag`、`tagService.deleteTag`、`bindTags`、`unbindTag`。 |
| 52 | + |
| 53 | +**完成标准**： |
| 54 | +- 能创建/编辑/删除应用，能管理标签并绑定到应用。 |
| 55 | +- 列表与筛选正常，后续「流程列表」可基于 appId 拉取流程。 |
| 56 | + |
| 57 | +**建议文件/目录**： |
| 58 | +- 使用现有 `views/engine/App` 占位，实现为完整列表+表单。 |
| 59 | +- 标签可为同页 Tab 或独立路由（如 `/engine/tags`），按你菜单结构定。 |
| 60 | + |
| 61 | +--- |
| 62 | + |
| 63 | +### 阶段 2：数据源（端点）管理 |
| 64 | + |
| 65 | +**目的**：维护 HTTP、DB、WebService 等端点，供流程中「连接类」节点（如 DB 节点）选择数据源。 |
| 66 | + |
| 67 | +**页面与功能**： |
| 68 | + |
| 69 | +1. **端点列表页**（如 `/engine/endpoints`） |
| 70 | + - 列表：名称、类型、分类、状态、创建时间、操作。 |
| 71 | + - 筛选：名称、类型、分类、状态（与 `EndpointSearchParams` 一致）。 |
| 72 | + - 分页。 |
| 73 | + - 操作：新增、编辑、删除、批量删除。 |
| 74 | + - 接口：`endpointService.getEndpointList`、`endpointService.addEndpoint`、`endpointService.updateEndpoint`、`endpointService.deleteEndpoint`、`endpointService.batchDelete`。 |
| 75 | + |
| 76 | +2. **端点表单（新增/编辑）** |
| 77 | + - 基础信息：名称、描述、端点类型、分类、模式、状态、备注。 |
| 78 | + - 连接配置：根据 `endpointType` 动态渲染（如 DB：主机、端口、库名、用户名、密码等），对应实体的 `config` 字段。 |
| 79 | + - 可选：保存前「测试连接」按钮（若后端有测试接口则调用）。 |
| 80 | + - 提交：组装为 `Endpoint` 调用 `addEndpoint` / `updateEndpoint`。 |
| 81 | + |
| 82 | +3. **端点类型配置**（可选，多为管理员功能） |
| 83 | + - 列表：端点类型、类型名称、Schema 版本等。 |
| 84 | + - 用于查看/维护各类型的 `schemaFields`（若后端支持配置化），便于前端动态表单与 DB 节点等一致。 |
| 85 | + - 接口：`endpointConfigService.list`、`endpointConfigService.getById` 等。 |
| 86 | + |
| 87 | +**完成标准**： |
| 88 | +- 能创建/编辑/删除端点，列表与筛选正常。 |
| 89 | +- 至少一种类型（如 DB）的表单与测试连接可用。 |
| 90 | +- 流程编排里「DB 节点」配置时能下拉选择已创建的端点（阶段 4 实现选择器）。 |
| 91 | + |
| 92 | +**建议文件/目录**： |
| 93 | +- 实现 `views/engine/Endpoint`：列表 + 表单（含按类型的 config 动态表单）。 |
| 94 | +- 若需单独管理类型配置，可用 `views/engine/EndpointConfig` 或同模块下子页。 |
| 95 | + |
| 96 | +--- |
| 97 | + |
| 98 | +### 阶段 3：插件（节点）维护 |
| 99 | + |
| 100 | +**目的**：让配置与运营人员能看到「有哪些节点可用」、每个节点的配置项（Schema），并为流程编排提供节点面板数据源；若做市场，可在此阶段增加安装/卸载。 |
| 101 | + |
| 102 | +**页面与功能**： |
| 103 | + |
| 104 | +1. **可用插件/节点列表页**（如 `/engine/plugins`） |
| 105 | + - 数据源：`pluginService.listAvailable(tenantId, pluginType)`（内置 + 已安装），或先只用 `pluginService.getRegistryGrouped()` 做只读展示。 |
| 106 | + - 展示：按分类（trigger/processor/connector/control）分组，每项显示名称、类型、描述、图标等。 |
| 107 | + - 点击某项：进入「节点详情」或抽屉，展示该插件的 `configSchema`（只读或简单预览），便于理解编排时该节点有哪些配置项。 |
| 108 | + |
| 109 | +2. **节点 Schema 预览** |
| 110 | + - 根据 `configSchema` 做简单渲染（只读）：字段名、类型、必填、默认值等，不要求可编辑（编辑在编排器里做）。 |
| 111 | + - 若后端返回 `PluginVersion` 或 `MarketListingVO.latestVersion`，可用其 `configSchema`。 |
| 112 | + |
| 113 | +3. **插件市场（可选，可合并到本阶段或单独阶段 6）** |
| 114 | + - 市场列表：`marketService.search(params)`，分页、关键字、分类筛选。 |
| 115 | + - 详情：`marketService.getDetail(listingId)`，展示说明、最新版本、安装数、评分等。 |
| 116 | + - 安装/卸载：`marketService.install`、`marketService.uninstall`；已安装列表 `marketService.listInstallations(tenantId)`。 |
| 117 | + - 安装后，`listAvailable` 会多出该插件，编排器节点面板自动出现新节点类型。 |
| 118 | + |
| 119 | +**完成标准**： |
| 120 | +- 能查看当前可用节点列表（按分类），能查看任意节点的配置 Schema。 |
| 121 | +- 若做市场：能浏览、安装、卸载，安装后编排器可见新节点。 |
| 122 | + |
| 123 | +**建议文件/目录**： |
| 124 | +- 实现 `views/engine/Plugin`：列表（分组）+ 节点详情/Schema 预览。 |
| 125 | +- 若做市场：实现 `views/engine/Market`（列表、详情、安装/卸载、已安装）。 |
| 126 | + |
| 127 | +--- |
| 128 | + |
| 129 | +### 阶段 4：流程编排器 |
| 130 | + |
| 131 | +**目的**：按应用选择流程，在画布上拖拽节点、连线、配置节点（含选数据源），保存草稿、发布，并查看版本与路由状态。 |
| 132 | + |
| 133 | +**页面与功能**： |
| 134 | + |
| 135 | +1. **流程列表（按应用）** |
| 136 | + - 入口：从「应用管理」进入某应用下的流程列表，或全局「流程管理」先选应用再列流程。 |
| 137 | + - 列表：`flowDefinitionService.listByAppId(appId)`，展示 flowKey、flowName、描述、操作（编排/编辑/删除）。 |
| 138 | + - 操作：新建流程（调用 `flowDefinitionService.create`）、删除流程。 |
| 139 | + |
| 140 | +2. **编排器布局** |
| 141 | + - 左侧：**节点面板**。数据源：`pluginService.listAvailable(tenantId, pluginType)`（或按分类分 Tab），展示可拖拽节点类型（名称+图标）。 |
| 142 | + - 中间：**画布**。使用 ReactFlow 或你现有 Workflow 画布，支持从左侧拖入节点、连线（source/target）。 |
| 143 | + - 右侧：**节点配置面板**。选中画布上某节点时，根据该节点对应的 `configSchema` 渲染表单；若为 DB 类节点，增加「数据源」选择（下拉调用端点列表或 `endpointService.getEndpointList` 的简化版）。 |
| 144 | + |
| 145 | +3. **画布与数据** |
| 146 | + - 加载：进入编排页时根据 flowId 调用 `flowVersionService.getCurrent(flowId)` 或草稿接口，将 `flow_snapshot` 或草稿的 nodes/edges 转成画布模型（id、nodeKey、position、data.config 等）。 |
| 147 | + - 保存草稿：把画布 nodes/edges 转成后端 DTO（nodeKey、sourceNodeKey、targetNodeKey、config 等），调用 `flowVersionService.saveDraft(flowId, payload)`。 |
| 148 | + - 发布：调用 `flowVersionService.publish(flowId, tag?, remark?)`，成功后可选提示并刷新「当前版本」与路由状态。 |
| 149 | + |
| 150 | +4. **版本与路由** |
| 151 | + - 版本列表：`flowVersionService.listVersions(flowId)`，展示版本号、状态、发布时间等。 |
| 152 | + - 当前版本与路由状态：`flowVersionService.getCurrent`、`flowVersionService.getRouteStatus(flowId)`，展示是否运行中、最后触发时间等。 |
| 153 | + - 操作：回滚到某版本（调用 `flowVersionService.rollback`）、重新部署（`flowVersionService.redeploy`）、停止路由（`flowVersionService.stopRoute`），按需在 UI 暴露。 |
| 154 | + |
| 155 | +5. **节点配置与数据源** |
| 156 | + - 通用：根据插件 `configSchema` 生成表单，写入节点 `config`。 |
| 157 | + - DB/连接类节点：表单项中增加「端点/数据源」选择，值为 endpointId，保存到 config；运行时由后端根据 endpointId 解析连接信息。 |
| 158 | + |
| 159 | +**完成标准**： |
| 160 | +- 能选择应用 → 选流程 → 打开编排器。 |
| 161 | +- 能从左侧拖入多种节点、连线、配置节点（含选数据源）。 |
| 162 | +- 能保存草稿、发布，并看到版本与路由状态。 |
| 163 | +- 发布后后端路由可运行，执行记录能在阶段 5 查到。 |
| 164 | + |
| 165 | +**建议文件/目录**： |
| 166 | +- 在 `views/engine/Flow` 下实现：流程列表子页 + 编排器页（或复用/迁移现有 `views/integrated/Workflow`，逐步把接口切到 `@/services/engine`）。 |
| 167 | +- 节点面板、画布、配置面板拆成子组件，便于维护。 |
| 168 | + |
| 169 | +--- |
| 170 | + |
| 171 | +### 阶段 5：执行与指标 |
| 172 | + |
| 173 | +**目的**：查看某流程/版本的执行记录、单次 Trace 的节点明细、死信处理、以及简单指标图表。 |
| 174 | + |
| 175 | +**页面与功能**： |
| 176 | + |
| 177 | +1. **执行列表** |
| 178 | + - 筛选：流程（flowId）、版本（flowVersionId）、时间范围（from/to，必填）。 |
| 179 | + - 列表：`executionService.pageExecutions(params)`，展示 traceId、状态、开始/结束时间、耗时等。 |
| 180 | + - 操作：点击某条进入「Trace 详情」。 |
| 181 | + |
| 182 | +2. **Trace 详情** |
| 183 | + - 入参：traceId + 时间范围（与列表一致或从列表带过来）。 |
| 184 | + - 调用：`executionService.getByTraceId(traceId, from, to)` 得到 FlowExecution；`executionService.listNodeExecutions(executionId, from, to)` 得到节点明细。 |
| 185 | + - 展示：流程级状态、耗时；节点列表（nodeKey、状态、耗时、错误信息等），可选简单时间线或列表。 |
| 186 | + |
| 187 | +3. **死信管理** |
| 188 | + - 列表：`executionService.pageDeadLetters(params)`，筛选 status、时间范围。 |
| 189 | + - 操作：单条「标记已解决」→ `executionService.resolveDeadLetter(id, createdTime)`。 |
| 190 | + |
| 191 | +4. **指标** |
| 192 | + - 筛选：flowId、flowVersion、粒度（MINUTE/HOUR/DAY）、时间范围。 |
| 193 | + - 接口：`metricsService.queryFlowMetrics`、`metricsService.queryNodeMetrics`。 |
| 194 | + - 展示：折线图/柱状图（请求量、成功率、延迟 P95 等），按你们实际返回字段定。 |
| 195 | + |
| 196 | +**完成标准**： |
| 197 | +- 能按流程+版本+时间查执行列表，能点进 Trace 看节点明细。 |
| 198 | +- 能查死信并标记已解决。 |
| 199 | +- 能看流程/节点维度的指标图。 |
| 200 | + |
| 201 | +**建议文件/目录**： |
| 202 | +- 实现 `views/engine/Execution`（执行列表 + Trace 详情 + 死信）。 |
| 203 | +- 实现 `views/engine/Metrics`（指标筛选 + 图表），或与 Execution 同模块不同 Tab。 |
| 204 | + |
| 205 | +--- |
| 206 | + |
| 207 | +### 阶段 6：插件市场（可选） |
| 208 | + |
| 209 | +**目的**：提供「发现与安装插件」的入口，安装后编排器节点面板自动出现对应节点。 |
| 210 | + |
| 211 | +**页面与功能**： |
| 212 | + |
| 213 | +1. **市场首页/列表** |
| 214 | + - 调用 `marketService.search(params)`，分页、关键字、分类、是否内置筛选。 |
| 215 | + - 卡片：图标、名称、摘要、安装数、评分、安装按钮（未安装时）。 |
| 216 | + |
| 217 | +2. **插件详情** |
| 218 | + - `marketService.getDetail(listingId)`：说明、最新版本、configSchema 预览、评价列表等。 |
| 219 | + - 操作：安装（选择版本可选）、卸载（若已安装）。 |
| 220 | + |
| 221 | +3. **已安装** |
| 222 | + - `marketService.listInstallations(tenantId)`，列表展示已安装插件，支持禁用/启用/卸载（对应后端 disable/enable/uninstall）。 |
| 223 | + |
| 224 | +**完成标准**： |
| 225 | +- 能浏览市场、安装/卸载插件。 |
| 226 | +- 安装后，编排器「可用节点」列表更新（依赖阶段 3/4 使用 `listAvailable`）。 |
| 227 | + |
| 228 | +**建议文件/目录**： |
| 229 | +- 实现 `views/engine/Market`（若阶段 3 只做了列表与 Schema 预览，这里补市场完整能力）。 |
| 230 | + |
| 231 | +--- |
| 232 | + |
| 233 | +## 四、路由与菜单建议 |
| 234 | + |
| 235 | +在现有菜单下增加「引擎」或「集成」分组（与现有路由风格一致），例如： |
| 236 | + |
| 237 | +| 菜单项 | 路由示例 | |
| 238 | +|--------------|-------------------------------| |
| 239 | +| 应用管理 | `/engine/apps` | |
| 240 | +| 标签管理 | `/engine/tags`（或合并到应用页） | |
| 241 | +| 数据源/端点 | `/engine/endpoints` | |
| 242 | +| 端点类型配置 | `/engine/endpoint-configs`（可选） | |
| 243 | +| 插件/节点 | `/engine/plugins` | |
| 244 | +| 流程编排 | `/engine/flows`（列表）、`/engine/flows/:flowId/editor`（画布） | |
| 245 | +| 执行记录 | `/engine/executions` | |
| 246 | +| 指标 | `/engine/metrics` 或 `/engine/executions?tab=metrics` | |
| 247 | +| 插件市场 | `/engine/market` | |
| 248 | + |
| 249 | +--- |
| 250 | + |
| 251 | +## 五、接口与类型约定 |
| 252 | + |
| 253 | +- 所有请求使用 `@/services/engine` 下各模块（app、flow、plugin、market、endpoint、execution、metrics）。 |
| 254 | +- 实体与 DTO 与后端一致：`EngineApp`、`FlowDefinition`、`FlowVersion`、`Endpoint`、`PluginDefinition`、`MarketListingVO`、`FlowExecution`、`NodeExecution`、`DeadLetter`、`MetricsFlowAgg`、`MetricsNodeAgg` 等，避免前端自造结构。 |
| 255 | +- 时间范围：执行、死信、指标查询统一传 ISO 8601 的 `from`/`to`，与后端分区表与接口一致。 |
| 256 | + |
| 257 | +--- |
| 258 | + |
| 259 | +## 六、建议执行顺序小结 |
| 260 | + |
| 261 | +1. **阶段 1**：应用与标签 → 有「应用」可挂流程。 |
| 262 | +2. **阶段 2**：端点/数据源 → DB 等节点有数据源可选。 |
| 263 | +3. **阶段 3**：插件/节点维护（+ 可选市场）→ 节点面板有数据、可安装新节点。 |
| 264 | +4. **阶段 4**：流程编排器 → 画布、节点、配置、草稿、发布、版本与路由。 |
| 265 | +5. **阶段 5**：执行与指标 → 可观测、死信处理。 |
| 266 | +6. **阶段 6**：插件市场完整能力（若未在阶段 3 做完）。 |
| 267 | + |
| 268 | +按该顺序做，前端依赖清晰，每阶段都可单独验收。 |
0 commit comments