InvoiceHeadController

📊 Resumen del Controlador

2

Servicios Inyectados

5

Endpoints Totales

1

Entidad Principal

CRUD

Operaciones Completas

El InvoiceHeadController es el controlador encargado de gestionar todos los aspectos relacionados con las cabeceras de facturas del restaurante. Proporciona una API RESTful completa con operaciones CRUD para la entidad Factura, incluyendo gestión de estados y control de transacciones.

🎯 Funcionalidades Principales

Gestión CRUD completa de cabeceras de facturas (4 endpoints)
Consulta de facturas específicas por tipo, serie y número
Creación de nuevas facturas con validación de datos
Actualización de facturas existentes en el sistema
Eliminación de facturas con control de integridad
Gestión de estados de facturas (1 endpoint específico)
Manejo de transacciones con contexto de base de datos
Resultados tipados con ServiceResult para mejor control de errores

🔧 Servicios Utilizados

Servicios Inyectados por Constructor:

IInvoiceHeadService - Servicio principal de gestión de cabeceras de facturas
DbWorkingContextHelper - Helper para configuración de contexto de base de datos

⚠️ Parámetros de Conexión

Todos los endpoints requieren los siguientes parámetros de conexión a la base de datos:

initialCatalog (string): Nombre de la base de datos
userID (string, opcional): ID de usuario de la base de datos
password (string, opcional): Contraseña de la base de datos

📋 Categorías de Endpoints

📄 Gestión de Facturas

Operaciones CRUD completas para la gestión de cabeceras de facturas

CRUD

Core

Endpoints: 4 métodos

GET /{tipoDocumento}/{serie}/{factura}
POST /
PUT /
DELETE /{tipoDocumento}/{serie}/{factura}

Ver detalles →

🔄 Gestión de Estados

Control de estados de las facturas

Status

Control

Endpoints: 1 método

PUT /{tipoDocumento}/{serie}/{factura}/status

Ver detalles →

🔗 Estructura de Rutas

Ruta Base: `/WorkingData/InvoiceHead`

Todos los endpoints del controlador están bajo la ruta /WorkingData/InvoiceHead, lo que indica que maneja datos de trabajo del sistema.

Patrones de URL por Categoría:

Gestión de Facturas:
- /{tipoDocumento}/{serie}/{factura} - GET, DELETE
- / - POST, PUT
Gestión de Estados: /{tipoDocumento}/{serie}/{factura}/status - PUT

⚠️ Identificación de Facturas

Las facturas se identifican mediante tres parámetros:

tipoDocumento (string): Tipo de documento (ej: "FACTURA", "TICKET")
serie (string): Serie del documento
factura (double): Número de factura

📊 Códigos de Respuesta

✅ 200 - OK

Operación exitosa, datos devueltos correctamente

Usado en: GET, POST, PUT, DELETE exitosos

❌ 400 - Bad Request

Error en la solicitud o validación

Usado en: Errores de validación o lógica de negocio

📝 Nota sobre Códigos de Respuesta

Este controlador utiliza ServiceResult para manejar resultados, por lo que todos los endpoints devuelven 200 (éxito) o 400 (error), con la información detallada del resultado en el cuerpo de la respuesta.

🔍 Características Técnicas

🎯 Características del Controlador

Async/Await: Todos los métodos son asíncronos para mejor rendimiento
Swagger Documentation: Documentación completa con Swagger/OpenAPI
ServiceResult Pattern: Manejo estructurado de resultados y errores
Dependency Injection: Inyección de servicios + helper de contexto
RESTful Design: Diseño REST completo con verbos HTTP apropiados
Type Safety: Uso de tipos fuertemente tipados para respuestas
Constructor Injection: Inyección de dependencias por constructor
Context Management: Gestión automática de contexto de base de datos

⚠️ Consideraciones de Seguridad

Todos los endpoints requieren parámetros de conexión a la base de datos
Los errores se manejan a través de ServiceResult sin exponer información sensible
Se recomienda implementar autenticación y autorización adicional
Validación de entrada en todos los endpoints POST/PUT
Las facturas son documentos legales, requiere auditoría completa

📝 Patrones de Diseño Utilizados

ServiceResult Pattern: Manejo estructurado de resultados
Repository Pattern: Acceso a datos a través de servicios
Dependency Injection: Inversión de control para servicios
Async/Await Pattern: Programación asíncrona
Context Pattern: Gestión de contexto de base de datos
RESTful API Design: Diseño de API REST estándar

📈 Estadísticas Detalladas

150

Líneas de Código

1

Región de Código

5

Métodos Públicos

4

Verbos HTTP

Distribución de Métodos HTTP:

GET: 1 endpoint (20%) - Consultas y recuperación de datos
POST: 1 endpoint (20%) - Creación de recursos
PUT: 2 endpoints (40%) - Actualización de recursos y estados
DELETE: 1 endpoint (20%) - Eliminación de recursos

📋 Modelo de Datos - Factura

Propiedades principales del modelo Factura:

TipoDocumento (string): Tipo de documento (FACTURA, TICKET, etc.)
Serie (string): Serie del documento
Factura (double): Número de factura
Fecha (DateTime): Fecha de emisión de la factura
Cliente (string): Identificación del cliente
Total (decimal): Importe total de la factura
Estado (string): Estado actual de la factura
Empleado (string): Empleado que emitió la factura

📝 Estados Comunes de Facturas

BORRADOR: Factura en proceso de creación
EMITIDA: Factura completada y emitida
PAGADA: Factura pagada completamente
ANULADA: Factura cancelada o anulada
PENDIENTE: Factura pendiente de pago

📝 Nota sobre la validación automática de Fecha en cobros

Nota: En la creación de facturas con cobros, el campo Fecha de cada cobro es obligatorio. Si no se envía, el sistema asigna la fecha y hora actual del servidor.