phronCare/Domain/Dtos/Stock/ExpeditionItemDto.cs

namespace Domain.Dtos.Stock
{
    /// <summary>
    /// Ítem de expedición para lectura en UI e impresión (detalle ya resuelto).
    /// Contiene la información mínima y suficiente para mostrar/emitir la nota de entrega.
    /// </summary>
    public sealed class ExpeditionItemDto
    {
        /// <summary>
        /// Identificador interno del renglón (detalle) de la expedición.
        /// Útil para acciones sobre el ítem (eliminar, editar cantidad, etc.).
        /// </summary>
        public int Id { get; set; }

        /// <summary>
        /// Identificador del producto en el catálogo maestro (FK a PhLSM_Product.Id).
        /// No es necesariamente visible en impresión; se usa para joins y trazabilidad.
        /// </summary>
        public int ProductId { get; set; }

        /// <summary>
        /// Código de producto definido por la fábrica o fabricante.
        /// Puede variar según proveedor, presentación o país de origen.
        /// Recomendado como código “principal” a mostrar en la nota.
        /// </summary>
        public string FactoryCode { get; set; } = string.Empty;

        /// <summary>
        /// Nombre del producto tal como figura en el catálogo (técnico o comercial).
        /// Se utiliza para la descripción en la tabla de ítems de la impresión.
        /// </summary>
        public string ProductName { get; set; } = string.Empty;

        /// <summary>
        /// Cantidad a expedir para este ítem.
        /// Para productos con trazabilidad por unidad/serial, suele ser 1 por línea.
        /// Para productos por lote (batch), puede ser una cantidad agregada.
        /// </summary>
        public decimal Quantity { get; set; }

        /// <summary>
        /// Lote del producto (GS1 AI 10).
        /// Aplica a productos con trazabilidad por lote; puede ser null si no corresponde.
        /// </summary>
        public string? Batch { get; set; }

        /// <summary>
        /// Serial/Número de serie del producto (GS1 AI 21).
        /// Aplica a productos con trazabilidad por unidad; puede ser null si no corresponde.
        /// </summary>
        public string? Serial { get; set; }

        /// <summary>
        /// Fecha de vencimiento (GS1 AI 17) en precisión de día.
        /// Es null cuando el tipo de trazabilidad no requiere fecha.
        /// </summary>
        public DateOnly? Expiration { get; set; }

        /// <summary>
        /// Identificador de la ubicación/depósito desde donde se despacha (FK a StockLocation).
        /// Puede ser null si no aplica o no se registró en el momento de la expedición.
        /// </summary>
        public int? LocationId { get; set; }

        /// <summary>
        /// Nombre legible de la ubicación/depósito (resuelto por join).
        /// Se usa para impresión y visualización sin pedir más datos al front.
        /// </summary>
        public string? LocationName { get; set; }
    }
}