erupt-admin

Files (43)

• CODE_OF_CONDUCT.md · .github/
• CONTRIBUTING.md · .github/
• GOVERNANCE.md · .github/
• SECURITY.md · .github/
• issue_template.md · .github/
• pull_request_template.md · .github/
• .gitignore
• LICENSE
• README.md
• README.zh.md
• SKILL.md
• icon.svg · docs/
• index.html · docs/
• annotations.md · reference/
• doc-map.md · reference/
• erupt-api.md · reference/
• erupt-cube.md · reference/
• erupt-datasource.md · reference/
• erupt-ecosystem.md · reference/
• erupt-hooks.md · reference/
• erupt-i18n.md · reference/
• erupt-lambda-query.md · reference/
• erupt-model.md · reference/
• erupt-module.md · reference/
• erupt-tpl.md · reference/
• erupt-upms.md · reference/
• build-m2-seed.sh · scripts/
• compile.sh · scripts/
• run.sh · scripts/
• setup-env.sh · scripts/
• verify.sh · scripts/
• warmup.sh · scripts/
• README.md · template-module/
• pom.xml · template-module/
• ModuleAutoConfiguration.java · template-module/src/main/java/modtpl/
• org.springframework.boot.autoconfigure.AutoConfiguration.imports · template-module/src/main/resources/META-INF/spring/
• DemoApplication.java · template-module/src/test/java/modtpl/demo/
• application.yml · template-module/src/test/resources/
• pom.xml · template/
• Application.java · template/src/main/java/app/
• application.yml · template/src/main/resources/
• app.css · template/src/main/resources/public/
• app.js · template/src/main/resources/public/

SKILL.md (first lines)

# erupt 一句话生成数据管理后台

根据用户一句话需求，生成基于 [erupt](https://www.erupt.xyz) 框架的完整可运行数据管理后台（内置 H2 数据库、自动登录页、增删改查、搜索、导入导出、权限管理），并自动准备 JDK 与 Maven 环境后启动。

## 工作流程

### 第 0 步：预热运行环境与依赖（立即执行，不要等）

收到需求后**第一时间**用后台方式执行：

```bash
bash <skill目录>/scripts/warmup.sh
```

该脚本先准备 JDK/Maven 环境，再用模板项目跑一次真实构建，把 Spring Boot 与 erupt 依赖提前下载到 `~/.m2`——这样在你解析需求、编写代码的同时，依赖已在并行下载，用户项目首次构建基本免等待。环境说明：

- 系统已有 JDK 17+ 和 Maven 时直接复用，秒级完成
- 无系统 JDK 时按需下载 **OpenJDK 25**：Adoptium 官方源，失败自动切清华镜像（国内下载很快），解压到 `~/.erupt-skill/runtime` 后缓存复用；Maven 3.9 同样自动下载，依赖默认走阿里云镜像
- `vendor/m2/`（不入 git）可选放置依赖种子（`scripts/build-m2-seed.sh` 生成），存在时首次构建完全免下载
- 预热前先查最新 erupt 版本并锁定到临时 pom，确保预下的 erupt 依赖与第 4 步生成项目实际用的版本一致（避免预热了旧版、首次构建仍重下）；缓存标记按「模板 pom 内容 + 解析出的 erupt 版本」双重键控，模板变更或 erupt 新版发布都会自动重新预热；预热失败不阻塞流程，`run.sh` 构建时会自动补齐
- 预热进行中时 `run.sh` / `compile.sh` 会自动等待其完成（避免 Maven 本地仓库并发写入），无需人工协调

### 第 1 步：需求解析

从用户一句话中推断出领域模型，**不要追问细节**，用领域常识补全：

- 识别核心实体（通常 2~5 个），如"图书管理" → 图书、分类、借阅记录
- 为每个实体设计 5~10 个常识字段（名称、状态、时间、金额等）
- 识别实体间关系（分类→树形、明细→一对多、标签→多对多）
- 业务实体带树形维度（部门、分类、区域等）时，主动为其配置 **左树右表**（`linkTree`）：左侧树导航 + 右侧表格联动过滤，数据可视化浏览体验远好于纯列表，见 annotations.md「左树右表」
- 全局只有一条记录的实体（系统设置、参数配置等）→ FORM 表单视图，见 annotations.md「单行数据表单管理」
- 实体与字段命名用英文，界面标题（title）用用户使用的语言

### 第 2 步：生成项目

> **模板分流**：本 skill 的默认场景是生成**应用**（管理后台），一律复制 `template/`。仅当用户**明确提出**要开发可复用的 erupt 功能模块/扩展/插件（产出是 jar，给其他 erupt 应用加依赖使用，如"做一个 erupt-xx 模块"）时，才改用 `template-module/`，流程见 `reference/erupt-module.md`。拿不准时按应用处理，**不要**因为需求里出现"模块"二字（如"用户模块""订单模块"，那只是业务功能）就选 template-module。

1. 项目名用英文 kebab-case（如 `library-admin`），在用户当前目录下创建
2. 复制本 skill 的 `template/` 目录到项目目录
3. 将模板中**所有文件**的 `__ARTIFACT_ID__` 全部替换为项目名（涉及 `pom.xml`、`application.yml`、`Application.java` 三处，建议全局搜索确认无遗漏）
4. **erupt 版本尽量用最新**：查询 Maven 仓库版本列表，取语义化排序最大的正式版，更新 pom.xml 的 `<erupt.version>`：

   ```bash
   curl -s --max-time 10 "https://maven.aliyun.com/repository/public/xyz/erupt/erupt-spring-boot-starter/maven-metadata.xml" \
     | grep -oE "<version>[0-9]+\.[0-9]+\.[0-9]+</version>" | grep -oE "[0-9]+\.[0-9]+\.[0-9]+" | sort -V | tail -1
   ```

   版本选择规则：
   - 取「模板默认版本」与「查询结果」中**较高**者，但采用前必须校验该版本真实存在（如下），不存在则用查询到的最新已发布版本：

     ```bash
     curl -s -o /dev/null -w "%{http_code}" --max-time 10 "https://maven.aliyun.com/repository/public/xyz/erupt/erupt-spring-boot-starter/<版本>/erupt-spring-boot-starter-<版本>.pom"   # 200 才可用
     ```

   - **版本号必须来自上述命令的实际输出，严禁凭记忆或训练数据填写**（曾出现过误写 1.13.0 旧版本的情况）
   - artifact 固定为 `erupt-spring-boot-starter`，不要查 `erupt`、`erupt-core` 等其他 artifact
   - 阿里云查不到时换 `https://repo1.maven.org/maven2/...`（路径相同）；两源都失败时保留模板默认版本，不要阻塞生成流程

   > **版本基线（全部版本的唯一声明点，升级只改这些位置）**：
   > - erupt 兜底版本：`template/pom.xml` 与 `template-module/pom.xml` 的 `<erupt.version>`（生成时自动查最新版覆盖）
   > - Spring Boot 版本：上述两个 pom 的 `<parent>`（Maven 要求 parent 版本必须写死，与 erupt 官方仓库使用的 Spring Boot 版本对齐，两处需同步改）
   > - `reference/` 各文档的实测核实基线：**erupt 2.3.0（2026-09）**，只记录在本行，reference 文档内不写版本号
5. 将 `src/main/resources/public/app.js` 中的 `__APP_TITLE__` 替换为系统名（如"图书管理系统"）、`__APP_DESC__` 替换为一句话描述
6. 在 `src/main/java/app/model/` 下编写实体类

**实体类必须严格遵循 [reference/annotations.md](reference/annotations.md) 的规范**，这是本 skill 的核心，编写前必读。需要完整注解字典（所有属性、枚举值、子注解定义）时读 [reference/erupt-model.md](reference/erupt-model.md)。

### 第 3 步：构建并启动

```bash
bash <skill目录>/scripts/run.sh <项目目录> [端口]
```

- 用后台方式运行此命令（依赖已在第 0 步预热时基本就绪；若预热未完成会自动等待或补齐下载）
- 环境已在第 0 步准备完毕，此处直接复用；`ERUPT_SKILL_NO_MIRROR=1` 可关闭阿里云镜像
- 持续观察日志：出现 `Started Application` 即启动成功；出现编译错误则修复实体类后重启
- 端口默认 8080，被占用时换端口重启（如 8081）

### 第 4 步：交付

告知用户：

> 后台已启动：http://localhost:8080
> 账号 / 密码：erupt / erupt
> 数据保存在项目 `data/` 目录下（H2 文件数据库），无需安装任何数据库

**交付前先跑 API 自检**（只读，不写数据）：登录 → 拉菜单 → 逐表查询，任何实体注解错误（联动表达式、权限配置等）都会在这一步暴露，而不是等用户点到才发现：

```bash
bash <skill目录>/scripts/verify.sh [端口]
```

输出 `PASS` 再交付；某张表报 ERROR 时按报错信息修复实体后重启复检。如可用浏览器工具，可再截图登录页确认。

### 第 5 步：迭代（用户继续一句话提需求）

**任何 Java 代码改动后，必须先前台编译校验，通过后再重启，不要只改代码不验证**：

```bash
bash <skill目录>/scripts/compile.sh <项目目录>
```

- 编译报错时根据错误信息修复（缺 import、注解属性写错、类型不匹配等），修到编译通过为止
- 加字段 / 加实体：改代码 → 编译校验 → 重启（`generate-ddl: true` 会自动加列、建表）
- 改外观（标题、Logo、favicon、主题色、暗色/紧凑/皮肤风格、菜单模式、登录页布局与背景图、表单面板形态、PWA 图标、页脚、顶栏按钮、登录/退出钩子）：编辑 `src/main/resources/public/app.js`（eruptSiteConfig 配置，模板已列出常用项并注释说明）；改样式（菜单 emoji 图标等）：编辑 `app.css`（模板内有注释示例）。两者无需改 Java 代码，重启后刷新页面生效。注意 `theme` 里配的是**默认值**，用户在右上角设置抽屉里选过之后以用户选择为准（存 localStorage）；要让全员外观统一就设 `theme.customizable: false`
  - Logo 三个键（`logoPath` / `logoFoldPath` / `loginLogoPath`）的规则：**不写**该键 = 用默认 erupt 标识，写 `null` 或 `''` = 该位置不显示 Logo。所以想显示默认 Logo 时把整行删掉或注释掉，不要写 `logoPath: null`
  - 登录页背景图用 `theme.loginBackground`（一张图替换所有布局的默认插画），不要再用 CSS 覆盖登录页容器
- 登录后首页：**默认用 erupt 自带的工作台**（问候语、统计卡片、常用与最近打开的菜单，随权限与收藏变化），模板不再放 home.html，不要主动创建。只有用户明确要求换掉首页时，才新建 `src/main/resources/public/home.html` 覆盖它
  - 自写首页的接入方式：该页由主框架以 iframe 同源加载，URL 自带 `_token`（调 erupt-api 时放请求头 `token`）与 `_lang`；用 `<a target="_parent" href="#/build/table/实体名">` 跳转主框架菜单。需要仪表盘/统计卡片时直接 fetch `erupt-api/menu`、`erupt-api/userinfo` 或自写接口即可，无需注册菜单
  - 自写首页要跟随暗色模式：主框架在自己的 `<html>` 上挂 `dark` 类、写 `--ant-primary-color`，同源读 `window.parent.document.documentElement` 并用 `MutationObserver` 监听 class/style 变化同步到本页
  - 后台给某个用户配了「首页菜单」（EruptUser 的 eruptMenu 字段）时，登录后直接进那个菜单，工作台和自定义 home.html 都不会显示——用户反馈"首页没生效"先查这里
  - 若首页需要作为菜单项复用或做多个自定义页面，改用 TPL（见下条）
- 自定义整页界面（仪表盘、数据大屏、任意自定义页面）：用 TPL——HTML 放 `src/main/resources/tpl/`，在 `initMenus()` 注册 type 为 `"tpl"` 的菜单即成为全页面菜单项，零 Java 代码，**必读 [reference/erupt-tpl.md](reference/erupt-tpl.md)**
- 改字段类型 / 删字段：H2 不会自动删旧列，若启动报错，提示用户可删除项目 `data/` 目录重置数据后重启
- 换数据库：MySQL 等生产库只需改 `application.yml` 的 datasource 并在 pom 加对应驱动

### 进阶需求参考文档

用户迭代提出以下需求时，**先读对应参考文档再动手**：

From plinian/erupt-skill, Apache-2.0.