# CLAUDE.md

这个文件为Claude Code (claude.ai/code)提供在此代码库中工作的指导。

## 项目概述

ZKH Framework是一个基于Spring Boot 3.5.7和Java 21的企业级Java开发框架，采用多模块Maven架构。框架提供了Web开发、数据访问、安全认证等核心功能。

## 模块架构

项目采用多模块架构，包含以下核心模块：

### zkh-common
- **作用**: 通用工具类和基础实体类
- **关键组件**:
  - `R<T>`: 统一响应结果封装类
  - `BaseEntity`: 基础实体类，包含审计字段（id, createTime, updateTime, createBy, updateBy）
  - `BizException`: 业务异常类
- **依赖**: Spring Data JPA, Jakarta Persistence API, Jackson Annotations

### zkh-web
- **作用**: Web层组件和安全配置
- **关键组件**:
  - `WebSecurityConfig`: Spring Security配置，支持Token认证
  - `TokenFilter`: Token认证过滤器
  - `JsonUsernamePasswordAuthenticationFilter`: JSON格式的用户名密码认证
  - `TokenRedisStorage`: Redis Token存储管理
  - `GlobalExceptionHandler`: 全局异常处理
- **特性**:
  - 基于Redis的Token认证机制
  - 支持CORS和JSON格式登录
  - 自动清理过期Token（每30分钟）
  - JPA审计支持

### zkh-data
- **作用**: 数据访问层组件
- **关键组件**:
  - `DynamicSpecificationBuilder`: 动态Specification构建器，支持复杂查询条件
  - `FieldMatch`: 字段匹配注解，用于查询条件映射
  - `MatchType`: 匹配类型枚举（EQUALS, CONTAINS, GREATER_THAN等）
  - `LogicalOperator`: 逻辑操作符（AND, OR）
- **特性**:
  - 基于注解的动态查询构建
  - 支持嵌套属性查询（如: user.address.city）
  - 查询条件缓存机制
  - 支持AND/OR逻辑组合

## 构建和开发

### 构建命令
```bash
# 编译整个项目
mvn clean compile

# 运行测试
mvn test

# 打包项目
mvn clean package

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

# 安装到本地仓库
mvn clean install

# 发布到Maven Central（需要GPG签名）
mvn clean deploy -P release
```

### 开发环境要求
- JDK 21
- Maven 3.6+
- Redis（用于Token存储）
- 数据库（支持JPA的任何数据库）

## 核心技术栈

- **Spring Boot**: 3.5.7
- **Spring Security**: 认证和授权
- **Spring Data JPA**: 数据访问层
- **Redis**: Token存储和缓存
- **Jackson**: JSON序列化/反序列化
- **Lombok**: 减少样板代码
- **BCrypt**: 密码加密

## 使用指南

### Token认证
- 登录成功后返回UUID格式的Token
- 请求时在Header中添加 `Authorization: Bearer <token>`
- 支持单点登出和全部登出

### 动态查询
使用`@FieldMatch`注解在DTO字段上配置查询条件：
```java
@FieldMatch(matchType = MatchType.CONTAINS, ignoreCase = true)
private String name;

@FieldMatch(matchType = MatchType.BETWEEN)
private Date[] createTimeRange;
```

### 审计功能
继承`BaseEntity`类自动获得：
- 主键自增
- 创建/更新时间自动记录
- 创建/更新人自动记录

## 项目配置

### 安全配置
通过`SecurityProps`配置忽略认证的URL路径。

### Redis配置
确保Redis服务可用，用于Token存储和管理。

### 数据库配置
配置Spring Boot数据源以使用JPA功能。