Yudao

https://github.com/yunaiv/ruoyi-vue-pro
Admin
An open-source Spring Boot 2.7 enterprise development platform with modular architecture,...
Tokens:37,342
Snippets:448
Trust Score:9.3
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Start HighGo Database Container

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/sql/tools/README.md

Load the HighGo image, tag it, and start the container.

```Bash
docker load -i <highgo-image>.tar
docker tag <image>:<tag> highgo:local
```

```Bash
docker compose up -d highgo
```

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

### Start KingbaseES Container

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/sql/tools/README.md

Load the KingbaseES image and start the container, followed by manual schema initialization.

```Bash
docker load -i kdb_x86_64_V009R001C001B0025.tar
```

```Bash
docker compose up -d kingbase
# 注意：启动完 kingbase 后，需要手动再执行如下命令
docker compose exec kingbase bash -c 'ksql -U $DB_USER -d test -f /tmp/schema.sql'
```

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

### Start OpenGauss Container

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/sql/tools/README.md

Start the OpenGauss container and manually execute the schema initialization script.

```Bash
docker compose up -d opengauss
# 注意：启动完 opengauss 后，需要手动再执行如下命令
docker compose exec opengauss bash -c '/usr/local/opengauss/bin/gsql -U $GS_USERNAME -W $GS_PASSWORD -d postgres -f /tmp/schema.sql'
```

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

### Start LiveKit Server PoC

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/script/livekit-poc/README.md

Commands to navigate to the directory, start the containers, and run the verification script.

```bash
cd tools/livekit-poc
docker compose up -d
bash verify.sh
```

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

### Start MySQL Container

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/sql/tools/README.md

Quickly start a MySQL database container using Docker Compose.

```Bash
docker compose up -d mysql
```

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

### Install SQL Conversion Dependencies

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/sql/tools/README.md

Install the required Python library for the database conversion script.

```Bash
pip install simple-ddl-parser
# pip3 install simple-ddl-parser
```

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

### Start PostgreSQL Container

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/sql/tools/README.md

Quickly start a PostgreSQL database container using Docker Compose.

```Bash
docker compose up -d postgres
```

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

### Start SQL Server Container

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/sql/tools/README.md

Start SQL Server and manually execute the schema creation script as it is not supported automatically.

```Bash
docker compose up -d sqlserver
# 注意：启动完 sqlserver 后，需要手动再执行如下命令，因为 SQL Server 不支持初始化脚本
docker compose exec sqlserver bash /tmp/create_schema.sh
```

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

### Start DM8 Database Container

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/sql/tools/README.md

Load the DM8 image and start the container, followed by manual schema initialization.

```Bash
docker load -i dm8_20240715_x86_rh6_rq_single.tar
```

```Bash
docker compose up -d dm8
# 注意：启动完 dm 后，需要手动再执行如下命令，因为 dm 不支持初始化脚本
docker compose exec dm8 bash -c 'printf "SET DEFINE OFF;\n" > /tmp/schema-with-define-off.sql && cat /tmp/schema.sql >> /tmp/schema-with-define-off.sql && /opt/dmdbms/bin/disql SYSDBA/SYSDBA001 `/tmp/schema-with-define-off.sql'
exit
```

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

### Start Oracle Container

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/sql/tools/README.md

Start Oracle database containers, with specific commands for x86 and Apple Silicon architectures.

```Bash
## x86 版本
docker compose up -d oracle

## MacBook Apple Silicon
docker compose up -d oracle_m1
```

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

### List Menu Tree Response

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/05-system-module-api.md

Example response from the GET /system/menu/list-tree endpoint returning a hierarchical structure.

```json
{
    "code": 0,
    "msg": "",
    "data": [
        {
            "id": 1,
            "name": "系统管理",
            "path": "/system",
            "children": [
                {
                    "id": 100,
                    "name": "用户管理",
                    "path": "/system/user"
                }
            ]
        }
    ]
}
```

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

### Build and start service

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/script/docker/Docker-HOWTO.md

Command to build and start the services using Docker Compose.

```shell
docker compose --env-file docker.env up -d
```

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

### File List

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/script/docker/Docker-HOWTO.md

Lists the relevant files and directories for Docker setup.

```text
. 
├── Docker-HOWTO.md 
├── docker-compose.yml 
├── docker.env <-- 提供docker-compose环境变量配置
├── yudao-server
│   └── Dockerfile
└── yudao-ui-admin
    ├── .dockerignore
    ├── Dockerfile
    └── nginx.conf <-- 提供基础配置，gzip压缩、api转发
```

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

### Define standard code example block

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

Use this format for language-specific code examples to ensure proper syntax highlighting.

```java
// Language-specific (java, yaml, json, bash)
// Syntax highlighted and executable
```

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

### Get Dictionary Data Response

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/05-system-module-api.md

Example response for retrieving dictionary data entries via GET /system/dict-data/get-dict-data.

```json
{
    "code": 0,
    "msg": "",
    "data": [
        {
            "label": "Pending",
            "value": "1"
        },
        {
            "label": "Shipped",
            "value": "2"
        }
    ]
}
```

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

### Get Permission Info API Usage

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/02-authentication-system.md

Example cURL request for retrieving user permissions.

```bash
curl -X GET http://localhost:8080/system/auth/get-permission-info \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

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

### List Endpoint Pagination Example

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/05-system-module-api.md

Standard usage of pagination parameters for list-based API requests.

```bash
GET /system/user/list?pageNo=1&pageSize=20
```

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

### Register User API Request

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/02-authentication-system.md

Example cURL command to register a new user account.

```bash
curl -X POST http://localhost:8080/system/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "password": "password123",
    "passwordConfirm": "password123",
    "mobile": "15601691300"
  }'
```

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

### Status Filtering Example

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/05-system-module-api.md

Example of filtering list results by status to exclude disabled records.

```bash
GET /system/user/list?status=0
```

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

### Apply ApiAccessLog Annotation

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/04-framework-web-components.md

Examples demonstrating manual configuration and automatic discovery of API logging metadata.

```java
@PostMapping("/create")
@ApiAccessLog(
    operateModule = "用户管理",
    operateName = "创建用户",
    operateType = OperateTypeEnum.CREATE,
    sanitizeKeys = {"password", "token"}
)
public CommonResult<UserRespVO> create(@RequestBody UserCreateReqVO req) {
    return success(userService.create(req));
}
```

```java
@Tag(name = "用户管理")
@RestController
@RequestMapping("/user")
public class UserController {
    
    @PostMapping("/create")
    @Operation(summary = "创建用户")
    @ApiAccessLog(operateType = OperateTypeEnum.CREATE)  // Module & name auto-read
    public CommonResult<UserRespVO> create(@RequestBody UserCreateReqVO req) {
        return success(userService.create(req));
    }
}
```

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

### Login API Usage

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/02-authentication-system.md

Example cURL request for performing a login operation.

```bash
curl -X POST http://localhost:8080/system/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "yudaoyuanma",
    "password": "buzhidao",
    "captchaId": "...",
    "captchaCode": "..."
  }'
```

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

### List Department Tree Response

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/05-system-module-api.md

Example response structure for retrieving the department hierarchy via GET /system/dept/list-tree.

```json
{
    "code": 0,
    "msg": "",
    "data": [
        {
            "id": 100,
            "name": "Headquarters",
            "children": [
                {
                    "id": 101,
                    "name": "Development Department"
                }
            ]
        }
    ]
}
```

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

### Usage Example in Response VO

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/04-framework-web-components.md

Demonstrates how to apply multiple desensitization annotations within a response object.

```java
@Data
public class UserRespVO {
    private Long id;
    
    @MobileDesensitize
    private String mobile;  // "15601691300" → "156****1300"
    
    @ChineseNameDesensitize
    private String realName;  // "赵勇强" → "赵*强"
    
    @EmailDesensitize
    private String email;  // "test@example.com" → "t****@example.com"
}
```

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

### Example JSON Response

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/04-framework-web-components.md

Shows the resulting JSON output after desensitization is applied.

```json
{
    "id": 1,
    "mobile": "156****1300",
    "realName": "赵*强",
    "email": "t****@example.com"
}
```

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

### GET /system/user

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/03-types-and-data-structures.md

Retrieves a paginated list of users from the system.

```APIDOC
## GET /system/user

### Description
Retrieves a paginated list of users.

### Method
GET

### Endpoint
/system/user

### Parameters
#### Query Parameters
- **pageNo** (integer) - Optional - The page number to retrieve
- **pageSize** (integer) - Optional - The number of items per page

### Request Example
curl -X GET "http://localhost:8080/system/user?pageNo=1&pageSize=10" \
  -H "Authorization: Bearer token"

### Response
#### Success Response (200)
- **list** (array) - List of user objects
- **total** (integer) - Total number of records

#### Response Example
{
    "code": 0,
    "msg": "",
    "data": {
        "list": [
            {
                "id": 1,
                "username": "admin",
                "email": "admin@example.com"
            }
        ],
        "total": 100
    }
}
```

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

### Social Quick Login Request Example

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/02-authentication-system.md

cURL command to perform a social login using an authorization code.

```bash
curl -X POST http://localhost:8080/system/auth/social-login \
  -H "Content-Type: application/json" \
  -d '{
    "socialType": 10,
    "code": "authorization_code_from_wechat",
    "state": "state_param"
  }'
```

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

### Exception Response Examples

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/03-types-and-data-structures.md

Standardized JSON error responses for different exception types.

```json
{
    "code": 1001001000,
    "msg": "用户不存在",
    "data": null
}
```

```json
{
    "code": 500,
    "msg": "系统异常",
    "data": null
}
```

```json
{
    "code": 400,
    "msg": "请求参数不正确",
    "data": {
        "username": "登录账号不能为空",
        "password": "密码长度为 4-16 位"
    }
}
```

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

### GET /system/user/list

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/05-system-module-api.md

Retrieves a paginated list of users with optional filters.

```APIDOC
## GET /system/user/list

### Description
List users with pagination and filtering.

### Method
GET

### Endpoint
/system/user/list

### Parameters
#### Query Parameters
- **pageNo** (Integer) - Optional - Page number (default: 1)
- **pageSize** (Integer) - Optional - Items per page (default: 10)
- **username** (String) - Optional - Filter by username
- **mobile** (String) - Optional - Filter by mobile
- **status** (Integer) - Optional - Filter by status (0/1)
- **deptId** (Long) - Optional - Filter by department
- **createTime** (LocalDateTime[]) - Optional - Filter by date range
```

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

### GET /system/operation-log/list

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/05-system-module-api.md

Retrieves a paginated list of system operation logs based on optional filters.

```APIDOC
## GET /system/operation-log/list

### Description
Retrieves a paginated list of system operation logs.

### Method
GET

### Endpoint
/system/operation-log/list

### Parameters
#### Query Parameters
- **pageNo** (Integer) - Optional - Page number
- **pageSize** (Integer) - Optional - Items per page
- **module** (String) - Optional - Filter by module
- **type** (Integer) - Optional - Filter by operation type
- **startTime** (LocalDateTime) - Optional - Start date
- **endTime** (LocalDateTime) - Optional - End date
- **succeed** (Boolean) - Optional - Filter by success/failure

### Response
#### Success Response (200)
- **id** (Integer) - Log ID
- **module** (String) - Module name
- **name** (String) - Operation name
- **type** (Integer) - Operation type
- **userId** (Integer) - User ID
- **username** (String) - Username
- **result** (Integer) - Result code
- **resultMsg** (String) - Result message
- **requestMethod** (String) - HTTP method
- **requestUrl** (String) - Request URL
- **requestIp** (String) - Request IP
- **userAgent** (String) - User agent string
- **createTime** (LocalDateTime) - Creation timestamp
```

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

### Pagination API Request

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/03-types-and-data-structures.md

Example cURL request for paginated data retrieval.

```bash
curl -X GET "http://localhost:8080/system/user?pageNo=1&pageSize=10" \
  -H "Authorization: Bearer token"
```

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

### Refresh Token API Usage

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/02-authentication-system.md

Example cURL request for refreshing an access token.

```bash
curl -X POST "http://localhost:8080/system/auth/refresh-token?refreshToken=eyJ..."
```

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

### GET /system/menu/list-tree

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/05-system-module-api.md

Retrieves the hierarchical menu structure for frontend navigation.

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

### Description
Returns the full hierarchical menu structure used for rendering the frontend navigation tree.

### Method
GET

### Endpoint
/system/menu/list-tree

### Response
#### Success Response (200)
- **data** (List) - Hierarchical list of menu objects

#### Response Example
{
    "code": 0,
    "msg": "",
    "data": [
        {
            "id": 1,
            "name": "系统管理",
            "path": "/system",
            "children": [
                {
                    "id": 100,
                    "name": "用户管理",
                    "path": "/system/user"
                }
            ]
        }
    ]
}
```

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

### Global Response Wrapping Examples

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/04-framework-web-components.md

Demonstrates how GlobalResponseBodyHandler automatically wraps raw controller returns while preserving existing CommonResult objects.

```java
// Before: Controller returns raw object
@GetMapping("/user/{id}")
public UserRespVO getUser(@PathVariable Long id) {
    return userService.getUser(id);
}

// After: Wrapped in CommonResult
{
    "code": 0,
    "msg": "",
    "data": {
        "id": 1,
        "username": "admin",
        "email": "admin@example.com"
    }
}

// Before: Controller returns CommonResult
@GetMapping("/user/{id}")
public CommonResult<UserRespVO> getUser(@PathVariable Long id) {
    return success(userService.getUser(id));
}

// After: No double wrapping (returned as-is)
{
    "code": 0,
    "msg": "",
    "data": {
        "id": 1,
        "username": "admin"
    }
}
```

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

### Logout API Usage

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/02-authentication-system.md

Example cURL request for logging out the current user.

```bash
curl -X POST http://localhost:8080/system/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

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

### Get Permission Info Controller Method

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/02-authentication-system.md

Defines the signature for retrieving user permission information.

```java
public CommonResult<AuthPermissionInfoRespVO> getPermissionInfo()
```

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

### GET /system/auth/get-permission-info

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/02-authentication-system.md

Retrieve the current user's permission information including roles, menus, and buttons.

```APIDOC
## GET /system/auth/get-permission-info

### Description
Retrieve the current user's permission information including roles, menus, and buttons.

### Method
GET

### Endpoint
/system/auth/get-permission-info

### Parameters
- **Authorization** (Header) - Required - Bearer <token>

### Response
#### Success Response (200)
- **user** (Object) - User profile information
- **roles** (Array) - List of assigned roles
- **menus** (Array) - List of accessible menus

#### Response Example
{
  "user": {
    "id": 1,
    "username": "yudaoyuanma",
    "nickname": "芋道",
    "email": "yudao@iocoder.cn",
    "mobile": "15601691300",
    "status": 0
  },
  "roles": [
    {
      "id": 1,
      "name": "超级管理员",
      "code": "admin"
    }
  ],
  "menus": [
    {
      "id": 100,
      "name": "系统管理",
      "path": "/system",
      "icon": "system"
    }
  ]
}
```

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

### Startup Configuration Logging

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/06-framework-configuration.md

Monitor configuration sources and connection strings during application startup.

```text
# Application logs on startup
Configuration loaded from application-${profile}.yml
Database: jdbc:mysql://host:3306/db
Redis: host:6379
```

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

### Configure Quartz Scheduler

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/06-framework-configuration.md

Sets up the Quartz job store type, database schema initialization, and thread pool parameters.

```yaml
spring:
  quartz:
    job-store-type: jdbc         # Store in database
    jdbc:
      initialize-schema: never   # Don't auto-init schema
    wait-for-jobs-to-complete-on-shutdown: true
    properties:
      org:
        quartz:
          scheduler:
            instanceName: yudaoScheduler
            instanceId: AUTO
          jobStore:
            driverDelegateClass: org.quartz.impl.jdbcjobstore.StdJDBCDelegate
            useProperties: true
            tablePrefix: QRTZ_
            misfireThreshold: 60000
          threadPool:
            threadCount: 10       # Thread pool size
```

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

### Documenting Configuration Defaults

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/06-framework-configuration.md

Include comments for default values and tuning parameters to assist in environment-specific adjustments.

```yaml
# Connection pool
spring:
  datasource:
    druid:
      max-active: 20         # Max active connections (increase for heavy load)
      min-idle: 5            # Min idle connections (adjust based on traffic)
```

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

### GET /system/dept/list-tree

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/05-system-module-api.md

Retrieves the department list as a tree structure.

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

### Description
Fetches all departments organized in a hierarchical tree structure.

### Method
GET

### Endpoint
/system/dept/list-tree

### Response
#### Success Response (200)
- **data** (Array) - List of department objects with children

#### Response Example
{
    "code": 0,
    "msg": "",
    "data": [
        {
            "id": 100,
            "name": "Headquarters",
            "children": [
                {
                    "id": 101,
                    "name": "Development Department"
                }
            ]
        }
    ]
}
```

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

### GET /system/dict-data/get-dict-data

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/05-system-module-api.md

Retrieves dictionary data entries for a specific type.

```APIDOC
## GET /system/dict-data/get-dict-data

### Description
Retrieves all data entries associated with a given dictionary type.

### Method
GET

### Endpoint
/system/dict-data/get-dict-data

### Parameters
#### Query Parameters
- **type** (String) - Required - The dictionary type identifier

### Response Example
{
    "code": 0,
    "msg": "",
    "data": [
        {
            "label": "Pending",
            "value": "1"
        },
        {
            "label": "Shipped",
            "value": "2"
        }
    ]
}
```

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

### POST /system/menu

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/05-system-module-api.md

Creates a new menu or permission entry in the system.

```APIDOC
## POST /system/menu

### Description
Creates a new menu or permission entry.

### Method
POST

### Endpoint
/system/menu

### Request Body
- **name** (String) - Required - Menu display name
- **path** (String) - Optional - Route path
- **component** (String) - Optional - Vue component path
- **icon** (String) - Optional - Menu icon
- **type** (Integer) - Required - 1=Menu, 2=Permission
- **status** (Integer) - Required - 0=enabled, 1=disabled
- **permissions** (List<String>) - Optional - Permission identifiers
- **parentId** (Long) - Optional - Parent menu ID (0=root)
- **sort** (Integer) - Optional - Display order

### Request Example
{
    "name": "User Management",
    "path": "/system/user",
    "component": "system/user/index",
    "icon": "peoples",
    "type": 1,
    "status": 0,
    "permissions": ["system:user:query", "system:user:add"],
    "parentId": 0,
    "sort": 1
}
```

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

### Run SQL Conversion Script

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/sql/tools/README.md

Execute the conversion script to generate SQL for target databases.

```Bash
python3 convertor.py postgres
# python3 convertor.py postgres > tmp.sql
# python3 convertor.py highgo ../mysql/ruoyi-vue-pro.sql > ../highgo/ruoyi-vue-pro.sql
```

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

### Configure Swagger/Springdoc

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/06-framework-configuration.md

Sets up the API documentation paths and package scanning for Springdoc.

```yaml
springdoc:
  api-docs:
    path: /v3/api-docs           # API docs path
  swagger-ui:
    path: /swagger-ui.html       # Swagger UI path
    enabled: true                # Enable Swagger UI
  
  packages-to-scan: cn.iocoder.yudao.module  # Scan packages
  paths-to-match: /**            # Match all paths
```

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

### Configure Aliyun OSS Storage

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/06-framework-configuration.md

Configures Aliyun OSS by providing region, endpoint, credentials, bucket name, and domain.

```yaml
yudao:
  file:
    storage-type: aliyun         # Use Aliyun OSS
    aliyun:
      region: oss-cn-beijing     # Region
      endpoint: https://oss-cn-beijing.aliyuncs.com
      access-key-id: "${ALIYUN_ACCESS_KEY_ID}"      # From environment
      access-key-secret: "${ALIYUN_ACCESS_KEY_SECRET}"
      bucket: yudao-bucket       # Bucket name
      domain: https://yudao.oss-cn-beijing.aliyuncs.com
```

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

### GET /system/user/{id}

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/05-system-module-api.md

Retrieves details for a specific user by ID.

```APIDOC
## GET /system/user/{id}

### Description
Get user details by ID.

### Method
GET

### Endpoint
/system/user/{id}

### Parameters
#### Path Parameters
- **id** (Long) - Required - User ID
```

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

### Enable HTTPS in Production

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/07-best-practices-and-patterns.md

Configure SSL settings in the server and security modules to ensure encrypted communication.

```yaml
server:
  ssl:
    enabled: true
    key-store: classpath:keystore.p12

yudao:
  security:
    require-https: true
```

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

### Configure DataSource and Druid Connection Pool

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/06-framework-configuration.md

Sets up the MySQL driver, connection URL, and Druid connection pool parameters for database management.

```yaml
spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://127.0.0.1:3306/yudao?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true
    username: root
    password: root
    
    # Connection Pool (Druid)
    type: com.alibaba.druid.pool.DruidDataSource
    druid:
      initial-size: 5            # Initial pool size
      max-active: 20             # Max active connections
      min-idle: 5                # Min idle connections
      max-wait: 60000            # Max wait time (ms)
      time-between-eviction-runs-millis: 60000  # Eviction interval
      min-evictable-idle-time-millis: 300000    # Min idle time before evict
      test-while-idle: true      # Test connection while idle
      test-on-borrow: false      # Test on borrow
      test-on-return: false      # Test on return
      validation-query: SELECT 1 # Validation query
```

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

### Configure Server and Application Settings

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/06-framework-configuration.md

Defines the application name, active profile, and web server properties including port and compression settings.

```yaml
spring:
  application:
    name: yudao-server           # Application name
    version: @project.version@   # Project version (Maven filtered)
  
  profiles:
    active: dev                  # Active profile
  
  # Web Server
  servlet:
    context-path: /              # Application context path
  
  server:
    port: 8080                   # Server port
    compression:
      enabled: true              # Enable gzip compression
      min-response-size: 1024    # Minimum response size to compress
```

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

### Configure development environment profile

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/06-framework-configuration.md

Development configuration settings for local database and Redis instances.

```yaml
server:
  port: 8080

spring:
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/yudao_dev
  redis:
    host: 127.0.0.1

logging:
  level:
    root: INFO
    cn.iocoder.yudao: DEBUG

yudao:
  security:
    jwt:
      secret: dev_secret_key
  demo-enable: true              # Demo mode
```

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

### POST /system/post

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/05-system-module-api.md

Creates a new organizational post.

```APIDOC
## POST /system/post

### Description
Creates a new organizational post in the system.

### Method
POST

### Endpoint
/system/post

### Request Body
- **name** (String) - Required - Post name
- **code** (String) - Required - Post code
- **status** (Integer) - Required - Post status
- **sort** (Integer) - Required - Sort order
```

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

### Example Paginated JSON Response

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/03-types-and-data-structures.md

The structure of a JSON response containing paginated data.

```json
{
    "code": 0,
    "msg": "",
    "data": {
        "list": [
            {"id": 1, "name": "Item 1"},
            {"id": 2, "name": "Item 2"}
        ],
        "total": 100
    }
}
```

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

### Configure Infrastructure Module Settings

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/06-framework-configuration.md

Manages code generation paths, file upload constraints, and API documentation settings.

```yaml
yudao:
  infra:
    # Code generation
    codegen:
      template-path: /templates/codegen  # Template directory
      output-path: /gen/code              # Output directory
    
    # File upload
    upload:
      max-file-size: 104857600   # 100MB
      allowed-extensions: txt,doc,docx,xls,xlsx,pdf,zip
    
    # API documentation
    api-doc:
      enable: true               # Enable API docs
      format: markdown           # Export format
```

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

### Get User Endpoint

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/05-system-module-api.md

Request format for retrieving details of a specific user by ID.

```http
GET /system/user/100
Authorization: Bearer <token>
```

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

### POST /system/auth/register

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/02-authentication-system.md

Registers a new user account in the system.

```APIDOC
## POST /system/auth/register

### Description
Register a new user account in the system.

### Method
POST

### Endpoint
/system/auth/register

### Request Body
- **username** (String) - Required - Desired username (4-30 characters, alphanumeric)
- **password** (String) - Required - Password (4-16 characters)
- **passwordConfirm** (String) - Required - Password confirmation (must match password)
- **mobile** (String) - Optional - Phone number for SMS verification
- **email** (String) - Optional - Email address
- **verificationCode** (String) - Conditional - SMS or email verification code

### Request Example
{
  "username": "newuser",
  "password": "password123",
  "passwordConfirm": "password123",
  "mobile": "15601691300"
}
```

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

### Use CommonResult for API Responses

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/03-types-and-data-structures.md

Examples of creating success/error responses and handling result validation.

```java
// Success response
CommonResult<UserVO> success = CommonResult.success(new UserVO(1L, "user"));
// Output: {"code": 0, "msg": "", "data": {...}}

// Error response with error code
CommonResult<Void> error = CommonResult.error(
    GlobalErrorCodeConstants.BAD_REQUEST);
// Output: {"code": 400, "msg": "请求参数不正确", "data": null}

// Check result and extract data safely
CommonResult<UserVO> result = getUserResult();
if (result.isSuccess()) {
    UserVO user = result.getData();
}

// Throw exception if error
result.checkError(); // Throws ServiceException if error
UserVO user = result.getCheckedData(); // Returns data or throws
```

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

### Configure SLF4J with Logback

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/06-framework-configuration.md

Defines logging levels, file rotation policies, and output patterns for the application.

```yaml
logging:
  level:
    root: INFO                   # Root logger level
    cn.iocoder.yudao: DEBUG      # Application logger level
    org.springframework: INFO     # Spring framework level
    com.alibaba.druid: INFO      # Druid connection pool level
  
  file:
    name: logs/yudao.log         # Log file path
    max-size: 10MB               # Max file size
    max-history: 30              # Max history days
  
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n"
    file: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n"
```

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

### Build jar package

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/script/docker/Docker-HOWTO.md

Commands to create a Maven cache volume and build the jar package using Docker.

```shell
# 创建maven缓存volume
docker volume create --name yudao-maven-repo

docker run -it --rm --name yudao-maven \
    -v yudao-maven-repo:/root/.m2 \
    -v $PWD:/usr/src/mymaven \
    -w /usr/src/mymaven \
    maven mvn clean install package '-Dmaven.test.skip=true'
```

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

### Configure production environment profile

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/06-framework-configuration.md

Production settings including SSL, connection pooling, and externalized secrets.

```yaml
server:
  port: 8080
  ssl:
    enabled: true                # Enable HTTPS
    key-store: classpath:keystore.p12
    key-store-password: "${KEYSTORE_PASSWORD}"
    key-store-type: PKCS12

spring:
  datasource:
    url: jdbc:mysql://prod-db:3306/yudao
    hikari:
      maximum-pool-size: 30      # Larger pool for production
  redis:
    host: prod-redis
    password: "${REDIS_PASSWORD}"

logging:
  level:
    root: WARN
    cn.iocoder.yudao: INFO
  file:
    name: /var/log/yudao/yudao.log

yudao:
  security:
    jwt:
      secret: "${JWT_SECRET}"
    require-https: true          # Require HTTPS
  demo-enable: false
```

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

### Throw Exceptions in Service Layer

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/07-best-practices-and-patterns.md

Examples of throwing business and system exceptions within service methods.

```java
// Business validation error
if (resource == null) {
    throw new ServiceException(RESOURCE_NOT_FOUND);
}

// With context in message
if (resource == null) {
    throw new ServiceException(RESOURCE_NOT_FOUND.getCode(), 
        "资源ID " + id + " 不存在");
}

// Chained throw
LambdaQueryWrapper<ResourceDO> queryWrapper = 
    Wrappers.<ResourceDO>lambdaQuery().eq(ResourceDO::getId, id);
ResourceDO resource = resourceMapper.selectOne(queryWrapper);
if (resource == null) {
    throw new ServiceException(RESOURCE_NOT_FOUND);
}

// System error (rare)
try {
    // external API call
} catch (Exception e) {
    throw new ServerException(INTERNAL_SERVER_ERROR);
}
```

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

### Unit Testing with Spring Boot

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/07-best-practices-and-patterns.md

Demonstrates a standard unit test structure using @SpringBootTest, including data preparation, service invocation, and database verification.

```java
@SpringBootTest
@ActiveProfiles("test")
class ResourceServiceTest {
    
    @Resource
    private ResourceService resourceService;
    
    @Resource
    private ResourceMapper resourceMapper;
    
    @Test
    public void testCreate() {
        // 1. Prepare data
        ResourceCreateReqVO req = ResourceCreateReqVO.builder()
            .name("Test Resource")
            .description("Test Description")
            .type(1)
            .build();
        
        // 2. Call service
        ResourceRespVO resp = resourceService.create(req);
        
        // 3. Verify result
        assertNotNull(resp.getId());
        assertEquals("Test Resource", resp.getName());
        
        // 4. Verify database
        ResourceDO resource = resourceMapper.selectById(resp.getId());
        assertNotNull(resource);
        assertEquals("Test Resource", resource.getName());
    }
    
    @Test
    public void testCreateDuplicateName() {
        // Setup
        ResourceCreateReqVO req = ResourceCreateReqVO.builder()
            .name("Duplicate")
            .description("desc")
            .type(1)
            .build();
        resourceService.create(req);
        
        // Test duplicate
        assertThrows(ServiceException.class, () -> {
            resourceService.create(req);
        });
    }
}
```

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

### Implementing Feature Toggles

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/06-framework-configuration.md

Use profiles or environment variables to manage feature toggles with sensible defaults.

```yaml
yudao:
  demo-enable: "${DEMO_ENABLE:false}"  # Feature toggle with default
```

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

### POST /system/user

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/05-system-module-api.md

Creates a new admin user in the system.

```APIDOC
## POST /system/user

### Description
Create a new admin user.

### Method
POST

### Endpoint
/system/user

### Request Body
- **username** (String) - Required - 4-30 alphanumeric characters
- **password** (String) - Required - 4-16 characters
- **nickname** (String) - Required - Display name
- **email** (String) - Optional - Email address (unique)
- **mobile** (String) - Optional - Phone number (unique)
- **deptId** (Long) - Optional - Department ID
- **postIds** (List<Long>) - Optional - Post IDs
- **roleIds** (List<Long>) - Optional - Role IDs
- **status** (Integer) - Required - 0=enabled, 1=disabled

### Request Example
{
    "username": "newuser",
    "password": "password123",
    "nickname": "New User",
    "email": "newuser@example.com",
    "mobile": "15601691300",
    "deptId": 103,
    "postIds": [1, 2],
    "roleIds": [2],
    "status": 0
}
```

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

### WebFrameworkUtils Helper Methods

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/04-framework-web-components.md

Provides static utility methods for extracting request information such as IDs, paths, client IPs, and authorization tokens.

```java
public class WebFrameworkUtils {
    // Get request ID for tracing
    public static String getRequestId(HttpServletRequest request)
    
    // Get request path
    public static String getRequestPath(HttpServletRequest request)
    
    // Get client IP address
    public static String getClientIp(HttpServletRequest request)
    
    // Extract authorization token
    public static String getAuthorization(HttpServletRequest request)
}
```

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

### POST /system/auth/login

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/02-authentication-system.md

Login with username and password, optionally binding a social account simultaneously.

```APIDOC
## POST /system/auth/login

### Description
Login with username and password, optionally binding a social account simultaneously.

### Method
POST

### Endpoint
/system/auth/login

### Parameters
#### Request Body
- **username** (String) - Required - Login username (4-30 alphanumeric characters)
- **password** (String) - Required - Login password (4-16 characters)
- **socialType** (Integer) - Optional - Social platform type enum value (10=WeChat, etc.)
- **socialCode** (String) - Conditional - Authorization code from social platform (required if socialType provided)
- **socialState** (String) - Conditional - OAuth state parameter (required if socialType provided)
- **captchaVerificationReqVO** (CaptchaVerificationReqVO) - Required - CAPTCHA verification data

### Request Example
{
  "username": "yudaoyuanma",
  "password": "buzhidao",
  "captchaId": "...",
  "captchaCode": "..."
}

### Response
#### Success Response (200)
- **userId** (Long) - Unique user identifier
- **accessToken** (String) - JWT token for API authentication (short-lived)
- **refreshToken** (String) - Token to refresh access token (long-lived)
- **expiresTime** (LocalDateTime) - Access token expiration timestamp

#### Response Example
{
  "userId": 1,
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresTime": "2024-08-08T18:30:00"
}
```

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

### Social Auth Redirect Response Example

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/02-authentication-system.md

JSON response structure containing the authorization URL for social platforms.

```json
{
    "code": 0,
    "msg": "成功",
    "data": "https://open.weixin.qq.com/connect/oauth2/authorize?appid=..."
}
```

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

### SMS Login API Request

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/02-authentication-system.md

Example cURL command to authenticate using a mobile number and SMS code.

```bash
curl -X POST http://localhost:8080/system/auth/sms-login \
  -H "Content-Type: application/json" \
  -d '{
    "mobile": "15601691300",
    "smsCode": "123456"
  }'
```

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

### GET /system/auth/social-auth-redirect

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/02-authentication-system.md

Redirects the user to the social platform's OAuth authorization page to initiate the login flow.

```APIDOC
## GET /system/auth/social-auth-redirect

### Description
Redirect user to social platform's OAuth authorization page.

### Method
GET

### Endpoint
/system/auth/social-auth-redirect

### Parameters
#### Query Parameters
- **type** (Integer) - Required - Social platform type: 10=WeChat, 20=DingTalk, 30=Alipay, etc.
- **redirectUri** (String) - Optional - Return URL after authorization

### Response
#### Success Response (200)
- **data** (String) - Authorization URL to redirect to

#### Response Example
{
    "code": 0,
    "msg": "成功",
    "data": "https://open.weixin.qq.com/connect/oauth2/authorize?appid=..."
}
```

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

### POST /system/auth/login

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

Authenticates a user and returns access and refresh tokens.

```APIDOC
## POST /system/auth/login

### Description
Authenticates the user credentials and returns an access token and a refresh token.

### Method
POST

### Endpoint
/system/auth/login

### Response
#### Success Response (200)
- **accessToken** (string) - The token used for authorized requests.
- **refreshToken** (string) - The token used to refresh the access token.
```

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

### Reset Password API Request

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/02-authentication-system.md

Example cURL command to update a user password using a valid SMS code.

```bash
curl -X POST http://localhost:8080/system/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "mobile": "15601691300",
    "smsCode": "123456",
    "newPassword": "newpassword"
  }'
```

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

### POST /system/dict-type

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/05-system-module-api.md

Creates a new dictionary type.

```APIDOC
## POST /system/dict-type

### Description
Registers a new dictionary type category.

### Method
POST

### Endpoint
/system/dict-type

### Request Example
{
    "type": "order_status",
    "name": "Order Status",
    "status": 0,
    "remark": "订单状态"
}
```

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

### Send SMS Code API Request

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/02-authentication-system.md

Example cURL command to request an SMS verification code for a specific scenario.

```bash
curl -X POST http://localhost:8080/system/auth/send-sms-code \
  -H "Content-Type: application/json" \
  -d '{
    "mobile": "15601691300",
    "smsScene": "login"
  }'
```

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

### Implement Standard Service Layer in Java

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/07-best-practices-and-patterns.md

A template for a service class demonstrating CRUD operations, business validation, and data conversion using MapStruct and MyBatis Plus.

```java
@Service
public class ResourceService {
    
    @Resource
    private ResourceMapper resourceMapper;
    
    @Resource
    private ResourceConvert resourceConvert;
    
    // ========== Create ==========
    
    public ResourceRespVO create(ResourceCreateReqVO req) {
        // 1. Validate business rules
        checkNameDuplicate(null, req.getName());
        
        // 2. Convert VO to DO
        ResourceDO resource = resourceConvert.convert(req);
        
        // 3. Set audit fields
        resource.setCreator(SecurityFrameworkUtils.getLoginUserId());
        resource.setCreateTime(LocalDateTime.now());
        
        // 4. Insert to database
        resourceMapper.insert(resource);
        
        // 5. Convert DO to VO and return
        return resourceConvert.convert(resource);
    }
    
    // ========== Update ==========
    
    public ResourceRespVO update(Long id, ResourceUpdateReqVO req) {
        // 1. Check exists
        ResourceDO resource = checkResourceExists(id);
        
        // 2. Validate business rules
        checkNameDuplicate(id, req.getName());
        
        // 3. Convert VO to DO
        ResourceDO updateResource = resourceConvert.convert(req);
        
        // 4. Update to database
        resourceMapper.updateById(updateResource);
        
        // 5. Get updated record and return
        return get(id);
    }
    
    // ========== Delete ==========
    
    public void delete(Long id) {
        // 1. Check exists
        checkResourceExists(id);
        
        // 2. Check if referenced
        checkIfReferenced(id);
        
        // 3. Delete from database
        resourceMapper.deleteById(id);
    }
    
    // ========== Get ==========
    
    public ResourceRespVO get(Long id) {
        ResourceDO resource = checkResourceExists(id);
        return resourceConvert.convert(resource);
    }
    
    public ResourceDO getById(Long id) {
        return resourceMapper.selectById(id);
    }
    
    // ========== List ==========
    
    public PageResult<ResourceRespVO> list(ResourceListReqVO req) {
        // 1. Build query wrapper
        LambdaQueryWrapper<ResourceDO> queryWrapper = Wrappers.<ResourceDO>lambdaQuery()
            .likeIfPresent(ResourceDO::getName, req.getName())
            .eqIfPresent(ResourceDO::getType, req.getType())
            .betweenIfPresent(ResourceDO::getCreateTime, 
                req.getCreateTime() != null ? req.getCreateTime()[0] : null,
                req.getCreateTime() != null ? req.getCreateTime()[1] : null)
            .orderByDesc(ResourceDO::getId);
        
        // 2. Query with pagination
        IPage<ResourceDO> page = resourceMapper.selectPage(
            new Page<>(req.getPageNo(), req.getPageSize()),
            queryWrapper
        );
        
        // 3. Convert to VO and return
        return new PageResult<>(
            resourceConvert.convertList(page.getRecords()),
            page.getTotal()
        );
    }
    
    // ========== Utility Methods ==========
    
    private ResourceDO checkResourceExists(Long id) {
        ResourceDO resource = resourceMapper.selectById(id);
        if (resource == null) {
            throw new ServiceException(RESOURCE_NOT_FOUND);
        }
        return resource;
    }
    
    private void checkNameDuplicate(Long id, String name) {
        ResourceDO existing = resourceMapper.selectOne(
            Wrappers.<ResourceDO>lambdaQuery()
                .eq(ResourceDO::getName, name)
                .ne(id != null, ResourceDO::getId, id)
        );
        if (existing != null) {
            throw new ServiceException(RESOURCE_NAME_DUPLICATE);
        }
    }
    
    private void checkIfReferenced(Long id) {
        // Check if this resource is referenced by other entities
        // if referenced, throw RESOURCE_REFERENCED error
    }
}
```

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

### Permission and Department Management

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/00-REFERENCE-INDEX.md

Endpoints for managing system menus and department structures.

```APIDOC
## POST /system/menu

### Description
Create a new menu item.

### Method
POST

### Endpoint
/system/menu

## GET /system/menu/list-tree

### Description
Retrieve the menu structure as a tree.

### Method
GET

### Endpoint
/system/menu/list-tree

## POST /system/dept

### Description
Create a new department.

### Method
POST

### Endpoint
/system/dept

## GET /system/dept/list-tree

### Description
Retrieve the department structure as a tree.

### Method
GET

### Endpoint
/system/dept/list-tree
```

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

### Use MapStruct Mapper for Conversions

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/07-best-practices-and-patterns.md

Demonstrates how to invoke the generated mapper instance for object and list conversions.

```java
// Convert request to DO
ResourceDO resource = ResourceConvert.INSTANCE.convert(req);

// Convert DO to response
ResourceRespVO resp = ResourceConvert.INSTANCE.convert(resource);

// Convert list
List<ResourceRespVO> respList = ResourceConvert.INSTANCE.convertList(doList);
```

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

### Create Role

Source: https://github.com/yunaiv/ruoyi-vue-pro/blob/master/_autodocs/05-system-module-api.md

Creates a new system role with the specified name, code, and status.

```APIDOC
## POST /system/role

### Description
Creates a new system role.

### Method
POST

### Endpoint
/system/role

### Request Body
- **name** (String) - Required - Role display name
- **code** (String) - Required - Role code (unique)
- **description** (String) - Optional - Role description
- **status** (Integer) - Required - 0=enabled, 1=disabled
- **dataScope** (Integer) - Optional - Data permission scope (1-5)

### Request Example
{
    "name": "Content Manager",
    "code": "content_manager",
    "description": "Manages all content",
    "status": 0
}
```
Tokens:
Raw