# 多代码模板包设计 ## 目标 把当前固定使用 `qing` 的生成链路升级为可选择的代码模板包机制。`qing` 继续作为默认模板包，后续新增模板通过统一的模板包元数据、模板文件、结构树和生成选择策略接入，不再在生成服务里为每个模板反复增加硬编码分支。 第一期目标是支持多个技术栈或代码风格模板包，例如 `qing`、`qing-lite`、`vue3-plus`。行业业务提示词仍由现有 `industryTemplate` 表达，不和代码模板包混用。 ## 当前上下文 现有 `qing` 生成能力由三部分组成： - 文件系统基线模板：`ruoyi-generator/src/main/resources/qing/*.vm`。 - 数据库模板记录：`sys_template`、`sys_template_file`、`sys_project_structure`，种子主要在 `sql/qing_templates.sql` 和 `sql/db.sql`。 - 生成服务选择逻辑：`GenProjectServiceImpl` 根据 `templateType` 解析模板，当前优先选择 9201、9202、9203 这三个可运行模板 ID。 这说明新增模板不能只复制一个目录。一个可用模板必须同时具备模板包标识、每类模板文件、结构树、输出路径约定、预览下载支持和运行预览兼容性。 ## 用户体验 前台生成工作台在创建或编辑项目时增加“代码模板”选择。默认选中 `qing`。选择项来自后端接口，只展示启用状态的模板包。 预览页不再写死三类页签，而是读取当前项目模板包支持的目标类型： - `backend` - `frontend` - `admin_frontend` - `sql` 如果模板包不支持某一类，前端不展示对应页签，下载全部源码时也跳过该类。`frontendEnabled = 0` 时仍按现有逻辑隐藏用户前台。 ## 数据模型 新增模板包表 `sys_template_bundle`： ```sql bundle_id bigint primary key, bundle_code varchar(64) not null unique, bundle_name varchar(100) not null, description varchar(500), status char(1) not null default '0', is_default char(1) not null default '0', support_backend char(1) not null default '1', support_frontend char(1) not null default '1', support_admin_frontend char(1) not null default '1', support_sql char(1) not null default '1', sort_order int default 0, create_by varchar(64), create_time datetime, update_by varchar(64), update_time datetime ``` 扩展 `sys_template`： - 增加 `bundle_code varchar(64)`，用于把 `backend`、`frontend`、`admin_frontend` 等模板记录归属到同一个模板包。 - 保留 `template_type` 表示目标类型，不改变现有模板文件和结构树关系。 - `qing` 现有 9201、9202、9203 记录补充 `bundle_code = 'qing'`。 扩展前台项目表： - 增加 `code_template varchar(64)`，默认 `qing`。 - `FrontProjectCreateRequest`、`FrontProjectUpdateRequest`、`AiGenerationTaskCreateRequest` 同步增加 `codeTemplate`。 - `FrontProjectConverter.toGenProject` 把该字段传给 `GenProject`，供预览和下载使用。 ## 后端架构 新增模板包服务： - `TemplateBundle` domain、mapper、service。 - `listEnabledBundles()`：前端创建项目时使用。 - `getBundle(code)`：生成服务解析模板时使用。 - `getDefaultBundle()`：项目未指定时回退到默认模板包，默认应为 `qing`。 - `getSupportedTemplateTypes(code, frontendEnabled)`：预览页和下载逻辑使用。 调整 `GenProjectServiceImpl`： - `resolveProjectTemplate(project, type)` 先读取 `project.codeTemplate`。 - 未指定时回退默认模板包 `qing`。 - 通过 `bundle_code + template_type + template_status = 0` 查询模板。 - 移除 9201、9202、9203 作为固定优先模板的业务含义，只保留数据迁移兼容。 - 如果项目后台手动绑定了 `sys_project_template`，仍优先使用绑定记录，以保持现有后台配置能力。 生成入口需要统一使用同一个模板包： - `getProjectStructure` - `previewCode` - `downloadStructure` - `downloadAll` - `run-preview` 源码准备 - 一键生成中 `SOURCE_PREVIEW` 阶段的结构校验 ## 模板资源组织 第一期可以继续以数据库模板为渲染来源，文件系统模板作为内置基线和测试对照。后续可逐步收敛到以下目录规范： ```text ruoyi-generator/src/main/resources/templates/ qing/ manifest.yml backend/ frontend/ admin_frontend/ vue3-plus/ manifest.yml backend/ frontend/ admin_frontend/ ``` `manifest.yml` 描述模板包基本信息、支持类型、推荐端口、模板文件清单和结构树种子来源。第一期不强制实现自动导入 manifest，但新增模板应按这个结构准备，避免继续把 `qing` 当作特殊目录。 ## 数据流 1. 用户创建项目，选择 `codeTemplate`。 2. 后端保存项目草稿，未传则写入默认模板包 `qing`。 3. AI 生成蓝图、数据库、业务动作和页面设计时继续使用现有行业提示词，不受代码模板选择影响。 4. 预览结构时，`GenProjectServiceImpl` 用 `project.codeTemplate + templateType` 找到模板记录。 5. 根据模板记录读取 `sys_template_file`，根据模板 ID 读取 `sys_project_structure`。 6. Velocity 渲染模板内容，结构树里的 `category` 对应模板文件名或路径。 7. 下载全部源码时，后端遍历模板包支持的类型，合并 zip。 8. 运行预览从下载出的结构中启动后端、用户前台和后台前端；不支持的类型跳过。 ## 错误处理 模板包不存在或未启用： - 创建/更新项目时返回明确错误。 - 老项目没有 `codeTemplate` 时回退默认模板包。 模板包缺少某个目标类型： - 前端不展示对应页签。 - 后端收到不支持的 `templateType` 时返回“当前模板包不支持该生成类型”。 模板记录存在但文件缺失： - `getRequiredTemplateFiles` 继续抛出模板未配置文件错误。 - 错误信息补充模板包 code、templateType 和 templateId，便于排查。 结构树 category 找不到模板文件： - 预览单文件时提示未找到模板文件。 - 下载时记录失败模板路径，避免静默跳过。 运行预览不兼容： - 源码下载仍可用。 - 运行预览返回失败状态和日志。 - 模板包元数据可在后续增加 `run_preview_supported` 做显式控制。 ## SQL 和迁移 第一期迁移脚本做这些事： - 创建 `sys_template_bundle`。 - 给 `sys_template` 增加 `bundle_code`。 - 给 `front_project` 增加 `code_template`。 - 插入默认模板包 `qing`。 - 将 9201、9202、9203 的 `bundle_code` 更新为 `qing`。 - 更新历史前台项目 `code_template = 'qing'`。 - 保证只有一个启用的默认模板包。 模板包种子建议独立文件： - `sql/code_template_bundles.sql`：模板包表结构和 qing 默认数据。 - `sql/qing_templates.sql`：继续维护 qing 的模板文件和结构树。 - `sql/db.sql`：整合完整初始化脚本。 ## 前端改造 `easycode-web` 增加接口： - `listCodeTemplateBundles()` - `getProjectSupportedTemplateTypes(projectId)` 创建和编辑项目表单增加代码模板选择。展示文案建议： - `qing`：默认可运行 Spring Boot + Vue2 模板 - 新模板：按模板包元数据展示名称和描述 `PreviewView` 改造： - `templateTypes` 来自后端，而不是固定数组。 - 下载全部源码默认调用现有下载接口。 - 单类下载时继续传 `templateType`。 - 如果当前激活类型不在支持列表，自动切回第一个可用类型。 ## 测试策略 后端单元测试： - 未指定 `codeTemplate` 时回退 `qing`。 - 指定模板包时按 `bundle_code + template_type` 选择模板。 - 后台项目模板绑定仍优先于模板包默认模板。 - 禁用模板包不可用于新项目。 - 不支持的 `templateType` 返回明确错误。 - 老项目迁移后可以继续预览 backend、frontend、admin_frontend 和 sql。 模板一致性测试： - `qing` 模板包的 9201、9202、9203 都能找到文件和结构树。 - 结构树 `category` 都能匹配模板文件名或路径。 - 复制出的测试模板包不会被 9201、9202、9203 固定优先逻辑覆盖。 前端测试： - 创建项目表单展示代码模板选择。 - 未选择时提交默认 `qing`。 - 预览页按后端返回的支持类型渲染页签。 - `frontendEnabled = 0` 时隐藏用户前台。 人工验收： 1. 导入迁移脚本。 2. 创建项目，不手动选择模板，确认使用 `qing`。 3. 创建项目，选择测试模板包，确认预览结构来自新模板包。 4. 下载全部源码，确认只包含模板包支持的目标类型。 5. 启动运行预览，确认 qing 模板仍可运行。 ## 分期 第一期： - 数据库增加模板包和项目模板选择字段。 - 后端模板包服务和选择策略。 - 前台创建/编辑项目支持代码模板选择。 - 预览页动态读取支持类型。 - qing 作为默认模板包完成迁移。 第二期： - 引入 `manifest.yml` 导入工具。 - 增加模板包复制、启停、导入导出。 - 模板包运行预览能力声明。 - 模板包版本管理。 第三期： - 模板市场化管理。 - 模板包依赖能力声明，例如业务块、图表、文件上传、认证方式。 - 模板包质量检查和在线试生成。 ## 自检 - 范围聚焦在代码模板包，不混入行业业务模板。 - `qing` 作为默认行为保留，老项目有回退路径。 - 模板选择逻辑从固定 ID 改为模板包 code，不再扩大硬编码。 - 数据库模板文件和结构树仍沿用现有模型，避免一次性重写生成器。 - 前端页签和下载逻辑从模板包能力派生，避免新增模板后继续改页面常量。