Documentación del Sistema

Appearance

Cupón de Pago ​

Esta sección documenta el sistema completo de cupones de pago de membresías, que permite generar cupones con código de barras ITF para facilitar el cobro de cuotas mensuales, incluyendo validación automática y cobro cross-schema entre sucursales.

Descripción General ​

El sistema de cupones de pago permite:

  • Generación de cupones PDF: Con código de barras ITF de 19 dígitos

  • Validación automática: Al escanear el código de barras se valida contra facturación, con soporte de modo prueba

  • Cobro simplificado: Precarga automática del recibo con datos validados

  • Cobro cross-schema: Pago de deudas en sucursal diferente a la emisora

  • Algoritmo de verificación: Módulo 10 con ponderación 3-1 para integridad de datos

Componentes Documentados ​

Generación de Cupones ​

  • Generación de Cupón PDF: Proceso completo de generación
    • Generación de código de barras ITF 19 dígitos
    • Formato: [SUCU(4)][CLIENTE(8)][PERIODO(6)][DV(1)]
    • Algoritmo Módulo 10 con ponderación 3-1 para dígito verificador
    • Template HTML con Bootstrap
    • Código de barras en SVG
    • Monto pendiente actualizado
    • Instrucciones de pago
    • Generación PDF vía PdfGeneratorService (puerto 9999)
    • Generación individual y masiva

Validación de Cupones ​

  • Validación de Cupón (Escaneo): Validación automática al escanear
    • Decodificación de código de barras (sucursal, cliente, período)
    • Verificación de dígito verificador (Módulo 10)
    • Búsqueda de factura en base de datos
    • Validación de estado de factura (pendiente/cancelada)
    • Detección automática de cobro cross-schema
    • Soporte de modo prueba: consulta BD _p cuando modo_prueba = true en la facturación
    • Auto-switch de modo en frontend al detectar cupón de prueba
    • Retorno de datos para precarga de recibo
    • Entrada manual de código como fallback

Cobro Cross-Schema ​

  • Cobro Multi-Sucursal: Cobro en sucursal diferente
    • Transacción atómica en dos schemas (origen + destino)
    • Cancelación de factura en schema origen
    • Registro de movimiento de caja en schema destino
    • Validación de permisos especiales
    • Auditoría completa de operación
    • Rollback automático en caso de error
    • Referencias bidireccionales entre schemas

Flujo Completo de Cupón de Pago ​

mermaid
graph TD
    A[Facturación por Lotes] --> B[Genera facturas de membresía]
    B --> C[Miembro solicita cupón]
    C --> D[Generación de Cupón PDF]
    D --> E[Cupón con código de barras ITF]
    E --> F[Miembro presenta cupón en caja]
    F --> G[Cajero escanea código]
    G --> H{Validación}
    H -->|OK Local| I[Precarga recibo]
    H -->|Cross-Schema| J[Detecta sucursal diferente]
    H -->|Error| K[Muestra error al cajero]
    J --> L{Tiene permiso?}
    L -->|Sí| M[Cobro cross-schema]
    L -->|No| N[Rechaza cobro]
    I --> O[Cajero confirma y cobra]
    M --> P[Transacción distribuida]
    P --> Q[Cancelar factura origen]
    Q --> R[Registrar caja destino]
    R --> S{Éxito?}
    S -->|Sí| T[Commit ambos schemas]
    S -->|No| U[Rollback automático]
    O --> V[Factura cancelada]
    T --> V

Estructura del Código de Barras ITF ​

Formato (19 dígitos) ​

[SUCU(4)][CLIENTE(8)][PERIODO(6)][DV(1)]

Componentes ​

ComponentePosiciónLongitudDescripciónEjemplo
SUCU1-44Código de sucursal (4 dígitos, pad left con 0)0001
CLIENTE5-128ID del cliente (8 dígitos, pad left con 0)00000123
PERIODO13-186Período YYYYMM202501
DV191Dígito verificador (Módulo 10)7

Ejemplo Completo ​

0001000001232025017
  • Sucursal: 0001
  • Cliente: 00000123
  • Período: 202501 (Enero 2025)
  • Dígito verificador: 7

Algoritmo de Dígito Verificador (Módulo 10) ​

Paso 1: Ponderación 3-1 ​

Multiplicar cada dígito alternadamente por 3 y 1 (de derecha a izquierda):

Código: 0 0 0 1 0 0 0 0 0 1 2 3 2 0 2 5 0 1
Pond.:  3 1 3 1 3 1 3 1 3 1 3 1 3 1 3 1 3 1
Prod.:  0 0 0 1 0 0 0 0 0 1 6 3 6 0 6 5 0 1

Paso 2: Suma de Productos ​

Suma = 0+0+0+1+0+0+0+0+0+1+6+3+6+0+6+5+0+1 = 29

Paso 3: Módulo 10 ​

Resto = 29 % 10 = 9

Paso 4: Dígito Verificador ​

DV = (10 - Resto) % 10 = (10 - 9) % 10 = 1

Si el resto es 0, el DV es 0.

Reglas de Negocio Principales ​

Generación de Cupones ​

RN-001: Formato Estándar ITF ​

El código de barras debe cumplir con el estándar ITF (Interleaved 2 of 5):

  • Longitud fija: 19 dígitos
  • Codificación numérica únicamente
  • Dígito verificador obligatorio
  • Pad left con ceros para completar longitud

RN-002: Monto Actualizado ​

El cupón muestra el monto pendiente actualizado al momento de la generación:

  • Se consulta el saldo actual de la factura
  • No se "congela" el monto en el cupón
  • Útil para pagos parciales previos

RN-003: Un Cupón por Período ​

Un cliente puede tener solo un cupón válido por período:

  • Si se solicita cupón para período ya facturado: Se genera
  • Si se solicita cupón para período no facturado: Error
  • No se valida unicidad del cupón (pueden generarse varios del mismo período)

RN-004: Generación Masiva ​

El sistema permite generar cupones para múltiples clientes:

  • Rango de IDs de clientes
  • Mismo período para todos
  • Generación en lote con reporte de resultados

Validación de Cupones ​

RN-001: Validación de Formato ​

El código escaneado debe cumplir:

  • Longitud exacta: 19 dígitos
  • Solo caracteres numéricos
  • Dígito verificador correcto (Módulo 10)

RN-002: Verificación de Dígito Verificador ​

Se recalcula el DV usando Módulo 10 con ponderación 3-1:

  • Si coincide: Código válido
  • Si no coincide: Error de lectura o manipulación

RN-003: Factura Existente ​

Debe existir una factura de membresía para:

  • Cliente indicado en el código
  • Período indicado en el código
  • En el schema correspondiente a la sucursal

RN-004: Factura Pendiente ​

La factura debe estar pendiente de pago:

  • Si ya fue cancelada: Error con fecha de cancelación
  • Si tiene saldo parcial: Se permite cobro del saldo pendiente

RN-005: Detección Cross-Schema Automática ​

El sistema detecta automáticamente si la sucursal del cupón es diferente a la sucursal actual:

  • Compara código de sucursal del cupón vs sucursal actual (X-Schema header)
  • Si son diferentes: Dispara flujo de cobro cross-schema
  • Si son iguales: Flujo de cobro local normal

Cobro Cross-Schema ​

RN-001: Permiso Especial Requerido ​

El cobro cross-schema requiere permiso específico:

  • Permiso: COBRO_CROSS_SCHEMA o similar
  • Validación antes de ejecutar la transacción
  • Rechazo si el usuario no tiene el permiso

RN-002: Transacción Atómica Distribuida ​

El cobro cross-schema es una transacción atómica en dos schemas:

  • Schema Origen (sucursal que facturó): Cancelar factura
  • Schema Destino (sucursal que cobra): Registrar movimiento de caja
  • Commit solo si ambas operaciones son exitosas
  • Rollback automático si cualquiera falla

RN-003: Referencias Bidireccionales ​

Se registran referencias entre schemas:

  • Factura origen: Referencia al movimiento de caja destino (schema, ID)
  • Movimiento destino: Referencia a la factura origen (schema, ID)
  • Permite auditoría completa y trazabilidad

RN-004: Auditoría Completa ​

Se registra en auditoría:

  • Usuario que ejecutó el cobro
  • Sucursal origen y destino
  • IDs de factura y movimiento de caja
  • Timestamp de la operación
  • Resultado (éxito/error)

RN-005: Rollback Automático ​

Si cualquier operación falla:

  • Se hace rollback de todas las operaciones
  • No quedan datos inconsistentes
  • Se informa el error al usuario con detalle

Casos de Uso Comunes ​

1. Generar Cupón Individual ​

  1. Desde vista del cliente o desde módulo de cupones
  2. Seleccionar cliente
  3. Seleccionar período (mes/año)
  4. Generar
  5. Sistema busca factura del período
  6. Sistema genera código de barras ITF
  7. Sistema genera PDF con cupón
  8. Descargar PDF

2. Cobrar con Cupón (Local - Mismo Schema) ​

  1. Cliente presenta cupón en caja
  2. Cajero escanea código de barras
  3. Sistema valida formato y DV
  4. Sistema busca factura en schema actual
  5. Factura encontrada y pendiente
  6. Sistema precarga recibo con datos validados
  7. Cajero confirma monto y forma de pago
  8. Sistema registra cobro y cancela factura

3. Cobrar con Cupón (Cross-Schema) ​

  1. Cliente presenta cupón de sucursal A en sucursal B
  2. Cajero de sucursal B escanea código
  3. Sistema detecta que el código es de sucursal A (diferente)
  4. Sistema valida permiso COBRO_CROSS_SCHEMA del cajero
  5. Si tiene permiso: Sistema precarga recibo indicando "COBRO CROSS-SCHEMA"
  6. Cajero confirma cobro
  7. Sistema ejecuta transacción distribuida:
    • Cancelar factura en schema de sucursal A
    • Registrar movimiento de caja en schema de sucursal B
  8. Commit atómico de ambas operaciones
  9. Recibo generado con referencias a ambos schemas

4. Error en Validación de Cupón ​

  1. Cajero escanea cupón
  2. Sistema detecta error:
    • Código mal formado (longitud incorrecta)
    • DV inválido (error de lectura)
    • Factura no encontrada
    • Factura ya cancelada
  3. Sistema muestra mensaje de error descriptivo
  4. Cajero puede:
    • Re-escanear cupón
    • Ingresar código manualmente
    • Buscar factura manualmente

Vistas Frontend ​

  • /movimientos/generar-cupon - Generación de cupones de pago
  • Integración con módulo de cobros (CtaCte) para validación y cobro

Modales ​

(Los modales de validación y cobro están en el módulo de CtaCte)

Endpoints API ​

Generación ​

  • Reporte 0004 en informes/reports/mod-ctacte/ - Genera PDF de cupón

Validación ​

  • POST /ctacte/cupones/validar - Valida código de barras escaneado

Cobro Cross-Schema ​

  • Transacción distribuida (no endpoint público específico)
  • Se ejecuta como parte del proceso de cobro del módulo CtaCte

Archivos del Sistema de Informes ​

Generación de Cupón ​

  • informes/reports/mod-ctacte/cupon-pago-datos.php - Extrae datos de la factura
  • informes/reports/mod-ctacte/cupon-pago-render.php - Template HTML del cupón
  • informes/reports/mod-ctacte/util/BarcodeGenerator.php - Genera código de barras SVG

Dependencias ​

Funcionalidades Relacionadas ​

  • Facturación por Lotes: Genera las facturas para las cuales se solicitan cupones
  • Gestión de Miembros: Los clientes del cupón son miembros
  • Integración con CtaCte: Validación y cobro de cupones

Módulos Externos ​

  • CtaCte: Módulo de cobros que consume la validación de cupones
  • Informes: Sistema de generación de PDFs (puerto 9999)
  • Ventas: Facturas de membresía que se cobran con cupón

Servicios Externos ​

  • PdfGeneratorService - Servicio externo en puerto 9999 para generar PDFs

Consideraciones de Seguridad ​

Validación de Integridad ​

  • El dígito verificador previene errores de lectura y manipulación
  • Algoritmo Módulo 10 detecta hasta el 95% de errores de transcripción

Permisos Cross-Schema ​

  • El cobro cross-schema requiere permiso especial
  • Previene cobros no autorizados entre sucursales
  • Se audita cada operación cross-schema

Transacción Atómica ​

  • El rollback automático previene inconsistencias
  • No es posible cancelar una factura sin registrar el cobro (o viceversa)
  • Garantiza integridad de datos entre schemas

Consideraciones Multi-Tenant ​

Aislamiento de Schemas ​

  • Cada sucursal tiene su propio schema
  • Los cupones contienen el código de la sucursal emisora
  • La validación busca la factura en el schema correspondiente

Cobro Cross-Schema ​

  • Permite cobrar en sucursal diferente a la emisora
  • Mantiene aislamiento de schemas con transacción distribuida
  • Referencias bidireccionales para auditoría completa

Documentación de Referencia ​

Existe documentación integral previa que cubre el proceso completo:

Estadísticas ​

  • 3 documentos de requisitos de negocio (componentes)
  • 1 documento integral de referencia
  • 31 criterios de aceptación (todos implementados)
  • 14 reglas de negocio
  • 9 casos de uso detallados
  • 2 endpoints API principales
  • 3 archivos en sistema de informes

Estado ​

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

Última actualización: 2026-03-06