Entity mapping — @Entity, @Id, @GeneratedValue, naming strategy

@Entity
@Table(name = "projects")
public class Project {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true, length = 100)
    private String name;

    @Column(length = 500)
    private String description;

    @Enumerated(EnumType.STRING)
    @Column(nullable = false, length = 20)
    private ProjectStatus status;

    @Column(name = "created_at", nullable = false, updatable = false)
    private Instant createdAt;

    // 1. No-arg constructor (PROTECTED OR PUBLIC) — JPA require
    protected Project() {}

    // 2. Business constructor
    public Project(String name, String description, ProjectStatus status) {
        this.name = name;
        this.description = description;
        this.status = status;
        this.createdAt = Instant.now();
    }

    // 3. Getters
    public Long getId() { return id; }
    public String getName() { return name; }
    public String getDescription() { return description; }
    public ProjectStatus getStatus() { return status; }
    public Instant getCreatedAt() { return createdAt; }

    // 4. Setters (chỉ cho field mutable nghiệp vụ)
    public void setName(String name) { this.name = name; }
    public void setDescription(String description) { this.description = description; }
    public void setStatus(ProjectStatus status) { this.status = status; }

    // 5. equals/hashCode based on ID
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Project p)) return false;
        return id != null && id.equals(p.id);
    }

    @Override
    public int hashCode() {
        return getClass().hashCode();   // constant — handle ID null/change
    }
}

// SAI — JPA reject
@Entity
public record Project(@Id Long id, String name) {}

// Entity (DB)
@Entity public class Project { ... }

// DTO (API)
public record ProjectDto(Long id, String name, String description) {
    public static ProjectDto from(Project p) {
        return new ProjectDto(p.getId(), p.getName(), p.getDescription());
    }
}

@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;

CREATE TABLE projects (
    id BIGSERIAL PRIMARY KEY,        -- auto-increment
    name VARCHAR(100) NOT NULL,
    ...
);

INSERT INTO projects (name, ...) VALUES (?, ...) RETURNING id;

@Id
@GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "project_seq")
@SequenceGenerator(name = "project_seq", sequenceName = "projects_id_seq", allocationSize = 50)
private Long id;

CREATE SEQUENCE projects_id_seq INCREMENT 50 START 1;

CREATE TABLE projects (
    id BIGINT PRIMARY KEY,
    ...
);

@Id
@GeneratedValue(strategy = GenerationType.UUID)
private UUID id;

@Id
@GeneratedValue(strategy = GenerationType.UUID)
@UuidGenerator(style = UuidGenerator.Style.TIME)   // UUID v7
private UUID id;

@Column(
    name = "project_name",         // column name (default: snake_case từ field)
    nullable = false,                // NOT NULL constraint
    unique = true,                   // UNIQUE constraint
    length = 100,                    // VARCHAR(100)
    insertable = true,                // include in INSERT
    updatable = true,                 // include in UPDATE
    columnDefinition = "VARCHAR(100) CHECK (LENGTH(name) >= 3)"  // custom DDL
)
private String name;

spring:
  jpa:
    hibernate:
      naming:
        implicit-strategy: org.springframework.boot.orm.jpa.hibernate.SpringImplicitNamingStrategy
        physical-strategy: org.springframework.boot.orm.jpa.hibernate.SpringPhysicalNamingStrategy

@Column(name = "fname")          // explicit, không apply strategy
private String firstName;

@Entity
public class Project {
    @Id Long id;                    // → id
    String name;                     // → name
    String description;              // → description
    ProjectStatus status;            // → status
    Instant createdAt;               // → created_at (auto)
}

public enum ProjectStatus { PLANNING, ACTIVE, DONE, ARCHIVED }

@Enumerated(EnumType.STRING)
@Column(nullable = false, length = 20)
private ProjectStatus status;

public enum Status { PLANNING, ACTIVE, DONE }
// DB: 0, 1, 2

// Future: thêm enum value
public enum Status { PLANNING, INTERNAL_REVIEW, ACTIVE, DONE }
// DB: 0, 1, 2, 3
// Old row '1' = ACTIVE → bay gio thanh INTERNAL_REVIEW. CORRUPT DATA.

public enum ProjectStatus {
    PLANNING("planning"),
    ACTIVE("active"),
    DONE("done"),
    ARCHIVED("archived");

    @Getter
    private final String code;

    ProjectStatus(String code) { this.code = code; }

    public static ProjectStatus from(String code) {
        for (ProjectStatus s : values()) {
            if (s.code.equals(code)) return s;
        }
        throw new IllegalArgumentException("Unknown: " + code);
    }
}

@Convert(converter = ProjectStatusConverter.class)
private ProjectStatus status;

@Converter
public class ProjectStatusConverter implements AttributeConverter<ProjectStatus, String> {
    public String convertToDatabaseColumn(ProjectStatus s) { return s == null ? null : s.getCode(); }
    public ProjectStatus convertToEntityAttribute(String code) { return code == null ? null : ProjectStatus.from(code); }
}

@Embeddable
public class Money {

    @Column(name = "amount_value", precision = 19, scale = 4)
    private BigDecimal amount;

    @Column(name = "amount_currency", length = 3)
    private String currency;

    protected Money() {}                               // JPA require
    public Money(BigDecimal amount, String currency) {
        this.amount = amount;
        this.currency = currency;
    }
    // getters
}

@Entity
public class Order {
    @Id Long id;

    @Embedded
    private Money total;        // → 2 column: amount_value, amount_currency
}

CREATE TABLE orders (
    id BIGINT PRIMARY KEY,
    amount_value NUMERIC(19, 4),
    amount_currency VARCHAR(3)
);

@Entity
public class Order {
    @Embedded
    @AttributeOverrides({
        @AttributeOverride(name = "amount", column = @Column(name = "subtotal_value")),
        @AttributeOverride(name = "currency", column = @Column(name = "subtotal_currency"))
    })
    private Money subtotal;

    @Embedded
    @AttributeOverrides({
        @AttributeOverride(name = "amount", column = @Column(name = "tax_value")),
        @AttributeOverride(name = "currency", column = @Column(name = "tax_currency"))
    })
    private Money tax;
}

@Entity
public class Project {

    @PrePersist
    protected void onCreate() {
        if (createdAt == null) createdAt = Instant.now();
        if (status == null) status = ProjectStatus.PLANNING;
    }

    @PreUpdate
    protected void onUpdate() {
        // Note: KHONG set updatedAt qua method nay neu da co @LastModifiedDate
    }

    @PostLoad
    protected void afterLoad() {
        // Compute derived field tu data DB
    }

    @PreRemove
    protected void beforeDelete() {
        // Cleanup audit log
    }
}

@PrePersist
protected void prePersist() {
    if (createdAt == null) createdAt = Instant.now();
}

@PreUpdate
protected void preUpdate() {
    updatedAt = Instant.now();
}

// SAI 1: equals based on all fields (Lombok @EqualsAndHashCode)
@EqualsAndHashCode
@Entity
public class Project {
    @Id Long id;
    String name;
    Instant createdAt;
}

// SAI 2: equals based on ID, hashCode based on ID
@EqualsAndHashCode(of = "id")
@Entity
public class Project {
    @Id Long id;
}

@Entity
public class Project {
    @Id @GeneratedValue Long id;

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Project p)) return false;
        return id != null && id.equals(p.id);    // null-id never equal
    }

    @Override
    public int hashCode() {
        return getClass().hashCode();             // CONSTANT — same for all instance
    }
}

@Entity
@Table(
    name = "projects",
    schema = "taskflow",
    indexes = {
        @Index(name = "idx_project_status", columnList = "status"),
        @Index(name = "idx_project_created", columnList = "created_at DESC")
    },
    uniqueConstraints = {
        @UniqueConstraint(name = "uk_project_name", columnNames = "name")
    }
)
public class Project { ... }

@Entity
public class Project {
    @Id @GeneratedValue
    private Long id;

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Project that)) return false;
        return id != null && id.equals(that.id);
    }

    @Override
    public int hashCode() {
        return getClass().hashCode();        // CONSTANT — independent of id
    }
}

@Entity
public class Project {
    @Lob
    @Basic(fetch = FetchType.LAZY)
    private String description;
}

<plugin>
    <groupId>org.hibernate.orm.tooling</groupId>
    <artifactId>hibernate-enhance-maven-plugin</artifactId>
    <version>${hibernate.version}</version>
    <executions>
        <execution>
            <configuration>
                <enableLazyInitialization>true</enableLazyInitialization>
            </configuration>
            <goals><goal>enhance</goal></goals>
        </execution>
    </executions>
</plugin>

@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
public abstract class Auditable {
    @CreatedDate Instant createdAt;
    @LastModifiedDate Instant updatedAt;
    @CreatedBy String createdBy;
    @LastModifiedBy String updatedBy;
}

@Entity
public class Project extends Auditable { ... }

@SpringBootTest
@Testcontainers
class SchemaValidationTest {
    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16");

    @Test
    void hibernateValidatesSchema() {
        // ddl-auto: validate, Flyway migrate
        // Test fail nếu schema mismatch
    }
}

@Enumerated(EnumType.ORDINAL)     // mang nguy hiem

@Data       // sinh equals/hashCode based on all fields
@Entity
public class Project { ... }

@Entity
public final class Project { ... }    // Hibernate khong tao proxy — fail

@Entity
public class Project {
    @Id Long id;
    public Project(Long id) { ... }     // chi co arg constructor — JPA fail
}

public void setId(Long id) { this.id = id; }    // ID khong nen mutable