OmniMarket Operations Hub — Frontend
Dashboard en español para operaciones de e-commerce: analítica, Kanban con arrastre y actualización optimista, y acceso OAuth con Google/GitHub. La sesión y los datos pertenecen al backend.
Stack: Next.js 15 (App Router) · TypeScript · Tailwind CSS v4 · shadcn/ui · dnd-kit · Recharts · SWR · React Hook Form · Zod · Vitest · Playwright.
Desarrollo local
Configura primero y arranca PostgreSQL y la API siguiendo el README de OmniMarketBack. Para OAuth local, registra estos callbacks en Google y GitHub:
http://localhost:3000/api/auth/google/callbackhttp://localhost:3000/api/auth/github/callback
En OmniMarketBack/.env, configura API_ORIGIN=http://localhost:3000, WEB_ORIGIN=http://localhost:3000 y las credenciales GOOGLE_* y GITHUB_*. Después, desde esta carpeta:
cp .env.example .env.local
npm install
npm run dev
En Windows (PowerShell): Copy-Item .env.example .env.local; si la política de ejecución bloquea npm, usa npm.cmd.
OMNIMARKET_API_URL apunta al servicio backend (por defecto http://localhost:3001). Next.js reenvía OAuth por /api/auth/*, las rutas oficiales de auditoría por /api/test/* y las llamadas de datos por /backend/*; las cookies quedan en el mismo origen del frontend. No configures DATABASE_URL aquí.
| Script | Uso |
|---|
npm run dev / build / start | Next.js |
npm run lint | ESLint |
npm run typecheck | tsc --noEmit |
npm test | Vitest con dos proyectos: unit (lógica pura en Node: formatos, finanzas, schemas, analítica, Kanban, guardas) y components (jsdom + React Testing Library + user-event + MSW: hooks y componentes con red simulada) |
npm run test:e2e | Playwright con backend mock local y autenticación de prueba aislada |
npm run test:e2e:published-api | Playwright contra /api/test/* del frontend local, proxificado al backend publicado |
npm run test:cypress | Cypress (levanta el dev server en :3100 y corre cypress run); npm run cypress lo abre en modo interactivo |
Rutas
| Ruta | Acceso | Contenido |
|---|
/ | Pública | Landing de producto |
/login | Pública | Acceso con Google o GitHub |
/dashboard | Sesión backend | Resumen de métricas y órdenes |
/dashboard/analytics | Sesión backend | Gráficas, filtros por fecha/categoría y tabla paginada |
/dashboard/kanban | Sesión backend | Cinco estados, arrastre, bulk y creación de órdenes |
/dashboard/catalog | Sesión backend | Productos y categorías; lectura para usuarios y gestión para administradores |
/dashboard/orders/:id | Sesión backend | Detalle, edición versionada de artículos y eliminación de una orden |
middleware.ts comprueba la presencia de omni_session; el layout consulta GET /api/auth/session al backend antes de renderizar el dashboard. OAuth, lectura y cierre de sesión usan la cookie HttpOnly del backend. Google y GitHub se configuran únicamente en el backend.
Contrato integrado
lib/api/client.ts valida las respuestas con Zod y adapta el contrato del backend a los modelos de pantalla.
| Operación | Contrato que usa el frontend |
|---|
| Analítica | GET /api/analytics?page&limit&from&to&categoryId; responde summary, items con category anidada y pagination |
| Tablero | GET /api/orders?page&limit; el cliente consulta todas las páginas y agrupa órdenes por estado |
| Catálogo | GET /api/categories y GET /api/products; la vista de administración cubre alta, edición, detalle y eliminación de productos/categorías |
| Mover orden | PATCH /api/orders/:id/status con { status, position, expectedVersion }; conflicto optimista HTTP 409 |
| Crear orden | POST /api/orders con { customer: { name, email }, items }; el backend crea en PENDING |
| Detalle de orden | GET /api/orders/:id; edición de artículos con PATCH /api/orders/:id y expectedVersion; eliminación con DELETE /api/orders/:id |
| Bulk | PATCH /api/orders/bulk con { ids, status }; máximo 100 órdenes por transacción |
| Auditoría | GET /api/health, GET /api/test/analytics, GET /api/test/kanban-status y GET /api/test/contract |
| Reset de fixtures | POST /api/test/reset-data; el navegador lo invoca mediante una ruta servidor que exige TEST_RESET_ENABLED=true (despliegue de fixtures) y comprueba origen, sesión ADMIN y TEST_API_TOKEN; sin el interruptor responde 404 |
NEXT_PUBLIC_USE_MOCKS=true habilita el adaptador local para desarrollo visual y E2E (siempre sobre next dev); en producción debe ser false. Un build o arranque con NODE_ENV=production falla si NEXT_PUBLIC_USE_MOCKS o E2E_MOCK_AUTH están en true (lib/env-guard.ts). La sesión E2E sólo se acepta con E2E_MOCK_AUTH=true y el modo de pruebas explícito OMNIMARKET_TEST_ENV=true, que fijan playwright.config.ts, npm run test:cypress y la CI. Las mutaciones reales envían credenciales incluidas para la cookie HttpOnly. El token de reset es solo de servidor y no debe llevar prefijo NEXT_PUBLIC_.
Scraper de despliegues
npm run scrape:production inspecciona el frontend y backend publicados con solicitudes GET. Comprueba portada y login, redirecciones del dashboard sin sesión, salud de API, contratos y proxy, valores de analítica, tres muestras por origen bajo 300 ms, rechazo de limit=101 y lectura del pedido de prueba en Kanban. No ejecuta reset ni modifica pedidos.
Usa npm run scrape:production -- --json para obtener un informe JSON. Los orígenes, timeout, SLA y número de muestras se pueden ajustar con --front, --back, --timeout-ms, --sla-ms y --repeats; también se aceptan OMNIMARKET_FRONT_URL y OMNIMARKET_API_URL.
Vercel y CI/CD
Conecta ambos repositorios a sus proyectos Vercel. En GitHub Actions el check requerido es Frontend CI Gate para el frontend y Backend CI Gate para el backend. En cada proyecto Vercel, agrega el check correspondiente en Settings → Deployment Checks → GitHub Checks para que una falla detenga la promoción a producción. El despliegue a producción lo hace la CI (deploy tras quality y e2e, seguido de smoke); los secretos y los ajustes manuales de GitHub y Vercel están en docs/DEPLOY.md. En el proyecto frontend configura:
OMNIMARKET_API_URL: URL estable del backend accesible desde el servidor Next.js.NEXT_PUBLIC_USE_MOCKS=false.TEST_API_TOKEN: mismo valor privado que en backend, solo si se necesita habilitar el reset de fixtures.TEST_RESET_ENABLED=true: interruptor explícito del reset de fixtures; déjalo sin definir en producción.
En backend, configura API_ORIGIN y WEB_ORIGIN con el origen público del frontend. Registra Google/GitHub con callback https://<dominio-frontend>/api/auth/{google|github}/callback, y permite ese origen en CORS mediante WEB_ORIGIN o CORS_ALLOWED_ORIGINS.
La configuración de variables no prueba que los proveedores OAuth, la base PostgreSQL o los servicios externos estén provisionados; valida cada flujo en el entorno después de configurarlos.
