Guía de ingeniería de Dashboard

Usa esta guía para desarrollar con el código fuente público de Ordering.co Dashboard en la rama main. Mantén la configuración de desarrollo aislada de los entornos de clientes y producción. Verifica los efectos de la API por separado de lo que muestra la interfaz.

Arquitectura y mapa del repositorio

Ruta	Responsabilidad
src/App.js	Contenedor autenticado de la aplicación, registro de rutas, controles de rutas del cliente y comportamiento de ciclo de vida de nivel superior.
src/pages/	Adaptadores de página que componen flujos de trabajo para operadores.
src/@/components-dashboard/	Componentes compartidos dentro del repositorio, código SDK, contextos, elementos de interfaz y controladores consumidos mediante alias de Vite.
src/config.json y src/config.js	Configuración base del cliente y combinación con una sobrescritura opcional de ejecución window.__CONFIG__.
src/__tests__/ y __tests__/ junto a los archivos	Cobertura de Vitest y Testing Library para rutas, páginas, contextos, utilidades y comportamiento de interfaz.
i18n/	Herramientas para generar, validar y sincronizar catálogos de traducción.
vite.config.js	Compilación React, alias, configuración de pruebas, alcance de cobertura y salida de dist/config.json.
wrangler.toml, worker/ y docs/CLOUDFLARE.md	Configuración de compilación y servicio de Cloudflare; su presencia en el repositorio no demuestra un despliegue.

La app usa React 18, React Router 5, styled-components y la cadena de herramientas Vite 7. Los contextos compartidos de Ordering.co coordinan API, sesión, configuración, pedidos, negocios, idioma, tiempo real y otros estados entre páginas.

Configuración local

Usa Node.js 24, fijado en .nvmrc, y pnpm 9.15.0 mediante Corepack.

git clone https://github.com/Ordering-co/ordering-dashboard.git
cd ordering-dashboard
corepack enable
corepack prepare pnpm@9.15.0 --activate
pnpm install --frozen-lockfile
node scripts/onboarding/cli.mjs detect
node scripts/onboarding/cli.mjs configure --project my-project
node scripts/onboarding/cli.mjs doctor
pnpm dev --host 127.0.0.1

Sustituye my-project por un proyecto de pruebas autorizado. Consulta la guía pública de configuración para configurar el proyecto manualmente o usar Docker. Vite sirve la app en http://localhost:3001. La comprobación de configuración valida la resolución pública del proyecto. Comprueba el inicio de sesión y el acceso a datos por separado con tu cuenta de pruebas.

Configura el entorno de forma segura

El repositorio público incluye .env.example para servicios opcionales. Si los necesitas, sigue la guía pública de configuración y usa valores aprobados para tu entorno de pruebas en un .env local ignorado por Git. Mantén .env, src/config.json, el almacenamiento del navegador y la configuración de ejecución separados por entorno.

Recuerda:

• todos los valores expuestos a Vite o incluidos en la configuración del cliente se pueden leer en el navegador;
• la identidad del proyecto, API, socket, idioma y aplicación deben corresponder al mismo entorno;
• las sobrescrituras de ejecución combinan objetos anidados api y socket con la configuración base;
• analítica, notificaciones, soporte, sockets e inicialización autenticada pueden arrancar durante el inicio normal de la app, por lo que cargarla no garantiza una prueba de solo lectura; y
• utiliza cuentas y registros sintéticos para desarrollo. Nunca incluyas datos de clientes ni credenciales en fixtures, capturas de pantalla, registros o configuración versionada.

Comandos de desarrollo y validación

pnpm dev
pnpm lint:check
pnpm test
pnpm test:coverage
pnpm i18n:check-generated
pnpm i18n:verify
pnpm build
pnpm preview

Usa pnpm test:watch durante el trabajo acotado. La compilación de producción reserva un heap de Node mayor debido al tamaño del bundle. Ejecuta primero la prueba más específica y luego las comprobaciones de lint, pruebas, i18n y compilación que requiera el cambio. No uses pnpm lint como comprobación de solo lectura, porque ese script aplica correcciones.

Flujo de cambios

1. Sigue la ruta desde src/App.js hasta su página y el componente o controlador dentro del repositorio.
2. Identifica el contexto de API, configuración, sesión, tiempo real, plugin o proveedor que utiliza el flujo.
3. Confirma el contrato publicado de API en vez de inferir un esquema del servidor a partir de llamadas del cliente.
4. Añade o actualiza pruebas junto a la página, componente, contexto o utilidad responsable.
5. Verifica los estados de carga, vacío, acceso denegado, error, éxito y solo lectura que pueda alcanzar el cambio.
6. Ejecuta una compilación de producción e inspecciona la ruta afectada con datos sintéticos.
7. Si tu organización despliega la compilación, comprueba la revisión en el entorno previsto mediante su sistema de publicación.

Límites de compilación y publicación

pnpm build crea archivos estáticos en dist/. Para el alojamiento opcional en Workers, sigue la guía pública de Cloudflare y configura tu propia cuenta de Cloudflare, Worker, proyecto autorizado y vinculaciones opcionales. La CI pública valida el código fuente. El despliegue de tu instancia es una operación aparte que ejecutas para tu entorno.

Ordering.co publica el Dashboard alojado mediante su propio proceso. Si despliegas tu instancia con autorización, verifica la revisión desplegada, el identificador del despliegue, el entorno de destino y el resultado en el sitio por separado de la compilación local.

Resolución de problemas

Síntoma	Comprobación
Vite no puede resolver ~components o ~ui	Confirma que el checkout completo de src/@/components-dashboard y los alias de Vite estén presentes.
El inicio muestra un proyecto o backend incorrecto	Detente antes de autenticar; inspecciona la configuración base y de ejecución sin secretos y limpia solo el estado de pruebas local conocido.
Una ruta protegida redirige de forma inesperada	Inspecciona la inicialización de sesión, el control de nivel de la ruta y las opciones de solo lectura; luego confirma por separado la autorización del servidor.
Las lecturas de API funcionan, pero no las actualizaciones en tiempo real	Comprueba por separado el límite del socket, el estado de conexión autenticada y los errores de proveedor o red.
Las pruebas pasan localmente, pero CI falla	Iguala la versión fijada de pnpm, la instalación congelada, la versión de Node aceptada por CI y los comandos exactos de lint e i18n sin modificaciones.
La compilación termina por falta de memoria	Confirma que se aplique la asignación de heap documentada y que el host tenga memoria suficiente; no debilites las pruebas ni la minificación para ocultar el fallo.

Seguridad y escalamiento

Escala al responsable de API las dudas de autorización o contrato, al responsable de proyecto o configuración la selección de entorno, al responsable del proveedor las credenciales y callbacks, y al responsable de publicación los despliegues. Detén las pruebas si un flujo puede escribir datos de clientes, activar actividad de proveedores, enviar una notificación, alterar facturación o exponer credenciales sin un plan aprobado de efectos y limpieza.

Referencias relacionadas: Integraciones, API y transferencias a proveedores de Dashboard