Saltar a contenido

Componentes y middleware del frontend

Panorama de los bloques reutilizables del cliente Next.js y cómo interactúan con el backend.

Tablas dinámicas

frontend/components/dynamic-table/dynamic-table.tsx

  • Props principales:
  • apiUrl: endpoint paginado que responda con { page, size, total, data }.
  • columns: configuración de cada columna (name, key, type, renderizadores custom).
  • initialPage, initialPageSize, initialSearch, initialOrderBy, initialAscending.
  • persistenceKey: clave para guardar preferencias de columnas/tamaño en localStorage.
  • rowOptions: acciones contextuales (menú, debug, etc.).
  • allowSelection + selectionActions: manejo de filas seleccionadas.
  • Estados manejados: page, pageSize, search, orderBy, ascending, data, total, loading, error.
  • Integraciones:
  • Debounce de búsqueda (useDebounce).
  • Exportaciones (export-utils.ts → Excel/PDF).
  • Debug modal que muestra el objeto crudo (showDebugModal).
  • Soporte opcional de Gantt (gantt-chart.tsx).
  • Expectativas del backend: parámetros page, size, search, order_by, ascending; responde PageModel.

Subcomponentes

Archivo Función
search-bar.tsx Construye expresiones DSL con una UI guiada. Permite historial, plantillas, atajos de fechas.
pagination.tsx Controla páginas y total (compatible con teclado).
context-menu.tsx Menú contextual por fila (copiar JSON, acciones personalizadas).
cell-renderers.tsx Renderizado según tipo (text, number, currency, badge-list, boolean, etc.).
export-config-dialog.tsx Configuración avanzada para exportar (columnas visibles, rangos, título).
gantt-chart.tsx Renderiza la vista Gantt opcional si las columnas lo ameritan.

Selección de centros de costos

  • frontend/components/project-selector.tsx:
  • Muestra un asistente si useProjectSession indica que el usuario no ha elegido centros.
  • Agrupa centros de costos por proyecto, permite seleccionar individualmente o por proyecto.
  • Envía la selección a /api/admin/centros_costos/select y vuelve a cargar la sesión.
  • frontend/components/project-selector-navbar.tsx:
  • Atajo en la navegación para reabrir el selector.
  • frontend/lib/project-client.ts:
  • Store Zustand (useProjectSession) que cachea centros, indica si está vacío y ofrece loadProject/clear.

Layout y navegación

  • frontend/components/navigation.tsx: barra lateral y superior, consume NavigationMenu entregados por el backend.
  • frontend/components/page-layout-sesion.tsx: layout protegido que inserta navegación, breadcrumbs y slots para contenido.
  • frontend/components/ui/: base de componentes Shadcn (inputs, tablas, selects, badges, etc.).

Hooks y librerías auxiliares

Archivo Descripción
frontend/hooks/use-debounce.ts Hook simple para estabilizar search en la DynamicTable.
frontend/lib/handleError.ts Normaliza respuestas de error HTTP y extrae mensajes adecuados para toast.

Middleware de Next.js

frontend/middleware.ts

  • Objetivo: Rescribir rutas según subdominio (auth, admin, ingenieria, construccion, lda) y validar sesiones antes de servir páginas protegidas.
  • Flujo:
  • Detecta host (X-Forwarded-Host/Host) y permite archivos públicos (/_next, /favicon, /public).
  • Si es un subdominio válido consulta POST /api/auth/access (en FastAPI) pasando host y pathname.
  • Según el status devuelto:
    • 401: redirige a /login?origin=... salvo para rutas de auth.
    • 403/404: responde directamente con ese código.
    • 200: reescribe la URL (/admin/..., /ingenieria/..., etc.) para que Next.js sirva la ruta correspondiente.
  • Si la ruta es de autenticación pero ya hay sesión válida, redirige al home.
  • Helpers: fetchWithTimeout (para evitar bloqueos), listas SUBDOMAINS, AUTH_PATHS, PUBLIC_PATHS.
  • Config: matcher excluye assets _next, favicon, logos, robots.txt, sitemap.xml.

Otros módulos destacados

  • frontend/app/**: cada ruta monta sus páginas, usualmente envolviendo el contenido en <ProjectSelector> cuando requieren centros de costos.
  • frontend/components/dynamic-table/types.ts: tipados compartidos para columnas, props y respuestas API.
  • frontend/components/dynamic-table/export-utils.ts: helpers para construir workbooks (SheetJS) y PDFs (pdf-lib) con estilos coherentes.
  • frontend/components/dynamic-table/menu-items.tsx: define acciones comunes (ver objeto, copiar JSON, abrir enlace).
  • frontend/lib/project-client.ts: además de gestionar sesión de centros, sirve como punto de acceso compartido para componentes y middleware.

Consulta users.md para ver un ejemplo completo integrando tabla, formularios y toasts en el módulo de administración de usuarios.