Hooke / vue-flow-editor2

Go to a project
Toggle navigation Toggle navigation pinning
Switch branch/tag
2026-03-31-flow-editor-migration-implementation-plan.md 16.3 KB

流程编辑器迁移实施计划

执行说明： 后续真正进入实施阶段时，建议逐任务执行，并在每个任务完成后立即补充验证结果与文档记录。

目标： 先在旧项目建立自动化行为基线，再在新项目中以 Vue 3、Element Plus、LogicFlow 2.0、Vite 逐步重建流程编辑器，并在每一阶段保持可验证、可回退。

架构方式： 采用“双仓协同 + 测试先行”的迁移策略。旧仓库负责定义真实业务行为基线，新仓库负责按兼容契约逐层实现替代能力，测试、夹具、操作脚本尽量复用同一套语义。

技术栈： Vue 3、TypeScript、Vite、Element Plus、LogicFlow 2.0、Vitest、Vue Test Utils、Playwright

执行原则

  • 先迁测试，再迁功能。
  • 先保护旧行为，再替换底层引擎。
  • 每个阶段只处理一个主要风险面。
  • 每个任务都必须带验证动作。
  • 每次提交只包含一个清晰目标，避免大批量混合改动。

目录规划

旧项目建议新增目录

  • /Users/huyirui/program/itomix/git/vue-flow-editor/tests/e2e
  • /Users/huyirui/program/itomix/git/vue-flow-editor/tests/fixtures/graphs
  • /Users/huyirui/program/itomix/git/vue-flow-editor/tests/fixtures/operations
  • /Users/huyirui/program/itomix/git/vue-flow-editor/tests/helpers
  • /Users/huyirui/program/itomix/git/vue-flow-editor/playwright.config.ts

新项目建议初始目录

  • /Users/huyirui/program/itomix/git/vue-flow-editor2/apps/demo
  • /Users/huyirui/program/itomix/git/vue-flow-editor2/packages/flow-editor
  • /Users/huyirui/program/itomix/git/vue-flow-editor2/tests/e2e
  • /Users/huyirui/program/itomix/git/vue-flow-editor2/tests/fixtures/graphs
  • /Users/huyirui/program/itomix/git/vue-flow-editor2/tests/fixtures/operations
  • /Users/huyirui/program/itomix/git/vue-flow-editor2/tests/unit

任务 1：冻结旧项目基线样板页

目标： 把旧项目 doc/index.vue 固定为首个官方回归入口，避免后续基线页面持续漂移。

涉及文件：

  • 修改：/Users/huyirui/program/itomix/git/vue-flow-editor/doc/index.vue
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor/doc/README-基线回归页.md

步骤：

  1. 检查 doc/index.vue 当前依赖的数据、事件、插槽和演示能力。
  2. 标记哪些区域属于回归必测区，哪些属于展示性区块。
  3. 在基线说明文档中写清楚启动方式、演示入口、核心交互列表。
  4. 尽量减少基线页中的随机性数据和不稳定异步行为。
  5. 记录该页面暴露的 onRef 方法、事件和业务钩子。

验证：

  • 能稳定打开旧项目示例页。
  • 页面至少包含节点渲染、工具栏、右侧面板、节点编辑、删除、预览能力。

完成标准：

  • 任何人都能根据文档找到旧项目基线回归入口。

任务 2：在旧项目接入 Playwright 基础设施

目标： 让旧项目具备最小可运行的端到端测试能力。

涉及文件：

  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor/package.json 中测试脚本
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor/playwright.config.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor/tests/e2e/smoke.spec.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor/tests/helpers/editor-page.ts

步骤：

  1. 安装并配置 Playwright。
  2. 配置旧项目本地启动命令与 baseURL。
  3. 编写最小冒烟测试，只验证页面能正常加载、画布存在、工具栏存在。
  4. 抽一层页面对象，避免测试直接依赖过深 DOM 结构。
  5. 先确保测试可以本地稳定运行。

验证：

  • 执行 Playwright 冒烟用例能够通过。
  • 启动失败时能够明确定位是服务问题还是测试问题。

完成标准：

  • 旧项目具备第一条可重复执行的自动化用例。

任务 3：沉淀第一批图数据夹具

目标： 把旧项目中的典型流程图数据整理成稳定的测试夹具。

涉及文件：

  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor/tests/fixtures/graphs/base-single-node.json
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor/tests/fixtures/graphs/linear-approval-flow.json
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor/tests/fixtures/graphs/branching-flow.json
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor/tests/fixtures/README.md

步骤：

  1. 从旧项目示例页提取最小单节点数据。
  2. 提取线性审批流数据。
  3. 提取包含分支的流程图数据。
  4. 去掉无关噪音字段，保留渲染与行为必需字段。
  5. 为每份夹具补充用途说明。

验证：

  • 每份夹具都能在旧项目中正常读入。
  • 节点数、边数、关键标签与预期一致。

完成标准：

  • 至少三份高价值夹具可在自动化测试中复用。

任务 4：补齐旧项目核心行为回归脚本

目标： 先把最关键、最容易回归出问题的交互变成自动化脚本。

涉及文件：

  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor/tests/e2e/toolbar.spec.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor/tests/e2e/selection.spec.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor/tests/e2e/delete-undo-redo.spec.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor/tests/e2e/node-edge-create.spec.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor/tests/e2e/panel-preview.spec.ts

步骤：

  1. 先覆盖工具栏：网格、缩略图、缩放、适应画布、实际尺寸。
  2. 覆盖选择行为：单选、多选、框选、全选。
  3. 覆盖删除、撤销、重做。
  4. 覆盖新增节点、拖拽连线。
  5. 覆盖双击节点打开右侧面板、预览弹窗打开。

验证：

  • 每条用例都能输出清晰断言结果。
  • 测试失败时能快速定位到是工具栏、选择、命令还是新增链路。

完成标准：

  • 旧项目主路径至少有 8 到 12 条自动化场景。

任务 5：补齐旧项目对外契约断言

目标： 把 onRef、事件和 hooks 这些宿主契约也纳入自动化保护。

涉及文件：

  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor/tests/e2e/contract.spec.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor/tests/helpers/contract-probe.ts

步骤：

  1. 在基线页中增加仅供测试读取的探针输出。
  2. 记录 onRef 是否暴露出预期方法。
  3. 记录 click-node、select-change 等事件是否触发。
  4. 记录 beforeAdd/afterAdd、beforeDelete/afterDelete 的触发顺序。
  5. 对外契约断言不要依赖具体引擎内部对象结构。

验证：

  • 自动化用例能稳定拿到对外契约状态。
  • hook 的触发次数和顺序可被断言。

完成标准：

  • “宿主接入不变”被转成测试可验证事实。

任务 6：初始化新项目工程骨架

目标： 在新仓库建立标准工程结构，但先不急于实现完整编辑能力。

涉及文件：

  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/package.json
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/pnpm-workspace.yaml
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/tsconfig.json
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/vite.config.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/apps/demo/*
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/packages/flow-editor/*

步骤：

  1. 初始化 Vite + Vue 3 + TypeScript 工程。
  2. 接入 Element Plus。
  3. 接入 LogicFlow 2.0。
  4. 建立 apps/demo 和 packages/flow-editor 双层结构。
  5. 让示例页能成功启动并展示一个最小占位编辑器。

验证：

  • dev 启动成功。
  • 页面能正常渲染占位编辑器壳层。

完成标准：

  • 新项目具备最小可运行骨架。

任务 7：把旧项目测试资产迁入新项目

目标： 让新项目从一开始就共享旧项目的测试语义与夹具。

涉及文件：

  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/tests/fixtures/graphs/*
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/tests/fixtures/operations/*
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/playwright.config.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/tests/e2e/smoke.spec.ts

步骤：

  1. 迁入旧项目图数据夹具。
  2. 保持文件命名和语义一致。
  3. 在新项目创建对应的 Playwright 配置。
  4. 先落一条冒烟测试，验证新项目示例页可打开。
  5. 为后续复用行为脚本预留页面对象封装。

验证：

  • 新项目能运行第一条端到端测试。
  • 夹具目录结构与旧项目保持一致。

完成标准：

  • 新项目测试底座与旧项目开始对齐。

任务 8：实现数据适配层

目标： 先让旧数据可以在新项目中被读入，而不是一开始就实现全部交互。

涉及文件：

  • 新增：/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/tests/unit/g6-to-logicflow.spec.ts

步骤：

  1. 定义旧图数据和新图数据的目标类型。
  2. 先完成节点映射。
  3. 再完成边映射。
  4. 保留关键业务字段和节点文案。
  5. 为异常输入写保护逻辑。

验证：

  • 单元测试覆盖单节点、线性流、分支流三种夹具。
  • 新项目示例页可以静态渲染夹具。

完成标准：

  • 旧图数据在新项目可读、可画、可断言。

任务 9：实现兼容层与编辑器壳层

目标： 先恢复宿主侧最容易感知的对外接口，而不是马上深入复杂交互。

涉及文件：

  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/packages/flow-editor/src/components/FlowEditor.vue
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/packages/flow-editor/src/compat/props.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/packages/flow-editor/src/compat/events.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/packages/flow-editor/src/compat/ref-api.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/tests/unit/compat-contract.spec.ts

步骤：

  1. 先定义兼容 props。
  2. 再定义兼容事件映射。
  3. 实现 onRef 暴露对象的基础结构。
  4. 先接通只读渲染链路。
  5. 在示例页中以旧项目调用方式接入新组件。

验证：

  • 单元测试可验证 props 和 onRef 基本结构。
  • 示例页能用旧项目风格参数启动新编辑器。

完成标准：

  • 宿主接入层具备最小兼容能力。

任务 10：实现命令系统第一批能力

目标： 先恢复最基础但最高频的命令语义。

涉及文件：

  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/packages/flow-editor/src/core/commands/commander.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/packages/flow-editor/src/core/commands/use-editor-commands.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/tests/unit/commander.spec.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/tests/e2e/toolbar.spec.ts

步骤：

  1. 先实现命令注册、执行、撤销、重做骨架。
  2. 实现缩放、适应画布、实际尺寸。
  3. 接入工具栏按钮。
  4. 把命令状态映射到按钮禁用态。
  5. 补充最小 E2E 验证。

验证：

  • 单元测试覆盖命令队列行为。
  • 工具栏端到端测试至少覆盖缩放和视图控制。

完成标准：

  • 新项目已恢复第一批可感知命令能力。

任务 11：实现选择、删除、撤销/重做链路

目标： 打通最关键的编辑闭环。

涉及文件：

  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/packages/flow-editor/src/features/selection/*
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/packages/flow-editor/src/features/node/delete-node.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/tests/unit/delete-command.spec.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/tests/e2e/delete-undo-redo.spec.ts

步骤：

  1. 先实现单选。
  2. 再实现多选和框选。
  3. 实现删除逻辑与 hooks 接入。
  4. 接入撤销/重做回放。
  5. 补齐端到端断言。

验证：

  • 能删除节点或边。
  • 删除前后 hooks 正常触发。
  • 撤销/重做可恢复前一状态。

完成标准：

  • 新项目具备“选中 -> 删除 -> 撤销 -> 重做”完整闭环。

任务 12：实现新增节点、连线与节点编辑

目标： 恢复完整编辑链路。

涉及文件：

  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/packages/flow-editor/src/features/node/add-node.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/packages/flow-editor/src/features/edge/add-edge.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/packages/flow-editor/src/features/node/update-node.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/tests/e2e/node-edge-create.spec.ts
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/tests/e2e/panel-preview.spec.ts

步骤：

  1. 接入左侧菜单创建节点。
  2. 实现锚点或等价交互的新建连线。
  3. 接通 beforeAdd/afterAdd。
  4. 接通双击节点打开右侧面板。
  5. 接通 updateModel、read、clearStates。

验证：

  • 节点可新增、连线可新增、节点内容可更新。
  • 预览弹窗可以打开。
  • 基础编辑链路端到端通过。

完成标准：

  • 新项目已恢复旧编辑器的核心业务闭环。

任务 13：迁移旧示例页到新项目

目标： 用真实业务接入方式验证新编辑器，而不是只在简化 demo 里通过。

涉及文件：

  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/apps/demo/src/pages/legacy-compatible-demo.vue
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/tests/e2e/legacy-compatible-demo.spec.ts

步骤：

  1. 把旧项目接入方式按兼容层迁到新示例页。
  2. 先保留高频业务面板和工具栏交互。
  3. 对差异点逐条记录。
  4. 补充真实接入回归脚本。
  5. 确认宿主使用方式无需大改或只需极小改动。

验证：

  • 新示例页能跑主要旧用法。
  • 差异点有文档可追踪。

完成标准：

  • 新项目具备可替代旧项目示例页的能力。

任务 14：收口文档、差异和发布策略

目标： 确保迁移不是“能跑就算完”，而是有明确交付口径。

涉及文件：

  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/docs/migration/compatibility-matrix.md
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/docs/migration/open-issues.md
  • 新增：/Users/huyirui/program/itomix/git/vue-flow-editor2/docs/migration/release-checklist.md

步骤：

  1. 列出已兼容能力与未兼容能力矩阵。
  2. 记录已知风险和残留问题。
  3. 写清楚发布前检查项。
  4. 写清楚回滚方式。
  5. 与自动化结果一起形成交付材料。

验证：

  • 文档能够支撑最终切换决策。
  • 任何已知差异都有记录。

完成标准：

  • 项目进入可灰度替换旧编辑器的状态。

推荐提交节奏

  • docs: add migration implementation plan
  • test: add legacy editor playwright smoke tests
  • test: add legacy editor regression fixtures
  • chore: scaffold new flow editor workspace
  • feat: add logicflow data adapter
  • feat: add compatibility shell
  • feat: add commander foundation
  • feat: add selection and delete flow
  • feat: add node and edge creation flow

每阶段强制检查项

  • 是否新增或更新了自动化测试
  • 是否更新了中文文档
  • 页面主要逻辑是否补充了中文注释
  • 是否记录了兼容差异
  • 是否能够明确回退

下一步建议

最稳妥的下一步不是直接创建新项目代码，而是先执行任务 1 到任务 5，把旧项目行为基线完全立起来。这样一旦进入新项目实现阶段，我们就不会失去“到底哪里变坏了”的判断依据。