# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 始终使用中文回复

- 在所有沟通和代码注释中，必须使用中文进行交流
- 保持语言的专业性和技术准确性

## mcp 工具使用

- 当涉及到相关库的使用时，应该用 context7 查询相关文档

## Project Overview

FlashSaleSystem is a high-concurrency flash sale (秒杀) system built with Spring Boot and Redis Cluster. The system
implements distributed architecture with anti-overselling mechanisms, rate limiting, and distributed locking using Redis
and Lua scripts.

**Project Completion**: 90%

## Core Architecture

### Technology Stack

- **Backend**: Spring Boot 2.7.6, Java 1.8
- **Database**: MySQL with JPA/Hibernate
- **Cache**: Redis Cluster with Redisson
- **Frontend**: JSP + JSTL + Bootstrap 5 + jQuery
- **Build Tool**: Maven
- **API Documentation**: Knife4j (Swagger)

### Key Components

- **Controllers**: Handle HTTP requests for different modules (flash sales, cart, orders, admin)
- **Services**: Business logic layer with Redis-based caching and distributed operations
- **Repositories**: JPA data access layer for MySQL operations
- **DTOs**: Data transfer objects for API communication
- **Entities**: JPA entities mapping to database tables

### Package Structure

```
com.org.flashsalesystem/
├── controller/     # REST controllers and web endpoints
├── service/        # Business logic and Redis operations
├── repository/     # JPA repositories for data access
├── entity/         # JPA entities (User, Product, Order, FlashSale)
├── dto/            # Data transfer objects
├── config/         # Configuration classes (Redis, Swagger, Web)
└── util/           # Utility classes and JSP functions
```

### Redis Integration

- **Cluster Configuration**: Multi-node Redis cluster setup via RedissonConfig
- **Data Types**: String (locks, sessions), Hash (user/product info, cart), List (order queues), Set (successful users),
  ZSet (rankings)
- **Lua Scripts**: Atomic operations for flash sales, distributed locks, rate limiting, cart operations
- **Message Queues**: Pub/Sub for order status changes and inventory updates

## Common Development Commands

### Build and Run

```bash
# Compile project
mvn clean compile

# Run application
mvn spring-boot:run

# Package application
mvn clean package
```

### Testing

```bash
# Run all tests (if available)
mvn test

# Run specific test classes
mvn test -Dtest=FlashSaleServiceTest
mvn test -Dtest=RedisServiceTest

# Note: Test classes may need to be created for comprehensive testing
```

### Database Setup

```bash
# Create database
mysql -u root -p
CREATE DATABASE flash_sale_db;

# Import schema and test data
mysql -u root -p flash_sale_db < src/main/resources/sql/schema.sql
mysql -u root -p flash_sale_db < src/main/resources/sql/test-data.sql
```

## Application Configuration

### Key Configuration Files

- `application.yml`: Main application configuration including Redis cluster, database, and custom flash sale settings
- `pom.xml`: Maven dependencies and build configuration
- `src/main/resources/lua/`: Lua scripts for Redis atomic operations

### Important Configuration Sections

- **Redis Cluster**: Configured for 6-node cluster with authentication
- **Flash Sale Settings**: Rate limiting (10 requests/minute), max quantity per user (1), stock preload timing
- **Cache TTL**: User info (30min), product info (60min), flash sale data (10min)
- **Database**: HikariCP connection pool with optimized settings

## Development Guidelines

### Service Layer Patterns

- All Redis operations use Redisson for cluster support
- Critical operations (stock deduction, cart updates) use Lua scripts for atomicity
- Distributed locks prevent overselling using Redisson's RLock
- Rate limiting implemented via sliding window algorithm in Lua

### Key Services

- **FlashSaleService**: Core flash sale logic with distributed locking and Lua scripts
- **RedisService**: Generic Redis operations wrapper
- **DistributedLockService**: Distributed locking abstraction
- **RateLimitService**: API rate limiting using Redis
- **CartService**: Shopping cart operations with Redis Hash storage

### Testing Approach

- Unit tests should be created for core services (FlashSaleService, RedisService, CartService)
- Integration tests should verify Redis cluster connectivity and database operations
- Load testing recommended for flash sale scenarios to validate concurrency handling

## Lua Script Usage

The system includes 5 Lua scripts in `src/main/resources/lua/`:

- `flashsale.lua`: Atomic stock deduction with overselling prevention
- `distributed_lock.lua`: Distributed lock acquisition
- `unlock.lua`: Safe distributed lock release
- `rate_limit.lua`: Sliding window rate limiting
- `cart_operation.lua`: Atomic shopping cart operations

## API Documentation

- **Swagger UI**: http://localhost:8080/doc.html (Knife4j)
- **API Docs**: http://localhost:8080/v3/api-docs

## Monitoring and Health

- **Actuator Endpoints**: /actuator/health, /actuator/metrics, /actuator/prometheus
- **Log Files**: logs/flash-sale-system.log with detailed Redis and SQL logging
- **Debug Level**: Enabled for package com.org.flashsalesystem and Redis operations

## Security Considerations

- **Redis Authentication**: Cluster uses password authentication as configured in application.yml
- **Database Connection**: Uses HikariCP with connection pooling and timeout configurations
- **Password Encoding**: Spring Security crypto for password hashing
- **Rate Limiting**: Built-in rate limiting to prevent abuse of flash sale endpoints