RuoYi Framework Development Expert

1. Skill Overview

1.1 Core Capabilities

Core Capabilities:
  - Project Setup: SpringBoot + MyBatis + Shiro/Security
  - Code Generation: Automatic CRUD code generation
  - Permission Management: Menu permissions, button permissions, data permissions
  - Dynamic Routing: Dynamic routing based on sys_menu table
  - Best Practices: RuoYi framework development standards

Applicable Scenarios:
  - Permission issues during new feature development
  - Page 404 after menu configuration
  - Code generator usage
  - Permission annotations not working
  - Data scope filtering exceptions

1.2 Collaboration with Other Skills

2. Quick Diagnosis Mode

2.1 Problem Classification Index

Problem Types:
  Routing Issues:
    - Page 404
    - Menu not displaying
    - Route 404

  Permission Issues:
    - Permission annotations not working
    - Buttons not displaying
    - Data scope errors

  Code Generation Issues:
    - Generated code errors
    - Adjustments needed after generation

  Configuration Issues:
    - Database configuration
    - Redis cache
    - Session management

2.2 Routing Issue Diagnosis

Problem: Page 404 after clicking menu

Diagnosis Process:
1. Check sys_menu table configuration
   SELECT * FROM sys_menu WHERE menu_name = 'XXX';

2. Check component path
   - Path relative to src/views
   - File must exist

3. Check visible field
   - '0' = Show menu
   - '1' = Hide menu

4. Check if parent menu exists
   SELECT * FROM sys_menu WHERE menu_id = parent_id;

5. Check role permission assignment
   SELECT * FROM sys_role_menu WHERE menu_id = menu_id;

2.3 Permission Issue Diagnosis

Problem: @PreAuthorize annotation not working

Diagnosis Process:
1. Check if annotation is correct
   @PreAuthorize("@ss.hasPermi('xxx:xxx:xxx')")

2. Check permission identifier in sys_menu table
   - perms field must match the annotation

3. Check role menu assignment
   SELECT * FROM sys_role_menu WHERE menu_id IN
   (SELECT menu_id FROM sys_menu WHERE perms = 'xxx:xxx:xxx');

4. Check user role
   SELECT * FROM sys_user_role WHERE user_id = user_id;

5. Clear Redis cache
   FLUSHDB

3. Core Configuration Standards

3.1 Menu Configuration Standards

-- Directory Type (M)
INSERT INTO sys_menu (menu_name, parent_id, order_num, path, component, menu_type, visible, perms, icon)
VALUES ('Asset Management', 0, 1, 'asset', NULL, 'M', '0', NULL, 'asset');

-- Menu Type (C) - List Page
INSERT INTO sys_menu (menu_name, parent_id, order_num, path, component, menu_type, visible, perms, icon)
VALUES ('Asset List', parent_id, 1, 'list', 'asset/index', 'C', '0', 'asset:list:list', 'list');

-- Menu Type (C) - Hidden Page (Add/Edit/Detail)
INSERT INTO sys_menu (menu_name, parent_id, order_num, path, component, menu_type, visible, perms)
VALUES ('Asset Add', parent_id, 10, 'add', 'asset/form', 'C', '1', 'asset:list:add');

-- Button Type (F) - Permission Control
INSERT INTO sys_menu (menu_name, parent_id, order_num, path, component, menu_type, visible, perms)
VALUES ('Asset Add Button', menu_id, 1, '', '', 'F', '0', 'asset:list:add');

3.2 Permission Annotation Standards

// Controller Layer
@RestController
@RequestMapping("/asset/list")
public class AssetListController {

    // List Query - Requires list permission
    @PreAuthorize("@ss.hasPermi('asset:list:list')")
    @GetMapping
    public AjaxResult list() { }

    // Add - Requires add permission
    @PreAuthorize("@ss.hasPermi('asset:list:add')")
    @PostMapping
    public AjaxResult add() { }

    // Edit - Requires edit permission
    @PreAuthorize("@ss.hasPermi('asset:list:edit')")
    @PutMapping
    public AjaxResult edit() { }

    // Delete - Requires remove permission
    @PreAuthorize("@ss.hasPermi('asset:list:remove')")
    @DeleteMapping
    public AjaxResult remove() { }

    // Export - Requires export permission
    @PreAuthorize("@ss.hasPermi('asset:list:export')")
    @GetMapping("/export")
    public void export() { }
}

3.3 Data Permission Standards

// Service Layer
public interface IAssetService {

    // Add @DataScope annotation
    @DataScope(deptAlias = "d", userAlias = "u")
    List<Asset> selectAssetList(Asset asset);
}

// Mapper XML
<select id="selectAssetList" resultMap="AssetResult">
    SELECT a.*, d.dept_name
    FROM asset a
    LEFT JOIN sys_dept d ON a.dept_id = d.dept_id
    LEFT JOIN sys_user u ON a.create_by = u.user_name
    WHERE a.del_flag = '0'
    ${params.dataScope}
</select>

4. Code Generator Usage

4.1 Required Adjustments After Generation

4.2 Code Adjustment Examples

// Before Adjustment (Generator Default)
@PostMapping
public AjaxResult add(Asset asset) {
    return AjaxResult.success(assetService.insertAsset(asset));
}

// After Adjustment (Add Parameter Validation)
@PreAuthorize("@ss.hasPermi('asset:list:add')")
@Log(title = "Asset Management", businessType = BusinessType.INSERT)
@PostMapping
public AjaxResult add(@Validated @RequestBody Asset asset) {
    return AjaxResult.success(assetService.insertAsset(asset));
}

// Entity Class Add XSS Protection
@Excel(name = "Asset Name")
@Xss
private String assetName;

// List Query Add Data Permission
@DataScope(deptAlias = "d", userAlias = "u")
List<Asset> selectAssetList(Asset asset);

5. Common Problem Solutions

5.1 Page 404 Issue

Problem: Page 404 after clicking menu

Troubleshooting Steps:

-- Step 1: Check if menu exists
SELECT * FROM sys_menu WHERE menu_name LIKE '%XXX%';

-- Step 2: Check if component path is correct
-- Path format: module/path (relative to src/views)
-- Example: equity-transfer/apply/index

-- Step 3: Check if file exists
-- src/views/equity-transfer/apply/index.vue

-- Step 4: Check parent menu
SELECT * FROM sys_menu WHERE menu_id = parent_id;

-- Step 5: Check role permissions
SELECT * FROM sys_role_menu WHERE menu_id = menu_id;

Solutions:

1. Confirm component path in sys_menu table is correct
2. Confirm Vue file exists in correct location
3. Confirm menu is assigned to user role
4. Clear Redis cache
5. Re-login

5.2 Permission Annotation Not Working

Problem: @PreAuthorize annotation not working, all users can access

Troubleshooting Steps:

-- Step 1: Check if permission identifier matches
SELECT perms FROM sys_menu WHERE menu_name = 'XXX';

-- Step 2: Check role menu assignment
SELECT r.role_name, m.menu_name
FROM sys_role_menu rm
JOIN sys_menu m ON rm.menu_id = m.menu_id
WHERE m.perms = 'xxx:xxx:xxx';

-- Step 3: Check user role
SELECT u.user_name, r.role_name
FROM sys_user_role ur
JOIN sys_role r ON ur.role_id = r.role_id
WHERE ur.user_id = user_id;

Solutions:

1. Confirm permission identifier in annotation matches sys_menu.perms
2. Confirm role is assigned corresponding menu permission
3. Confirm user is assigned corresponding role
4. Clear Redis cache
5. Re-login to get latest permissions

5.3 Data Scope Filtering Not Working

Problem: Users can see data not belonging to their department

Troubleshooting Steps:

-- Step 1: Check user's department
SELECT u.user_name, d.dept_name, d.dept_id
FROM sys_user u
JOIN sys_dept d ON u.dept_id = d.dept_id
WHERE u.user_id = user_id;

-- Step 2: Check data permission configuration
-- Check if Mapper XML correctly configured ${params.dataScope}

-- Step 3: Check @DataScope annotation
-- Confirm deptAlias and userAlias match SQL aliases

Solutions:

1. Confirm @DataScope annotation is configured correctly
2. Confirm table aliases in Mapper XML are correct
3. Confirm dept_id in sys_user table is correct
4. Re-login to get new session information

5.4 Button Permission Not Displaying

Problem: User has permission but button doesn't display

Troubleshooting Steps:

// Check if frontend has v-hasPermi directive
<el-button v-hasPermi="['asset:list:add']">
  Add
</el-button>

// Check if permission identifier is consistent
// Frontend: asset:list:add
// Backend: @PreAuthorize("@ss.hasPermi('asset:list:add')")
// Database: sys_menu.perms = 'asset:list:add'

Solutions:

1. Confirm frontend button uses v-hasPermi directive
2. Confirm permission identifier is completely consistent
3. Confirm button's corresponding menu permission is assigned
4. Clear browser cache
5. Re-login

6. Best Practices Checklist

6.1 Development Checklist

New Feature Checklist:
  - [ ] sys_menu table configuration complete (directory/menu/button)
  - [ ] component path correct
  - [ ] Permission identifier unique and standardized
  - [ ] Role menu permissions assigned
  - [ ] @PreAuthorize annotation configured correctly
  - [ ] @DataScope annotation configured correctly (if needed)
  - [ ] @Validated parameter validation added
  - [ ] @Xss text field protection added
  - [ ] @Log operation log added
  - [ ] Redis cache cleared
  - [ ] User re-login

6.2 API Naming Standards

// Standard API Naming
export function listAsset(query) {
  return request({ url: '/asset/list', method: 'get', params: query });
}

export function getAsset(assetId) {
  return request({ url: '/asset/' + assetId, method: 'get' });
}

export function addAsset(data) {
  return request({ url: '/asset', method: 'post', data });
}

export function updateAsset(data) {
  return request({ url: '/asset', method: 'put', data });
}

export function delAsset(assetId) {
  return request({ url: '/asset/' + assetId, method: 'delete' });
}

export function exportAsset(query) {
  return request({ url: '/asset/export', method: 'get', params: query });
}

7. Guardrails

7.1 Must Follow

• All pages (including hidden pages) must be configured in sys_menu table
• Permission identifier must match sys_menu.perms exactly
• Data permissions must configure ${params.dataScope}
• @RequestBody parameters must add @Validated annotation
• Text fields should add @Xss annotation

7.2 Avoid

• ❌ Hardcoding permission identifiers
• ❌ Skipping menu configuration to access pages directly
• ❌ Frontend validation replacing backend validation
• ❌ Forgetting to clear Redis cache

8. Local Development Guide

This project has specific development standards and historical experience, please prioritize reference when providing suggestions:

8.1 Project Rule Files

8.2 Local Development Documentation

8.3 Historical Issue Reference

The following RuoYi framework related issues are recorded in .trae/rules/lessons.md:

1. Menu Routing Configuration Issue (2026-03-08)
   • Problem: New page 404
   • Cause: Route not configured in sys_menu table
   • Solution: All pages (including hidden pages) need configuration
2. API Method Naming Standard Issue (2026-03-08)
   • Problem: Frontend-backend naming inconsistency
   • Cause: Standards not defined first
   • Solution: Design documentation first, code implementation follows
3. FP-ZCCZ1-001 Code Review Practice (2026-03-08)
   • Problem: Missing parameter validation, XSS protection, data permissions
   • Solution: Add @Validated, @Xss, @DataScope annotations

8.4 Project Specific Checklist

Project Specific Checklist:
  - [ ] Check if lessons.md has solutions for related issues
  - [ ] Follow naming standards in project_rules.md
  - [ ] Reference implementation patterns of existing code
  - [ ] Confirm database configuration: mysql6.sqlpub.com:3311/asset_ruoyi

9. External Reference Documentation

• RuoYi Official Website
• RuoYi Documentation
• RuoYi-Vue GitHub
• RuoYi-Vue Gitee

10. Version History