33 Módulo de Caja y Pagos Comprobantes Pagos Parciales en Laravel Sistema de Odontología
Duración: 15 minDescripción
🎓 Lección 33: Módulo de Caja, Pagos y Comprobantes Parciales en Laravel
Objetivo General: Implementar la arquitectura completa para la gestión de ingresos, tesorería y comprobantes de pago (totales y parciales) mediante migraciones relacionales, permisos granulares con Middleware, generación de documentos imprimibles/PDFs y actualización en tiempo real del dashboard del consultorio.
🚀 Pasos Clave con Timestamps
- ⏱️ 00:39 Modelo Entidad-Relación (DBML): Definición del diagrama relacional integrando las tablas pagos y pagos_detalle vinculadas a pacientes, doctores, citas y usuarios.
- ⏱️ 02:08 Estrategia de Migraciones: Creación del esquema con campos para montos totales, abonos parciales, saldos pendientes, métodos de pago (efectivo, QR, tarjeta) y estados (completado, parcial, anulado).
- ⏱️ 03:21 Configuración de Modelos Eloquent: Establecimiento de la relación hasMany y belongsTo entre los modelos Pago y PagoDetalle junto con asignación masiva de atributos ($fillable).
- ⏱️ 03:47 Seeder de Permisos y Roles: Registro en base de datos de los 4 permisos específicos para el control de acceso: ver pagos, registrar transacciones, anular recibos e imprimir comprobantes.
- ⏱️ 04:25 Enrutamiento Protegido: Mapeo de rutas HTTP en routes/web.php asociadas a acciones del PagoController con middleware de autorización.
- ⏱️ 05:11 Estructura del PagoController: Desarrollo de los métodos base (index, create, store, imprimir, pdf, anular) y vinculación con la capa de vistas en Blade.
- ⏱️ 05:58 Poblamiento de Datos con Factories: Generación sintética de historiales clínicos y citas utilizando HistorialClinicoFactory y DatabaseSeeder para pruebas relacionales masivas (php artisan migrate:fresh --seed).
- ⏱️ 07:47 Flujo de Reserva y Anticipo (50%): Simulación del proceso desde la perspectiva del paciente reservando cita y pago del anticipo de confirmación en la interfaz de caja.
- ⏱️ 11:08 Emisión de Comprobantes: Generación de recibo parcial en formato ticket e impresión en PDF enviado directamente al paciente.
- ⏱️ 13:25 Atención Médica e Historial: Registro del tratamiento efectuado por el médico, prescripción en receta e interacción con el módulo de odontograma.
- ⏱️ 16:21 Liquidación Final y Multiconcepto: Incorporación de nuevos ítems o tratamientos adicionales en el cobro, cálculo automático del saldo restante y emisión del comprobante de "Pago Total".
- ⏱️ 18:34 Auditoría y Métricas del Dashboard: Sincronización en tiempo real del monto acumulado en la caja general del consultorio y validación de registros en MySQL.
🛠️ Comandos y Rutas Principales
| Tipo / Contexto | Comando / Ruta | Acción / Propósito |
|---|---|---|
| 💻 Artisan CLI | php artisan make:migration create_pagos_table | Crea la migración base para las cabeceras de pago |
| 💻 Artisan CLI | php artisan make:migration create_pago_detalles_table | Crea la migración relacional para el desglose de ítems |
| 💻 Artisan CLI | php artisan migrate:fresh --seed | Reinicia la base de datos y ejecuta los seeders con datos falsos |
| 🌐 HTTP GET | /admin/pagos | Muestra el listado general de transacciones e historial |
| 🌐 HTTP GET | /admin/pagos/create/{cita_id} | Despliega el formulario de cobro vinculado a una cita |
| 🌐 HTTP POST | /admin/pagos/store | Procesa y almacena la transacción y su detalle |
| 🌐 HTTP GET | /admin/pagos/{id}/imprimir | Renderiza la vista previa del ticket térmico para impresión |
| 🌐 HTTP GET | /admin/pagos/{id}/pdf | Exporta y descarga el comprobante en formato PDF |
| 🌐 HTTP PUT/PATCH | /admin/pagos/{id}/anular | Modifica el estado de la transacción a anulado |
🔒 Buenas Prácticas y Seguridad
- 🛡️ Transacciones ACID en Base de Datos: Envuelve el guardado de la tabla pagos y el recorrido de sus ítems en pagos_detalle dentro de un bloque DB::transaction(function() { ... }). Esto evita inconsistencias financieras si la inserción del detalle falla.
- 🔐 Control de Acceso Granular (Spatie Permissions): No permitas que cualquier usuario registrado anule o edite un recibo. Aplica middleware de permisos estrictos (por ejemplo, can:anular pagos) para restringir la anulación de comprobantes únicamente a supervisores o administradores.
- 🧮 Cálculo de Saldos en el Servidor: Jamás confíes en los montos totales o saldos pendientes enviados desde los inputs del cliente HTML o JavaScript. Recalcula siempre el subtotal, total y saldo dentro del controlador antes de persistir la información.
- 🧾 Inmutabilidad de Comprobantes: En lugar de eliminar registros cuando un cliente cancela un pago, implementa un "borrado lógico" cambiando el estado a anulado. Esto mantiene la trazabilidad contable auditables en caja.
