refactor: 对齐后端样例工程规范

backend/api/internal/models/entity.go

@@ -0,0 +1,28 @@
+// Package models 定义与数据库表同名的领域模型和数据访问方法。
+package models
+
+import (
+	"time"
+
+	"github.com/google/uuid"
+)
+
+// Entity 是所有主表共享字段；identity 必须由应用生成 UUID V7，禁止自增主键。
+type Entity struct {
+	Identity          uuid.UUID  `gorm:"column:identity;type:uuid;primaryKey" json:"identity"`                      // 主键，UUID V7
+	CreatedAt         time.Time  `gorm:"column:created_at;type:timestamptz;not null" json:"created_at"`             // 创建时间
+	UpdatedAt         time.Time  `gorm:"column:updated_at;type:timestamptz;not null" json:"updated_at"`             // 更新时间
+	CreatedByIdentity *uuid.UUID `gorm:"column:created_by_identity;type:uuid" json:"created_by_identity,omitempty"` // 创建人主键
+	UpdatedByIdentity *uuid.UUID `gorm:"column:updated_by_identity;type:uuid" json:"updated_by_identity,omitempty"` // 更新人主键
+	Status            string     `gorm:"column:status;type:varchar(32);not null;default:'draft'" json:"status"`     // 业务状态
+	Version           int        `gorm:"column:version;not null;default:1" json:"version"`                          // 乐观锁版本
+}
+
+// NewIdentity 生成时间有序 UUID V7，生成失败属于不可恢复的运行时错误。
+func NewIdentity() uuid.UUID {
+	identity, err := uuid.NewV7()
+	if err != nil {
+		panic(err)
+	}
+	return identity
+}