Documentación técnica — Administración y Finanzas / Nómina

Sistema integrado con Control Escolar

Versión: 1.0

Tecnología: Laravel 11 · PHP 8.2+ · MySQL / MariaDB (o SQLite en desarrollo)

Este documento describe el subconjunto funcional y técnico desarrollado para Administración y Finanzas, en particular nómina, conceptos de cobro, planes de pago y promociones, información fiscal (CFDI) y gestión de usuarios del sistema. Complementa la documentación de *Control Escolar* del mismo proyecto.

1. Descripción general

El módulo de Administración y Finanzas cubre procesos administrativos y financieros alineados con el personal docente y la facturación:

• Nómina: cálculo de horas y percepciones por docente y ciclo, registro de incidencias/descuentos (incidencias_docente_nomina), exportación de recibos (individual y masivo en ZIP según implementación).

• Catálogos de nómina: conceptos de nómina (activos/inactivos, tipos de pago).

• Descuentos de nómina (vista operativa): consulta de incidencias guardadas en BD, con nombre de docente (join a docentes), filtros por periodo/ciclo/docente, exportación imprimir / PDF / Excel y eliminación de registros.

• Conceptos de venta: servicios y productos (conceptos_venta).

• Planes de pago y descuentos/promociones: catálogos para cobranza (planes_pago, descuentos_promociones).

• Información fiscal: registro de datos fiscales y archivos privados para emisión de facturas (datos_fiscales); certificado .cer, llave .key y contraseña opcionales en el alta.

• Registro de usuarios (Mi institución): alta de cuentas en users, listado, activación/desactivación (users.activo) y eliminación; el login rechaza usuarios desactivados cuando la columna existe.

La aplicación sigue siendo un monolito MVC con vistas Blade, consumo JSON/fetch desde el front de varias pantallas y persistencia en base de datos relacional.

2. Arquitectura

2.1 Estilo arquitectónico

• Monolito Laravel 11, patrón MVC.

• Rutas web en routes/web.php (grupo auth para lo protegido).

• Lógica en app/Http/Controllers.

• Modelos Eloquent en app/Models.

• Esquema en database/migrations; scripts SQL manuales opcionales en database/sql/.

• Vistas en resources/views (tema tipo Velzon / layouts.master).

2.2 Flujo de petición (alto nivel)

1. El cliente solicita una ruta HTTP.

2. Laravel aplica middleware web (sesión, CSRF en formularios, etc.).

3. El enrutador despacha al controlador.

4. El controlador valida, consulta modelos o DB::, responde Blade o JSON.

2.3 Seguridad relevante

• Rutas de este módulo bajo autenticación (middleware auth), salvo login/logout públicos.

• Rate limiting de login (configurable, ver config/security.php y variables de entorno).

• CSRF en peticiones que lo requieran; APIs internas JSON suelen enviar cabecera X-CSRF-TOKEN.

• Información fiscal: archivos y contraseña en disco privado (local); contraseña de llave con cifrado en modelo (encrypted).

• Usuarios: campo activo (si existe en BD) impide sesión tras Auth::attempt en AuthController.

3. Tecnologías utilizadas

4. Estructura de carpetas (fragmento relevante)

proyecto_nominas/
  app/
    Exports/                 # Exportaciones Excel (FromView)
    Http/Controllers/
      NominaController.php
      NominaMasivoController.php
      NominaDescuentosController.php
      ConceptoNominaController.php
      ConceptoVentaController.php
      PlanPagoController.php
      DescuentoPromocionController.php
      InformacionFiscalController.php
      ConfigUsuarioController.php
      AuthController.php
    Models/
      User.php, Docente.php, DatoFiscal.php, ConceptoNomina.php, ...
  resources/views/
    nominas/
    conceptos-venta/
    planes-de-pago/
    config/
    exports/                 # Plantillas para PDF/Excel de incidencias
  database/
    migrations/
    sql/                     # Scripts manuales (p. ej. users.activo, datos fiscales)
  routes/
    web.php
  docs/                      # Documentación del proyecto

5. Módulos funcionales

5.1 Nómina — cálculo y exportación

Controladores: NominaController, NominaMasivoController

• Pantalla de cálculo de nómina con datos de docentes, ciclos y horarios (consulta a docentes, ciclos, grupos/horarios o disponibilidad_docente según existencia de tablas).

• Exportación de recibo a Excel (endpoint POST).

• Incidencias de docente asociadas a nómina: alta y baja vía API JSON (incidencias_docente_nomina).

• Exportación masiva ZIP de Excel (ruta GET dedicada).

5.2 Conceptos de nómina

Controlador: ConceptoNominaController

• CRUD de conceptos (conceptos_nomina): listado JSON, alta, edición, baja.

5.3 Descuentos / incidencias de nómina (listado administrativo)

Controlador: NominaDescuentosController

• Vista Descuentos (nominas/descuentos): listado desde incidencias_docente_nomina con nombre de docente (join opcional a docentes).

• Filtros: año, mes, ciclo, docente.

• Exportación: imprimir (vista HTML), PDF (DomPDF), Excel (export FromView).

• Eliminación por fila (DELETE).

5.4 Conceptos de venta

Controlador: ConceptoVentaController

• Pantallas de servicios y productos; API de búsqueda y CRUD sobre conceptos_venta.

5.5 Planes de pago y descuentos/promociones

Controladores: PlanPagoController, DescuentoPromocionController

• CRUD de planes de pago (planes_pago).

• CRUD de descuentos y promociones (descuentos_promociones) bajo ruta planes-de-pago/descuentos.

5.6 Información fiscal

Controlador: InformacionFiscalController

Modelo: DatoFiscal — tabla datos_fiscales

• Registro de razón social, RFC, domicilio, régimen, diseño de factura, etc.

• Subida opcional de certificado .cer, llave .key, contraseña (cifrada) y escudo PNG.

• Listado, edición, activación por registro, eliminación (y limpieza de archivos en disco).

5.7 Registro de usuarios (Mi institución)

Controlador: ConfigUsuarioController

• Vista config/usuarios enlazada desde menú Configuración → Mi institución.

• Listado JSON de usuarios; alta con validación; PATCH activo/inactivo; DELETE usuario.

• Compatibilidad si aún no existe columna activo (listado/alta sin romper); script SQL de referencia: database/sql/users_activo_manual.sql.

5.8 Vistas placeholder (nómina)

• nominas/empleados, nominas/registro-empleados: rutas que devuelven vista estática; pueden evolucionar a CRUD real.

6. Endpoints principales (módulo Administración y Finanzas)

Todas las rutas siguientes están bajo **middleware auth**, salvo indicación contraria. Prefijo de aplicación según APP_URL.

6.1 Nómina

6.2 Conceptos de venta

6.3 Planes de pago y descuentos comerciales

6.4 Configuración — Información fiscal y usuarios

7. Flujos funcionales

7.1 Cálculo de nómina e incidencias

1. El usuario autenticado abre Cálculo de nómina.

2. El sistema carga docentes y ciclos desde BD (con fallback de configuración de ejemplo si aplica).

3. Se calculan horas según horarios vinculados a grupos (o disponibilidad docente).

4. El usuario registra incidencias (descuentos) que se persisten en incidencias_docente_nomina.

5. Puede exportar recibo en Excel y, en flujo masivo, generar ZIP.

7.2 Consulta y exportación de descuentos (incidencias)

1. Acceso a Nóminas → Descuentos.

2. Aplicación de filtros (año, mes, ciclo, docente).

3. Carga AJAX del listado; columnas alineadas a la tabla de incidencias + nombre docente.

4. Exportación con los mismos filtros en imprimir / PDF / Excel.

5. Eliminación puntual de un registro.

7.3 Información fiscal

1. Acceso a Configuración → Administración y Finanzas → Información fiscal (según menú).

2. Alta o edición de datos; archivos CFDI opcionales en alta.

3. Archivos almacenados en disco privado por ID de registro.

7.4 Registro de usuarios

1. Configuración → Mi institución → Registro de usuarios.

2. Alta de usuario (nombre, email, contraseña); validación de unicidad de email.

3. Activar/desactivar con switch; usuario desactivado no puede mantener sesión (si existe columna activo).

8. Base de datos — tablas dominio (Administración y Finanzas)

Laravel base: sessions, cache, etc., compartidas con el resto del sistema.

Relaciones destacadas

• incidencias_docente_nomina.docente_id → docentes.id

• incidencias_docente_nomina.ciclo_id → identificador de ciclo (tipo string en migración; coherente con ciclos.id)

9. Instalación y configuración

9.1 Requisitos

• PHP 8.2+

• Composer 2.x

• Node.js 18+ (recomendado) y npm

• MySQL / MariaDB (producción) o SQLite (pruebas)

9.2 Pasos típicos (desarrollo)

composer install
cp .env.example .env
php artisan key:generate
php artisan migrate
npm install
npm run build
php artisan serve

En producción, si APP_ENV=production, usar php artisan migrate --force o ejecutar SQL manual en el servidor (p. ej. columna users.activo).

9.3 Variables de entorno relevantes

10. Despliegue en servidor

1. Subir código y sincronizar dependencias (composer install --no-dev en producción si aplica).

2. Configurar .env (BD, APP_URL, APP_DEBUG=false).

3. Ejecutar migraciones o scripts SQL en el mismo servidor donde corre la app y la BD.

4. Limpiar/cachar configuración: php artisan config:cache (opcional).

Nota: Si el despliegue es solo por FTP/subida de archivos, los comandos Artisan deben ejecutarse en el hosting (SSH/panel) o sustituirse por SQL en phpMyAdmin cuando corresponda.

11. Observaciones técnicas

• Gran parte de las pantallas administrativas consumen JSON desde el mismo dominio (fetch + Accept: application/json).

• Las rutas de Administración y Finanzas conviven en routes/web.php con el módulo académico; el mantenimiento a largo plazo puede beneficiarse de archivos de rutas por módulo.

• Exportación Excel de nómina depende de que el paquete maatwebsite/excel esté instalado; el repositorio puede incluir el código de exportación aunque el paquete no figure aún en composer.json — conviene unificar dependencias antes del cierre del proyecto.

• incidencias_docente_nomina no define FK en migración; integridad referencial depende de la aplicación y de convenciones de IDs.

12. Riesgos y ambigüedades

13. Mejoras propuestas

• Modularizar rutas (routes/nominas.php, routes/finanzas.php e include en bootstrap/app.php o RouteServiceProvider según versión).

• Policies/Gates para restringir “registro de usuarios” e “información fiscal” solo a roles administrativos.

• Pruebas Feature para: login con usuario inactivo, CRUD concepto nómina, alta incidencia, export descuentos.

• Documentación OpenAPI para endpoints JSON internos.

• Foreign keys explícitas en incidencias_docente_nomina hacia docentes y ciclos si el motor y los tipos lo permiten.

14. Referencias de código clave

15. Glosario breve

16. Cómo generar un .docx a partir de este archivo

1. Abrir Microsoft Word.

2. Archivo → Abrir y elegir Documentacion_Tecnica_Administracion_Finanzas_Nomina.md (Word 2016+ suele importar Markdown) o copiar y pegar el contenido en un documento vacío.

3. Aplicar estilos de título (Título, Título 1, Título 2) a las secciones si Word no los detecta.

4. Guardar como → Documento de Word (.docx).

*Documento elaborado para alinearse con el estilo y profundidad de la “Documentación Técnica Control Escolar” del mismo proyecto, centrado en el alcance de Administración y Finanzas / Nómina.*