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工具进行数据库相关操作
• 使用根目录中的ry.bat控制后端的启动，不要自行在命令行中启动后端
• 测试方式为生成可执行的测试脚本
• 测试脚本在运行完成后需要保存所有接口输出并生成测试用例报告
• /login/test接口可以传入username和password获取token，用于测试验证接口的功能。 用于测试的账号：username: admin password admin123
• swagger-ui的地址为/swagger-ui/index.html

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/