ccdi/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a discipline preliminary check system built on the RuoYi (若依) v3.9.1 rapid development framework. It is an enterprise-grade management system using a front-end/back-end separated architecture.

Technology Stack

Backend:

• Spring Boot 3.5.8
• Spring Security + JWT (authentication)
• MyBatis 3.0.5 (ORM)
• MySQL 8.2.0
• Redis (caching)
• Quartz 2.5.2 (scheduled tasks)
• SpringDoc 2.8.14 (API documentation)
• Java 17

Frontend:

• Vue 2.6.12
• Element UI 2.15.14
• Vuex 3.6.0 (state management)
• Vue Router 3.4.9
• Axios 0.28.1

Common Commands

Backend (Maven)

# Compile the project
mvn clean compile

# Run the application (development)
mvn spring-boot:run

# Package for deployment
mvn clean package

# Run using startup scripts
./ry.bat          # Windows
./ry.sh start     # Linux/Mac

Frontend (npm)

cd ruoyi-ui

# Install dependencies
npm install

# Development server (runs on port 80 by default)
npm run dev

# Production build
npm run build:prod

# Staging build
npm run build:stage

# Preview production build
npm run preview

Database Initialization

# Main database schema
mysql -u root -p < sql/ry_20250522.sql

# Quartz scheduler tables
mysql -u root -p < sql/quartz.sql

Project Architecture

Module Structure

discipline-prelim-check/
├── ruoyi-admin/          # Main application entry point
├── ruoyi-framework/      # Core framework (Security, config, filters)
├── ruoyi-system/         # System management (Users, Roles, Menus, Depts)
├── ruoyi-common/         # Common utilities (annotations, utils, constants)
├── ruoyi-quartz/         # Scheduled task management
├── ruoyi-generator/      # Code generator (CRUD scaffolding)
├── ruoyi-ui/             # Frontend Vue application
├── sql/                  # Database scripts
├── bin/                  # Startup scripts
└── openspec/             # OpenSpec specification workflow

Backend Architecture: MVC + Modular Design

The backend follows a standard MVC pattern with modular separation:

Controller Layer (ruoyi-admin/web/controller/)
├── common/       # Common controllers (captcha, file upload)
├── monitor/      # Monitoring controllers (cache, server, logs)
├── system/       # System management (users, roles, menus)
└── tool/         # Tools (code generator, swagger)

Service Layer (ruoyi-system/service/)
├── ISysUserService.java
├── ISysRoleService.java
└── ...

Mapper Layer (ruoyi-system/mapper/)
├── SysUserMapper.java
├── SysRoleMapper.java
└── ...

Domain Layer (ruoyi-system/domain/)
├── SysUser.java           # Entity
├── vo/                    # Value objects
└── ...

Frontend Architecture: Vue SPA

ruoyi-ui/src/
├── api/              # API request definitions
├── assets/           # Static resources (images, styles)
├── components/       # Reusable components
├── layout/           # Main layout (Sidebar, Navbar, TagsView)
├── router/           # Vue Router configuration
├── store/            # Vuex state management
├── utils/            # Utility functions
├── views/            # Page components organized by feature
│   ├── dashboard/
│   ├── monitor/
│   ├── system/
│   └── tool/
└── permission.js     # Permission directives

Module Dependencies

ruoyi-admin (startup module)
    ↓ depends on
ruoyi-framework (core security & config)
ruoyi-system (system core business)
ruoyi-common (shared utilities)
ruoyi-quartz (scheduled tasks)
ruoyi-generator (code generation)

Key Development Patterns

Code Generation Workflow

RuoYi provides a powerful code generator for rapid CRUD development:

1. Create database table - Design your table schema
2. Import table - Use System Tools → Code Generation → Import
3. Configure - Edit table info, generate info (module, function name, etc.)
4. Generate code - Download the generated zip
5. Copy files - Extract to appropriate directories:
   • Backend: ruoyi-admin/web/controller/, service, mapper files
   • Frontend: ruoyi-ui/src/views/, ruoyi-ui/src/api/

Permission System

The permission system uses Role-Menu-Button hierarchy:

• Menus: Define navigation items and route permissions
• Roles: Assign menu permissions to roles
• Users: Assign roles to users
• Data Permissions: Control data scope (all, custom, department, etc.)

Permission keys in code use format: system:user:edit, system:user:remove, etc.

API Response Format

All API responses use AjaxResult wrapper:

// Success
AjaxResult.success("操作成功", data);

// Error
AjaxResult.error("操作失败");

// Custom
AjaxResult.put("key", value);

Frontend API Calls

API calls are defined in ruoyi-ui/src/api/:

import request from '@/utils/request'

export function listUser(query) {
  return request({
    url: '/system/user/list',
    method: 'get',
    params: query
  })
}

export function addUser(data) {
  return request({
    url: '/system/user',
    method: 'post',
    data: data
  })
}

OpenSpec Workflow

This project uses OpenSpec for specification-driven development. Always reference openspec/AGENTS.md when:

• Planning or proposing new features
• Making breaking changes
• Modifying architecture
• Handling ambiguous requirements

Key OpenSpec Commands

# List active changes
openspec list

# List all specifications
openspec list --specs

# View details
openspec show [change-id or spec-id]

# Validate changes
openspec validate [change-id] --strict --no-interactive

# Archive completed changes
openspec archive <change-id>

When to Create Proposals

Create proposal for:

• New features or capabilities
• Breaking changes (API, schema)
• Architecture changes
• Performance optimizations that change behavior

Skip proposal for:

• Bug fixes (restoring intended behavior)
• Typos, formatting, comments
• Non-breaking dependency updates
• Configuration changes

Configuration Notes

• Default Admin: admin/admin123
• Backend Port: 8080
• Frontend Dev Port: 80
• API Base Path: Configured in ruoyi-ui/vue.config.js proxy
• Database Config: ruoyi-admin/src/main/resources/application.yml

Important File Locations

Purpose	Location
Main application entry	ruoyi-admin/src/main/java/com/ruoyi/RuoYiApplication.java
Security configuration	ruoyi-framework/src/main/java/com/ruoyi/framework/config/SecurityConfig.java
Database config	ruoyi-admin/src/main/resources/application.yml
MyBatis mappers	ruoyi-system/src/main/resources/mapper/system/
Vue router	ruoyi-ui/src/router/index.js
Vuex store	ruoyi-ui/src/store/