### Install JDK, MySQL, and Redis

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/README.md

Ensure you have JDK 17+, MySQL 8.0+, and Redis 6.0+ installed before proceeding with the project setup.

```bash
# Install JDK 17+
# Install MySQL 8.0+
# Install Redis 6.0+
```

--------------------------------

### Clone and Install RuoYi-Vue Project

Source: https://github.com/y_project/ruoyi-vue/blob/master/ruoyi-ui/README.md

Clone the project repository and install its dependencies using npm. It's recommended to use a specific registry for npm to avoid potential issues.

```bash
git clone https://gitee.com/y_project/RuoYi-Vue

cd ruoyi-ui

npm install

npm install --registry=https://registry.npmmirror.com
```

--------------------------------

### SysDept JSON Example

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/types.md

Provides a JSON example for a SysDept object, demonstrating its hierarchical structure with nested children.

```json
{
  "deptId": 100,
  "parentId": 0,
  "deptName": "深圳总公司",
  "orderNum": 0,
  "leader": "若依",
  "phone": "15888888888",
  "email": "ry@qq.com",
  "status": "0",
  "delFlag": "0",
  "children": [
    {
      "deptId": 101,
      "parentId": 100,
      "deptName": "深圳总公司-研发部门"
    }
  ]
}
```

--------------------------------

### Run RuoYi-Vue Development Server

Source: https://github.com/y_project/ruoyi-vue/blob/master/ruoyi-ui/README.md

Start the development server for the RuoYi-Vue project. Access the application via a web browser at http://localhost:80.

```bash
npm run dev
```

--------------------------------

### SysRole JSON Example

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/types.md

Illustrates the JSON structure for a SysRole object, showing typical values for its attributes.

```json
{
  "roleId": 1,
  "roleName": "管理员",
  "roleKey": "admin",
  "roleSort": 1,
  "status": "0",
  "delFlag": "0",
  "createTime": "2024-01-01 10:00:00"
}
```

--------------------------------

### LoginBody JSON Example

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/authentication.md

An example of the JSON payload for a user login request.

```json
{
  "username": "admin",
  "password": "admin123",
  "code": "j3ki",
  "uuid": "8b8a0a1e-8b8a-4b8a-8b8a-8b8a0a1e8b8a"
}
```

--------------------------------

### Build and Run RuoYi-Vue Application

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/README.md

Compile the project using Maven and then run the `ruoyi-admin` module to start the application. Access the application via `http://localhost:8080/`.

```bash
cd ruoyi-vue
mvn clean install
cd ruoyi-admin
mvn spring-boot:run
```

--------------------------------

### BaseEntity JSON Serialization Example

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/types.md

An example demonstrating how BaseEntity fields are serialized into JSON format.

```json
{
  "createBy": "admin",
  "createTime": "2024-07-07 10:30:45",
  "updateBy": "admin",
  "updateTime": "2024-07-07 14:30:45",
  "remark": "用户记录"
}
```

--------------------------------

### Get Menu List Endpoint

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/endpoints.md

Retrieves a hierarchical list of system menus. Requires 'system:menu:list' permission.

```json
{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "menuId": 1,
      "menuName": "系统管理",
      "parentId": 0,
      "orderNum": 1,
      "path": "system",
      "component": null,
      "children": [
        {
          "menuId": 100,
          "menuName": "用户管理",
          "path": "user"
        }
      ]
    }
  ]
}
```

--------------------------------

### GET /system/role/list

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/endpoints.md

Retrieves a list of roles with pagination and filtering capabilities. Supports filtering by role name and key.

```APIDOC
## GET /system/role/list

### Description
Retrieves a list of roles with pagination and filtering capabilities. Supports filtering by role name and key.

### Method
GET

### Endpoint
/system/role/list

### Parameters
#### Query Parameters
- **pageNum** (Integer) - Optional - Current page number
- **pageSize** (Integer) - Optional - Number of records per page
- **roleName** (String) - Optional - Role name
- **roleKey** (String) - Optional - Role permission character
- **status** (String) - Optional - Role status

### Response
#### Success Response (200)
- **total** (Integer) - Total number of roles
- **rows** (Array) - List of roles
- **code** (Integer) - Response code
- **msg** (String) - Response message

### Response Example
```json
{
  "total": 10,
  "rows": [
    {
      "roleId": 1,
      "roleName": "管理员",
      "roleKey": "admin",
      "roleSort": 1,
      "status": "0",
      "delFlag": "0",
      "createTime": "2024-01-01 10:00:00"
    }
  ],
  "code": 200,
  "msg": "查询成功"
}
```
```

--------------------------------

### Get Menu List

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/endpoints.md

Retrieves a hierarchical list of system menus. This endpoint is useful for displaying navigation structures or managing menu configurations.

```APIDOC
## GET /system/menu/list

### Description
Retrieves a hierarchical list of system menus.

### Method
GET

### Endpoint
/system/menu/list

### Response
#### Success Response (200)
- **data** (array) - Tree structure of menu data.

### Response Example
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "menuId": 1,
      "menuName": "系统管理",
      "parentId": 0,
      "orderNum": 1,
      "path": "system",
      "component": null,
      "children": [
        {
          "menuId": 100,
          "menuName": "用户管理",
          "path": "user"
        }
      ]
    }
  ]
}
```
```

--------------------------------

### GET /system/dept/list

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/endpoints.md

Retrieves a list of departments in a tree structure. Supports filtering by department name and status.

```APIDOC
## GET /system/dept/list

### Description
Retrieves a list of departments in a tree structure. Supports filtering by department name and status.

### Method
GET

### Endpoint
/system/dept/list

### Parameters
#### Query Parameters
- **deptName** (String) - Optional - Department name, for fuzzy query
- **status** (String) - Optional - Department status

### Response
#### Success Response (200)
- **code** (Integer) - Response code
- **msg** (String) - Response message
- **data** (Array) - Tree structure of departments

### Response Example
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "deptId": 100,
      "deptName": "深圳总公司",
      "parentId": 0,
      "orderNum": 0,
      "status": "0",
      "children": [
        {
          "deptId": 101,
          "deptName": "深圳总公司-研发部门"
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Get Dictionary Data by Type Endpoint

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/endpoints.md

Fetches dictionary data based on a specified dictionary type. The 'dictType' is a required path parameter.

```json
{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "dictCode": 1,
      "dictLabel": "男",
      "dictValue": "0",
      "dictType": "sys_user_sex",
      "dictSort": 1
    },
    {
      "dictCode": 2,
      "dictLabel": "女",
      "dictValue": "1",
      "dictType": "sys_user_sex",
      "dictSort": 2
    }
  ]
}
```

--------------------------------

### Get Dictionary Data by Type

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/endpoints.md

Fetches dictionary data based on a specified dictionary type. This is useful for populating dropdowns or selecting predefined values.

```APIDOC
## GET /system/dict/data/type/{dictType}

### Description
Retrieves dictionary data based on the provided dictionary type.

### Method
GET

### Endpoint
/system/dict/data/type/{dictType}

### Parameters
#### Path Parameters
- **dictType** (String) - Required - The type of dictionary to retrieve.

### Response
#### Success Response (200)
- **data** (array) - A list of dictionary items, each containing label, value, and type.

### Response Example
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "dictCode": 1,
      "dictLabel": "男",
      "dictValue": "0",
      "dictType": "sys_user_sex",
      "dictSort": 1
    },
    {
      "dictCode": 2,
      "dictLabel": "女",
      "dictValue": "1",
      "dictType": "sys_user_sex",
      "dictSort": 2
    }
  ]
}
```
```

--------------------------------

### Get Department List API

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/endpoints.md

Retrieves a list of departments in a tree structure. Supports filtering by department name and status.

```json
{
  "code": 200,
  "msg": "查询成功",
  "data": [
    {
      "deptId": 100,
      "deptName": "深圳总公司",
      "parentId": 0,
      "orderNum": 0,
      "status": "0",
      "children": [
        {
          "deptId": 101,
          "deptName": "深圳总公司-研发部门"
        }
      ]
    }
  ]
}
```

--------------------------------

### Get Role List API

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/endpoints.md

Retrieves a list of roles with pagination and filtering capabilities. Supports filtering by role name, key, and status.

```json
{
  "total": 10,
  "rows": [
    {
      "roleId": 1,
      "roleName": "管理员",
      "roleKey": "admin",
      "roleSort": 1,
      "status": "0",
      "delFlag": "0",
      "createTime": "2024-01-01 10:00:00"
    }
  ],
  "code": 200,
  "msg": "查询成功"
}
```

--------------------------------

### Build RuoYi-Vue for Deployment

Source: https://github.com/y_project/ruoyi-vue/blob/master/ruoyi-ui/README.md

Build the RuoYi-Vue project for different deployment environments. Use 'build:stage' for testing and 'build:prod' for production.

```bash
npm run build:stage

npm run build:prod
```

--------------------------------

### Initialize RuoYi-Vue Database

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/README.md

Import the provided SQL file into your MySQL database to initialize the RuoYi-Vue schema and data.

```bash
# Import SQL file to MySQL
mysql -uroot -p ry-vue < sql/ry_20240101.sql
```

--------------------------------

### Configure PageHelper for Pagination

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/configuration.md

Sets up database dialect, argument support, and parameter configuration for PageHelper pagination.

```yaml
pagehelper:
  helperDialect: mysql
  supportMethodsArguments: true
  params: count=countSql
```

--------------------------------

### Basic Application Configuration

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/configuration.md

Defines core project settings such as name, version, copyright year, file upload path, address lookup enablement, and captcha type.

```yaml
ruoyi:
  name: RuoYi
  version: 3.9.2
  copyrightYear: 2026
  profile: /home/ruoyi/uploadPath  # Linux环境
  addressEnabled: false
  captchaType: math
```

--------------------------------

### Create Product Entity, Mapper, Service, and Controller

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/README.md

Defines the structure for a new 'Product' entity, its corresponding data access interface (Mapper), business logic interface (Service), and web request handler (Controller).

```java
// 1. Create entity class
public class Product extends BaseEntity {
    private Long productId;
    private String productName;
    private Double price;
    
    // getter/setter...
}

// 2. Create Mapper interface
public interface ProductMapper {
    Product selectById(Long productId);
    List<Product> selectList(Product product);
    int insert(Product product);
    int update(Product product);
    int delete(Long productId);
}

// 3. Create Service interface and implementation
public interface IProductService {
    Product selectById(Long productId);
    List<Product> selectList(Product product);
    int insertProduct(Product product);
    int updateProduct(Product product);
    int deleteProduct(Long productId);
}

// 4. Create Controller
@RestController
@RequestMapping("/product")
public class ProductController extends BaseController {
    
    @Autowired
    private IProductService productService;
    
    @GetMapping("/list")
    public TableDataInfo list(Product product) {
        startPage();
        return getDataTable(productService.selectList(product));
    }
    
    @PostMapping
    @Log(title = "产品管理", businessType = BusinessType.INSERT)
    public AjaxResult add(@RequestBody Product product) {
        return toAjax(productService.insertProduct(product));
    }
}
```

--------------------------------

### Default Login Credentials

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/README.md

Use the default username 'admin' and password 'admin123' for initial login.

```text
- Username: admin
- Password: admin123
```

--------------------------------

### Activate Specific Configuration Profile

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/configuration.md

Activate a specific configuration profile using either command-line arguments or by setting it in `application.yml`. This allows for dynamic switching between different environment configurations.

```bash
java -jar ruoyi-admin.jar --spring.profiles.active=prod
```

```yaml
spring:
  profiles:
    active: prod
```

--------------------------------

### Development Environment Basic Configuration

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/configuration.md

Basic configuration for the development environment, including server port, database connection details (Druid master), Redis host, token expiration time, and logging level.

```yaml
server:
  port: 8080

spring:
  datasource:
    druid:
      master:
        url: jdbc:mysql://localhost:3306/ry-vue
        username: root
        password: root

  data:
    redis:
      host: localhost

token:
  expireTime: 720  # 开发环境设置较长的过期时间

logging:
  level:
    com.ruoyi: debug
```

--------------------------------

### LoginUser Constructor (User and Permissions)

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/authentication.md

Creates a LoginUser object with basic user information and permissions.

```java
public LoginUser(SysUser user, Set<String> permissions)
```

--------------------------------

### Add New User

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/DOCUMENTATION_INDEX.md

This snippet demonstrates how to add a new user. It uses `@HasPermi` for authorization, `@Log` for audit logging, and `toAjax` for handling the result of the `insertUser` operation.

```java
import com.ruoyi.common.core.controller.BaseController;
import com.ruoyi.common.core.domain.AjaxResult;
import com.ruoyi.common.annotation.HasPermi;
import com.ruoyi.common.annotation.Log;
import com.ruoyi.common.enums.BusinessType;
import com.ruoyi.system.domain.SysUser;
import com.ruoyi.system.service.ISysUserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;

@RequestMapping("/system/user")
public class UserController extends BaseController {

    @Autowired
    private ISysUserService userService;

    @PostMapping
    @HasPermi("system:user:add")
    @Log(title = "用户管理", businessType = BusinessType.INSERT)
    public AjaxResult add(@RequestBody SysUser user) {
        user.setCreateBy(getUsername());
        return toAjax(userService.insertUser(user));
    }
}
```

--------------------------------

### LoginUser Key Methods

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/authentication.md

Provides essential methods for retrieving user credentials and status, implementing the UserDetails interface.

```java
public String getUsername()
public String getPassword()
public Collection<? extends GrantedAuthority> getAuthorities()
public boolean isAccountNonExpired()
public boolean isAccountNonLocked()
public boolean isCredentialsNonExpired()
public boolean isEnabled()
```

--------------------------------

### LoginUser Constructor (Full Details)

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/authentication.md

Creates a comprehensive LoginUser object with user ID, department ID, user details, and permissions.

```java
public LoginUser(Long userId, Long deptId, SysUser user, Set<String> permissions)
```

--------------------------------

### Configure Swagger/SpringDoc API Documentation

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/configuration.md

Enables and configures the API documentation path and Swagger UI.

```yaml
springdoc:
  api-docs:
    path: /v3/api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
    tags-sorter: alpha
```

--------------------------------

### Production Environment Full Configuration

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/configuration.md

Comprehensive configuration for the production environment. Includes server thread pool settings, Druid connection pool details, Redis connection pool configuration, token secret retrieval from environment variables, and specific logging levels for different packages.

```yaml
server:
  port: 8080
  tomcat:
    threads:
      max: 1000
      min-spare: 200

spring:
  datasource:
    druid:
      master:
        url: jdbc:mysql://mysql.prod.example.com:3306/ry-vue
        username: prod_user
        password: ${DB_PASSWORD}
      minIdle: 20
      maxActive: 50

  data:
    redis:
      host: redis.prod.example.com
      password: ${REDIS_PASSWORD}
      lettuce:
        pool:
          max-active: 30

token:
  secret: ${TOKEN_SECRET}  # 从环境变量获取
  expireTime: 30

user:
  password:
    maxRetryCount: 3
    lockTime: 30

logging:
  level:
    com.ruoyi: info
    org.springframework: warn
```

--------------------------------

### Token Configuration

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/configuration.md

Sets up token header name, secret key for JWT signing, and token expiration time. Remember to use a strong, unique secret in production.

```yaml
token:
  header: Authorization
  secret: your-secret-key-with-sufficient-length
  expireTime: 30
```

--------------------------------

### Configure Druid Datasource

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/README.md

Edit the `application-druid.yml` file to set your database connection details, including URL, username, and password.

```yaml
spring:
  datasource:
    druid:
      master:
        url: jdbc:mysql://localhost:3306/ry-vue
        username: root
        password: your-password
```

--------------------------------

### Production Environment Configuration

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/configuration.md

Configuration for the production environment, typically using `application-prod.yml`. Sets the active profile to 'prod' and configures logging level for `com.ruoyi` to 'info'. Includes settings for address enablement, user password retry counts, and lock times.

```yaml
spring:
  profiles: prod
  
logging:
  level:
    com.ruoyi: info

ruoyi:
  addressEnabled: true

user:
  password:
    maxRetryCount: 3
    lockTime: 30
```

--------------------------------

### POST /system/role

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/endpoints.md

Creates a new role with specified details including name, key, sort order, status, remark, and associated menu IDs.

```APIDOC
## POST /system/role

### Description
Creates a new role with specified details including name, key, sort order, status, remark, and associated menu IDs.

### Method
POST

### Endpoint
/system/role

### Parameters
#### Request Body
- **roleName** (string) - Required - Role name
- **roleKey** (string) - Required - Permission character
- **roleSort** (integer) - Required - Sort order
- **status** (string) - Optional - 0 for normal, 1 for disabled
- **remark** (string) - Optional - Remarks
- **menuIds** (Array of integers) - Required - Array of menu IDs

### Request Example
```json
{
  "roleName": "string",
  "roleKey": "string",
  "roleSort": "integer",
  "status": "string",
  "remark": "string",
  "menuIds": [
    1,
    2,
    3
  ]
}
```
```

--------------------------------

### HTTP and Server Configuration

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/configuration.md

Configures the HTTP server port, application context path, and Tomcat-specific settings like URI encoding, connection queue, and thread pool sizes.

```yaml
server:
  port: 8080
  servlet:
    context-path: /
  tomcat:
    uri-encoding: UTF-8
    accept-count: 1000
    threads:
      max: 800
      min-spare: 100
```

--------------------------------

### Implement Product Data Caching with Redis

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/README.md

Retrieves product data from Redis cache first; if not found, it queries the database and then caches the result for future requests. Cache expiration is set to 30 minutes.

```java
@Autowired
private RedisCache redisCache;

public Product getProduct(Long productId) {
    String cacheKey = "product:" + productId;
    
    // First get from cache
    Product product = redisCache.getCacheObject(cacheKey);
    
    // Cache not found, query from database
    if (product == null) {
        product = productMapper.selectById(productId);
        if (product != null) {
            redisCache.setCacheObject(cacheKey, product, 30, TimeUnit.MINUTES);
        }
    }
    
    return product;
}
```

--------------------------------

### Cache System Configurations

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/redis-cache.md

Caches system configurations as a map. Allows retrieving specific configuration values by key from the cached map.

```java
public void initConfigCache() {
    Map<String, String> configMap = new HashMap<>();
    configMap.put("appName", "RuoYi");
    configMap.put("version", "3.9.2");
    configMap.put("copyright", "2024");
    
    redisCache.setCacheMap("config:system", configMap);
}

public String getConfig(String key) {
    return redisCache.getCacheMapValue("config:system", key);
}
```

--------------------------------

### Query User List

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/DOCUMENTATION_INDEX.md

Use this snippet to retrieve a paginated list of users. It requires the `userService` and `startPage` methods, and is annotated with `@HasPermi` for permission checking.

```java
import com.ruoyi.common.core.controller.BaseController;
import com.ruoyi.common.core.domain.AjaxResult;
import com.ruoyi.common.core.page.TableDataInfo;
import com.ruoyi.common.annotation.HasPermi;
import com.ruoyi.system.domain.SysUser;
import com.ruoyi.system.service.ISysUserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import java.util.List;

@RequestMapping("/system/user")
public class UserController extends BaseController {

    @Autowired
    private ISysUserService userService;

    @GetMapping("/list")
    @HasPermi("system:user:list")
    public TableDataInfo list(SysUser user) {
        startPage();
        List<SysUser> list = userService.selectUserList(user);
        return getDataTable(list);
    }
}
```

--------------------------------

### Development Environment Configuration

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/configuration.md

Configuration for the development environment, typically using `application-dev.yml`. Sets the active profile to 'dev' and configures logging level for `com.ruoyi` to 'debug'.

```yaml
spring:
  profiles: dev
  
logging:
  level:
    com.ruoyi: debug
```

--------------------------------

### Logging Configuration

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/configuration.md

Sets the logging levels for the RuoYi project and the Spring framework. Allows customization of log verbosity for different components.

```yaml
logging:
  level:
    com.ruoyi: debug
    org.springframework: warn
    com.alibaba.druid: debug
```

--------------------------------

### Handle Service Exceptions

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/DOCUMENTATION_INDEX.md

This snippet demonstrates how to catch and handle `ServiceException` during user insertion. It returns an error message to the client if an exception occurs. This pattern is useful for providing user-friendly error feedback.

```java
import com.ruoyi.common.exception.ServiceException;
import com.ruoyi.common.core.domain.AjaxResult;
import com.ruoyi.system.domain.SysUser;
import com.ruoyi.system.service.ISysUserService;

// Assuming userService is injected and user object is available
// ISysUserService userService;
// SysUser user;

try {
    userService.insertUser(user);
} catch (ServiceException e) {
    return AjaxResult.error(e.getMessage());
}
```

--------------------------------

### Simple Success Response

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/base-controller.md

Returns the simplest success response. Use this when no specific message or data needs to be conveyed beyond a general success status.

```java
public AjaxResult success()
```

```json
{
  "code": 200,
  "msg": "操作成功"
}
```

--------------------------------

### Configure Anti-Hotlinking

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/configuration.md

Enables anti-hotlinking and specifies allowed domains to prevent unauthorized resource access.

```yaml
referer:
  enabled: true
  allowed-domains: localhost,127.0.0.1,ruoyi.vip,www.ruoyi.vip
```

--------------------------------

### Implement Asynchronous Task Processing

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/README.md

Defines an asynchronous service method for background processing. This method simulates a task that takes 1 second to complete and prints a message upon completion.

```java
@Service
public class AsyncService {
    
    @Async
    public void asyncProcess(String data) {
        // Asynchronous processing logic
        Thread.sleep(1000);
        System.out.println("Asynchronous processing completed: " + data);
    }
}

// Usage
@PostMapping("/async-task")
public AjaxResult asyncTask(@RequestBody TaskData data) {
    asyncService.asyncProcess(data.getName());
    return success("Task submitted, please process shortly");
}
```

--------------------------------

### LoginUser Constructor (Empty)

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/authentication.md

Creates an empty LoginUser object.

```java
public LoginUser()
```

--------------------------------

### Use Redis Cache for User Data

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/DOCUMENTATION_INDEX.md

This snippet shows how to retrieve user data from Redis cache. If the data is not found, it fetches from the service and then caches it for 30 minutes. Ensure Redis cache is configured and available.

```java
import com.ruoyi.common.core.redis.RedisCache;
import com.ruoyi.system.domain.SysUser;
import com.ruoyi.system.service.ISysUserService;
import java.util.concurrent.TimeUnit;

// Assuming userId is available and userService and redisCache are injected
// ISysUserService userService;
// RedisCache redisCache;
// Long userId;

String cacheKey = "user:" + userId;
SysUser user = redisCache.getCacheObject(cacheKey);
if (user == null) {
    user = userService.selectUserById(userId);
    redisCache.setCacheObject(cacheKey, user, 30, TimeUnit.MINUTES);
}
```

--------------------------------

### LoginBody Class Signature

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/authentication.md

Defines the structure for user login requests, including username, password, and captcha details.

```java
public class LoginBody
```

--------------------------------

### Override Configuration with Environment Variables

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/configuration.md

Set environment variables to override application configuration properties. This is useful for managing sensitive information or environment-specific settings without modifying configuration files.

```bash
export RUOYI_PROFILE=/var/ruoyi/upload
export SERVER_PORT=9090
export SPRING_DATASOURCE_DRUID_MASTER_URL=jdbc:mysql://db.example.com:3306/ry-vue
export SPRING_DATA_REDIS_HOST=redis.example.com
export TOKEN_SECRET=your-production-secret-key
```

--------------------------------

### Spring File Upload Configuration

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/configuration.md

Defines the maximum size for individual files and the total size for multipart requests.

```yaml
spring:
  servlet:
    multipart:
      max-file-size: 10MB
      max-request-size: 20MB
```

--------------------------------

### Success Response Methods

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/base-controller.md

Methods for returning standardized success responses.

```APIDOC
## success()

### Description
Returns the simplest success response.

### Method Signature
```java
public AjaxResult success()
```

### Response
#### Success Response (200)
- **code** (integer) - 200
- **msg** (string) - "操作成功"

### Response Example
```json
{
  "code": 200,
  "msg": "操作成功"
}
```
```

```APIDOC
## success(String message)

### Description
Returns a success response with a custom message.

### Method Signature
```java
public AjaxResult success(String message)
```

### Parameters
#### Path Parameters
- **message** (String) - Required - The success message.

### Response
#### Success Response (200)
- **code** (integer) - 200
- **msg** (string) - The provided success message.

### Request Example
```java
@PostMapping("/add")
public AjaxResult add(@RequestBody SysUser user) {
    userService.insertUser(user);
    return success("用户添加成功");
}
```
```

```APIDOC
## success(Object data)

### Description
Returns a success response with data.

### Method Signature
```java
public AjaxResult success(Object data)
```

### Parameters
#### Path Parameters
- **data** (Object) - Required - The response data.

### Response
#### Success Response (200)
- **code** (integer) - 200
- **msg** (string) - "操作成功"
- **data** (Object) - The provided data.

### Request Example
```java
@GetMapping("/{userId}")
public AjaxResult getUser(@PathVariable Long userId) {
    SysUser user = userService.selectUserById(userId);
    return success(user);
}
```
```

```APIDOC
## success(String message, Object data)

### Description
Returns a success response with a custom message and data.

### Method Signature
```java
public AjaxResult success(String message, Object data)
```

### Parameters
#### Path Parameters
- **message** (String) - Required - The success message.
- **data** (Object) - Required - The response data.

### Response
#### Success Response (200)
- **code** (integer) - 200
- **msg** (string) - The provided success message.
- **data** (Object) - The provided data.

### Request Example
```java
@PostMapping("/add")
public AjaxResult add(@RequestBody SysUser user) {
    int rows = userService.insertUser(user);
    return success("用户添加成功", user);
}
```
```

--------------------------------

### Configure MyBatis Type Aliases and Mappers

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/configuration.md

Specifies the package for type aliases and the location of Mapper XML files for MyBatis.

```yaml
mybatis:
  typeAliasesPackage: com.ruoyi.**.domain
  mapperLocations: classpath*:mapper/**/*Mapper.xml
  configLocation: classpath:mybatis/mybatis-config.xml
```

--------------------------------

### Add Role API Request Body

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/endpoints.md

Defines the structure for creating a new role. Requires role name, key, sort order, and menu IDs. Status and remark are optional.

```json
{
  "roleName": "string",      // 必需，角色名称
  "roleKey": "string",       // 必需，权限字符
  "roleSort": "integer",     // 必需，排序
  "status": "string",        // 可选，0正常/1停用
  "remark": "string",        // 可选，备注
  "menuIds": [1, 2, 3]       // 必需，菜单ID数组
}
```

--------------------------------

### PageDomain JSON Structure

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/types.md

Defines parameters for pagination queries. Specifies current page, page size, sorting column, and sort order.

```json
{
  "pageNum": 1,
  "pageSize": 10,
  "orderByColumn": "createTime",
  "isAsc": "desc"
}
```

--------------------------------

### User Password Configuration

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/configuration.md

Configures the maximum number of password retries and the lockout duration after exceeding the retry limit.

```yaml
user:
  password:
    maxRetryCount: 5
    lockTime: 10
```

--------------------------------

### Success Response with Message and Data

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/base-controller.md

Returns a success response with both a custom message and data. This is useful for providing detailed feedback along with the operation's result.

```java
public AjaxResult success(String message, Object data)
```

```java
@PostMapping("/add")
public AjaxResult add(@RequestBody SysUser user) {
    int rows = userService.insertUser(user);
    return success("用户添加成功", user);
}
```

--------------------------------

### Success Response with Custom Message

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/base-controller.md

Returns a success response with a custom message. Use this to provide specific feedback to the client about the successful operation.

```java
public AjaxResult success(String message)
```

```java
@PostMapping("/add")
public AjaxResult add(@RequestBody SysUser user) {
    userService.insertUser(user);
    return success("用户添加成功");
}
```

--------------------------------

### Configure XSS Protection

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/configuration.md

Enables XSS filtering and defines excluded URLs and URL patterns for protection.

```yaml
xss:
  enabled: true
  excludes: /system/notice,/system/config
  urlPatterns: /system/*,/monitor/*,/tool/*
```

--------------------------------

### Success Response with Data

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/base-controller.md

Returns a success response that includes data. Use this when the operation's result is a specific object or collection that needs to be returned to the client.

```java
public AjaxResult success(Object data)
```

```java
@GetMapping("/{userId}")
public AjaxResult getUser(@PathVariable Long userId) {
    SysUser user = userService.selectUserById(userId);
    return success(user);
}
```

--------------------------------

### Pagination Response Format

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/endpoints.md

Standard response format for paginated list interfaces, including total records and current page data.

```json
{
  "total": 100,
  "rows": [...],
  "code": 200,
  "msg": "查询成功"
}
```

--------------------------------

### LoginBody

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/authentication.md

Represents the request body for user login operations. It includes fields for username, password, verification code, and its unique identifier.

```APIDOC
## LoginBody

### Description
User login request body.

### Attributes
- **username** (String) - Required - Username
- **password** (String) - Required - User password
- **code** (String) - Required - Verification code
- **uuid** (String) - Required - Verification code unique identifier

### JSON Example
```json
{
  "username": "admin",
  "password": "admin123",
  "code": "j3ki",
  "uuid": "8b8a0a1e-8b8a-4b8a-8b8a-8b8a0a1e8b8a"
}
```
```

--------------------------------

### BaseEntity Getter Methods

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/types.md

Provides getter methods for common auditing fields within BaseEntity.

```java
public String getSearchValue()
public void setSearchValue(String searchValue)

public String getCreateBy()
public void setCreateBy(String createBy)

public Date getCreateTime()
public void setCreateTime(Date createTime)

public String getUpdateBy()
public void setUpdateBy(String updateBy)

public Date getUpdateTime()
public void setUpdateTime(Date updateTime)

public String getRemark()
public void setRemark(String remark)

public Map<String, Object> getParams()
public void setParams(Map<String, Object> params)
```

--------------------------------

### LoginBody Getters and Setters

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/authentication.md

Provides accessors and mutators for the properties of the LoginBody object.

```java
public String getUsername()
public void setUsername(String username)

public String getPassword()
public void setPassword(String password)

public String getCode()
public void setCode(String code)

public String getUuid()
public void setUuid(String uuid)
```

--------------------------------

### LoginUser Getters and Setters

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/authentication.md

Provides accessors and mutators for all properties of the LoginUser object.

```java
public Long getUserId()
public void setUserId(Long userId)

public Long getDeptId()
public void setDeptId(Long deptId)

public String getToken()
public void setToken(String token)

public Long getLoginTime()
public void setLoginTime(Long loginTime)

public Long getExpireTime()
public void setExpireTime(Long expireTime)

public String getIpaddr()
public void setIpaddr(String ipaddr)

public String getLoginLocation()
public void setLoginLocation(String loginLocation)

public String getBrowser()
public void setBrowser(String browser)

public String getOs()
public void setOs(String os)

public Set<String> getPermissions()
public void setPermissions(Set<String> permissions)

public SysUser getUser()
public void setUser(SysUser user)
```

--------------------------------

### SysDept Class Definition

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/types.md

Defines the SysDept entity, which extends TreeEntity. It includes properties for department ID, parent ID, ancestors, name, order, leader, contact information, status, deletion flag, and a list of child departments.

```java
public class SysDept extends TreeEntity
```

--------------------------------

### Common HTTP Status Codes

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/endpoints.md

Reference for common status codes used in API responses.

```text
200 | 操作成功
301 | 操作警告
500 | 操作失败
401 | 未授权（需要登录）
403 | 禁止访问（无权限）
```

--------------------------------

### Cache User Information

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/redis-cache.md

Caches user data by user ID. Retrieves from cache first, then from the database if not found. Updates also clear the cache.

```java
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import java.util.concurrent.TimeUnit;

@Service
public class UserService {
    @Autowired
    private RedisCache redisCache;
    @Autowired
    private SysUserMapper userMapper;
    
    public SysUser getUserById(Long userId) {
        String cacheKey = "user:" + userId;
        
        // 先从缓存获取
        SysUser user = redisCache.getCacheObject(cacheKey);
        
        // 缓存不存在，从数据库查询
        if (user == null) {
            user = userMapper.selectById(userId);
            if (user != null) {
                // 缓存30分钟
                redisCache.setCacheObject(cacheKey, user, 30, TimeUnit.MINUTES);
            }
        }
        
        return user;
    }
    
    public void updateUser(SysUser user) {
        userMapper.update(user);
        // 更新后清除缓存
        redisCache.deleteObject("user:" + user.getUserId());
    }
}
```

--------------------------------

### LoginUser

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/authentication.md

Represents a logged-in user, containing permission information and implementing Spring Security's UserDetails interface. It holds details like user ID, department ID, token, login timestamps, IP address, and permissions.

```APIDOC
## LoginUser

### Description
Login user object, containing permission information, implements Spring Security's UserDetails interface.

### Attributes
- **userId** (Long) - User ID
- **deptId** (Long) - Department ID
- **token** (String) - JWT token
- **loginTime** (Long) - Login timestamp (milliseconds)
- **expireTime** (Long) - Token expiration timestamp (milliseconds)
- **ipaddr** (String) - Login IP address
- **loginLocation** (String) - Login location
- **browser** (String) - Browser type
- **os** (String) - Operating system
- **permissions** (Set<String>) - Permission string set
- **user** (SysUser) - User entity information

### Key Methods
#### getUsername()
Gets the username, implementing the UserDetails interface.
Returns: `String` username

#### getPassword()
Gets the password, implementing the UserDetails interface.
Returns: `String` encrypted password

#### getAuthorities()
Gets the list of authorities, implementing the UserDetails interface.
Returns: `Collection<SimpleGrantedAuthority>` list of authorities

#### isAccountNonExpired()
Checks if the account is not expired.
Returns: `boolean` true if the account is not expired

#### isAccountNonLocked()
Checks if the account is not locked.
Returns: `boolean` true if the account is not locked

#### isCredentialsNonExpired()
Checks if the credentials are not expired.
Returns: `boolean` true if the credentials are not expired

#### isEnabled()
Checks if the account is enabled.
Returns: `boolean` true if the account is enabled
```

--------------------------------

### Error Response Methods

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/base-controller.md

Methods for returning standardized error responses.

```APIDOC
## error()

### Description
Returns the default error response.

### Method Signature
```java
public AjaxResult error()
```

### Response
#### Error Response (500)
- **code** (integer) - 500
- **msg** (string) - "操作失败"

### Response Example
```json
{
  "code": 500,
  "msg": "操作失败"
}
```
```

```APIDOC
## error(String message)

### Description
Returns an error response with a custom error message.

### Method Signature
```java
public AjaxResult error(String message)
```

### Parameters
#### Path Parameters
- **message** (String) - Required - The error message.

### Response
#### Error Response (500)
- **code** (integer) - 500
- **msg** (string) - The provided error message.

### Request Example
```java
@PostMapping("/add")
public AjaxResult add(@RequestBody SysUser user) {
    if (StringUtils.isEmpty(user.getUserName())) {
        return error("用户名不能为空");
    }
    
    if (!userService.checkUserNameUnique(user)) {
        return error("用户名已存在");
    }
    
    userService.insertUser(user);
    return success("用户添加成功");
}
```
```

--------------------------------

### Cache User Permissions

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/redis-cache.md

Caches a set of user permissions for a specified duration. Retrieves the set of permissions from the cache.

```java
public void cachePermissions(Long userId, Set<String> permissions) {
    redisCache.setCacheSet("user:permissions:" + userId, permissions, 24, TimeUnit.HOURS);
}

public Set<String> getPermissions(Long userId) {
    return redisCache.getCacheSet("user:permissions:" + userId);
}
```

--------------------------------

### PUT /system/role

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/endpoints.md

Updates an existing role identified by its ID. Allows modification of name, key, sort order, status, and associated menu IDs.

```APIDOC
## PUT /system/role

### Description
Updates an existing role identified by its ID. Allows modification of name, key, sort order, status, and associated menu IDs.

### Method
PUT

### Endpoint
/system/role

### Parameters
#### Request Body
- **roleId** (long) - Required
- **roleName** (string) - Optional - Role name
- **roleKey** (string) - Optional - Permission character
- **roleSort** (integer) - Optional - Sort order
- **status** (string) - Optional - 0 for normal, 1 for disabled
- **menuIds** (Array of integers) - Optional - Array of menu IDs

### Request Example
```json
{
  "roleId": "long",
  "roleName": "string",
  "roleKey": "string",
  "roleSort": "integer",
  "status": "string",
  "menuIds": [
    1,
    2,
    3
  ]
}
```
```

--------------------------------

### Error Response with Custom Message

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/base-controller.md

Returns an error response with a specific error message. Use this to inform the client about the exact reason for the failure.

```java
public AjaxResult error(String message)
```

```java
@PostMapping("/add")
public AjaxResult add(@RequestBody SysUser user) {
    if (StringUtils.isEmpty(user.getUserName())) {
        return error("用户名不能为空");
    }
    
    if (!userService.checkUserNameUnique(user)) {
        return error("用户名已存在");
    }
    
    userService.insertUser(user);
    return success("用户添加成功");
}
```

--------------------------------

### SysRole Class Definition

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/types.md

Defines the SysRole entity, which extends BaseEntity. It includes properties for role ID, name, key, sort order, status, deletion flag, and associated menu and department IDs.

```java
public class SysRole extends BaseEntity
```

--------------------------------

### Default Error Response

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/base-controller.md

Returns a default error response. Use this for general server-side errors where a specific message is not immediately available or necessary.

```java
public AjaxResult error()
```

```json
{
  "code": 500,
  "msg": "操作失败"
}
```

--------------------------------

### General API Response Format

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/endpoints.md

All API responses adhere to this standard format, including a status code, message, and optional data payload.

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": { }
}
```

--------------------------------

### Add Permission Control to Controller Endpoint

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/README.md

Applies a custom annotation `@HasPermi` to a controller method to enforce specific user permissions for accessing the endpoint.

```java
@GetMapping("/list")
@HasPermi("product:list")  // Permission character
public TableDataInfo list(Product product) {
    startPage();
    return getDataTable(productService.selectList(product));
}
```

--------------------------------

### Delete Role API Path Parameter

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/endpoints.md

Specifies the role ID as a path parameter for deleting a role.

```json
{
  "roleId": "Long"           // 必需，角色ID
}
```

--------------------------------

### BaseEntity Class Definition

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/types.md

The base class for all business entities, providing common auditing fields like creation and update timestamps.

```java
public class BaseEntity implements Serializable
```

--------------------------------

### UserStatus Enum Definition

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/types.md

Defines the status of a user account, indicating whether it is active or disabled.

```java
public enum UserStatus {
    OK("0", "正常"),
    DISABLE("1", "停用");
    
    private String code;
    private String info;
}
```

--------------------------------

### LoginUser Class Signature

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/api-reference/authentication.md

Represents an authenticated user, implementing Spring Security's UserDetails interface with additional authorization information.

```java
public class LoginUser implements UserDetails
```

--------------------------------

### JWT Authentication Header

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/endpoints.md

Specifies the required format for JWT token authentication in request headers.

```text
Authorization: Bearer {token}
```

--------------------------------

### TreeSelect JSON Structure

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/types.md

Represents a node in a tree structure, commonly used for menu or department selection. Includes node ID, label, and a list of children.

```json
{
  "id": 100,
  "label": "深圳总公司",
  "children": [
    {
      "id": 101,
      "label": "深圳总公司-研发部门",
      "children": []
    }
  ]
}
```

--------------------------------

### DELETE /system/role/{roleId}

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/endpoints.md

Deletes a role based on its unique role ID.

```APIDOC
## DELETE /system/role/{roleId}

### Description
Deletes a role based on its unique role ID.

### Method
DELETE

### Endpoint
/system/role/{roleId}

### Parameters
#### Path Parameters
- **roleId** (Long) - Required - Role ID
```

--------------------------------

### BusinessStatus Enum Definition

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/types.md

Represents the status of a business operation, indicating success or failure.

```java
public enum BusinessStatus {
    SUCCESS,  // 成功
    FAIL      // 失败
}
```

--------------------------------

### TableDataInfo JSON Structure

Source: https://github.com/y_project/ruoyi-vue/blob/master/_autodocs/types.md

Encapsulates the result of a paginated query. Includes total records, current page data, status code, and a message.

```json
{
  "total": 100,
  "rows": [
    {
      "userId": 1,
      "userName": "admin"
    }
  ],
  "code": 200,
  "msg": "操作成功"
}
```