kindergarten_java/docs/dev-logs/2026-03-13-orm-refactor.md

# ORM 实体类重构 - 2026-03-13

> 本文档记录两次 ORM 实体类重构：
> 1. **表名规范化** - 统一表名与实体类名
> 2. **BaseEntity 继承** - 消除重复字段

---

## 二、BaseEntity 继承重构

### 重构背景

项目中所有 40 个实体类都包含重复的公共字段（`id`, `createdAt`, `updatedAt`, `deleted`），需要统一继承 `BaseEntity` 基类来减少重复代码。

### BaseEntity 定义

```java
@Data
public abstract class BaseEntity {
    @TableId(type = IdType.ASSIGN_ID)
    private Long id;

    @CreatedBy
    @TableField(fill = FieldFill.INSERT)
    private String createBy;

    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createdAt;

    @LastModifiedBy
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private String updateBy;

    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updatedAt;

    @TableLogic
    @JsonIgnore
    private Integer deleted;
}
```

### 实体类状态分析

| 状态 | 实体类数量 | 公共字段情况 | 操作 |
|------|-----------|-------------|------|
| A | 37 个 | 完整字段（id, createdAt, updatedAt, deleted） | extends BaseEntity + 移除 4 字段 |
| B | 2 个 | 缺 deleted（CoursePackage, Theme） | extends BaseEntity + 移除 3 字段 |
| C | 1 个 | 缺 updatedAt, deleted（StudentClassHistory） | extends BaseEntity + 移除 2 字段 |

### 修改的实体类清单

#### 状态 B：缺少 deleted 字段（2 个）

| 序号 | 实体类 | 修改内容 |
|------|--------|---------|
| 1 | CoursePackage | 添加 extends BaseEntity，移除 id/createdAt/updatedAt |
| 2 | Theme | 添加 extends BaseEntity，移除 id/createdAt/updatedAt |

#### 状态 C：缺少 updatedAt 和 deleted（1 个）

| 序号 | 实体类 | 修改内容 |
|------|--------|---------|
| 1 | StudentClassHistory | 添加 extends BaseEntity，移除 id/createdAt/deleted |

#### 状态 A：完整字段（37 个）

| 序号 | 实体类 | 修改内容 |
|------|--------|---------|
| 1 | AdminUser | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 2 | Clazz | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 3 | ClassTeacher | 添加 extends BaseEntity，移除 id/createdAt/deleted（缺 updatedAt） |
| 4 | Course | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted/createdBy |
| 5 | CourseActivity | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 6 | CourseLesson | 添加 extends BaseEntity，移除 id/createdAt/updatedAt |
| 7 | CoursePackageCourse | 添加 extends BaseEntity，移除 id |
| 8 | CourseResource | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 9 | CourseScript | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 10 | CourseScriptPage | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 11 | CourseVersion | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 12 | GrowthRecord | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 13 | Lesson | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 14 | LessonFeedback | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 15 | LessonStep | 添加 extends BaseEntity，移除 id/createdAt/updatedAt |
| 16 | LessonStepResource | 添加 extends BaseEntity，移除 id/createdAt/updatedAt |
| 17 | Notification | 添加 extends BaseEntity，移除 id/createdAt/deleted |
| 18 | OperationLog | 添加 extends BaseEntity，移除 id/createdAt |
| 19 | Parent | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 20 | ParentStudent | 添加 extends BaseEntity，移除 id/createdAt/deleted |
| 21 | ResourceItem | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted/createdBy/updatedBy |
| 22 | ResourceLibrary | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted/createdBy/updatedBy |
| 23 | SchedulePlan | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 24 | ScheduleTemplate | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 25 | Student | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 26 | StudentRecord | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 27 | SystemSetting | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 28 | Tag | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 29 | Task | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 30 | TaskCompletion | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 31 | TaskTarget | 添加 extends BaseEntity，移除 id/createdAt/deleted |
| 32 | TaskTemplate | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 33 | Teacher | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 34 | Tenant | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 35 | TenantCourse | 添加 extends BaseEntity，移除 id/createdAt/updatedAt/deleted |
| 36 | TenantPackage | 添加 extends BaseEntity，移除 id/createdAt/updatedAt |

### 修改模式

每个实体类按照以下模式修改：

1. **添加 `extends BaseEntity`** 到类声明
2. **添加 `@EqualsAndHashCode(callSuper = true)`** 注解
3. **移除重复字段**：
   - `Long id`（带 `@TableId` 注解）
   - `LocalDateTime createdAt`（带 `@TableField(fill = FieldFill.INSERT)`）
   - `LocalDateTime updatedAt`（带 `@TableField(fill = FieldFill.INSERT_UPDATE)`）
   - `Integer deleted`（带 `@TableLogic`）
   - `String createBy` 和 `String updateBy`（如果存在）
4. **清理 import**：
   - 移除 `import com.baomidou.mybatisplus.annotation.*;`
   - 只保留实际使用的注解 import
   - 添加 `import lombok.EqualsAndHashCode;`
   - 移除不再使用的 `import java.time.LocalDateTime;`

### 验证结果

```bash
export JAVA_HOME="/f/Java/jdk-17"
mvn clean compile -DskipTests
```

**编译结果**: ✅ BUILD SUCCESS

**警告说明**: MapStruct 提示部分字段未映射（如 `createBy`, `updateBy` 等），这些警告不影响运行，是因为 BaseEntity 新增的字段在 DTO 映射时需要显式处理。

### 数据库迁移脚本

创建了 3 个 Flyway 迁移脚本：

1. **V20260313__rename_tables_to_singular.sql** - 表名规范化（复数改单数）
2. **V20260313_2__add_audit_fields.sql** - 为所有表添加审计字段（create_by, update_by）
3. **V20260313_3__fix_missing_tables.sql** - 修复缺失的表（创建所有未创建的表）

**V20260313_2__add_audit_fields.sql 说明**：
- 为 39 个表添加了 `create_by` 和 `update_by` 字段
- 为部分表补充了缺失的 `deleted`、`created_at`、`updated_at` 字段
- 确保数据库表结构与 BaseEntity 实体类保持一致

**V20260313_3__fix_missing_tables.sql 说明**：
- 创建 V1 和 V20260313 迁移中缺失的所有基础表
- 包含所有 39 个实体类对应的数据库表
- 自动包含所有必要的字段和索引
- 插入默认超级管理员账号（admin/123456）

---

## 一、表名规范化重构