Documentación del Sistema

Appearance

Módulo de Membresías ​

El módulo de membresías es un sistema completo de gestión de socios para clubes, gimnasios y organizaciones deportivas/sociales, integrado con Sistema Bautista ERP.

Descripción General ​

Sistema integral que permite:

  • Gestión completa de miembros: ABM con datos básicos, comerciales y de membresía
  • Grupos familiares: Consolidación de facturación y beneficios compartidos
  • Catálogos base: Categorías, disciplinas y tipos de relación
  • Facturación masiva: Generación de comprobantes electrónicos por lotes con ARCA
  • Cupones de pago: Códigos de barras ITF para cobro simplificado
  • Cobro cross-schema: Pago de deudas en sucursales diferentes
  • Soporte técnico: Enriquecimiento, eventos, integraciones, caché, validaciones

Funcionalidades Documentadas ​

Gestión de Miembros ​

ABM completo de miembros con gestión de disciplinas y productos.

Funcionalidades clave:

  • Listado con paginación server-side y filtros combinados
  • Crear/editar con validación Zod
  • Dar de baja con motivo y reactivación
  • Asignación masiva de productos a múltiples miembros
  • Eventos de dominio para automatización

Grupos Familiares ​

Sistema de agrupación de miembros relacionados para facturación consolidada.

Funcionalidades clave:

  • Crear grupo designando miembro principal (titular)
  • Agregar miembros con tipo de relación
  • Cambiar titular del grupo
  • Resumen consolidado de categoría, disciplinas y productos
  • Facturación única por grupo familiar

Catálogos Base ​

Tablas maestras de configuración del módulo.

Funcionalidades clave:

  • Categoría por defecto única
  • Productos asociados a categorías y disciplinas
  • Asignación masiva de categorías
  • Requerimiento de ficha médica por disciplina
  • Validación de uso al eliminar

Facturación ​

Facturación masiva de membresías con integración ARCA.

Funcionalidades clave:

  • Facturación por rango de IDs y período
  • Agrupación automática por grupos familiares
  • Cálculo de deuda con DDD (Domain-Driven Design)
  • Determinación de tipo de comprobante (A/B/C) por condición IVA
  • Integración con ARCA para CAE
  • Registro automático en módulo de Ventas
  • Re-facturación con generación de NC
  • Estadísticas detalladas de resultados

Cupón de Pago ​

Sistema completo de cupones con código de barras para cobro simplificado.

Funcionalidades clave:

  • Código de barras ITF 19 dígitos con dígito verificador Módulo 10
  • Validación automática al escanear
  • Detección de cobro cross-schema
  • Transacción atómica distribuida entre schemas
  • Precarga automática de recibo
  • Referencias bidireccionales para auditoría

Documentación de referencia:

Soporte Técnico ​

Funcionalidades técnicas que soportan el módulo.

Funcionalidades clave:

  • Sistema de scopes (min/max) para optimizar consultas
  • Batch loading para evitar N+1 queries
  • Eventos de dominio (MiembroBajaEvent, MiembroReactivacionEvent, FacturacionLoteProcesadaEvent)
  • Caché tenant-aware con invalidación automática
  • Validaciones transversales (categoría defecto única, principal único, etc.)
  • Generación automática de especificación OpenAPI 3.0.3

Arquitectura del Módulo ​

Backend (PHP 8.2+ / Slim 4) ​

5 Capas DDD:

  1. Routes: Definición de endpoints + validators middleware
  2. Controllers: HTTP request/response handling
  3. Services: Business logic orchestration + transactions
  4. Domain: Pure business logic (DeudaMembresiaCalculator, etc.)
  5. Models: Data access + DTO mapping

Frontend (React 19 + TypeScript 5.8) ​

Tecnologías:

  • React Hook Form + Zod validation
  • React Query para estado remoto
  • Axios con interceptores X-Schema
  • Bootstrap (AdminLTE legacy)
  • Vitest para testing

Informes (Reportes PDF/Excel) ​

Sistema de cupones:

  • Generación de cupones PDF con código de barras ITF
  • PdfGeneratorService (puerto 9999)

Estadísticas del Módulo ​

Documentación ​

  • 18 documentos de requisitos de negocio
  • 6 índices de carpetas
  • 175+ criterios de aceptación (todos implementados)
  • 68+ reglas de negocio
  • 40+ casos de uso detallados

Código ​

  • 180+ archivos backend (PHP)
  • 91 archivos frontend (TypeScript/React)
  • 3 archivos informes (cupón de pago)
  • 92 tests PHPUnit

API ​

  • 40+ endpoints REST
  • 11 rutas frontend
  • 32 modales de interfaz

Reglas de Negocio Clave ​

  1. Categoría defecto única: Solo una categoría puede ser "por defecto"
  2. Principal único: Solo un miembro "Principal" por grupo familiar
  3. Condición de venta fija: Facturación siempre a Cuenta Corriente 30 días
  4. Agrupación familiar: Un grupo genera una única factura al titular
  5. Baja con grupo: Si es titular, requiere designar nuevo titular
  6. Deuda consolidada: Categoría + productos + disciplinas de todo el grupo
  7. Tipo de comprobante automático: Según condición IVA del cliente
  8. Cobro cross-schema: Requiere permiso especial y transacción atómica

Vistas Frontend Principales ​

  • /bases/miembros - Listado de miembros
  • /bases/miembros/nuevo - Crear miembro
  • /bases/miembros/:id/editar - Editar miembro
  • /bases/categorias - CRUD de categorías
  • /bases/disciplinas - CRUD de disciplinas
  • /bases/tipos - CRUD de tipos de relación
  • /movimientos/facturacion-lote - Facturación masiva
  • /movimientos/generar-cupon - Generar cupón de pago
  • /utilidades/asignacion-productos - Asignación masiva de productos
  • /utilidades/asignacion-categorias - Asignación masiva de categorías

Dependencias con Otros Módulos ​

Ventas ​

  • Productos asociados a categorías y disciplinas
  • Registro de facturas generadas
  • Enriquecimiento de productos con extensión de membresía

CtaCte (Cuenta Corriente) ​

  • Validación de cupones de pago
  • Cobro de facturas
  • Saldo en cuenta corriente

ARCA (Servicio Externo) ​

  • Obtención de CAE
  • Validación de comprobantes
  • Registro fiscal

Informes ​

  • Generación de cupones PDF
  • PdfGeneratorService (puerto 9999)

Multi-Tenancy ​

  • Schema-based: Cada sucursal tiene su propio schema PostgreSQL
  • X-Schema header: Propagación automática del schema en requests
  • Caché aislada: Cada tenant tiene su propia caché
  • Cobro cross-schema: Transacción atómica entre schemas diferentes
  • Auditoría completa: Operaciones cross-schema se registran en ambos schemas

Estado de Implementación ​

✅ Implementado - Todas las funcionalidades documentadas están en producción

Versión: v3.10.0 Última actualización: 2026-01-27

Estructura organizativa: Documentación agrupada por funcionalidad en 6 carpetas temáticas con índices descriptivos.