FlashSaleSystem/CLAUDE.md

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

# Compile project
mvn clean compile

# Run application
mvn spring-boot:run

# Package application
mvn clean package

Testing

# 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

# 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