RuiCli

面向企业内部的若依后台“精简 + 可选扩展”脚手架。

核心思想：

• 基础模板 templates/ruoyi-admin-vue2/ruoyi-admin-base 保持最小可运行
• 扩展模块按类别放在 templates/ruoyi-admin-vue2/modules/<category>/
• 每个类别只维护一个总配置 modules.json
• 通过“文件拷贝 + 规则注入”生成项目，降低复杂度，便于维护

1. 快速开始

# -------------------------
# 一、安装与更新（全局）
# -------------------------

# 首次安装（发布后）
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. 目录结构与职责

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 增加：

{
  "avatar-upload": {
    "name": "avatar-upload",
    "description": "头像上传组件",
    "codeDir": "AvatarUpload",
    "dependencies": {
      "sortablejs": "^1.15.6"
    },
    "mainImports": ["import AvatarUpload from \"@/components/AvatarUpload\""],
    "mainComponents": ["Vue.component('AvatarUpload', AvatarUpload)"]
  }
}

第三步：验证

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 验证

这套约定可以保证脚手架在企业内部长期可维护、可扩展。