调研结论与决策

需求摘要

• 在 /Users/huyirui/program/itomix/git/vue-flow-editor2 中重建现有流程编辑器项目
• 保持 /Users/huyirui/program/itomix/git/vue-flow-editor 中既有业务逻辑和核心操作行为的一致性
• 将技术基座升级为最新的 Vue 3、Element Plus、LogicFlow 2.0 和 Vite
• 输出一份安全、可分阶段落地的迁移方案
• 在功能迁移前或迁移过程中优先补齐自动化测试护栏
• 尽量降低对人工点击回归和人工细查的依赖

测试环境信息

• 如后续调试页面登录态或接口联调时遇到登录问题，可优先使用测试账号：
• 用户名：jack
• 密码：000000
• 用途：测试环境排查登录与页面接入问题时使用

调研发现

• 新仓库当前是空仓库，尚未初始化工程
• 旧项目是“组件库式编辑器”，不是单纯的页面应用
• 旧项目的主要结构层次包括：
• src/editor：编辑器壳层、画布、工具栏、菜单、预览、表单/弹框组合
• src/shape：自定义节点、边、锚点、控制点
• src/behavior：拖拽、选择、连线、悬浮、框选等交互行为
• src/plugins/Command.ts：命令管理层，负责撤销/重做等命令式能力
• 旧项目使用 Vue CLI 风格构建链，并建立在 G6 3.x 时代的编辑器能力之上
• 旧项目同时存在 element-ui 与 element-plus 的混用痕迹，说明技术底座已经老化
• 旧项目对外契约不只是“画布渲染”，还包含 props、事件、插槽以及 onRef 暴露出的命令式 API
• src/editor/editor.ts 是迁移价值最高的行为核心，因为它集中承载了撤销、重做、删除、缩放、全选、新增边、新增节点、拖拽、更新等语义
• 旧项目画布通过行为注册组合了点击选择、节点拖拽、边拖拽、画布拖拽、悬浮态和框选能力
• 旧项目的 doc/index.vue 是非常接近真实业务接入的样板页，适合作为第一份自动化基线回归页面
• 旧项目基线页并不是纯静态示例页，启动后会请求流程版本和流程图数据接口；如果没有后端登录态，会触发 doc/axios.js 中的“登录失效”弹框逻辑
• 旧项目实际运行依赖 .nvmrc 指定的 Node v16.17.0，使用当前默认 Node 18 启动会触发 Vue CLI / webpack 运行异常
• 旧项目首页会通过 toolbarButtonHandler 隐藏默认工具栏中的 grid、miniMap，并在“当前启用版本”等于“当前选中版本”时继续隐藏 delete、undo、redo
• 旧项目基线测试使用统一的 /admin/** 接口拦截更稳，已知 flow_version、flow_nodes 返回固定数据，其他后台接口先兜底返回成功空对象，能够避免“登录失效”弹框打断测试
• 保存按钮链路会依赖 checkAllFlowNodePropertyAPI，只要该接口返回空数组，就能稳定进入“是否确定保存流程?”确认框
• 旧项目已经可以通过测试探针稳定验证 onRef 暴露出来的命令能力、节点选中、右侧面板打开、删除/撤销/重做等核心行为，无需在 E2E 中硬依赖 canvas 坐标点击
• 旧项目当前已经有 13 条稳定通过的基线回归，覆盖页面骨架、工具栏、版本区、预览、保存确认、实例契约、单选、多选、全选、节点面板、删除撤销、新增节点、新增连线
• 新项目已经完成第一轮工程初始化，当前具备 apps/demo + packages/flow-editor + tests 的最小双层结构
• 新项目首批平移的测试语义已经落地为 3 条基线用例：冒烟、工具栏、实例契约
• 新项目当前采用“兼容壳层 + 最小 LogicFlow 2.x 实例”的方式承接迁移起步，不再只是纯占位页面
• 在当前 npm 生态里，真正的 LogicFlow 2.x 包应使用 @logicflow/core 与 @logicflow/extension，而不是名为 logicflow 的同名旧包
• LogicFlow 2.x 的样式路径需要使用 @logicflow/core/lib/style/index.css 与 @logicflow/extension/lib/style/index.css
• LogicFlow 2.x 的 pluginsOptions 需要按插件名拆分；结合本地安装源码可确认 MiniMap 的 pluginName 实际为 miniMap
• 当前运行环境下，Playwright 自带 webServer 预检查会被本机代理或旧服务干扰，导致错误复用旧页面或误判端口占用；改为仓库脚本自管 Vite 生命周期后已稳定
• 直接对 Vue props 代理对象使用 structuredClone 会在浏览器中抛错；兼容层需要显式做图数据浅拷贝/结构化转换
• 旧项目保存时导出的边结构是 source/target/sourceAnchor/targetAnchor，而不是当前新仓夹具里的 sourceNodeId/targetNodeId
• 旧项目节点展示字段常见为 text/shape/activity/control，宿主语义字段再由业务补到 label/type
• 新项目已经实现统一适配流程：旧数据/新数据 -> normalizeGraphData -> toLogicFlowGraphData
• 适配层当前已覆盖三类高价值夹具：单节点、线性流、分支流
• 新项目当前已经具备基础可操作能力：工具栏缩放/适应画布、节点新增、节点选中、节点删除、预览打开
• 当前选中态已经和 LogicFlow 的 node:click、blank:click 事件同步，不再只是页面侧假状态
• 为了让页面尽快进入“可演示”状态，当前新增/删除节点仍以兼容层状态为主驱动，再同步给 LogicFlow 画布；后续再继续下沉到更完整的命令系统
• 当前页面已经移除了遮挡画布的过渡提示层，用户可以直接看到画布与侧边操作区
• 新项目当前已具备命令闭环的第一版能力：更新节点名称、创建新连线、撤销、重做
• 当前撤销/重做基于兼容层图数据快照实现，适用于现阶段的节点增删改和连线新增

技术决策

决策	原因
兼容性以“用户可感知行为一致”为准，而不是追求源码级一致	LogicFlow 2.0 和 Vite 的引入会带来内部架构变化
在迁移核心能力前先补旧项目基线回归测试	这能把“过去正确的行为”沉淀成可执行规格
将迁移拆成壳层、数据适配、交互模型、业务集成等阶段	能缩小每次改动的影响面，并便于逐阶段验收
将 doc/index.vue 作为第一份官方回归样板	它比孤立组件测试更接近真实接入场景
优先建设兼容层，而不是让宿主直接依赖 LogicFlow	这样更容易在新旧实现之间保持稳定契约
在设计文档之外单独输出实施计划	设计文档负责方向，实施计划负责逐任务落地
旧项目基线测试优先通过 Playwright 拦截初始化接口稳定运行	这样可以先摆脱真实后端登录态依赖，尽快把基线回归跑起来
工具栏回归测试应以基线页真实展示结果为准	旧项目示例页会二次过滤默认工具栏，不能直接拿组件默认配置做断言
基线接口 mock 优先做成统一 helper	后续新增预览、版本区、保存、删除等测试时可以直接复用同一套后台兜底逻辑
保存链路的第一批回归先验证“能弹确认框”	这比直接覆盖真实保存提交更稳，更适合作为基线起步
对 canvas 型交互优先引入测试探针而不是纯坐标点击	这样更稳定，也更适合作为后续 LogicFlow 迁移时的行为契约
旧项目阶段优先补“高价值行为基线”	先把最容易在迁移中回归的核心行为保护住，而不是追求面面俱到的 UI 覆盖
新项目初始化阶段先平移高价值测试语义，再逐步接入真实 LogicFlow 行为	这样能在每补一层实现时立刻看到与旧项目的偏差
新项目暂时只接入 MiniMap 作为 2.x 插件配置示例	先验证 2.x 包、样式、插件配置和运行方式，再继续补命令/交互迁移
新项目数据层优先支持“旧结构 + 新结构”双读	这样 demo、mock、后续 fixture 和真实保存链路可以逐步迁，不必一次改干净
新项目交互层先保证用户能完成“新增-选中-删除-预览”最小闭环	这是第一个真正值得人工打开页面查看的里程碑
命令系统先实现“对用户可见”的撤销/重做和连线创建	先优先满足页面体验，再考虑更深的引擎级命令抽象

遇到的问题

问题	处理方式
新仓库当前没有任何现成工程结构可供检查	在设计文档中补充了初始化与搭建建议
LogicFlow 2.x 的 npm 包名与用户常说的 logicflow 不一致	通过 npm search logicflow --json 与已安装包类型定义确认，应改用 @logicflow/core / @logicflow/extension
Playwright webServer 在当前机器上会把代理返回的 502 当成端口已占用	改成 scripts/run-e2e.mjs 手动拉起 Vite、等待 ready、执行测试并清理进程

参考资料

• 旧项目仓库：/Users/huyirui/program/itomix/git/vue-flow-editor
• 新项目仓库：/Users/huyirui/program/itomix/git/vue-flow-editor2
• 旧项目入口文件：/Users/huyirui/program/itomix/git/vue-flow-editor/src/editor/index.ts
• 旧项目依赖清单：/Users/huyirui/program/itomix/git/vue-flow-editor/package.json
• 旧项目 README：/Users/huyirui/program/itomix/git/vue-flow-editor/README.md
• 旧项目命令编排：/Users/huyirui/program/itomix/git/vue-flow-editor/src/editor/editor.ts
• 旧项目命令管理器：/Users/huyirui/program/itomix/git/vue-flow-editor/src/plugins/Command.ts
• 旧项目示例接入页：/Users/huyirui/program/itomix/git/vue-flow-editor/doc/index.vue
• 当前重构设计文档：/Users/huyirui/program/itomix/git/vue-flow-editor2/docs/plans/2026-03-31-flow-editor-rebuild-design.md
• 当前迁移实施计划：/Users/huyirui/program/itomix/git/vue-flow-editor2/docs/plans/2026-03-31-flow-editor-migration-implementation-plan.md
• 旧项目基线页说明：/Users/huyirui/program/itomix/git/vue-flow-editor/doc/README-基线回归页.md
• 新项目 LogicFlow 2.x 类型定义：/Users/huyirui/program/itomix/git/vue-flow-editor2/node_modules/@logicflow/core/lib/index.d.ts
• 新项目 LogicFlow 扩展类型定义：/Users/huyirui/program/itomix/git/vue-flow-editor2/node_modules/@logicflow/extension/lib/index.d.ts
• 新项目数据适配层：/Users/huyirui/program/itomix/git/vue-flow-editor2/packages/flow-editor/src/core/adapter/g6-to-logicflow.ts
• 新项目适配类型定义：/Users/huyirui/program/itomix/git/vue-flow-editor2/packages/flow-editor/src/core/schema/types.ts
• 新项目交互核心实现：/Users/huyirui/program/itomix/git/vue-flow-editor2/packages/flow-editor/src/components/FlowEditor.vue
• 新项目交互回归测试：/Users/huyirui/program/itomix/git/vue-flow-editor2/tests/e2e/interaction.spec.ts

可视化/浏览器结论

• 新项目基线页已可在浏览器中稳定渲染 .app、.vue-flow-editor、.vue-flow-editor-toolbar、.vue-flow-editor-canvas-target
• 新项目当前已跑通 3 条 Playwright 基线用例，验证页面骨架、工具栏语义和 onRef 实例契约
• 新项目基线页当前已经能直接消费旧口径 mock 数据，并通过适配层渲染到 LogicFlow 2.x
• 新项目基线页当前已经具备基础编辑能力，用户可以直接在页面上新增节点、选中节点、删除节点并打开预览
• 新项目基线页当前已经具备更完整的编辑演示能力，用户可以直接改节点名、创建连线并进行撤销/重做