ibs-fullstack/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 full-stack banking management system (数字支行辅助管理系统) built on the RuoYi framework v3.8.8. It provides grid-based customer relationship management, customer grouping, visit tracking, and performance statistics for banking institutions.

- **Backend**: Spring Boot 2.5.14 + MyBatis + MySQL + Redis + JWT
- **Frontend**: Vue 2.6.12 + Element UI 2.15.14
- **Java Version**: 1.8

## Architecture

### Backend Module Structure

The backend is a multi-module Maven project with the following modules:

```
ruoyi/
├── ruoyi-admin/         # Web entry point, main application (RuoYiApplication)
├── ruoyi-framework/     # Core framework (security, config, interceptors)
├── ruoyi-system/        # System management (users, roles, menus, depts)
├── ruoyi-common/        # Common utilities, annotations, domain classes
├── ruoyi-quartz/        # Scheduled task management
├── ruoyi-generator/     # Code generation tools
├── ibs/                 # Main business module: grid customer management (网格营销)
└── ibs-group/           # Customer group management module (客户分组)
```

### Business Domain Structure

Each business module (e.g., `ibs`, `ibs-group`) follows this package structure:

```
com.ruoyi.<module>/
├── controller/          # REST controllers (handle HTTP requests)
├── service/             # Business logic layer
├── mapper/              # MyBatis mappers (database access)
├── domain/
│   ├── entity/          # Database entities
│   ├── dto/             # Data Transfer Objects (request)
│   └── vo/              # View Objects (response)
└── handler/             # Custom MyBatis type handlers
```

### Frontend Structure

```
ruoyi-ui/
├── src/
│   ├── api/             # API request modules (organized by feature)
│   ├── views/           # Page components
│   ├── components/      # Reusable components
│   ├── store/           # Vuex state management
│   ├── router/          # Vue Router configuration
│   ├── utils/           # Utility functions
│   └── directive/       # Custom Vue directives
```

## Build and Run Commands

### Backend (Maven)

```bash
# Clean build artifacts
cd bin && clean.bat

# Package the project (creates JAR in ruoyi-admin/target/)
cd bin && package.bat

# Run the backend server (requires packaged JAR)
cd bin && run.bat

# Or run directly with Maven from ruoyi-admin/
mvn spring-boot:run

# The main class is: com.ruoyi.RuoYiApplication
# Default port: 8080
```

### Frontend (npm/Vue CLI)

```bash
cd ruoyi-ui

# Development server (runs on port 80)
npm run dev

# For older Node.js versions with OpenSSL issues
npm run dev_t

# Build for production
npm run build:prod

# Build for staging
npm run build:stage

# Build for pre-production
npm run build:pre

# Lint code
npm run lint
```

## Development Configuration

### Application Profiles

Backend uses Spring profiles located in `ruoyi-admin/src/main/resources/`:
- `application.yml` - Base configuration
- `application-dev.yml` - Development environment
- `application-uat.yml` - UAT environment
- `application-pre.yml` - Pre-production
- `application-pro.yml` - Production

Active profile is set in `application.yml` (default: `dev`).

### Frontend API Proxy

The Vue dev server proxies API requests to `http://localhost:8080`:
- Frontend dev server: `http://localhost:80`
- API requests: `/dev-api/*` → `http://localhost:8080/*`

## Key Patterns and Conventions

### Backend Code Patterns

1. **Controller-Service-Mapper Layering**
   - Controllers handle HTTP requests/responses, use `@RestController`
   - Services contain business logic, use `@Service`
   - Mappers use MyBatis annotations or XML files in `resources/mapper/`

2. **DTO/VO Pattern**
   - DTOs (Data Transfer Objects) for incoming requests
   - VOs (View Objects) for outgoing responses
   - Entities map directly to database tables

3. **Security & Authentication**
   - JWT-based authentication via `TokenService`
   - Role-based access: `head`, `branch`, `outlet`, `manager`
   - Use `SecurityUtils` for current user context: `SecurityUtils.getUsername()`, `SecurityUtils.getDeptId()`, `SecurityUtils.userRole()`

4. **Pagination**
   - Uses `PageHelper` for database pagination
   - Controllers return `TableDataInfo` with `total` and `rows`

5. **Caching**
   - Uses `RedisCache` for Redis operations
   - Cache keys often follow pattern: `{module}:{feature}:{key}`

### Frontend Code Patterns

1. **API Modules**
   - Each feature has a dedicated API file in `src/api/`
   - Uses `request()` wrapper around axios
   - API base URL is configured in `src/utils/request.js`

2. **Vuex Store**
   - Modules in `src/store/modules/`: user, app, permission, settings, tagsView
   - State persists via `vuex-persistedstate`

3. **Permission Directives**
   - `v-hasPermi` for button-level permissions
   - `v-hasRole` for role-based display

## Common Business Concepts

- **网格**: Grid-based territory management for customer assignment
- **客户经理**: Relationship managers assigned to customers
- **客户星级**: Customer rating levels (5星, 4星, 3星, 2星, 1星, 基础, 长尾)
- **AUM (Asset Under Management)**: Customer assets, tracked with monthly averages
- **PAD走访**: Mobile visit records for customer interactions

## MyBatis Configuration

- Mapper XML files: `classpath*:mapper/**/*Mapper.xml`
- Type aliases: `com.ruoyi.**.domain`
- Custom type handlers: `com.ruoyi.ibs.handler`
- Pagination: `pagehelper` with MySQL dialect

## Notes

- The project uses Chinese comments and variable names in many places
- Scheduled tasks use Quartz via `ruoyi-quartz` module
- File upload path configured in `application.yml`: `ruoyi.profile`
- Swagger/Knife4j API docs available when running