PowderCoatingLogix/src/PowderCoating.Core/Entities/Appointment.cs

namespace PowderCoating.Core.Entities;

/// <summary>
/// Represents a scheduled appointment for customer drop-offs, pick-ups, consultations, or job work.
/// </summary>
public class Appointment : BaseEntity
{
    /// <summary>
    /// Auto-generated appointment number in format APT-YYMM-####
    /// </summary>
    public string AppointmentNumber { get; set; } = string.Empty;

    /// <summary>
    /// Brief title/description of the appointment
    /// </summary>
    public string Title { get; set; } = string.Empty;

    /// <summary>
    /// Detailed description and notes about the appointment
    /// </summary>
    public string? Description { get; set; }

    // Customer Information
    /// <summary>
    /// Optional foreign key to Customer (not required for internal appointments like employee days off)
    /// </summary>
    public int? CustomerId { get; set; }

    /// <summary>
    /// Optional foreign key to Job (required for JOB_WORK appointment type)
    /// </summary>
    public int? JobId { get; set; }

    // Lookup Foreign Keys
    /// <summary>
    /// Foreign key to AppointmentStatusLookup
    /// </summary>
    public int AppointmentStatusId { get; set; }

    /// <summary>
    /// Foreign key to AppointmentTypeLookup
    /// </summary>
    public int AppointmentTypeId { get; set; }

    /// <summary>
    /// Optional foreign key to ApplicationUser assigned to handle this appointment
    /// </summary>
    public string? AssignedUserId { get; set; }

    // Timing
    /// <summary>
    /// Scheduled start date and time (UTC)
    /// </summary>
    public DateTime ScheduledStartTime { get; set; }

    /// <summary>
    /// Scheduled end date and time (UTC)
    /// </summary>
    public DateTime ScheduledEndTime { get; set; }

    /// <summary>
    /// Whether this is an all-day appointment (hides specific times)
    /// </summary>
    public bool IsAllDay { get; set; } = false;

    /// <summary>
    /// Actual start time when customer arrived (UTC, nullable until appointment starts)
    /// </summary>
    public DateTime? ActualStartTime { get; set; }

    /// <summary>
    /// Actual end time when appointment finished (UTC, nullable until appointment completes)
    /// </summary>
    public DateTime? ActualEndTime { get; set; }

    // Additional Information
    /// <summary>
    /// Optional location at the shop (e.g., "Main Office", "Loading Dock", "Inspection Area")
    /// </summary>
    public string? Location { get; set; }

    /// <summary>
    /// Internal notes for staff (not visible to customer)
    /// </summary>
    public string? Notes { get; set; }

    // Reminder Settings
    /// <summary>
    /// Whether to send reminder notifications
    /// </summary>
    public bool IsReminderEnabled { get; set; } = true;

    /// <summary>
    /// How many minutes before appointment to send reminder (default 30 minutes)
    /// </summary>
    public int ReminderMinutesBefore { get; set; } = 30;

    /// <summary>
    /// UTC timestamp when the reminder was dispatched. Null means it hasn't fired yet.
    /// The background service uses this as a deduplication guard to prevent double-sending.
    /// </summary>
    public DateTime? ReminderSentAt { get; set; }

    // Navigation Properties
    public virtual Customer? Customer { get; set; }
    public virtual Job? Job { get; set; }
    public virtual AppointmentStatusLookup AppointmentStatus { get; set; } = null!;
    public virtual AppointmentTypeLookup AppointmentType { get; set; } = null!;
    public virtual ApplicationUser? AssignedUser { get; set; }
}