# CLAUDE.md

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

## 项目概述

FlashSaleSystem 是一个基于 Spring Boot 2.7.6 和 Redis 集群构建的社区生鲜团购系统。系统采用分布式架构设计，通过 Redis 集群实现高并发处理，使用 Lua 脚本保证原子性操作，采用分布式锁防止超卖。

## 核心架构

### 技术栈
- **后端框架**: Spring Boot 2.7.6, Java 1.8
- **数据库**: MySQL 5.7+ (JPA/Hibernate)
- **缓存系统**: Redis 6.0+ (支持单节点/集群/哨兵模式)
- **分布式锁**: Redisson 3.24.3
- **前端技术**: JSP + JSTL + Bootstrap 5 + jQuery
- **API文档**: Knife4j 4.1.0 (增强版Swagger)
- **构建工具**: Maven 3.6+

### 包结构
```
com.org.flashsalesystem/
├── controller/     # 控制器层（REST API和页面控制）
├── service/        # 业务逻辑层（核心业务和Redis操作）
├── repository/     # 数据访问层（JPA接口）
├── entity/         # 实体类（User, Product, Order, FlashSale）
├── dto/            # 数据传输对象
├── config/         # 配置类（RedissonConfig, SwaggerConfig, WebConfig）
└── util/           # 工具类（JSPFunctions, PasswordGenerator）
```

## 常用开发命令

### 构建和运行
```bash
# 编译项目
mvn clean compile

# 单元测试编译
mvn test-compile

# 运行测试
mvn test
mvn test -Dtest=FlashSaleServiceTest

# 打包（跳过测试）
mvn clean package -DskipTests

# 本地运行（默认单节点Redis）
mvn spring-boot:run

# 运行指定profile
mvn spring-boot:run -Dspring.profiles.active=dev     # 开发环境
mvn spring-boot:run -Dspring.profiles.active=cluster # 集群环境

# 运行JAR包
java -jar target/FlashSaleSystem-0.0.1-SNAPSHOT.jar
java -jar target/FlashSaleSystem-0.0.1-SNAPSHOT.jar --spring.profiles.active=cluster
```

### 数据库初始化
```bash
# 创建数据库
mysql -u root -p -e "CREATE DATABASE flash_sale_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 导入表结构（JPA自动创建，可选）
mysql -u root -p flash_sale_db < src/main/resources/sql/schema.sql

# 导入演示用户
mysql -u root -p flash_sale_db < src/main/resources/sql/demo-users.sql

# 导入测试数据
mysql -u root -p flash_sale_db < src/main/resources/sql/test-data.sql
```

## Redis架构设计

### 支持模式
1. **单节点模式**（默认）: localhost:6379，适用于开发环境
2. **集群模式**: 6节点集群（42.192.62.91:7000-7005），生产环境推荐
3. **哨兵模式**: 高可用配置，支持主从切换

### Redis数据结构使用
- **String**: 分布式锁、会话存储、库存计数
- **Hash**: 用户信息、商品信息、购物车数据
- **List**: 订单队列、消息队列
- **Set**: 秒杀成功用户集合
- **ZSet**: 商品排行榜、热门活动

### Key前缀规范
- `flashsale:` - 秒杀活动数据
- `flashsale_stock:` - 实时库存信息
- `flashsale_lock:` - 秒杀分布式锁
- `flashsale_success:` - 成功用户集合
- `user:` - 用户信息缓存
- `product:` - 商品信息缓存
- `cart:` - 购物车数据
- `rate_limit:` - API限流计数器

### Lua脚本（src/main/resources/lua/）
1. **flashsale.lua**: 原子性库存扣减，防止超卖
2. **distributed_lock.lua**: 分布式锁获取
3. **unlock.lua**: 安全释放分布式锁
4. **rate_limit.lua**: 滑动窗口限流
5. **cart_operation.lua**: 购物车原子操作

## 核心业务流程

### 秒杀流程
1. **库存预热**: 活动前30分钟通过 `FlashSaleService.preloadStock()` 预加载库存到Redis
2. **限流检查**: `RateLimitService.checkFlashSaleRateLimit()` 检查用户请求频率（10次/分钟）
3. **分布式锁**: `RedissonLockService.tryLock()` 获取分布式锁，防止并发超卖
4. **库存扣减**: 执行 `flashsale.lua` 脚本原子性扣减库存
5. **订单创建**: 数据库创建订单，Redis记录成功用户
6. **消息发布**: 通过Pub/Sub发布秒杀结果通知

### 关键服务类
- **FlashSaleService**: 秒杀核心逻辑，包含库存预热、分布式锁、Lua脚本执行
- **RedisService**: Redis基础操作封装，支持各种数据类型和TTL设置
- **RedissonLockService**: Redisson分布式锁实现，支持自动续期
- **RateLimitService**: 基于Redis的滑动窗口限流
- **CartService**: 购物车服务，基于Redis Hash实现
- **RedisPipelineService**: 批量Redis操作优化
- **MessageListenerService**: Redis Pub/Sub消息监听处理

## 配置说明

### 核心配置文件
- `application.yml`: 主配置文件（数据库、Redis、业务配置）
- `pom.xml`: Maven依赖和构建配置

### 重要配置项
```yaml
# Redis模式切换（application.yml）
spring.redis.host: localhost        # 单节点配置
spring.redis.cluster.nodes: ...     # 集群配置（取消注释启用）

# 秒杀业务配置
flashsale.seckill.rate-limit.max-requests-per-minute: 10  # 限流
flashsale.seckill.max-quantity-per-user: 1                # 每人限购
flashsale.seckill.stock-preload.advance-minutes: 30       # 预热时间

# 缓存过期时间
flashsale.cache.user-expire-minutes: 30      # 用户信息
flashsale.cache.product-expire-minutes: 60   # 商品信息
flashsale.cache.flashsale-expire-minutes: 10 # 秒杀活动
```

## 性能优化策略

1. **连接池优化**: HikariCP数据库连接池(20)，Jedis连接池(20)
2. **批量操作**: 使用 `RedisPipelineService` 进行批量Redis操作
3. **多级缓存**: 本地缓存 + Redis缓存，合理设置TTL
4. **Lua脚本**: 减少网络往返，保证原子性
5. **库存预热**: 提前加载热点数据到缓存

## 监控和运维

### 访问地址
- **应用首页**: http://localhost:8080
- **API文档**: http://localhost:8080/doc.html
- **健康检查**: http://localhost:8080/actuator/health
- **Prometheus监控**: http://localhost:8080/actuator/prometheus

### 日志配置
- **日志文件**: logs/flash-sale-system.log
- **日志级别**: DEBUG (com.org.flashsalesystem, Redis, SQL)

## 测试策略

### 单元测试
- 核心服务测试: FlashSaleServiceTest (已创建框架)
- 建议补充: RedisServiceTest, CartServiceTest
- Mock策略: 使用Mockito模拟Redis和数据库操作

### 性能测试
- 推荐工具: JMeter, Gatling
- 测试场景: 高并发秒杀、库存扣减准确性、分布式锁效果

## 安全考虑

1. **密码加密**: BCrypt (strength=10)
2. **Redis认证**: 集群模式使用密码认证
3. **SQL注入防护**: JPA参数化查询
4. **限流保护**: API级别限流防止恶意请求
5. **会话管理**: Redis存储，30分钟超时

## 故障排查

### 常见问题
1. **Redis连接失败**: 检查网络、端口、密码配置
2. **库存超卖**: 验证Lua脚本加载、分布式锁配置
3. **高延迟**: 检查Redis集群状态、网络延迟
4. **内存溢出**: 监控Redis内存、调整缓存TTL

### 调试技巧
- 启用DEBUG日志查看详细Redis操作
- 使用Redis CLI监控命令: `MONITOR`
- 检查Lua脚本执行: `SCRIPT EXISTS`