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)

```bash
# 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)

```bash
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

```bash
# 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:

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

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

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

### Frontend API Calls

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

```javascript
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

```bash
# 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](ruoyi-admin/src/main/java/com/ruoyi/RuoYiApplication.java) |
| Security configuration | [ruoyi-framework/src/main/java/com/ruoyi/framework/config/SecurityConfig.java](ruoyi-framework/src/main/java/com/ruoyi/framework/config/SecurityConfig.java) |
| Database config | [ruoyi-admin/src/main/resources/application.yml](ruoyi-admin/src/main/resources/application.yml) |
| MyBatis mappers | [ruoyi-system/src/main/resources/mapper/system/](ruoyi-system/src/main/resources/mapper/system/) |
| Vue router | [ruoyi-ui/src/router/index.js](ruoyi-ui/src/router/index.js) |
| Vuex store | [ruoyi-ui/src/store/](ruoyi-ui/src/store/) |