Informe Técnico

El presente documento detalla el plan técnico para la **estructuración y ejecución** de un sistema integral de gestión de pagos. El objetivo es proporcionar un control completo sobre las transacciones financieras de los alumnos, soportar múltiples métodos de pago, automatizar notificaciones y generar reportes para la toma de decisiones.

Este plan está diseñado para ser implementado por un desarrollador y se divide en cuatro fases críticas: **1. Base de Datos**, **2. Lógica de Backend**, **3. Interfaz de Frontend** y **4. Flujo de Ejecución y Pruebas**.

1.1. Modificación de Tablas Existentes

Se requiere añadir una columna a la tabla `inscripciones_curso` para vincularla con un posible descuento o beca aplicada.

-- Modificación a la tabla de inscripciones para soportar descuentos
ALTER TABLE `inscripciones_curso`
ADD COLUMN `descuento_aplicado_id` INT(11) NULL DEFAULT NULL COMMENT 'FK a la tabla descuentos' AFTER `estado`,
ADD INDEX `idx_descuento_aplicado` (`descuento_aplicado_id`);

---

1.2. Creación de Nuevas Tablas

Se crearán 3 nuevas tablas para gestionar los pagos, las cuotas y los códigos de descuento de manera normalizada y escalable.

Tabla `pagos`

Centralizará cada transacción individual, sea manual o automática.

CREATE TABLE `pagos` (
  `id` INT NOT NULL AUTO_INCREMENT,
  `inscripcion_id` INT NOT NULL COMMENT 'Vincula al alumno y curso en la tabla inscripciones_curso',
  `monto_pagado` DECIMAL(10,2) NOT NULL,
  `fecha_pago` DATETIME NOT NULL,
  `metodo_pago` ENUM('transferencia', 'deposito', 'mercadopago', 'webpay', 'manual_admin', 'otro') NOT NULL,
  `estado` ENUM('pendiente_verificacion', 'confirmado', 'rechazado', 'anulado') NOT NULL COMMENT 'Anulado es para el borrado lógico',
  `id_transaccion_externa` VARCHAR(255) NULL COMMENT 'Para ID de Webpay, MercadoPago, etc.',
  `url_comprobante_alumno` VARCHAR(255) NULL COMMENT 'Ruta al archivo subido por el alumno',
  `observaciones_admin` TEXT NULL COMMENT 'Notas del administrador sobre el pago',
  `registrado_por` INT NULL COMMENT 'ID del admin que registró el pago manual',
  PRIMARY KEY (`id`),
  INDEX `idx_inscripcion` (`inscripcion_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Tabla `cuotas`

Permitirá gestionar un plan de pagos en cuotas para una inscripción.

CREATE TABLE `cuotas` (
  `id` INT NOT NULL AUTO_INCREMENT,
  `inscripcion_id` INT NOT NULL,
  `numero_cuota` INT NOT NULL COMMENT 'Ej: 0 para el pie, 1 para la primera cuota, etc.',
  `monto_cuota` DECIMAL(10,2) NOT NULL,
  `fecha_vencimiento` DATE NOT NULL,
  `estado` ENUM('pendiente', 'pagada', 'atrasada', 'anulada') NOT NULL DEFAULT 'pendiente',
  `pago_id` INT NULL COMMENT 'Vincula al pago específico que cubrió esta cuota',
  PRIMARY KEY (`id`),
  INDEX `idx_inscripcion_cuota` (`inscripcion_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Tabla `descuentos`

Gestionará los bonos y becas que pueden ser aplicados a las inscripciones.

CREATE TABLE `descuentos` (
  `id` INT NOT NULL AUTO_INCREMENT,
  `codigo` VARCHAR(50) NOT NULL UNIQUE COMMENT 'El código que el usuario ingresa',
  `descripcion` TEXT NULL,
  `tipo` ENUM('porcentaje', 'monto_fijo') NOT NULL,
  `valor` DECIMAL(10,2) NOT NULL,
  `fecha_expiracion` DATE NULL,
  `usos_maximos` INT NULL COMMENT 'NULL para ilimitado',
  `usos_actuales` INT NOT NULL DEFAULT 0,
  `estado` ENUM('activo', 'inactivo', 'expirado') NOT NULL DEFAULT 'activo',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

El backend se compondrá de varios scripts especializados para manejar cada funcionalidad, asegurando un código limpio y mantenible.

2.1. Gestión de Pagos

• **Script `admin/registrar_pago.php`:** Recibirá datos del formulario modal del administrador. Su lógica debe:
  1. Validar los datos de entrada (ID de inscripción, monto, etc.).
  2. Iniciar una transacción en la base de datos.
  3. Insertar un nuevo registro en la tabla `pagos` con estado 'confirmado'.
  4. Actualizar el estado de la `cuota` correspondiente (si aplica) a 'pagada'.
  5. Recalcular el saldo en `inscripciones_curso`.
  6. Confirmar la transacción (commit).
  7. Disparar el envío de un correo de confirmación al alumno.
• **Script `alumno/subir_comprobante.php`:** Manejará la subida de archivos del alumno.
  1. Validar la sesión del alumno y el archivo (tamaño, tipo: JPG, PNG, PDF).
  2. Mover el archivo a una ruta segura (ej: `archivos/comprobantes/[id_inscripcion]/`).
  3. Insertar un nuevo registro en la tabla `pagos` con estado **'pendiente_verificacion'** y la ruta en `url_comprobante_alumno`.
  4. Notificar al administrador sobre la nueva verificación pendiente.

2.2. Automatización y Reportes

• **Script `cron/recordatorios_pago.php`:** Diseñado para ser ejecutado diariamente por un **Cron Job** en el servidor.
  1. Buscará todas las `cuotas` con `estado = 'pendiente'` cuya `fecha_vencimiento` haya pasado.
  2. Actualizará su estado a 'atrasada'.
  3. Enviará un correo de recordatorio al alumno correspondiente.
• **Script `reportes/generar_balance.php`:**
  1. Recibirá parámetros (rango de fechas, curso_id, estado_pago) vía GET.
  2. Construirá una consulta SQL dinámica y segura para filtrar los registros de la tabla `pagos`.
  3. Devolverá los datos en formato JSON para una tabla dinámica o generará un archivo CSV para descargar.

3.1. Panel de Administración

Vista de Verificación de Pagos:

Se creará una nueva página `admin/verificar_pagos.php` que mostrará una tabla con todos los pagos en estado 'pendiente_verificacion'. Cada fila tendrá el comprobante del alumno (imagen o link), datos de la inscripción y dos botones: "Confirmar" y "Rechazar".

Modal de Registro Manual de Pago:

Este modal se activará desde la vista de detalle de una inscripción y permitirá al administrador registrar un pago directo.

3.2. Portal del Alumno

Sección "Mi Estado de Cuenta":

Dentro del perfil del alumno, esta nueva sección mostrará su plan de pagos y el historial.

Formulario para Subir Comprobante:

Un formulario simple para que el alumno suba su comprobante de transferencia o depósito.

3.3. Integración de Pasarela de Pagos (MercadoPago / Webpay)

4.1. Orden de Desarrollo Sugerido

1. Fundación: Aplicar los cambios en la Base de Datos.
2. Backend Core: Desarrollar los scripts para registrar y verificar pagos (lógica del admin).
3. Frontend Admin: Construir las interfaces para que el administrador pueda usar el backend.
4. Backend Alumno: Desarrollar el script de subida de comprobantes.
5. Frontend Alumno: Construir las interfaces para que el alumno vea su estado y suba comprobantes.
6. Automatización: Implementar y probar el Cron Job para los recordatorios.
7. Módulo Final: Desarrollar la generación de reportes.

4.2. Plan de Pruebas Esencial

Se deben probar rigurosamente los siguientes casos de uso:

• Caso 1 (Admin): Registrar un pago manual para un alumno. Verificar que el estado de la cuota y el saldo de la inscripción se actualicen correctamente y que el alumno reciba la notificación.
• Caso 2 (Alumno): Subir un comprobante de pago. Verificar que se cree el registro de pago como 'pendiente_verificacion'. Luego, el administrador debe confirmarlo y verificar que todos los estados se actualicen y el alumno sea notificado.
• Caso 3 (Rechazo): El administrador rechaza un comprobante inválido. Verificar que el estado del pago cambie a 'rechazado' y el alumno reciba una notificación para que pueda corregirlo.
• Caso 4 (Borrado Lógico): El administrador anula un pago registrado por error. Verificar que el pago cambie su estado a 'anulado' y no afecte los reportes de ingresos, pero se mantenga en el historial.
• Caso 5 (Reportes): Generar un balance mensual y cruzar la suma total con los registros 'confirmados' en la tabla `pagos` para ese mes. Los datos deben coincidir exactamente.