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
| Collaborating Skill | Collaboration Method | Input Data | Expected Output |
|---|---|---|---|
| pdd-implement-feature | Consultation | RuoYi technical issues | Solutions |
| pdd-code-reviewer | Reference | Discovered RuoYi issues | Framework best practices |
| software-engineer | Delegation | Code implementation tasks | Standards-compliant code |
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
| Adjustment Item | Reason | Priority |
|---|---|---|
| Add @Validated annotation | Parameter validation | P0 |
| Add @DataScope annotation | Data permissions | P0 |
| Add @Xss annotation | XSS protection | P0 |
| Configure sys_menu table | Menu routing | P0 |
| Assign role menu permissions | Permissions take effect | P0 |
| Clear Redis cache | Refresh permission cache | P0 |
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:
- Confirm component path in sys_menu table is correct
- Confirm Vue file exists in correct location
- Confirm menu is assigned to user role
- Clear Redis cache
- 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:
- Confirm permission identifier in annotation matches sys_menu.perms
- Confirm role is assigned corresponding menu permission
- Confirm user is assigned corresponding role
- Clear Redis cache
- 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:
- Confirm @DataScope annotation is configured correctly
- Confirm table aliases in Mapper XML are correct
- Confirm dept_id in sys_user table is correct
- 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:
- Confirm frontend button uses v-hasPermi directive
- Confirm permission identifier is completely consistent
- Confirm button's corresponding menu permission is assigned
- Clear browser cache
- 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
| File | Path | Content |
|---|---|---|
| Project Rules | .trae/rules/project_rules.md |
Directory structure, naming standards, development standards, API naming standards |
| Lessons Learned | .trae/rules/lessons.md |
Historical issues and solutions, including RuoYi framework specific issues |
8.2 Local Development Documentation
| Document | Path | Content |
|---|---|---|
| RuoYi Framework Style Modification Plan | docs/plans/若依框架样式修改方案.md |
Style adjustments, theme configuration, brand consistency |
8.3 Historical Issue Reference
The following RuoYi framework related issues are recorded in .trae/rules/lessons.md:
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
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
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
10. Version History
| Version | Date | Changes |
|---|---|---|
| 3.1 | 2026-03-22 | Added local development guide and documentation references |
| 3.0 | 2026-03-21 | Standardized structure, added diagnosis mode, enhanced collaboration guidance |
| 2.0 | Early | Improved problem solutions |
| 1.0 | Early | Initial version |