Documentación del Sistema

Appearance

Services - Logica de Negocio ​

Estado: Planificado

Servicios que implementan la logica de negocio del Portal de Clientes. Los servicios nuevos se ubican en sus respectivos sub-modulos bajo Modules/Portal/. Los servicios reutilizados pertenecen a modulos existentes del ERP.

Principios ​

Los services son la capa de logica de negocio:

  • Implementan reglas de negocio y validaciones de dominio
  • Orquestan operaciones entre modelos y servicios existentes
  • Manejan transacciones de base de datos
  • NO manejan HTTP (responsabilidad del Controller)
  • NO acceden directamente a la base de datos (usan Models/Repositories)

Servicios del Portal ​

PortalAuthService ​

Ubicacion: Modules/Portal/Auth/Service/PortalAuthService.php

Responsabilidad: Registro, autenticacion y gestion de credenciales de clientes del portal (usuarios finales).

Algoritmo JWT: HS256 con PORTAL_JWT_SECRET.

Funcionalidad:

  • Registro de usuario (auto-registro validando contra ordcon existente)
  • Login con DNI/CUIT + password, generacion de JWT
  • Forgot-password (generar codigo, enviar email)
  • Reset-password (validar codigo, actualizar password_hash)
  • Refresh-token (renovar JWT)
  • Bloqueo por intentos fallidos

Nota: AuthService (sin prefijo) es un alias deprecado que apunta a PortalAuthService. No usar en codigo nuevo.

ErpAuthService ​

Ubicacion: Modules/Portal/Auth/Service/ErpAuthService.php

Responsabilidad: Autenticacion de operadores del ERP (Admin UI).

Algoritmo JWT: RS256 con par de claves publica/privada del ERP.

Esta clase fue separada de PortalAuthService durante el refactor G3 para garantizar separacion total de los espacios de autenticacion. Un JWT generado por ErpAuthService no puede ser validado por el middleware del portal, y viceversa.

PortalCtaCteService ​

Ubicacion: Modules/Portal/Account/Service/PortalCtaCteService.php

Responsabilidad: Consultar cuenta corriente del cliente autenticado.

Funcionalidad:

  • Obtener deudas pendientes con campos calculados (dias_vencido, esta_vencido)
  • Generar resumen de cuenta (saldo total, facturas vencidas, ultimo pago)
  • Reutiliza modelo CuentaCorriente existente del ERP

PortalPaymentService ​

Ubicacion: Modules/Portal/Payment/Service/PortalPaymentService.php

Responsabilidad: Orquestar pagos online con multiples gateways y actualizar el estado de pagos portal. Maximo ≤6 dependencias en constructor (post-refactor G3).

Funcionalidad:

  • Iniciar pagos con gateways (MercadoPago, PagoTIC) via comandos tipados (IniciarPagoCommand, etc.)
  • Procesar webhooks de confirmacion
  • Actualizacion automatica de portal_payments cuando el webhook confirma o rechaza el pago
  • Patron Adapter + Factory para multiples gateways
  • Idempotencia con external_id
  • PaymentStatus backed enum: estados desconocidos lanzan excepcion en el punto de conversion

PortalReciboService ​

Ubicacion: Modules/Portal/Payment/Service/PortalReciboService.php

Responsabilidad: Generacion de recibos PDF, consulta y validacion de configuracion de recibo. Extraido de PortalPaymentService durante el refactor G3 (ADR-028). Maximo ≤5 dependencias.

Funcionalidad:

  • Consultar si la configuracion de recibo esta completa (recibo_configured)
  • Generacion del recibo PDF via PortalReciboCreatorService o flujo equivalente
  • Validacion de las claves de configuracion portal.recibo.cuenta_bancaria y portal.recibo.caja_schema

Ver ADR-028 para la motivacion del split.

CuponPagoService y CuponValidacionService (reutilizados) ​

Documentacion: cupon-pago-service.md

Ubicacion: Servicios existentes del modulo CtaCte

Responsabilidad: Generacion y validacion de cupones de pago.

Estos servicios NO son nuevos. El portal los reutiliza tal cual, exponiendolos a traves de endpoints autenticados con JWT. No existe tabla portal_cupones.

Funcionalidad expuesta al portal:

  • Generar cupones con codigo ITF de 19 digitos
  • Listar cupones por cliente
  • Validar cupones por codigo de barras

Diagrama de Dependencias ​

mermaid
graph TD
    A[PortalAuthService] --> B[portal_users table]
    A --> C[ordcon table]

    ERPA[ErpAuthService] --> ERP[ERP users table]

    D[PortalCtaCteService] --> E[CuentaCorriente model]
    D --> F[Cliente model]

    G[PortalPaymentService] --> H[PaymentGatewayFactory]
    H --> I[MercadoPagoAdapter]
    H --> J[PagoTicAdapter]
    G --> K[portal_payments table]

    R[PortalReciboService] --> G
    R --> RC[PortalReciboCreatorService]

    M[PortalCuponesController] --> N[CuponPagoService]
    M --> O[CuponValidacionService]

    style A fill:#e1f5fe
    style ERPA fill:#e1f5fe
    style D fill:#e1f5fe
    style G fill:#e1f5fe
    style R fill:#e1f5fe
    style M fill:#fff3e0
    style N fill:#e8f5e9
    style O fill:#e8f5e9

Leyenda:

  • Azul: Servicios nuevos del portal
  • Naranja: Controller del portal (sin servicio propio)
  • Verde: Servicios reutilizados del ERP

Multi-Tenant ​

La resolucion de tenant se hace via JWT:

  1. El JWT contiene tenant_id y sucursal_id
  2. tenant_id resuelve la base de datos via ini.sistema
  3. sucursal_id resuelve el schema (sucXXXX, o public si ordcon a nivel empresa)
  4. El middleware configura la conexion ANTES de llegar a los servicios
  5. Los servicios trabajan contra la conexion ya configurada

Patrones de Diseno ​

  • DDD Sub-modules: Cada sub-modulo encapsula su servicio, controller y modelos
  • Dependency Injection: Inyeccion via container de Slim
  • Factory + Adapter: Seleccion de gateways de pago
  • Reutilizacion: Servicios existentes del ERP se usan directamente, sin wrappers innecesarios