Portal de Clientes - Documentacion

Portal web para que clientes de Sistema Bautista consulten su cuenta corriente y realicen pagos online. El sistema tiene un frontend independiente desplegado como instancia Docker por tenant, y comparte el backend con el ERP Bautista a traves del modulo DDD Modules/Portal/.

Estado: Planificado

Vision General

• Frontend: Repo independiente portal-usuarios (submodulo), instancia Docker por tenant
• Backend: Modulo DDD Modules/Portal/ en bautista-backend (compartido)
• Autenticacion: JWT con portal_user_id, tenant_id, sucursal_id
• Multi-tenancy: Docker .env por tenant, backend resuelve tenant_id -> DB y sucursal_id -> schema via ini.sistema
• Alcance: Feature completa sin fases MVP

---

Navegacion de la Documentacion

Arquitectura

Decisiones arquitectonicas, patrones y diagramas del sistema.

• Vision General -- Arquitectura de alto nivel, flujos de request
• Multi-Tenancy -- Docker por tenant, resolucion via ini.sistema
• ADR -- Registro de decisiones arquitectonicas

Backend (Compartido)

Modulo DDD Modules/Portal/ con sub-modulos Auth, Account, Payment, Cupon.

• API Endpoints
  • Autenticacion
  • Cuenta Corriente
  • Pagos
  • Cupones
• Servicios
• Middleware
• Base de Datos

Portal Frontend (Separado)

Frontend en repo portal-usuarios, desplegado como instancia Docker por tenant.

• Arquitectura

Integraciones

Integraciones con gateways de pago.

• Payment Gateways

Deployment

Infraestructura Docker por tenant.

• Infraestructura

Desarrollo

Guias para desarrolladores.

• Testing

---

Arquitectura de Alto Nivel

graph TB
    subgraph "Tenant A - Docker"
        FA[Frontend Portal<br/>React PWA<br/>.env: TENANT_ID=1, SUCURSAL_ID=1]
    end

    subgraph "Tenant B - Docker"
        FB[Frontend Portal<br/>React PWA<br/>.env: TENANT_ID=2, SUCURSAL_ID=3]
    end

    subgraph "Backend Compartido"
        API[bautista-backend<br/>Modules/Portal/<br/>Auth - Account - Payment - Cupon]
    end

    subgraph "PostgreSQL"
        INI[(ini.sistema<br/>tenant config)]
        DBA[(DB Tenant A<br/>schema sucXXXX)]
        DBB[(DB Tenant B<br/>schema sucXXXX)]
    end

    FA -->|REST API + JWT| API
    FB -->|REST API + JWT| API
    API --> INI
    API --> DBA
    API --> DBB

---

Conceptos Clave

Frontend por Tenant (Docker)

• Cada tenant tiene su propia instancia Docker del frontend
• Configuracion via .env: BACKEND_URL, TENANT_ID, SUCURSAL_ID, branding (APP_NAME, LOGO_URL, PRIMARY_COLOR)
• NO hay resolucion por dominio: la URL no importa, la conexion se configura en deploy
• Repo independiente: portal-usuarios (submodulo git)

Backend Compartido (DDD Module)

• Modulo DDD moderno: Modules/Portal/
• Sub-modulos: Auth/, Account/, Payment/, Cupon/
• Reutiliza servicios existentes: CuponPagoService, CuponValidacionService, ReciboRelationsService
• NO usa legacy App\Controller\Portal\

Autenticacion JWT con Password

• Tabla portal_users con hash bcrypt
• Auto-registro: DNI/CUIT debe coincidir con ordcon existente; si no hay match, falla
• JWT payload: { portal_user_id, tenant_id, sucursal_id } -- IDs numericos, sin nombres de DB/schema
• Reset de password via codigo por email

Multi-tenancy sin Dominios

• NO hay tabla tenant_domains
• NO hay resolucion DNS por dominio
• Frontend envia tenant_id + sucursal_id desde su .env
• Backend resuelve: tenant_id -> DB (via ini.sistema), sucursal_id -> schema

Pagos Automaticos

• Cliente selecciona facturas -> backend crea pago en gateway
• Gateway webhook notifica al backend
• Backend auto-crea recibo en ctacte usando servicios existentes

---

Tablas Nuevas

Tabla	Ubicacion	Proposito
portal_users	Mismo schema level que ordcon	Credenciales de acceso al portal
portal_payments	Mismo schema level que ordcon	Registro de pagos online

NO se crean tablas tenant_domains ni portal_cupones (cupones reutilizan servicios existentes).