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)

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

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