core_wing_web/CLAUDE.md

# CLAUDE.md

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

## 项目概述

CoreWing 是一个基于 Spring Boot 2.6.13 的 Java Web 应用，使用 Gradle 作为构建工具。

**技术栈：**
- Java 8
- Spring Boot 2.6.13
- MyBatis Plus 3.5.14 (ORM 框架)
- Sa-Token 1.44.0 (权限认证框架)
- Druid 1.2.27 (数据库连接池)
- MySQL 8.x (数据库)
- Redis (缓存)
- Lombok (代码简化工具)

## 常用命令

### 构建和运行
```bash
# 构建项目
./gradlew build

# 构建项目（跳过测试）
./gradlew build -x test

# 运行应用 (端口 8080)
./gradlew bootRun

# 清理构建文件
./gradlew clean
```

### 测试
```bash
# 运行所有测试
./gradlew test

# 运行单个测试类
./gradlew test --tests com.corewing.app.CoreWingApplicationTests

# 运行测试并生成报告
./gradlew test --info
```

### 开发
```bash
# 使用 Spring Boot DevTools 运行 (支持热重载)
./gradlew bootRun

# 检查依赖
./gradlew dependencies
```

## 代码架构

### 包结构
```
com.corewing.app/
├── common/              # 通用类
│   └── Result.java     # 统一返回结果类
├── config/             # 配置类
│   ├── DruidConfig.java         # Druid 数据源监控配置
│   ├── I18nConfig.java          # 国际化配置
│   ├── MybatisPlusConfig.java   # MyBatis-Plus 配置
│   ├── RedisConfig.java         # Redis 配置
│   └── SaTokenConfig.java       # Sa-Token 权限配置
├── controller/         # 控制器层
│   └── AppUserController.java   # 用户控制器
├── dto/               # 数据传输对象
│   ├── LoginRequest.java            # 登录请求参数
│   ├── RegisterRequest.java         # 注册请求参数
│   ├── SendCodeRequest.java         # 发送验证码请求参数
│   └── UpdatePasswordRequest.java   # 修改密码请求参数
├── entity/            # 实体类
│   └── AppUser.java   # 用户实体
├── handler/           # 处理器
│   └── MyMetaObjectHandler.java  # MyBatis-Plus 自动填充处理器
├── mapper/            # Mapper 接口
│   └── AppUserMapper.java  # 用户 Mapper
├── service/           # 服务层
│   ├── AppUserService.java      # 用户服务接口
│   ├── VerifyCodeService.java   # 验证码服务接口
│   └── impl/
│       ├── AppUserServiceImpl.java     # 用户服务实现
│       └── VerifyCodeServiceImpl.java  # 验证码服务实现
└── util/              # 工具类
    ├── EmailUtil.java   # 邮件发送工具类
    ├── I18nUtil.java    # 国际化工具类
    ├── IpUtil.java      # IP 工具类
    ├── RedisUtil.java   # Redis 工具类
    └── SmsBaoUtil.java  # 短信宝工具类
```

### 配置文件
- `application.properties` - 应用配置文件
  - 服务端口：8080
  - 数据库：MySQL 8.x
  - Redis 缓存
  - Druid 连接池
  - MyBatis-Plus 配置
  - Sa-Token 配置
  - 短信宝配置
  - 邮件配置

### 资源文件
- `src/main/resources/i18n/messages_zh_CN.properties` - 中文国际化消息
- `src/main/resources/i18n/messages_en_US.properties` - 英文国际化消息

### 数据库
- 建表 SQL：`src/main/resources/db/user.sql`
- 主表：`app_user` - 应用用户表

## 核心功能

### 1. 用户管理
- 用户注册（密码 MD5 加密，需要验证码）
- 用户登录（Sa-Token 生成 token，支持用户名/邮箱/手机号）
- 用户登出
- 获取用户信息
- 更新用户信息
- 修改密码
- 发送验证码（短信/邮件）

### 2. 权限认证
- 使用 Sa-Token 进行身份认证
- 登录拦截器配置
- 排除路由：`/user/login`, `/user/register`, `/user/sendCode`, 静态资源等

### 3. 验证码功能
- 支持手机号和邮箱发送验证码
- 验证码存储在 Redis 中，有效期 5 分钟
- 手机验证码通过短信宝发送
- 邮件验证码通过 Spring Mail 发送，支持 HTML 格式的精美邮件模板

### 4. 数据持久化
- MyBatis-Plus 作为 ORM 框架
- 支持自动填充（创建时间、更新时间）
- 主键策略：数据库自增
- 驼峰命名自动转换

### 5. 缓存
- Redis 作为缓存
- RedisUtil 工具类封装常用操作
- 支持 String、Hash、Set、List 数据类型
- 验证码存储在 Redis 中

### 6. 数据库连接池
- Druid 连接池
- 监控后台：`http://localhost:8080/druid/`
- 登录账号：admin / admin123
- SQL 监控、慢 SQL 记录（>5秒）

### 7. 短信服务
- 使用短信宝（https://www.smsbao.com/）发送短信
- SmsBaoUtil 工具类封装短信发送功能
- 支持发送验证码短信

### 8. 邮件服务
- 使用 Spring Boot Mail 发送邮件
- EmailUtil 工具类封装邮件发送功能
- 支持发送简单文本邮件和 HTML 邮件
- 验证码邮件采用精美的 HTML 模板
- 支持多种邮箱服务商（QQ、163、Gmail 等）

### 9. 国际化支持
- 支持中文（zh_CN）和英文（en_US）双语
- 客户端通过 HTTP Header 的 `Accept-Language` 或 `lang` 指定语言
- 默认语言：中文
- 国际化范围：
  - API 响应消息（成功/失败提示）
  - 用户操作反馈（登录、注册、登出等）
  - 所有异常和错误消息
  - 邮件模板内容
  - 短信模板内容
  - 钉钉推送消息
- I18nUtil 工具类提供便捷的国际化消息获取
- 详细使用说明参见：`I18N_README.md`

## 开发规范

### 1. 依赖注入
- 推荐使用构造函数注入
- 使用 `final` 修饰依赖字段

### 2. 实体类
- 使用 Lombok 简化代码
- 时间类型使用 `LocalDateTime`
- 自动填充字段使用 `@TableField(fill = FieldFill.XXX)`

### 3. 控制器
- 统一返回 `Result<T>` 类型
- DTO 类独立定义，不使用内部类
- 使用 RESTful 风格 API

### 4. 密码安全
- 密码使用 MD5 加密存储
- 不直接返回密码字段给前端

### 5. IP 获取
- 使用 `IpUtil.getClientIp()` 获取真实 IP
- 支持多级代理

### 6. 国际化消息
- 所有用户可见的消息都应使用国际化
- 使用 `I18nUtil.getMessage("message.key")` 获取国际化消息
- 支持消息参数：`I18nUtil.getMessage("message.key", param1, param2)`
- 新增消息时需同时更新中英文资源文件

## 项目特点

- 项目使用 MyBatis Plus 作为 ORM 框架，支持自动代码生成
- 集成 Sa-Token 用于身份验证和权限管理
- 支持 MySQL 数据库和 Redis 缓存
- 使用 Lombok 简化实体类代码
- 开发环境支持热重载 (Spring Boot DevTools)
- Druid 数据库连接池，提供 SQL 监控功能
- 统一返回结果封装，规范 API 响应格式
- 完整的国际化支持，支持中英文双语切换