从旧版本迁移

对于 Jmix 应用程序，有两种不同的迁移场景。

如果你的项目已经基于 Jmix 2.x，可以使用 Jmix Studio 轻松将其升级到最新版本。Studio 支持更改平台版本，并为功能版本应用所需的项目更新，因此从任何较早的 2.x 版本迁移到当前版本是推荐的路径。有关详细说明，请参见 升级项目。

从 CUBA Platform 或 Jmix 1.x Classic UI 迁移则是另一种情况。由于这些平台在架构和 UI 技术上存在显著差异，无法进行自动升级。主要原因是旧的基于 Vaadin 8 的 UI 栈过渡到了基于较新 Vaadin 版本的 Flow UI。

对于这些类型的应用程序，我们建议创建一个新的 Jmix master 项目，并在 AI 编码助手的帮助下增量迁移应用程序。Jmix 提供了两个使用此方法的模板仓库：

推荐的迁移方式

推荐的迁移流程如下：

  1. 使用当前 Jmix 版本在 Jmix Studio 中创建一个新的目标项目。使用与源应用程序相同的基础包名。

  2. 从 jmix-framework/jmix-agent-guidelines 仓库将最新的 Jmix agent 安装到目标项目中：将 AGENTS.md 文件复制到目标项目，并确保 skills/ 目录对您的 AI agent 可用。

  3. 将源项目和新的目标项目并排放置在一个工作区中。

  4. 在 IntelliJ IDEA 中打开两个项目，并启用 IntelliJ IDEA MCP Server，以便 AI agent 可以检查代码、项目结构和 IDE 分析结果。

  5. 要求 agent 以小而可控的步骤迁移应用程序，而不是试图一次性转换所有内容。

按照以下顺序执行工作：实体、fetch plan、业务逻辑、fragments，然后是视图。对于大型应用程序，每个阶段应拆分为更小的任务，例如按功能包进行拆分。

使用该方法，目标项目从一开始就按照当前 Jmix 约定创建，而 AI agent 则增量地转移和适配源代码。换句话说，是在干净的 Jmix master 基础之上重建应用程序，并将源项目作为规范。