# CLAUDE.md

## 项目规则（重要）

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

### Documentation
- 编写 .md 文档时，也要用中文

## Java Code Style
- 在实体类中使用 `@Data` 注解保证代码的简洁
- 尽量使用 MyBatis Plus 进行 CRUD 操作（版本 3.5.10，Spring Boot 3 适配版）
- 服务层中的使用@Resource注释，替代@Autowired

# 测试验证
- /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.

<!-- OPENSPEC:START -->
# OpenSpec Instructions

These instructions are for AI assistants working in this project.

Always open `@/openspec/AGENTS.md` when the request:
- Mentions planning or proposals (words like proposal, spec, change, plan)
- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
- Sounds ambiguous and you need the authoritative spec before coding

Use `@/openspec/AGENTS.md` to learn:
- How to create and apply change proposals
- Spec format and conventions
- Project structure and guidelines

Keep this managed block so 'openspec update' can refresh the instructions.

<!-- OPENSPEC:END -->

## Project Overview

This is a **RuoYi v3.9.1** based rapid development platform - a Spring Boot + Vue.js full-stack separated admin system framework. Despite the "loan-pricing" directory name, this is the standard RuoYi framework template used as a foundation for a loan pricing system.

**Key Technologies:**
- Backend: Java 17, Spring Boot 3.5.8, **MyBatis Plus 3.5.10**, MySQL 8.2.0, Redis (Lettuce)
- Frontend: Vue 2.6.12, Element UI 2.15.14, Vue Router 3.4.9, Vuex 3.6.0
- Security: JWT token authentication, Spring Security with RBAC
- API Docs: SpringDoc OpenAPI 3.0 at `/swagger-ui.html`

## Development Commands

### Backend (Java/Maven)

**Building:**
```bash
# Package entire project (Windows)
bin\package.bat

# Or using Maven directly
mvn clean package -Dmaven.test.skip=true

# Clean build artifacts
bin\clean.bat
```

**Running:**
```bash
# Run using the packaged jar
bin\run.bat

# Or using Maven
mvn spring-boot:run

# Or run directly with java
java -jar ruoyi-admin/target/ruoyi-admin.jar
```

**Testing:**
```bash
mvn test
```

**Default Access:**
- Backend: http://localhost:8080
- API Docs: http://localhost:8080/swagger-ui.html
- Druid Monitor: http://localhost:8080/druid (ruoyi/123456)

### Frontend (Vue.js)

**Development:**
```bash
cd ruoyi-ui
npm install
npm run dev
```

**Production Build:**
```bash
cd ruoyi-ui
npm run build:prod
```

**Staging Build:**
```bash
npm run build:stage
```

**Default Access:** http://localhost

### Default Login Credentials

- Username: `admin`
- Password: `admin123`

## Architecture & Module Structure

### Maven Multi-Module Layout

```
ruoyi/
├── ruoyi-admin/         # Main web application entry point
├── ruoyi-framework/     # Framework utilities (security, config, MyBatis Plus, interceptors)
├── ruoyi-system/        # Core system modules (users, roles, menus, depts)
├── ruoyi-common/        # Common utilities and domain models
├── ruoyi-generator/     # Code generation tool (Velocity templates)
├── ruoyi-quartz/        # Scheduled task management
└── ruoyi-ui/           # Vue.js frontend
```

### Backend Architecture Patterns

**Layered Architecture:**
```
Controller (@RestController) -> Service (@Service) -> Mapper (MyBatis Plus) -> Database
```

**Key Conventions:**
- Controllers in `ruoyi-admin/src/main/java/com/ruoyi/web/controller/`
- Services in `ruoyi-system/src/main/java/com/ruoyi/system/service/`
- Domain entities in `ruoyi-common/src/main/java/com/ruoyi/common/core/domain/`
- MyBatis Plus Mappers 接口在 `ruoyi-system/src/main/java/com/ruoyi/system/mapper/`
- MyBatis XML 映射文件在 `ruoyi-system/src/main/resources/mapper/`

**Security Flow:**
1. JWT tokens stored in `Authorization` header
2. Spring Security filters validate tokens
3. `@PreAuthorize` annotations for method-level permissions
4. Data scoping by department (see `DataScope` aspect)

**Configuration:**
- Main config: [application.yml](ruoyi-admin/src/main/resources/application.yml)
- Environment-specific: [application-dev.yml](ruoyi-admin/src/main/resources/application-dev.yml) (dev profile active by default)
- MyBatis Plus config: [MybatisPlusConfig.java](ruoyi-framework/src/main/java/com/ruoyi/framework/config/MybatisPlusConfig.java)

### Frontend Architecture

**Structure:**
```
ruoyi-ui/
├── src/
│   ├── api/           # API request functions (axios)
│   ├── assets/        # Static resources
│   ├── components/    # Reusable Vue components
│   ├── layout/        # Layout components (sidebar, header)
│   ├── router/        # Vue Router configuration
│   ├── store/         # Vuex state management
│   ├── utils/         # Utility functions
│   └── views/         # Page components
├── vue.config.js      # Vue CLI configuration
└── package.json
```

**State Management:**
- Permission routes stored in Vuex `store/permission.js`
- User info in `store/user.js`
- Settings in `store/settings.js`

**API Integration:**
- Base URL configured in `vue.config.js` (proxy to backend)
- Request interceptors add JWT tokens in `src/utils/request.js`

## Database Setup

1. Import schema: [sql/ry_20250522.sql](sql/ry_20250522.sql)
2. Configure connection in [application-dev.yml](ruoyi-admin/src/main/resources/application-dev.yml)
3. Default database name: `ruoyi-test` (change as needed)
4. Redis required for caching (configured in same yml file)

## Code Generation

The framework includes a code generator at `/tool/gen` (when running):
- Generates Controller, Service, MyBatis Plus Mapper, domain classes
- Generates Vue CRUD pages
- Uses Velocity templates in `ruoyi-generator/src/main/resources/vm/`

## Important Configuration Notes

**File Upload:**
- Max single file: 10MB
- Max total: 20MB
- Upload path: `D:/ruoyi/uploadPath` (configurable in application.yml)

**Token Settings:**
- Expiration: 30 minutes
- Header name: `Authorization`
- Secret: configured in application.yml

**Validation:**
- Captcha type: `math` (math calculation) or `char` (character)
- Max password retry: 5 times
- Lock time: 10 minutes

## Common Development Patterns

**Adding a New Feature:**
1. Create database table
2. Use code generator at `/tool/gen` or create manually:
   - Domain entity in `ruoyi-common/.../domain/` (使用 `@Data` 注解)
   - MyBatis Plus Mapper 接口继承 `BaseMapper<Entity>` in `ruoyi-system/.../mapper/`
   - Service interface and implementation in `ruoyi-system/.../service/`
   - Controller in `ruoyi-admin/.../controller/`
   - Vue API function in `ruoyi-ui/src/api/`
   - Vue page component in `ruoyi-ui/src/views/`
3. Add menu permissions in system -> menu management
4. Assign permissions to roles

**Permission Control:**
- Backend: Use `@PreAuthorize("@ss.hasPermi('system:user:list')")`
- Frontend: Use `v-hasPermi="['system:user:add']"` directive

**Data Pagination:**
- Backend: 使用 MyBatis Plus 的 `Page<T>` 对象或 `PageHelper.startPage()`
- Frontend: Use `<el-pagination>` component

## OpenSpec Workflow

For significant changes, use the OpenSpec workflow:
1. Run `openspec list` to check active changes
2. Run `openspec list --specs` to see existing capabilities
3. Create proposal in `openspec/changes/[change-id]/`
4. Validate: `openspec validate [change-id] --strict --no-interactive`
5. Get approval before implementation
6. Archive after deployment: `openspec archive <change-id> --yes`

See [openspec/AGENTS.md](openspec/AGENTS.md) for detailed instructions.