Guía de ingeniería de Dashboard

Usa esta guía para cambios de código fuente en el repositorio Ordering.co Dashboard. Mantén la configuración de desarrollo aislada de los entornos de clientes y producción, y verifica los efectos de API por separado de la interfaz renderizada.

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

Los requisitos previos son Node.js 22 o posterior y pnpm 9.15.0 mediante Corepack.

corepack enable
corepack prepare pnpm@9.15.0 --activate
pnpm install --frozen-lockfile
pnpm dev

El script de desarrollo inicia Vite en el puerto 3001. El repositorio también documenta Docker, pero utiliza en cualquier caso un fixture local o un entorno no productivo aprobado explícitamente.

Configura el entorno de forma segura

El repositorio incluye .env.example; copia solo los nombres de sus claves a un .env local ignorado y solicita los valores al responsable del entorno. No copies .env, src/config.json, almacenamiento del navegador ni configuración de ejecución entre entornos.

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. Comprueba en el sistema de publicación de tu organización que se haya desplegado la revisión prevista. Una compilación local o una ejecución correcta del flujo de trabajo no lo confirman por sí solas.

Límites de compilación y publicación

pnpm build crea recursos estáticos en dist/. El repositorio también incluye comandos de Wrangler para desarrollo local del Worker y despliegues por entorno. Ejecuta un comando de despliegue solo con autorización explícita, la cuenta o entorno Cloudflare previsto, secretos aprobados y un plan de reversión y lectura posterior.

Después de una publicación autorizada, registra por separado la revisión fuente, identificador del despliegue, entorno de destino, resultado de compilación y lectura del sistema activo. No deduzcas ninguno de estos datos a partir del nombre de una rama.

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