Características

La aplicación Next.js implementa un robusto conjunto de características que abarcan la gestión de estados, el modelo de bases de datos y estrictos estándares de testing.

Gestión de Estado y Formularios

Para mantener una separación clara entre el servidor y el cliente, aplicamos diferentes estrategias dependiendo del dominio de los datos:

1. Estado del Servidor (Server State): Utilizamos @tanstack/react-query acoplado con @better-fetch/fetch para la recuperación, caché e invalidación de datos asíncronos.
2. Estado del Cliente (Client State): Delegamos el estado complejo e interactivo a zustand, manteniendo flujos de trabajo predecibles y una rápida reactividad.
3. Formularios y Validación: El procesamiento de formularios se maneja en el cliente usando react-hook-form en combinación con @hookform/resolvers y zod para la seguridad tipada de inicio a fin.

Estilos y Sistema de Diseño

Peligro

Restricción Estilística El uso de TailwindCSS o librerías de CSS-in-JS (como styled-components) está estrictamente prohibido.

La aplicación se apoya exclusivamente en CSS/SCSS Modules utilizando variables de diseño estandarizadas.

• Usamos el framework Bulma subyacente para grids y clases utilitarias base.
• Utilizamos tokens de diseño con el prefijo --lynx-* definidos en src/visual/theme.ts (ej. --lynx-box-radius), anulando las variables predeterminadas de Bulma.
• Siempre encapsulamos el diseño en un archivo .module.css o .module.scss para prevenir colisiones en cascada global.

Integraciones Clave

• Base de Datos: Se accede a la persistencia a través de Drizzle ORM (src/modules/database). Las migraciones siempre se ubican en src/modules/database/migrations.
• Autenticación: Implementada en src/modules/auth y orquestada por el paquete Better Auth global.
• Transaccionales: Lógica alojada en src/modules/mail consumiendo plantillas interactivas generadas vía React Email.

Estrategia de Testing (Vitest + Playwright)

Garantizar la estabilidad de esta capa es primordial. Hemos definido umbrales de cobertura que se verifican automáticamente en CI a través de Vitest.

| Nivel de Prueba | Alcance y Herramientas | Comando | | :----------------------------- | :------------------------------------------------------------------------------------------------ | :-------------- | | Unitaria (Unit) | Esquemas Zod, DTOs, constructores de configuración y slices de estado Zustand. | pnpm test | | Integración de Componentes | Renderizado usando React Testing Library (RTL) + userEvent simulando interacciones del usuario. | pnpm test | | End-to-End (E2E) | Navegadores reales ejecutando flujos completos con interacciones reales, a través de Playwright. | pnpm test-e2e |

Prácticas Recomendadas para Pruebas

1. Colocación: Crea el archivo de prueba (ej. mi-componente.test.tsx) directamente junto al archivo fuente en el mismo directorio.
2. Aislamiento: En pruebas unitarias, mockea (simula) siempre la base de datos, las peticiones de red y el sistema de archivos en los bordes.
3. Casos Reales: Usa la configuración e2e cuando necesites probar integraciones con infraestructura real (PostgreSQL, Redis, etc.).