github/RuoYi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
24049d50f1
RuoYi/PROJECT_DOC.md

432 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 若依管理系统 (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`，生产环境建议改密码
Reference in New Issue View Git Blame Copy Permalink