# 若依管理系统 (RuoYi) 项目文档

> 版本: v4.8.3 · 技术栈: Spring Boot 4.0.3 + JDK 17 + Shiro + MyBatis + Thymeleaf

---

## 一、项目简介

若依 (RuoYi) 是一个基于 Spring Boot 的**轻量级 Java 快速开发框架**，内置完善的后台管理系统基础功能，适合中小型企业管理后台的快速搭建。

### 核心能力

- **权限管理**: 用户 / 角色 / 菜单 / 部门 / 岗位，支持按钮级权限控制 (RBAC)
- **数据字典**: 动态配置下拉选项、状态值
- **参数配置**: 系统参数在线调整
- **操作日志**: 记录所有用户操作，支持导出
- **登录日志**: 记录登录历史，支持异常锁定与解锁
- **在线用户**: 查看当前在线用户，支持批量强退
- **定时任务**: Quartz 调度，可在线添加 Cron 表达式，支持立即执行
- **代码生成**: 根据数据库表一键生成完整 CRUD 代码（Controller/Service/Mapper/页面）
- **服务监控**: 实时 CPU / 内存 / 磁盘 / JVM 监控
- **缓存监控**: EhCache 缓存内容查看与清空
- **数据监控**: Druid 连接池 SQL 监控
- **通知公告**: 发布系统通知，已读状态追踪
- **表单构建**: 拖拽生成表单 HTML
- **系统接口**: 集成 Swagger/SpringDoc 接口文档

---

## 二、项目结构

```
system/
├── ruoyi-admin/        Web 入口层：所有 Controller + Thymeleaf 页面模板
├── ruoyi-common/       通用工具：注解、枚举、字符串/文件/安全/Excel 工具类
├── ruoyi-framework/    框架核心：Shiro 认证、数据源、AOP、全局异常处理
├── ruoyi-system/       业务服务层：Service 接口/实现、Domain 实体、Mapper XML
├── ruoyi-quartz/       定时任务模块：Quartz 调度控制器
├── ruoyi-generator/    代码生成模块：Velocity 模板生成 CRUD 代码
├── sql/
│   ├── ry_20260319.sql  业务数据库（21张表 + 种子数据）
│   └── quartz.sql       Quartz 调度器表（11张）
└── DEPLOY.md           发版部署指南
```

---

## 三、所有账号密码

| 系统 | 地址 | 用户名 | 密码 | 说明 |
|------|------|--------|------|------|
| 管理后台 | http://47.94.224.255:8080 | **admin** | **admin123** | 超级管理员 |
| 管理后台 | http://47.94.224.255:8080 | **ry** | **admin123** | 普通用户（测试用） |
| Druid 监控 | http://47.94.224.255:8080/druid | **ruoyi** | **123456** | 数据库连接池监控 |
| Swagger 接口 | http://47.94.224.255:8080/swagger-ui/index.html | — | — | 无需登录访问 |
| MySQL 数据库 | localhost:3306 | **root** | **password** | 数据库直接连接 |

### 密码策略

- 系统初始密码（新增用户时）: **123456**
- 密码加密方式: Shiro MD5(md5(password) + salt)，迭代 1024 次
- 登录错误锁定: 5 次错误后锁定 10 分钟
- 验证码: 开启，算术验证码

---

## 四、管理后台功能模块与菜单

### 4.1 系统管理

| 菜单 | 路径 | 说明 |
|------|------|------|
| **用户管理** | `/system/user` | 增删改查用户，分配角色，重置密码，导入/导出 Excel |
| **角色管理** | `/system/role` | 管理角色，分配菜单权限、数据权限（按部门） |
| **菜单管理** | `/system/menu` | 配置菜单树，设置权限标识（按钮级控制） |
| **部门管理** | `/system/dept` | 组织架构树（公司 → 部门 → 小组） |
| **岗位管理** | `/system/post` | 岗位独立管理，用户可关联岗位 |
| **字典管理** | `/system/dict` | 键值对字典（如性别、状态等），支持刷新缓存 |
| **参数设置** | `/system/config` | 系统全局参数 key-value 在线修改 |
| **通知公告** | `/system/notice` | 发布通知，标记已读，统计已读人数 |
| **操作日志** | `/monitor/operlog` | 记录用户增删改操作，支持导出和清空 |
| **登录日志** | `/monitor/logininfor` | 登录记录，支持账户解锁 |

### 4.2 系统监控

| 菜单 | 路径 | 说明 |
|------|------|------|
| **在线用户** | `/monitor/online` | 当前登录用户列表，支持批量强退 |
| **定时任务** | `/monitor/job` | 管理 Quartz 任务，Cron 在线生成 |
| **数据监控** | `/monitor/data` | 跳转 Druid 控制台（SQL 监控、URI 监控） |
| **服务监控** | `/monitor/server` | 实时服务器状态：CPU、内存、磁盘、JVM |
| **缓存监控** | `/monitor/cache` | EhCache 缓存查看、清空 |

### 4.3 系统工具

| 菜单 | 路径 | 说明 |
|------|------|------|
| **代码生成** | `/tool/gen` | 导入数据库表 → 生成 Controller/Service/Mapper/页面 |
| **表单构建** | `/tool/build` | 拖拽式表单设计器，生成 HTML 代码 |
| **系统接口** | `/tool/swagger` | 跳转 Swagger UI，查看所有 API 接口 |

---

## 五、接口文档

### 5.1 认证相关

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/login` | 登录页面 |
| `POST` | `/login` | Ajax 登录（参数: `username`, `password`, `rememberMe`） |
| `GET` | `/captcha/captchaImage` | 获取验证码图片（参数: `type=math\|char`） |
| `GET` | `/register` | 注册页面 |
| `POST` | `/register` | Ajax 注册新用户 |
| `GET` | `/logout` | 退出登录 |

### 5.2 系统管理接口

#### 用户管理 `/system/user`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/system/user/list` | 分页查询用户列表 |
| `POST` | `/system/user/export` | 导出用户数据 Excel |
| `POST` | `/system/user/importData` | 导入用户数据 |
| `GET` | `/system/user/authRole/{userId}` | 查询用户角色分配 |
| `POST` | `/system/user/authRole` | 保存用户角色分配 |
| `POST` | `/system/user/add` | 新增用户 |
| `GET` | `/system/user/edit/{userId}` | 编辑用户页面 |
| `POST` | `/system/user/edit` | 保存编辑 |
| `POST` | `/system/user/remove` | 批量删除用户 |
| `POST` | `/system/user/resetPwd` | 重置密码为初始密码 |
| `POST` | `/system/user/changeStatus` | 启用/停用用户 |
| `POST` | `/system/user/checkLoginNameUnique` | 校验登录名唯一 |
| `GET` | `/system/user/deptTreeData` | 获取部门树数据 |

#### 角色管理 `/system/role`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/system/role/list` | 分页查询角色列表 |
| `POST` | `/system/role/export` | 导出 |
| `POST` | `/system/role/add` | 新增 |
| `POST` | `/system/role/edit` | 修改 |
| `POST` | `/system/role/remove` | 删除 |
| `GET/POST` | `/system/role/authDataScope` | 数据权限分配 |
| `GET` | `/system/role/authUser/allocatedList` | 已分配用户列表 |
| `GET` | `/system/role/authUser/unallocatedList` | 未分配用户列表 |
| `POST` | `/system/role/authUser/selectAll` | 批量分配用户 |
| `POST` | `/system/role/authUser/cancel` | 取消单个用户授权 |
| `POST` | `/system/role/authUser/cancelAll` | 批量取消授权 |

#### 菜单管理 `/system/menu`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/system/menu/list` | 菜单树列表 |
| `POST` | `/system/menu/add` | 新增菜单/按钮 |
| `POST` | `/system/menu/edit` | 修改 |
| `POST` | `/system/menu/remove/{menuId}` | 删除 |
| `GET` | `/system/menu/roleMenuTreeData` | 加载角色菜单树（含权限标识） |
| `GET` | `/system/menu/menuTreeData` | 获取所有菜单树数据 |
| `GET` | `/system/menu/icon` | 图标列表 |

#### 部门管理 `/system/dept`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/system/dept/list` | 部门树列表 |
| `POST` | `/system/dept/add` | 新增部门 |
| `POST` | `/system/dept/edit` | 修改 |
| `GET` | `/system/dept/remove/{deptId}` | 删除 |
| `GET` | `/system/dept/selectDeptTree/{deptId}` | 选择部门树（排除指定部门） |

#### 岗位管理 `/system/post`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/system/post/list` | 分页查询 |
| `POST` | `/system/post/export` | 导出 |
| `POST` | `/system/post/add` | 新增 |
| `POST` | `/system/post/edit` | 修改 |
| `POST` | `/system/post/remove` | 删除 |

#### 字典管理

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/system/dict/list` | 字典类型分页 |
| `GET` | `/system/dict/detail/{dictId}` | 字典类型详情 |
| `GET` | `/system/dict/treeData` | 字典树 |
| `POST` | `/system/dict/add` | 新增字典类型 |
| `POST` | `/system/dict/edit` | 修改 |
| `POST` | `/system/dict/remove` | 删除 |
| `POST` | `/system/dict/refreshCache` | 刷新字典缓存 |
| `GET` | `/system/dict/data/list` | 字典数据分页 |
| `POST` | `/system/dict/data/add` | 新增字典数据 |
| `POST` | `/system/dict/data/edit` | 修改字典数据 |
| `POST` | `/system/dict/data/remove` | 删除字典数据 |

#### 参数配置 `/system/config`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/system/config/list` | 分页查询 |
| `POST` | `/system/config/add` | 新增 |
| `POST` | `/system/config/edit` | 修改 |
| `POST` | `/system/config/remove` | 删除 |
| `POST` | `/system/config/refreshCache` | 刷新缓存 |

#### 通知公告 `/system/notice`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/system/notice/list` | 分页查询 |
| `POST` | `/system/notice/add` | 新增 |
| `POST` | `/system/notice/edit` | 修改 |
| `POST` | `/system/notice/remove` | 删除 |

#### 个人信息 `/system/user/profile`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/system/user/profile` | 个人信息页面 |
| `POST` | `/system/user/profile/update` | 修改基本信息 |
| `POST` | `/system/user/profile/resetPwd` | 修改密码 |
| `POST` | `/system/user/profile/avatar` | 上传头像 |
| `POST` | `/system/user/profile/checkPassword` | 校验密码 |

### 5.3 系统监控接口

#### 在线用户 `/monitor/online`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/monitor/online/list` | 在线用户列表 |
| `POST` | `/monitor/online/batchForceLogout` | 批量强退 |

#### 操作日志 `/monitor/operlog`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/monitor/operlog/list` | 分页查询 |
| `POST` | `/monitor/operlog/export` | 导出 |
| `POST` | `/monitor/operlog/remove` | 删除 |
| `POST` | `/monitor/operlog/clean` | 清空所有日志 |

#### 登录日志 `/monitor/logininfor`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/monitor/logininfor/list` | 分页查询 |
| `POST` | `/monitor/logininfor/export` | 导出 |
| `POST` | `/monitor/logininfor/remove` | 删除 |
| `POST` | `/monitor/logininfor/clean` | 清空 |
| `POST` | `/monitor/logininfor/unlock/{loginName}` | 账户解锁 |

#### 缓存监控 `/monitor/cache`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/monitor/cache` | 缓存监控页面 |
| `GET` | `/monitor/cache/getNames` | 获取缓存名称列表 |
| `GET` | `/monitor/cache/getKeys/{cacheName}` | 获取缓存 key 列表 |
| `GET` | `/monitor/cache/getValue/{cacheName}/{cacheKey}` | 获取缓存值 |
| `POST` | `/monitor/cache/clearCacheName/{cacheName}` | 清空指定缓存名 |
| `POST` | `/monitor/cache/clearCacheKey/{cacheKey}` | 清空指定 key |
| `POST` | `/monitor/cache/clearAll` | 清空所有缓存 |

### 5.4 定时任务 `/monitor/job`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/monitor/job/list` | 任务列表 |
| `POST` | `/monitor/job/add` | 新增任务 |
| `POST` | `/monitor/job/edit` | 修改任务 |
| `POST` | `/monitor/job/remove` | 删除 |
| `POST` | `/monitor/job/changeStatus` | 启动/暂停 |
| `POST` | `/monitor/job/run` | 立即执行一次 |
| `GET` | `/monitor/job/cron` | Cron 生成器页面 |

#### 任务日志 `/monitor/jobLog`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/monitor/jobLog/list` | 调度日志分页 |
| `POST` | `/monitor/jobLog/export` | 导出 |
| `POST` | `/monitor/jobLog/remove` | 删除 |
| `POST` | `/monitor/jobLog/clean` | 清空 |

### 5.5 代码生成 `/tool/gen`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/tool/gen/list` | 已导入表列表 |
| `GET` | `/tool/gen/db/list` | 数据库表列表（可选择导入） |
| `GET` | `/tool/gen/column/list` | 某表字段信息 |
| `POST` | `/tool/gen/importTable` | 导入表到代码生成器 |
| `POST` | `/tool/gen/createTable` | 创建表 |
| `POST` | `/tool/gen/edit` | 修改生成配置 |
| `GET` | `/tool/gen/preview/{tableId}` | 预览生成代码 |
| `GET` | `/tool/gen/download/{tableName}` | 下载代码 ZIP |
| `GET` | `/tool/gen/genCode/{tableName}` | 生成代码到本地项目 |
| `GET` | `/tool/gen/synchDb/{tableName}` | 同步数据库表结构 |
| `POST` | `/tool/gen/batchGenCode` | 批量生成代码 |

### 5.6 通用功能 `/common`

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/common/download` | 文件下载 |
| `POST` | `/common/upload` | 单文件上传（参数: `file`） |
| `POST` | `/common/uploads` | 多文件上传 |
| `GET` | `/common/download/resource` | 本地资源下载 |

---

## 六、数据库表说明

### 系统管理表 (13张)

| 表名 | 说明 |
|------|------|
| `sys_user` | 用户表 |
| `sys_dept` | 部门表（树形结构） |
| `sys_post` | 岗位表 |
| `sys_role` | 角色表 |
| `sys_menu` | 菜单/权限表（M=目录, C=菜单, F=按钮） |
| `sys_user_role` | 用户-角色关联 |
| `sys_role_menu` | 角色-菜单关联 |
| `sys_role_dept` | 角色-部门数据权限 |
| `sys_user_post` | 用户-岗位关联 |
| `sys_dict_type` | 字典类型 |
| `sys_dict_data` | 字典数据 |
| `sys_config` | 系统参数配置 |
| `sys_oper_log` | 操作日志 |

### 监控/日志表 (5张)

| 表名 | 说明 |
|------|------|
| `sys_logininfor` | 登录日志 |
| `sys_user_online` | 在线用户记录 |
| `sys_notice` | 通知公告 |
| `sys_notice_read` | 通知已读记录 |
| `sys_job` | 定时任务配置 |
| `sys_job_log` | 定时任务执行日志 |

### 代码生成表 (2张)

| 表名 | 说明 |
|------|------|
| `gen_table` | 代码生成表配置 |
| `gen_table_column` | 代码生成字段配置 |

---

## 七、常见操作指南

### 新增菜单

1. 打开 **系统管理 → 菜单管理**
2. 点击 "新增"，选择类型：
   - **目录**: 作为父级菜单分组（如"系统管理"）
   - **菜单**: 实际页面入口，填写请求地址（如 `/system/user`）
   - **按钮**: 页面上的操作按钮（新增/修改/删除），填写权限标识（如 `system:user:add`）
3. 保存后在 **角色管理** 中给角色分配新菜单权限

### 新增用户

1. 打开 **系统管理 → 用户管理**
2. 点击 "新增"，填写登录名、用户姓名、部门、角色、岗位
3. 初始密码为 `123456`，用户首次登录可修改

### 使用代码生成器

1. 打开 **系统工具 → 代码生成**
2. 点击 "导入"，选择要生成代码的数据库表
3. 点击 "编辑" 可调整字段信息、生成模板
4. 点击 "生成代码"，可预览或下载 ZIP
5. 若选择 "生成到项目"，代码会写入对应模块目录

### 创建定时任务

1. 先在项目中编写任务方法（实现 `Job` 接口或使用 `@Scheduled`）
2. 打开 **系统监控 → 定时任务**
3. 点击 "新增"，填写：
   - **调用目标字符串**: 如 `ryTask.ryNoParams`
   - **Cron 表达式**: 可使用在线生成器
4. 点击状态按钮启动任务

### 自定义数据权限

1. 打开 **系统管理 → 角色管理**
2. 点击 "更多 → 数据权限"
3. 选择范围：
   - **全部数据权限**: 可看所有数据
   - **自定数据权限**: 只能看指定部门
   - **本部门数据权限**: 只看自己的部门
   - **本部门及以下**: 看自己和子部门
   - **仅本人**: 只能看自己的数据

---

## 八、配置参考

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `server.port` | 80 (生产 8080) | 服务端口 |
| `ruoyi.name` | RuoYi | 项目名称（显示在页面标题） |
| `ruoyi.version` | 4.8.3 | 版本号 |
| `ruoyi.demoEnabled` | true | 演示模式（禁止修改敏感数据） |
| `ruoyi.profile` | D:/ruoyi/uploadPath | 文件上传目录 |
| `shiro.captchaEnabled` | true | 验证码开关 |
| `shiro.captchaType` | math | 验证码类型 (math/char) |
| `shiro.maxSession` | -1 | 最大会话数（-1 不限） |
| `shiro.session.timeout` | 30min | Session 超时 |
| `shiro.login.maxRetryCount` | 5 | 登录错误锁定次数 |
| `shiro.login.lockTime` | 10min | 锁定时间 |
| `sys.user.initPassword` | 123456 | 新增/重置密码时的初始密码 |

---

## 九、注意事项

- **演示模式**: 生产部署建议关闭 `ruoyi.demoEnabled`，否则无法新增/修改/删除系统用户、角色等
- **验证码**: 生产环境建议开启，类型可选 `math`（算术）或 `char`（字符）
- **文件上传路径**: 默认 `D:/ruoyi/uploadPath`，Linux 服务器需改为 `/home/ruoyi/uploadPath` 等实际路径
- **数据库密码**: 请修改 `application-druid.yml` 中的数据库密码
- **Swagger**: 默认 `/swagger-ui/index.html`，生产环境建议关闭或加权限
- **Druid 监控**: 默认 `/druid/*`，账号 `ruoyi/123456`，生产环境建议改密码