Desarrollo - Portal de Clientes

Guias y recursos para desarrolladores del portal de clientes.

Estado: Planificado

Documentacion

Testing

• Backend Testing - Testing del modulo Portal en bautista-backend

Alcance de Implementacion

Implementacion completa (sin fases MVP):

• Autenticacion JWT con password (registro, login, forgot/reset password)
• Consulta de deudas con indicadores de vencimiento
• Pago online via gateway configurable por tenant (pago automatico con creacion de recibo)
• Cupones de pago (reutiliza CuponPagoService existente)
• Descarga de PDF de cupones via proxy backend
• Historial de pagos
• Polling automatico para actualizaciones de estado de pago

Arquitectura del Modulo

Backend: Modulo DDD

El portal se implementa como modulo DDD en Modules/Portal/:

Modules/Portal/
├── Domain/
│   ├── Entities/
│   ├── ValueObjects/
│   └── Exceptions/
├── Application/
│   ├── Services/
│   └── DTOs/
├── Infrastructure/
│   ├── Persistence/
│   ├── Adapters/         # PaymentGateway adapters
│   └── Http/
│       ├── Controllers/
│       ├── Middleware/
│       └── Routes/
└── Tests/
    ├── Unit/
    └── Integration/

Frontend: Repositorio independiente

El frontend vive en el repositorio portal-usuarios (submodule). Ver Frontend Architecture.

Testing Strategy

Backend (PHPUnit)

Tests en Modules/Portal/Tests/:

Tipo	Ubicacion	Cobertura objetivo
Unit	Tests/Unit/	>80%
Integration	Tests/Integration/	Flujos criticos

Componentes a testear:

• Autenticacion JWT (login, register, forgot/reset password)
• Validacion de registro contra ordcon
• Creacion automatica de recibo en pago aprobado
• Idempotencia de webhooks
• PaymentGatewayFactory y adapters
• Proxy PDF de cupones (streaming del servicio de informes)

Ver detalles en Backend Testing.

Frontend (Vitest + Testing Library + Playwright)

Vitest + Testing Library (componentes y hooks)

Tests rapidos en memoria con jsdom. Cubren la mayor parte de la logica del frontend.

Tipo	Herramienta	Cobertura objetivo
Componentes	Vitest + Testing Library	>70%
Hooks	Vitest + renderHook	>70%
Contexts	Vitest + Testing Library	Cobertura completa
Validators (Zod)	Vitest	Cobertura completa

Que testear con Vitest + Testing Library:

• Componentes de formulario: render, validacion Zod (mensajes de error), submit
  • LoginForm: validacion de DNI/CUIT y password
  • RegisterForm: validacion de email, password match, confirmacion
  • ForgotPasswordForm, ResetPasswordForm
• Componentes de datos: render con datos, estados vacios, loading (Skeleton)
  • DeudaCard: render con deuda vencida vs pendiente, Badge correcto
  • CuponCard: render con diferentes estados
  • PaymentStatusCard: render con estado pending, approved, rejected
• Hooks de TanStack Query: data flow, loading states, error handling
  • useDeudas, usePagos, useCupones, useMiCuenta
  • usePaymentStatus: verificar que refetchInterval se configura correctamente
• Contexts:
  • AuthContext: login guarda token en localStorage, logout limpia, isAuthenticated
  • BrandingContext: lee import.meta.env, aplica CSS variables en document.documentElement
• API Client: interceptors de request (JWT header, tenant headers), interceptor de response (retry en 401)
• Validators Zod: loginSchema, registerSchema, resetPasswordSchema (validaciones de largo, formato, match)

# Ejecutar tests de componentes
npm run test

# Con cobertura
npm run test -- --coverage

# Watch mode para desarrollo
npm run test -- --watch

Playwright (E2E - flujos criticos)

Tests de integracion en navegador real. Solo para flujos que involucran multiples paginas y comunicacion real con el backend.

Flujo	Paginas involucradas
Registro completo	/register -> /dashboard
Login completo	/login -> /dashboard -> /deudas
Forgot + reset password	/forgot-password -> /reset-password -> /login
Flujo de pago	/deudas -> /pagar -> gateway -> /pagar/exito
Descarga PDF cupon	/cupones -> click descarga -> archivo descargado

Que testear con Playwright:

• Registro: formulario completo -> validacion contra ordcon -> redirect a dashboard con datos del cliente
• Login: credenciales correctas -> JWT almacenado -> dashboard muestra nombre del cliente
• Login fallido: credenciales incorrectas -> mensaje de error visible -> no redirige
• Forgot + Reset Password: solicitar codigo -> ingresar codigo + nueva password -> redirect a login con mensaje de exito
• Flujo de pago: seleccionar facturas -> confirmar -> iniciar pago -> redireccion al gateway
• Resultado de pago: polling de status hasta estado final, UI actualiza sin recarga
• Descarga PDF: click en "Descargar PDF" en cupon -> archivo PDF descargado correctamente

# Ejecutar tests E2E
npx playwright test

# Con UI para debugging
npx playwright test --ui

# Solo un test especifico
npx playwright test login.spec.ts

Setup Local de Desarrollo

Requisitos

• Node.js 20+
• npm 10+
• Backend (bautista-backend) corriendo en localhost:8000

Backend

El backend (bautista-backend) se usa tal cual. No requiere setup especial para el portal.

cd /var/www/Bautista/bautista-backend
composer install
# Backend ya tiene endpoints del modulo Portal

Frontend

cd /var/www/Bautista/portal-usuarios

# Instalar dependencias
npm install

# Configurar variables de entorno
cp .env.example .env.local

# Editar .env.local con valores de desarrollo:
#   VITE_BACKEND_URL=http://localhost:8000
#   VITE_TENANT_ID=1
#   VITE_SUCURSAL_ID=1
#   VITE_APP_NAME=Portal Dev
#   VITE_LOGO_URL=
#   VITE_PRIMARY_COLOR=#1e40af
#   VITE_THEME_COLOR=#1e3a8a

# Iniciar dev server con HMR
npm run dev

Comandos del Proyecto Frontend

# Desarrollo (Vite dev server con HMR)
npm run dev

# Build de produccion
npm run build

# Preview del build de produccion
npm run preview

# Tests unitarios/componentes (Vitest)
npm run test
npm run test -- --coverage
npm run test -- --watch

# Tests E2E (Playwright)
npx playwright test
npx playwright test --ui

# Linting
npm run lint

# Type checking
npx tsc --noEmit

Docker Compose para desarrollo local

# docker-compose.dev.yml
version: "3.8"
services:
  portal-dev:
    build:
      context: ./portal-usuarios
      args:
        VITE_BACKEND_URL: "http://localhost:8000"
        VITE_TENANT_ID: "1"
        VITE_SUCURSAL_ID: "1"
        VITE_APP_NAME: "Portal Dev"
        VITE_LOGO_URL: ""
        VITE_PRIMARY_COLOR: "#1e40af"
        VITE_THEME_COLOR: "#1e3a8a"
    ports:
      - "3000:80"

Para desarrollo local se recomienda usar npm run dev directamente (Vite dev server con HMR) en lugar del contenedor Docker. El contenedor Docker es para validar el build de produccion.

Agregar componentes shadcn/ui

shadcn/ui usa un CLI para agregar componentes al proyecto:

# Agregar un componente
npx shadcn@latest add button
npx shadcn@latest add card
npx shadcn@latest add form
npx shadcn@latest add dialog

# Los componentes se copian a src/components/ui/
# Son archivos del proyecto, no dependencias externas

Estructura de Archivos de Test (Backend)

Modules/Portal/Tests/
├── Unit/
│   ├── Auth/
│   │   ├── LoginServiceTest.php
│   │   ├── RegisterServiceTest.php
│   │   ├── ForgotPasswordServiceTest.php
│   │   └── ResetPasswordServiceTest.php
│   ├── Payment/
│   │   ├── PaymentGatewayFactoryTest.php
│   │   ├── MercadoPagoAdapterTest.php
│   │   └── PaymentServiceTest.php
│   └── CtaCte/
│       └── PortalCtaCteServiceTest.php
└── Integration/
    ├── Auth/
    │   ├── LoginFlowTest.php
    │   └── RegisterFlowTest.php
    └── Payment/
        ├── PaymentFlowTest.php
        └── WebhookProcessingTest.php

Estructura de Archivos de Test (Frontend)

tests/
├── components/
│   ├── auth/
│   │   ├── LoginForm.test.tsx
│   │   ├── RegisterForm.test.tsx
│   │   ├── ForgotPasswordForm.test.tsx
│   │   └── ResetPasswordForm.test.tsx
│   ├── deudas/
│   │   ├── DeudaCard.test.tsx
│   │   └── DeudaList.test.tsx
│   └── pagos/
│       ├── SelectFacturas.test.tsx
│       └── PaymentStatusCard.test.tsx
├── hooks/
│   ├── use-auth.test.ts
│   ├── use-deudas.test.ts
│   ├── use-pagos.test.ts
│   └── use-payment-status.test.ts
├── contexts/
│   ├── auth-context.test.tsx
│   └── branding-context.test.tsx
├── validators/
│   └── auth-schemas.test.ts
└── e2e/
    ├── login.spec.ts
    ├── register.spec.ts
    ├── forgot-password.spec.ts
    └── payment-flow.spec.ts

Ver tambien

• Backend Testing
• Frontend Architecture
• Deployment
• Integraciones