package com.social.media.domain.shared;

import java.time.Instant;

/**
 * Base interface for all Domain Entities in the Social Media Manager application.
 * 
 * Entities are objects with identity that can change over time while maintaining
 * their identity. They are the core building blocks of the domain model.
 * 
 * All entities should:
 * - Have a unique identifier
 * - Have identity equality (equals/hashCode based on ID)
 * - Track creation and modification timestamps
 * - Be mutable through business operations
 * 
 * @param <ID> The type of the entity identifier
 * 
 * @author Social Media Manager Team
 * @version 2.0
 * @since 2025-01-01
 */
public interface Entity<ID> {
    
    /**
     * Gets the unique identifier of this entity.
     * 
     * @return the entity identifier, never null for persisted entities
     */
    ID getId();
    
    /**
     * Gets the timestamp when this entity was created.
     * 
     * @return the creation timestamp, never null for persisted entities
     */
    Instant getCreatedAt();
    
    /**
     * Gets the timestamp when this entity was last updated.
     * 
     * @return the last update timestamp, never null for persisted entities
     */
    Instant getUpdatedAt();
    
    /**
     * Checks if this entity is new (not yet persisted).
     * 
     * @return true if the entity is new, false if it's persisted
     */
    default boolean isNew() {
        return getId() == null;
    }
    
    /**
     * Validates the entity state.
     * Should be called before persistence operations.
     * 
     * @throws IllegalStateException if the entity is in an invalid state
     */
    default void validate() {
        // Default implementation does nothing
        // Concrete entities should override if validation is needed
    }
}