From 47945b245df21ae27770dc2a2b39c63773a0e3f2 Mon Sep 17 00:00:00 2001
From: pigeon <zs@vifo.net>
Date: Fri, 5 Jun 2026 11:55:44 +0800
Subject: [PATCH] =?UTF-8?q?docs(backend):=20=E6=B7=BB=E5=8A=A0=20BaseEntit?=
 =?UTF-8?q?y=20=E5=AD=97=E6=AE=B5=E8=AF=B4=E6=98=8E=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 说明所有业务实体必须继承的标准字段
- 包含字段类型、填充时机、数据库映射说明
- 提供 Java 和 SQL 使用示例
---
 backend/guides/BaseEntity字段说明.md | 63 ++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 backend/guides/BaseEntity字段说明.md

diff --git a/backend/guides/BaseEntity字段说明.md b/backend/guides/BaseEntity字段说明.md
new file mode 100644
index 0000000..fbf90bc
--- /dev/null
+++ b/backend/guides/BaseEntity字段说明.md
@@ -0,0 +1,63 @@
+# BaseEntity 字段说明
+
+> **适用范围**：所有业务实体必须继承 `BaseEntity`，包含框架自动维护的标准字段。
+
+## 类定义
+
+```java
+package com.rui.common.mybatis.model;
+
+public class BaseEntity implements Serializable {
+    // ...
+}
+```
+
+## 字段列表
+
+| 字段名 | 类型 | 说明 | 填充时机 | 数据库字段 |
+|--------|------|------|----------|------------|
+| `id` | `Long` | 主键ID，使用雪花算法生成 | 插入时自动填充 | `id` |
+| `tenantId` | `Long` | 租户ID，`0` 表示系统级 | 插入时自动填充 | `tenant_id` |
+| `deleted` | `Integer` | 逻辑删除标志，`0` 正常，`1` 已删除 | 插入时自动填充 | `deleted` |
+| `createdBy` | `Long` | 创建者ID | 插入时自动填充 | `created_by` |
+| `createdAt` | `LocalDateTime` | 创建时间 | 插入时自动填充 | `created_at` |
+| `updatedBy` | `Long` | 更新者ID | 插入/更新时自动填充 | `updated_by` |
+| `updatedAt` | `LocalDateTime` | 更新时间 | 插入/更新时自动填充 | `updated_at` |
+
+## 注解说明
+
+- `@TableId(type = IdType.ASSIGN_ID)` — 使用雪花算法分配 ID
+- `@TableLogic` — 逻辑删除字段，MyBatis Plus 自动处理删除逻辑
+- `@TableField(fill = FieldFill.INSERT)` — 插入时自动填充
+- `@TableField(fill = FieldFill.INSERT_UPDATE)` — 插入/更新时自动填充
+
+## 使用示例
+
+```java
+@Data
+public class User extends BaseEntity {
+    private String username;
+    private String email;
+    // 无需定义 id、createdAt 等公共字段
+}
+```
+
+## 数据库建表示例
+
+```sql
+CREATE TABLE sys_user (
+    id BIGINT PRIMARY KEY COMMENT '主键ID（雪花算法）',
+    username VARCHAR(100) NOT NULL COMMENT '用户名',
+    email VARCHAR(100) COMMENT '邮箱',
+    
+    -- 公共字段（由 BaseEntity + MyBatis Plus 自动维护）
+    tenant_id BIGINT DEFAULT 0 COMMENT '租户ID',
+    deleted TINYINT DEFAULT 0 COMMENT '逻辑删除（0-正常，1-已删）',
+    created_by BIGINT COMMENT '创建者ID',
+    created_at DATETIME COMMENT '创建时间',
+    updated_by BIGINT COMMENT '更新者ID',
+    updated_at DATETIME COMMENT '更新时间'
+) COMMENT='用户表';
+```
+
+> **注意**：所有业务表必须包含以上公共字段。