CuponPagoService y CuponValidacionService (Reutilizados)

Estado: Planificado

Responsabilidad

El portal NO implementa servicios nuevos de cupones. Reutiliza los servicios existentes del modulo CtaCte:

• CuponPagoService: Genera cupones con codigo de barras ITF de 19 digitos
• CuponValidacionService: Valida cupones por codigo de barras

Estos servicios ya existen y funcionan en el ERP. El portal simplemente los expone a traves de endpoints autenticados con JWT.

Arquitectura

Portal                              ERP (CtaCte)
                                    
PortalCuponesController             
  (Modules/Portal/Cupon/)           
        |                           
        +-- JWT auth + resolver     
        |   portal_user -> ordcon   
        |                           
        +-- CuponPagoService --------> Servicio existente
        |                              (genera cupones, lista por cliente)
        |                           
        +-- CuponValidacionService --> Servicio existente
                                       (valida por codigo de barras)

NO existe tabla portal_cupones. Los cupones se almacenan en la infraestructura existente del modulo CtaCte.

Diferencia entre Uso Interno y Portal

Aspecto	Uso interno (ERP)	Uso via portal
Quien llama	Operador desde la caja/sistema	Cliente desde el portal
Autenticacion	Session PHP del operador	JWT del portal
Identificacion	cliente_id directo	portal_user_id del JWT -> ordcon_id -> cliente_id
Servicios	CuponPagoService, CuponValidacionService	Los mismos, sin modificaciones
Permisos	Segun rol del operador	Solo cupones propios del cliente
Tabla de cupones	La que usa CtaCte	La misma

Flujo en el Portal

Generar Cupon

sequenceDiagram
    participant F as Frontend
    participant C as PortalCuponesController
    participant MW as JWT Middleware
    participant S as CuponPagoService
    participant DB as PostgreSQL

    F->>MW: POST /portal/cupones/generar + JWT
    MW->>MW: Decodificar JWT
    MW->>C: Request con portal_user_id
    C->>DB: Resolver cliente_id desde portal_users.ordcon_id
    C->>S: generarCupon(clienteId, facturas, total, diasVencimiento)
    S->>DB: INSERT cupon (logica existente)
    S-->>C: Datos del cupon
    C-->>F: 200 + cupon

Listar Cupones del Cliente

sequenceDiagram
    participant F as Frontend
    participant C as PortalCuponesController
    participant S as CuponPagoService
    participant DB as PostgreSQL

    F->>C: GET /portal/cupones/mis-cupones + JWT
    C->>DB: Resolver cliente_id desde portal_user_id
    C->>S: getCuponesByCliente(clienteId, estado, limit, offset)
    S->>DB: SELECT cupones (logica existente)
    S-->>C: Lista de cupones
    C-->>F: 200 + cupones

Consultar Cupon por Codigo

sequenceDiagram
    participant F as Frontend
    participant C as PortalCuponesController
    participant V as CuponValidacionService
    participant DB as PostgreSQL

    F->>C: GET /portal/cupones/{codigo} + JWT
    C->>DB: Resolver cliente_id desde portal_user_id
    C->>V: validarCupon(codigoBarras)
    V->>DB: SELECT cupon por codigo (logica existente)
    V-->>C: Datos del cupon o null
    C->>C: Verificar cupon.cliente_id == cliente_id autenticado
    alt No pertenece al cliente
        C-->>F: 403 Forbidden
    end
    C-->>F: 200 + cupon

Metodos Reutilizados

CuponPagoService::generarCupon()

Genera un cupon con codigo ITF de 19 digitos.

Formato del codigo:

SUCU(4) + CLIENTE(6) + TIMESTAMP(8) + DV(1) = 19 digitos
0001   + 056789    + 20260127    + 4     = 0001056789202601274

• SUCU: Codigo de sucursal (4 digitos)
• CLIENTE: ID del cliente (6 digitos, zero-padded)
• TIMESTAMP: Fecha actual AAAAMMDD (8 digitos)
• DV: Digito verificador (Modulo 10, ponderacion 3-1)

CuponPagoService::getCuponesByCliente()

Lista cupones de un cliente con filtros opcionales de estado y paginacion.

CuponValidacionService::validarCupon()

Valida un cupon por codigo de barras. Verifica formato, digito verificador, existencia y vigencia.

Integracion con Caja

Los cupones generados desde el portal son identicos a los generados desde el ERP. El sistema de caja puede:

1. Validar el cupon usando CuponValidacionService::validarCupon()
2. Procesar el pago si el cupon es valido
3. Marcar el cupon como "used" y vincular el recibo generado

No hay diferencia funcional entre un cupon generado desde el portal y uno generado desde el ERP.

Casos de Prueba

Los tests de CuponPagoService y CuponValidacionService ya existen en el modulo CtaCte. Los tests especificos del portal deben cubrir:

1. Generacion via portal: Controller resuelve portal_user_id -> cliente_id -> delega a CuponPagoService
2. Listado filtrado: Controller filtra solo cupones del cliente autenticado
3. Acceso denegado: Intentar ver cupon de otro cliente -> 403 Forbidden
4. Codigo invalido: Codigo de barras inexistente -> 404 Not Found