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 定义

@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;

验证结果

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）

---

一、表名规范化重构