Documentación del Sistema

Appearance

Arquitectura del Portal de Clientes ​

Documentacion de las decisiones arquitectonicas, patrones y estructura del Portal de Clientes.

Estado: Planificado

Contenido ​

Vision General ​

Arquitectura de alto nivel del sistema completo.

  • Modelo de deployment: Docker por tenant (frontend), backend compartido
  • Modulo DDD Modules/Portal/ con sub-modulos Auth, Account, Payment, Cupon
  • Autenticacion JWT con password (bcrypt)
  • Flujo de request con resolucion tenant_id -> DB, sucursal_id -> schema

Multi-Tenancy ​

Estrategia multi-tenant implementada.

  • Docker instance por tenant con .env config
  • Sin resolucion por dominio ni tabla tenant_domains
  • Backend resuelve tenant_id -> DB name via ini.sistema
  • Backend resuelve sucursal_id -> schema
  • Tabla portal_users al mismo nivel de schema que ordcon

ADR - Registro de Decisiones ​

Registro completo de decisiones arquitectonicas.

  • ADR-001: Repositorio independiente portal-usuarios
  • ADR-002: Autenticacion JWT con password y auto-registro
  • ADR-003: Modulo DDD Modules/Portal/
  • ADR-004: Docker por tenant (frontend), backend compartido
  • ADR-005: Tablas portal_users y portal_payments al nivel de ordcon
  • ADR-006: Alcance completo sin fases MVP
  • ADR-007: Cupones reutilizan servicios existentes
  • ADR-008: Branding via .env Docker + data_config del tenant

Diagrama de Arquitectura ​

mermaid
graph TB
    subgraph "Deploy por Tenant"
        T1[Docker Tenant 1<br/>Frontend React<br/>.env config]
        T2[Docker Tenant 2<br/>Frontend React<br/>.env config]
        TN[Docker Tenant N<br/>Frontend React<br/>.env config]
    end

    subgraph "Backend Compartido - bautista-backend"
        MW[Middleware JWT]
        subgraph "Modules/Portal/"
            AUTH[Auth/]
            ACC[Account/]
            PAY[Payment/]
            CUP[Cupon/]
        end
        SVC[Servicios existentes<br/>CuponPagoService<br/>ReciboRelationsService]
    end

    subgraph "PostgreSQL"
        INI[(ini.sistema)]
        DB1[(DB Tenant 1)]
        DB2[(DB Tenant 2)]
        DBN[(DB Tenant N)]
    end

    T1 -->|JWT + tenant_id| MW
    T2 -->|JWT + tenant_id| MW
    TN -->|JWT + tenant_id| MW
    MW --> AUTH
    MW --> ACC
    MW --> PAY
    MW --> CUP
    AUTH --> SVC
    PAY --> SVC
    CUP --> SVC
    MW -->|resolve| INI
    SVC --> DB1
    SVC --> DB2
    SVC --> DBN

Principios Arquitectonicos ​

1. Separacion Frontend/Backend por Deployment ​

  • Frontend: instancia Docker independiente por tenant, configurada via .env
  • Backend: unico, compartido entre todos los tenants
  • La URL del frontend no importa para la logica de negocio

2. Modulo DDD Moderno ​

  • NO se usa la arquitectura legacy de 5 capas (App\Controller\*)
  • Se usa Modules/Portal/ con sub-modulos por bounded context
  • Reutiliza servicios existentes del ERP donde corresponde

3. JWT sin Datos Sensibles ​

  • El JWT contiene IDs numericos: portal_user_id, tenant_id, sucursal_id
  • NO contiene nombres de bases de datos ni schemas
  • El backend resuelve IDs a conexiones via ini.sistema

4. Reutilizacion vs Componentes Nuevos ​

Reutilizar:

  • Servicios: CuponPagoService, CuponValidacionService, ReciboRelationsService
  • Modelos existentes: ordcon (clientes), ordcta (cuenta corriente)
  • Infraestructura: ConnectionManager, multi-tenant existente

Crear nuevo:

  • Modulo DDD: Modules/Portal/ completo
  • Tablas: portal_users, portal_payments
  • Middleware: validacion JWT para portal
  • Frontend: repo portal-usuarios completo

5. Seguridad ​

  • Autenticacion por password con bcrypt hash
  • JWT validado en backend (mismo mecanismo que Admin UI)
  • Auto-registro requiere match con ordcon existente
  • Reset de password via codigo por email (seguridad moderada -- portal es mayormente lectura)

Documentos Relacionados ​