npm package: @hashan-cn/ruicli
Description: RuoYi backend lite scaffold with modular add-ons
Latest version: 1.0.3

# RuiCli

面向企业内部的若依后台“精简 + 可选扩展”脚手架。

核心思想：

- 基础模板 `templates/ruoyi-admin-vue2/ruoyi-admin-base` 保持最小可运行
- 扩展模块按类别放在 `templates/ruoyi-admin-vue2/modules/<category>/`
- 每个类别只维护一个总配置 `modules.json`
- 通过“文件拷贝 + 规则注入”生成项目，降低复杂度，便于维护

---

## 1. 快速开始

```bash
# -------------------------
# 一、安装与更新（全局）
# -------------------------

# 首次安装（发布后）
npm install -g @hashan-cn/ruicli

# 升级到最新版
npm update -g @hashan-cn/ruicli

# 查看命令帮助
RuiCli --help


# -------------------------
# 二、命令调用教程
# -------------------------

# 1) 创建后台项目（推荐交互）
RuiCli create my-admin -admin

# 2) 创建后台项目（非交互，直接选模块）
RuiCli create my-admin -admin --yes --modules views/dashboard,components/editor --no-install

# 3) 创建小程序项目（直接复制模板）
RuiCli create my-mini -mini

# 4) 查看可用模块（后台模块）
RuiCli list

# 5) 给已创建后台项目追加模块
cd my-admin
RuiCli add components image-preview --no-install
```

> 说明：若你本地命令是 `ruoyi-cli` 或 `ruicli`，将上面的 `RuiCli` 替换为你的实际可执行命令名即可。

---

## 2. 交互流程（create/init）

当前流程：

1. 输入项目名称
2. 选择页面级拓展（单选，可不选）
3. 选择组件级拓展（多选，可不选）
4. 统一执行项目生成
   - 拷贝基础模板
   - 安装已选模块（拷贝文件 + 合并依赖 + 注入代码）
   - 记录安装结果到 `ruoyi.modules.json`

说明：

- `create` 与 `init` 等价，仅命令命名更贴近“创建项目”语义
- `--modules` 参数格式为：`类别/模块名,类别/模块名`

---

## 3. 目录结构与职责

```bash
ruoyi-lite-cli/
├─ bin/
│  └─ ruoyi-cli.js                    # CLI 入口（命令定义）
├─ src/
│  ├─ commands/                       # 命令层：只做交互和流程编排
│  │  ├─ init.js
│  │  ├─ add.js
│  │  └─ list.js
│  ├─ domain/                         # 业务层：脚手架业务语义
│  │  ├─ config/
│  │  │  ├─ category-config.js        # 读取类别配置（modules.json）
│  │  │  └─ registry.js               # 读写 ruoyi.modules.json
│  │  └─ installer/
│  │     └─ apply-module.js           # 应用模块（拷贝/注入/合并）
│  ├─ core/                           # 内核层：通用能力，无业务语义
│  │  ├─ inject/
│  │  │  ├─ marker-injector.js        # 标记位注入
│  │  │  └─ route-injector.js         # 路由注入
│  │  └─ merge/
│  │     └─ package-merge.js          # package.json 依赖合并
│  ├─ shared/
│  │  └─ constants.js                 # 全局常量
│  └─ utils/                          # 兼容层（旧路径转发），后续可逐步删除
├─ templates/
│  └─ ruoyi-admin-vue2/
│     ├─ ruoyi-admin-base/            # 基础模板
│     └─ modules/
│        ├─ components/
│     │  ├─ modules.json              # 组件类别总配置（唯一配置入口）
│     │  ├─ Editor/
│     │  ├─ FileUpload/
│     │  ├─ ImageUpload/
│     │  ├─ ImagePreview/
│     │  └─ RightToolbar/
│     └─ views/                       # 可按同样方式扩展页面模块
└─ README.md
```

---

## 4. 基线模板维护规范

`templates/ruoyi-admin-vue2/ruoyi-admin-base` 是你团队长期维护的**精简基线模板**。

约定：

- 基线里只保留“所有项目都需要”的能力
- 想做成可选项的内容（组件、页面包、监控、工具页等），应当从基线中删除
- 删除后的能力放到 `templates/ruoyi-admin-vue2/modules/<category>/...`，并在对应 `modules.json` 注册
- CLI 只做“复制精简基线 + 按需安装”，不会再自动帮你删除基线内容

这意味着：

- 你维护一次基线，所有项目默认都精简
- 需要的功能由开发者创建项目时勾选安装

## 5. 生成原理

模块安装由 `src/domain/installer/apply-module.js` 执行，顺序如下：

1. 从 `templates/ruoyi-admin-vue2/modules/<category>/modules.json` 获取模块配置
2. 按 `codeDir` 拷贝模板代码到目标项目
   - `components` 默认拷贝到 `src/components/<codeDir>`
   - `views` 默认拷贝到 `src/views/<codeDir>`
   - 可通过 `targetDir` 覆盖默认目标路径
3. 合并依赖到目标项目 `package.json`
4. 注入代码：
   - `main.js` 注入点：
     - `// @module-main-imports`
     - `// @module-main-components`
   - `router/index.js` 注入点（页面模块可用）：
     - `// @module-imports`
     - `// @module-routes`
5. 在目标项目写入 `ruoyi.modules.json`，记录已安装模块

---

## 5. 配置文件（modules.json）说明

路径示例：`templates/ruoyi-admin-vue2/modules/components/modules.json`

字段说明：

- `name`: 模块名称
- `description`: 模块描述（用于 CLI 展示）
- `codeDir`: 模块代码目录（相对当前类别目录）
- `dependencies`: 需要合并进目标项目的依赖
- `mainImports`: 注入到 `main.js` 的 import 语句列表
- `mainComponents`: 注入到 `main.js` 的全局组件注册语句列表
- `routeImports`: 注入到 `router/index.js` 的 import 语句列表（页面模块常用）
- `routeEntries`: 注入到 routes 数组的路由项（页面模块常用）
- `targetDir`（可选）: 覆盖默认拷贝目标路径

---

## 6. 如何新增一个“组件模块”

以新增 `AvatarUpload` 为例：

### 第一步：放代码

在 `templates/ruoyi-admin-vue2/modules/components/AvatarUpload/` 放组件代码。

### 第二步：改配置

在 `templates/ruoyi-admin-vue2/modules/components/modules.json` 增加：

```json
{
  "avatar-upload": {
    "name": "avatar-upload",
    "description": "头像上传组件",
    "codeDir": "AvatarUpload",
    "dependencies": {
      "sortablejs": "^1.15.6"
    },
    "mainImports": ["import AvatarUpload from \"@/components/AvatarUpload\""],
    "mainComponents": ["Vue.component('AvatarUpload', AvatarUpload)"]
  }
}
```

### 第三步：验证

```bash
node bin/ruoyi-cli.js list
node bin/ruoyi-cli.js create demo --yes --modules components/avatar-upload --no-install
```

---

## 7. 如何新增一个“页面模块”（views）

1. 新建目录：`templates/ruoyi-admin-vue2/modules/views/<PageName>/...`
2. 新建配置：`templates/ruoyi-admin-vue2/modules/views/modules.json`
3. 在模块配置里写：
   - `routeImports`
   - `routeEntries`
4. 确保基础模板 `src/router/index.js` 存在注入标记

---

## 8. 关键文件速查

- 命令入口：`bin/ruoyi-cli.js`
- 创建项目流程：`src/commands/init.js`
- 安装模块流程：`src/domain/installer/apply-module.js`
- 类别配置读取：`src/domain/config/category-config.js`
- 安装结果登记：`src/domain/config/registry.js`
- 标记注入：`src/core/inject/marker-injector.js`
- 路由注入：`src/core/inject/route-injector.js`
- 依赖合并：`src/core/merge/package-merge.js`

---

## 9. 开发约定（建议）

- 约定优于复杂逻辑：优先使用注入标记，不做 AST 重写
- 模块尽量“新增文件”为主，避免覆盖基础模板已有文件
- 所有可选能力先进入类别 `modules.json`，再实现代码
- 每次新增模块都执行一次 `create --yes --modules ... --no-install` 验证

这套约定可以保证脚手架在企业内部长期可维护、可扩展。