328 lines
10 KiB
Markdown
328 lines
10 KiB
Markdown
# 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 进行代码精简
|
||
- 在分析生成需求文档时，每次都需要在doc目录下新建文件夹并以需求内容为命名
|
||
|
||
## 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:ccdi_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/) |
|