# Project Configuration & Architecture Rules (.cursorrules)

## 1. Project Context (项目基础信息)
- **Root Package**: `src/main/java/com/yourcompany/project`  <-- 🔴 【请修改为你实际的包名】
- **Build Tool**: Maven
- **Language**: Java 17+
- **Framework**: Spring Boot 3.x

## 2. Allowed Dependencies (依赖白名单 - 严格执行)
AI 在生成代码时，**仅允许**使用以下库，严禁引入未在 `pom.xml` 中声明的第三方依赖：

- **Core**: Spring Boot Starter Web
- **ORM**: MyBatis Plus
- **Utils**: Hutool (`cn.hutool.*`), Lombok
- **JSON**: Jackson (`com.fasterxml.jackson.*`) - Spring Boot 默认自带
- **Docs**: Knife4j / Swagger
- **Test**: JUnit 5, Mockito

## 3. Directory Structure (目录结构规范)
AI 生成代码时，**必须**严格遵守以下分层结构，并自动创建不存在的文件夹：

### 3.1 Controller Layer
- **Path**: `controller/`
- **Rules**: 
  - 必须使用 `@RestController`。
  - 返回值统一封装为 `Result<T>`。
  - 禁止包含业务逻辑。

### 3.2 Service Layer
- **Interface**: `service/` (命名 `I*Service` 或 `*Service`)
- **Impl**: `service/impl/` (命名 `*ServiceImpl`，必须加 `@Service`)
- **Rules**: 事务必须加 `@Transactional(rollbackFor = Exception.class)`。

### 3.3 Mapper Layer
- **Path**: `mapper/`
- **Rules**: 必须继承 `BaseMapper<Entity>`，必须加 `@Mapper`。

### 3.4 Model Layer
- **`model/entity/`**: 数据库实体 (使用 `@TableName`)。
- **`model/dto/`**: 接收参数 (禁止使用 Entity)。
- **`model/vo/`**: 返回前端 (禁止直接返回 Entity)。

### 3.5 Common Layer
- **`common/api/`**: 存放 `Result<T>`, `ErrorCode`，`BusinessException`，`GlobalExceptionHandler`。
- **`common/util/`**: 存放自定义工具类。

## 4. Coding Standards (编码规范)

### 4.1 Utilities Selection (工具类选择指南 - 防止乱引包)
当需要进行以下操作时，**必须**使用指定的库：
- **String/Collection Utils**: 优先使用 `hutool` (如 `StrUtil`, `CollUtil`) 或 Spring 自带的 (`StringUtils`)。
  - ❌ 禁止引入 `org.apache.commons.lang3.*` (除非 pom.xml 明确有)。
- **JSON Processing**: 必须使用 `Jackson` (`ObjectMapper`) 或 `Hutool-JSON`。
  - ❌ 禁止引入 `com.alibaba.fastjson` / `Gson`。
- **Date/Time**: 必须使用 Java 8 `LocalDateTime` 或 `Hutool-DateUtil`。
  - ❌ 禁止使用 `java.util.Date`。
- **Bean Copy**: 必须使用 `BeanUtil.copyProperties()` (Hutool) 或 `BeanUtils` (Spring)。

### 4.2 Annotations
- **Lombok**: 所有 POJO 必须使用 `@Data`, `@Builder`, `@NoArgsConstructor`, `@AllArgsConstructor`。
- **Logs**: 必须使用 `@Slf4j` (Lombok)，禁止 `System.out`。

## 5. Negative Constraints (❌ 绝对禁止)
1. ❌ **禁止幻觉依赖**: 不要 import 项目中不存在的包（如 `Guava`, `Apache Commons`），除非你确定它们在 `pom.xml` 中。
2. ❌ **禁止** Controller 直接调用 Mapper。
3. ❌ **禁止** 返回 `Map<String, Object>`。
4. ❌ **禁止** 吞掉异常 (Empty catch block)。

### 5.2 Database & SQL Rules
- **Table Naming**: `snake_case` (e.g., `user_info`). 
  - Note: Avoid SQL reserved keywords like `order`, `user`, `group`.
- **Mandatory Fields**: Every table MUST have:
  - `id` (BIGINT, PK, Auto Increment)
  - `create_time` (DATETIME)
  - `update_time` (DATETIME)
  - `is_deleted` (TINYINT, Logic Delete)
- **Entity Mapping**: 
  - `is_deleted` field must use `@TableLogic`.
  - `create_time`/`update_time` should use `@TableField(fill = FieldFill.INSERT/UPDATE)`.

## 6. Initialization Prompt (初始化指令)
如果用户要求 "初始化项目"，请生成：
1. `common/api/Result.java`
2. `common/exception/GlobalExceptionHandler.java` (使用 @RestControllerAdvice)
3. `config/Knife4jConfig.java`

## 7. Import Safety Check (导入安全检查)
Before generating any `import` statement:
1. Check if the library is listed in **Section 2**.
2. If the library involves `apache.commons`, `google.guava`, or `alibaba`, **verify** if it exists in the project context.
3. If unsure, use Standard Java Library or Spring Boot built-in utils.

## 8. 🏗️ Skeleton Generation Mode (骨架生成模式)
当用户指令包含 **"生成骨架"**, **"Scaffold"**, **"Structure Only"** 时，请严格遵守以下规则：

1.  **只创建文件和类结构**，不要编写具体业务逻辑。
2.  **Entity/DTO/VO**: 必须包含所有字段、Lombok 注解、Swagger 注解（这是数据契约，必须完整）。
3.  **Controller**:
    - 定义好所有 URL 方法 (@GetMapping, @PostMapping)。
    - 定义好入参 (@RequestBody) 和返回值 (Result<VO>)。
    - **方法体**: 直接返回 `return Result.success(null);` 或 `return null;`。
    - 不要调用 Service，或者仅保留 Service 的注入字段。
4.  **Service Interface**: 定义好方法签名。
5.  **Service Impl**: 创建类并实现接口，但方法体内留空或抛出 `throw new UnsupportedOperationException("Pending implementation");`。
6.  **Mapper**: 仅创建接口继承 BaseMapper，不写 XML。

**目标**: 快速建立文件系统和类之间的引用关系，确保编译通过，但无实际功能。

前期准备：
0-1：IDEA新建项目        ------>       手动导入依赖 Hutool 和 Swagger (Knife4j)

步骤：

1.@规则 请按照规则，初始化项目通用层（Common Layer）。 需要生成 Result<T>, ErrorCode, BusinessException，GlobalExceptionHandler。

2.我要开发 **学生管理 (Student)** 模块。 请拆解任务并列出文件清单。

3.根据上述需求，请为 MySQL 数据库生成建表 SQL 语句。
要求：
1. 表名：`student`
2. 包含通用字段：`id` (主键自增), `create_time`, `update_time`, `is_deleted` (逻辑删除)。
3. 字段要有详细的注释 (COMMENT)。
4. 不使用外键。

4.SQL 已就绪。请启用 **Scaffold Mode**。 为 SchoolClass 模块生成代码骨架。 要求： 1. Entity 必须与 SQL 对应。 2. Controller/Service 方法留空，不写逻辑。 3. 生成 add, update, list 接口的定义。

注：我想要做一个 学生管理 (Student)模块 ，需要哪些接口，直接给我接口名字即可

5.@StudentServiceImpl.java (引用文件) @StudentAddDTO.java @Student.java 现在实现 `addStudent` 方法的业务逻辑。 逻辑要求： 1. 检查学号 (studentNo) 是否已存在，如果存在抛出异常。 2. 使用 BeanUtil 将 DTO 转为 Entity。 3. 保存到数据库。

注：检查学号 (studentNo) 是否已存在，就是主键字段

6.@StudentController.java @StudentServiceImpl.java 请完善 Controller 中的 `add` 方法，调用 Service 并返回结果。

工具类：

我要计算入学日期和当前日期的天数差。请问 Hutool 里有现成的方法吗？如果有直接告诉我怎么用；如果没有，帮我在 common/util 下生成一个 DateCalcUtil。