ccdi/CLAUDE.md

# CLAUDE.md
## 分析
- 在进行需求分析类型的任务时，自动开启深度思考模式，输入 “think more”、“think a lot”、“think harder” 或 “think longer” 触发更深层的思考
- 在进行需求分析与分解任务时，按照不同的模块分为不同的文件，创建模块名的文件夹并将对应文件保存在文件夹中，然后对模块的功能文件进行继续分解
- 在使用/openspec:proposal时，自动开启深度思考模式，输入 “think more”、“think a lot”、“think harder” 或 “think longer” 触发更深层的思考
- 在执行/openspec:apply后，使用code-simplifier 进行代码精简

## Communication
- 永远使用简体中文进行思考和对话

## Documentation
- 编写 .md 文档时，也要用中文
- 所有生成的文档都放在项目根目录下的doc文件中。

## 数据库规范
- 新建表时，需要加上项目英文名首字母集合


## Coding
### Java Code Style
- 新建模块命名方式为项目英文名首字母集合+主要功能
- 新的功能代码与若依框架自带的代码分离，新建模块，controller层也要放在新建模块中
- 使用 `@Data` 注解保证代码的简洁
- 尽量使用 MyBatis Plus 进行 CRUD 操作（版本 3.5.10，Spring Boot 3 适配版）
- 服务层中的使用@Resource注释，替代@Autowired
- 实体类不继承BaseEntity，单独添加审计字段
- 完成后端代码controller层代码生成测试后，在项目文件目录下生成API文档
- 接口传参需要使用单独的DTO，不可以与entity混用
- 需要单独的VO类，不可以与entity混用
- 审计字段通过添加注释的方式实现自动插入
- 简单的crud操作通过mybatis plus的方法实现，复杂的操作通过xml中写sql和mapper映射实现
- 控制层所有接口需要正确的添加注释，确保在swagger-ui中正确展示。控制层中任何接口发生变动，及时同步到doc中的接口文档中
- 控制层分页接口使用mybatis plus page，不要使用若依框架的分页


### 前端代码
- 在添加页面和组件后，注意与数据库中菜单表进行联动修改
- 前端组件代码需要组件化，复杂的组件需要进行拆分为单独的文件


## 运行
- 使用mcp:dpc_intermediary_blacklist进行数据库相关操作
- 不要在命令行中启动后端进行测试
- 测试方式为生成可执行的测试脚本
- 测试脚本在运行完成后需要保存所有接口输出并生成测试用例报告
- /login/test接口可以传入username和password获取token，用于测试验证接口的功能。
	用于测试的账号：username: admin password admin123
- swagger-ui的地址为/swagger-ui/index.html
- 在向doc文件夹添加文件时需要分门别类添加，根据


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/) |