# ruoyi-vue-plus-代码生成器技能版

**Repository Path**: echooooooo/ruoyi-codegen-skill

## Basic Information

- **Project Name**: ruoyi-vue-plus-代码生成器技能版
- **Description**: ruoyi-codegen-skill
面向 RuoYi-Vue-Plus 与 RuoYi-Plus-Soybean（Soybean Admin） 的 Cursor 技能：用内置 Python 脚本从 MySQL 风格 DDL 离线生成后端、前端 CRUD 及可选菜单 SQL，无需连库、无需打开若依内置在线代码生成页面。

本文档仅描述技能自身的能力、基线、用法与边界；不包含任何具体业务仓库名称或
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-05-14
- **Last Updated**: 2026-05-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: RuoYi-Vue-Plus, skill, RuoYi-Plus-Soybean

## README

# ruoyi-codegen-skill

面向 **RuoYi-Vue-Plus** 与 **RuoYi-Plus-Soybean（Soybean Admin）** 的 Cursor 技能：用内置 Python 脚本从 **MySQL 风格 DDL** 离线生成后端、前端 CRUD 及可选菜单 SQL，无需连库、无需打开若依内置在线代码生成页面。

本文档仅描述**技能自身**的能力、基线、用法与边界；不包含任何具体业务仓库名称或目录命名约定。将本目录整体复制到目标仓库的 Cursor 技能路径（常见为 `.cursor/skills/ruoyi-codegen-skill/`）即可复用。

---

## 适配基线（框架版本）

| 组件 | 版本 | 说明 |
|------|------|------|
| 后端模板 | **RuoYi-Vue-Plus v5.5.3** | Java 分层、注解、Sa-Token、MyBatis-Plus 等按该版本习惯生成。 |
| 前端模板 | **RuoYi-Plus-Soybean v2.0.0** | Vue3 + TypeScript + Naive UI 路线 Soybean 管理端。 |

若目标工程升级了框架（包路径、基类、前端目录、字段规范等），需在本技能目录内同步维护：

- `templates/java/*`
- `templates/soy/*`
- `scripts/codegen.py`

升级后建议先对**单表**做一次生成回归（编译 + 打开列表/表单），再批量生成。

---

## 实现的能力

- **输入**：一个或多个包含 `CREATE TABLE` 的 `.sql` DDL 文件（解析规则见脚本与模板约定）。
- **后端**：Entity、Vo、Bo、Mapper 接口、Mapper XML、Service、ServiceImpl、Controller。
- **前端（Soybean）**：API 类型声明、API 模块、列表页、搜索模块、新增/编辑抽屉。
- **可选**：`sys_menu` 菜单与按钮权限 SQL（需指定父菜单 ID）。
- **执行方式**：本地 Python + Jinja2 渲染；**不**依赖 Spring 启动、**不**依赖数据库连接。

---

## 目录结构（技能包内）

```
ruoyi-codegen-skill/
├── README.md              # 本说明（对外/封装用）
├── SKILL.md               # Cursor Agent 触发与执行规范
├── USAGE.md               # 配置项与对话侧补充说明
├── reference.md           # 命令速查（示例路径需按目标仓库调整）
├── requirements.txt       # Python 依赖
├── config.yaml            # 默认生成配置（包名、输出根路径、作者等）
├── scripts/codegen.py     # 入口脚本
├── templates/java/        # 后端 Jinja2 模板
├── templates/soy/         # 前端 Jinja2 模板
├── templates/sql/         # 菜单 SQL 模板
└── logs/                  # 运行日志（执行后生成）
```

---

## 使用方法

### 1. 环境

- Python 3.8+
- 在**目标业务仓库的根目录**作为当前工作目录（`cwd`），保证 `config.yaml` 中的相对输出路径能正确解析。

```bash
pip install -r <技能根目录>/requirements.txt
```

将 `<技能根目录>` 换为实际路径；若技能位于 `.cursor/skills/ruoyi-codegen-skill/`，则通常为：

```bash
pip install -r .cursor/skills/ruoyi-codegen-skill/requirements.txt
```

### 2. 配置

编辑技能目录下的 `config.yaml`（或使用 `--config` 指向副本），至少核对：

- `package_name`：生成 Java 的根包名。
- `output_base`：后端源码输出根目录（相对 **cwd**）。
- `frontend_output`：前端源码输出根目录；留空或配合 `--no-frontend` 可跳过前端。
- `tpl_category`：默认 `crud`；与 `--tpl` 一致。

命令行参数会覆盖 YAML 中同名项。

### 3. 常用命令（cwd = 目标仓库根）

**记 `CODEGEN` 为 `python <技能根目录>/scripts/codegen.py`。**

| 场景 | 说明 |
|------|------|
| 必填参数 | `--sql <ddl1.sql> [ddl2.sql ...]` |
| 仅后端 | `--no-frontend` |
| 菜单 SQL | `--parent-menu-id <父菜单雪花ID>` |
| 菜单输出目录 | `--sql-output <目录>` |
| 覆盖输出 | `--output`、`--frontend-output` |
| 模板类型 | `--tpl crud`（推荐）或 `--tpl tree`（见下文缺陷） |

示例（路径请按你的仓库替换）：

```bash
python .cursor/skills/ruoyi-codegen-skill/scripts/codegen.py --sql ddl/demo_table.sql
python .cursor/skills/ruoyi-codegen-skill/scripts/codegen.py --sql ddl/a.sql ddl/b.sql --no-frontend
python .cursor/skills/ruoyi-codegen-skill/scripts/codegen.py --sql ddl/demo_table.sql --parent-menu-id <父菜单ID>
```

### 4. Cursor Agent 行为约定

人类或 Agent 按 `SKILL.md` 执行：在仓库根运行脚本、读取控制台给出的日志路径、核对「全部完成」与无异常栈，向用户汇总产物路径与日志路径。详见 `SKILL.md`。

---

## 限制

- **DDL 形态**：依赖对 `CREATE TABLE` 及字段定义的解析，非标准或过于复杂的 DDL 可能需生成后手工改。
- **与若依在线生成器差异**：字段扩展属性、子表、树表细节等未必与官方在线生成器逐项一致；合并前建议 diff 与编译。
- **输出路径**：`config.yaml` 默认路径仅作示例；不同仓库的后端模块、前端工程位置不同，**必须**按目标工程调整或使用命令行覆盖。
- **雪花 ID**：菜单 SQL 等若使用字符串形式的 ID，与前端展示一致即可；勿将大整数 ID 转为 JS Number 以免精度丢失（属工程规范，非脚本独有）。

---

## 已知缺陷与风险

1. **树形模板（`--tpl tree` / `tpl_category: tree`）**  
   树表前后端模板链仍不完善，易出现父子字段、树组件与接口不一致等问题。**建议默认使用 `crud`**，树形需求在生成结果上手工改造，或待模板完善后再启用 `tree`。

2. **与目标工程「未全自动对齐」**  
   生成物通常仍需人工补充：路由注册、国际化词条、细粒度权限、业务校验、多租户切面等。

3. **Cursor / Agent 场景**  
   技能主要规范「如何跑脚本、如何回报」；具体仓库的目录名、模块名需由使用方在对话或配置中给出，Agent 未覆盖所有边界时仍需人工核对日志与文件是否落在预期目录。

---

## 与其他文档的关系

| 文件 | 用途 |
|------|------|
| `SKILL.md` | Cursor 识别与 Agent 执行流程（触发词、步骤、输出规范）。 |
| `USAGE.md` | 配置表、对话侧应提供的信息、命令示例。 |
| `reference.md` | 命令速查；其中示例 SQL 路径、默认输出目录可能与你的仓库不一致，以你本地的 `config.yaml` 为准。 |

封装为独立技能包分发时：**保留本 `README.md` + `SKILL.md` + 脚本与模板**即可；接入方修改 `config.yaml`（或提供独立 `--config`）以匹配其工程布局。