Guía de ingeniería de AI Dashboard

Usa esta guía para realizar cambios en el monorepo AI Dashboard. Mantén el frontend, el paquete compartido, los servicios independientes, las funciones y las migraciones de almacenamiento verificables y publicables por separado.

Mapa del repositorio

Ruta	Responsabilidad
apps/dashboard/	Aplicación React 19 y Vite 7, rutas, páginas, hooks, i18n, pruebas unitarias y comprobaciones con Playwright.
packages/shared/	Cliente API, configuración, contextos, stores, hooks, proveedores, utilidades e interfaz compartidos.
services/menu-import/	Adaptadores de fuentes de menú en Python FastAPI, normalización, copia opcional de imágenes y sincronización con Ordering.co API.
services/meta-ads/	Flujos Python FastAPI de OAuth de Meta, campañas, insights, cifrado de tokens y persistencia.
supabase/functions/	Funciones basadas en Deno para ciertos flujos de servidor de Supabase seleccionados por el repositorio.
supabase/migrations/	Cambios versionados de esquema y políticas de la base de datos.
scripts/, brand/ y design/	Herramientas de calidad, formato, localización, metadatos y cumplimiento del sistema de diseño de Ordering.co.
turbo.json y package.json de la raíz	Grafo de tareas del workspace y comandos raíz.
wrangler.jsonc	Servicio de recursos estáticos de la app y configuración de observabilidad; no demuestra un despliegue.

Configuración del frontend

La raíz declara Node.js 20 o posterior y Yarn 1.22.0. Usa el archivo de bloqueo versionado y ejecuta los comandos desde la raíz del monorepo, salvo que se indique un comando específico de workspace.

yarn install --frozen-lockfile
yarn dev

Para ejecutar únicamente la aplicación del navegador:

yarn workspace dashboard dev

Vite usa el puerto 3000 de forma predeterminada. Confirma que la app renderizada apunte a un proyecto no productivo aprobado antes de iniciar sesión o abrir una ruta que pueda inicializar sockets, analítica, notificaciones o solicitudes a proveedores.

Configuración del entorno

Usa los archivos .env.example versionados como inventario de nombres de claves para Dashboard y cada servicio. Crea archivos .env locales ignorados y solicita los valores al responsable del entorno correspondiente. Nunca copies valores de un entorno desplegado, otro desarrollador, almacenamiento del navegador, registros o ejemplos de documentación.

Clasifica las variables antes de usarlas:

• Los valores VITE_* son visibles en el navegador y nunca deben contener claves de service role, secretos internos, secretos de cliente OAuth, claves de cifrado de tokens ni credenciales privilegiadas de proveedores.
• Los límites de API, facturación, sockets, importadores, anuncios y Supabase público deben apuntar al entorno de pruebas previsto.
• Los servicios Python son responsables de sus secretos de proveedores, base de datos, cifrado, almacenamiento, callbacks y autenticación interna.
• Las funciones de Supabase reciben valores confiables mediante el mecanismo aprobado de secretos de funciones, no desde código fuente versionado ni configuración del frontend.

Pruebas y controles de calidad

Ejecuta primero la prueba más acotada afectada y después los controles correspondientes del workspace y la raíz.

yarn workspace dashboard test --run
yarn workspace dashboard test:coverage
yarn lint
yarn test
yarn format:check
yarn brand:check
yarn test:brand
yarn build

El workspace Dashboard también proporciona suites Playwright y comprobaciones específicas para las superficies de Ordering.co, diseño, localización, metadatos y superposiciones. Usa los scripts del repositorio en lugar de reconstruir sus opciones de comando. Las suites activas de solo lectura requieren autorización separada y evidencia conocida del entorno; que el nombre de una prueba lo diga no hace que una solicitud externa sea segura.

Para servicios independientes, crea un entorno virtual local desde el directorio del servicio, instala su requirements.txt y ejecuta pytest:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pytest

Usa fixtures sintéticos. Mantén los entornos virtuales, cobertura generada, resultados del navegador y archivos locales con secretos fuera de los commits.

Flujo de cambios

1. Identifica el límite responsable en Servicios y límites de datos.
2. Sigue la ruta del frontend a través de su página, hook, cliente API compartido y contrato del servidor.
3. Usa la referencia de API para los esquemas públicos de solicitudes y respuestas; no derives un contrato solo a partir de un hook.
4. Añade pruebas unitarias en el paquete responsable y pruebas de servicio para cada etapa backend modificada.
5. Cubre, según corresponda, los estados de carga, vacío, acceso denegado, parcial, fallo de proveedor, reintento y éxito.
6. Ejecuta los controles de conformidad, i18n, formato, pruebas y compilación que afecte el cambio.
7. Verifica localmente una compilación de producción con datos sintéticos. Mantén el despliegue como una acción con autorización separada.

Límites de compilación y publicación

yarn build ejecuta el grafo de compilación Turbo; yarn build:cloudflare compila el workspace Dashboard para servir recursos estáticos. La configuración Wrangler describe un posible destino de servicio, pero no demuestra que estén desplegados el checkout actual, los servicios, las funciones o las migraciones.

Publica cada límite con sus propias evidencias:

• revisión del código fuente del frontend, salida de compilación y lectura del despliegue estático;
• revisión de Ordering.co API y su relación con el despliegue de API;
• revisión del servicio independiente, evidencia de dependencias, comprobación de estado y prueba controlada con el proveedor;
• revisión de funciones y lectura de secretos/configuración; y
• registro de migraciones de base de datos y verificación de políticas.

No agrupes todo esto bajo una sola afirmación de que «está desplegado».

Resolución de problemas

Síntoma	Comprobación
Turbo no encuentra una tarea	Confirma que exista en el paquete del workspace de destino y esté conectada en turbo.json.
@finitless/shared no se resuelve	Ejecuta una instalación congelada desde la raíz y confirma que el layout del workspace y el lockfile estén intactos.
El navegador carga, pero las consultas a API están desactivadas o vacías	Inspecciona por separado la configuración saneada de funciones de endpoint, selección del proyecto, estado de sesión y respuesta del servidor.
Faltan campos de proveedor de agente	Confirma la respuesta del esquema de proveedor; no añadas una alternativa solo del cliente para un esquema cuya responsabilidad es del servidor.
El importador indica «not configured»	Confirma que exista la variable base del servicio segura para el navegador y que el servicio esté en ejecución; conserva en el servidor los secretos de proveedores y almacenamiento.
El servicio se inicia, pero falla la persistencia	Verifica el registro previsto de migraciones y políticas, el rol de base de datos del backend y la disponibilidad de la clave de cifrado sin imprimir valores.
Pasan las pruebas unitarias, pero falla el flujo del navegador	Ejecuta la comprobación enfocada de Playwright/configuración e inspecciona por separado rutas, red, consola y límites de proveedores.

Seguridad y escalamiento

Escala las dudas de autorización de API y esquemas centrales al responsable de API; los contratos de agentes y canales, al responsable del servicio; las credenciales, callbacks y fallos de entrega, al responsable del proveedor; las migraciones y políticas, al responsable de datos; y los despliegues, al responsable de publicación. Detente si una prueba puede crear campañas externas, enviar mensajes, importar datos de clientes, cambiar la facturación, escribir en una base de datos de producción o exponer un secreto sin un plan explícito de efectos, limpieza y lectura posterior.

Referencias relacionadas: Agentes, canales e integraciones de proveedores · Servicios y límites de datos