Guía de ingeniería de Website

Usa esta guía al contribuir al repositorio de Website. El acceso al repositorio requiere autorización. Describe las rutas de desarrollo y validación versionadas; no proporciona configuración de clientes, credenciales ni autorización de despliegue.

Arquitectura

Website es una aplicación de página única creada con React 18 y Vite. React Router v5 gestiona la navegación del navegador, los proveedores de contexto coordinan la sesión, la configuración, los pedidos, el tema y el consentimiento, y styled-components proporciona la capa de temas en tiempo de ejecución. Los módulos de página están en el directorio de fuentes de la aplicación y se cargan mediante su router y contenedor de app.

La lógica de comercio y la interfaz reutilizables llegan mediante el submódulo Git Components montado en el directorio de fuentes de la aplicación. Trata la app y la revisión fijada de su submódulo como una sola entrada de compilación: un cambio que funcione con otra revisión de Components no queda validado para este repositorio.

La compilación de producción escribe recursos estáticos en dist. El Cloudflare Worker versionado sirve esos recursos y gestiona el enrutamiento durante las solicitudes, la inyección de configuración en tiempo de ejecución y las respuestas relacionadas con SEO. El servidor de desarrollo de Vite no demuestra el comportamiento del Worker.

Mapa del repositorio

Ruta	Responsabilidad
Entrada de la aplicación, contenedor y router	Punto de entrada del navegador, proveedores, controles, páginas cargadas de forma diferida y rutas.
Páginas, componentes y contextos de la aplicación	Rutas para clientes, interfaz específica de Website y límites de estado.
Submódulo Components	Lógica e interfaz de comercio compartidas y fijadas.
Configuración de la aplicación y archivos de tema	Combinación de configuración pública del cliente y valores predeterminados del tema.
Directorio de pruebas unitarias de la aplicación	Cobertura de Vitest y Testing Library que mantiene este repositorio.
e2e/docs/	Contratos deterministas de documentación y flujos de captura con Playwright.
i18n/	Comprobaciones de catálogos generados y utilidades de traducción.
worker/ y wrangler.toml	Límites de recursos de Cloudflare, enrutamiento, configuración de ejecución y SEO.

Requisitos previos y configuración segura

• Git 2.30 o posterior.
• Node.js 24 o posterior, según package.json y CI.
• pnpm 9; el repositorio fija pnpm 9.15.0.
• Un navegador compatible para el desarrollo local.

Solicita acceso al repositorio a su responsable y utiliza el método de autenticación aprobado. Desde un checkout autorizado, inicializa los submódulos e instala el árbol de dependencias fijado:

git submodule update --init --recursive
corepack enable
corepack prepare pnpm@9.15.0 --activate
pnpm install --frozen-lockfile

No elimines un archivo de bloqueo, adelantes el submódulo a otra rama, sustituyas Components por un checkout arbitrario ni copies valores de entorno al repositorio como parte de la configuración.

Configura un proyecto local seguro

La configuración de la aplicación contiene valores predeterminados visibles en el navegador y los combina con la configuración en tiempo de ejecución que proporciona el Worker. Mantén explícito este límite:

• Trata como público todo lo que se envía al navegador.
• Usa únicamente un proyecto de desarrollo al que tengas autorización para acceder.
• Nunca incluyas secretos de API, claves privadas, tokens privilegiados, exportaciones de clientes ni credenciales de proveedores exclusivas de producción en la configuración del cliente.
• Conserva la estructura anidada de configuración de API y valida los cambios con las pruebas de configuración.
• Configura los valores del Worker mediante el mecanismo de entorno aprobado. No copies valores de entorno a fuentes, ejemplos, capturas de pantalla ni tickets.

El modo de producto, la resolución de proyecto, las rutas canónicas y la disponibilidad de proveedores pueden cambiar la experiencia visible. Consulta Experiencia y configuración de Website antes de suponer que un proyecto representa todas las instalaciones.

Ejecuta y valida localmente

Inicia el servidor de desarrollo de Vite:

pnpm start

Crea un paquete de producción y sírvelo localmente cuando el trabajo lo requiera:

pnpm build
pnpm preview

Usa pnpm cf:dev solo cuando necesites probar localmente el límite del Worker versionado. Un túnel HTTPS es una superficie de prueba opcional y accesible externamente; úsalo solo con datos de prueba no sensibles y un alcance de revisión autorizado.

Durante el desarrollo, ejecuta las comprobaciones más acotadas que correspondan y después los mismos controles de calidad que CI:

pnpm lint:check
pnpm test
pnpm i18n:check-generated
pnpm i18n:verify
pnpm build

Para cambios de comportamiento de documentación, ejecuta también pnpm docs:website:contract. Los comandos de captura docs:website:*:capture de Playwright inician un servidor local con ajustes controlados del navegador. Una captura demuestra el fixture local y el código fuente del checkout, no una ruta activa de un cliente o de producción. pnpm lint aplica correcciones; usa pnpm lint:check para obtener un resultado de lint sin escritura.

Reconoce las estructuras antiguas del repositorio

El material heredado capturado distingue Ordering-UI-release, que proporcionaba componentes, de Ordering-Website-release, que contenía el código frontend y cargaba componentes durante la compilación. En el repositorio actual, usa el submódulo Components fijado y las instrucciones del gestor de paquetes y archivo de bloqueo anteriores; no apliques al checkout actual los pasos antiguos de Yarn, edición de rutas o eliminación de archivos de bloqueo.

Localiza un componente antes de modificarlo

Identifica el elemento visible para el cliente, sigue sus componentes padre e hijo y revisa sus dependencias antes de editarlo. React Developer Tools puede ayudar a identificar un árbol de componentes en una sesión local autorizada del navegador, pero no demuestra que un componente pueda copiarse o cambiarse de forma independiente.

Trata el componente fuente, sus estilos, contexto, rutas, pruebas y submódulo compartido como un único alcance de revisión. Un ejemplo heredado que copia un componente HomeHero a src/components no es una autorización vigente para bifurcar o sustituir el componente gobernado.

Haz un cambio fácil de revisar

Localiza la página y la importación que muestran la superficie prevista y realiza el cambio más pequeño que conserve el límite del componente compartido. No reescribas alias de importación ni rutas de componentes solo para compilar un ejemplo antiguo; resuelve la relación de dependencias real en el checkout fijado actual.

Límites de compilación y publicación

pnpm build comprueba localmente el paquete de producción. pnpm cf:build además actualiza el submódulo fijado e instala el archivo de bloqueo congelado antes de compilar para Cloudflare.

La secuencia capturada del generador incluye un área de archivos personalizados, rutas de archivos, validación de búsqueda y reemplazo, una acción de compilación y una acción para sincronizar con staging. Son operaciones que afectan sistemas externos. No cargues archivos, ejecutes una compilación en el generador, sincronices staging ni despliegues sin un responsable de publicación autorizado, un entorno aprobado y un proceso definido de reversión y revisión.

Una compilación local o vista previa correcta solo confirma esa compilación o vista previa. Comprueba en el sistema de publicación de tu organización la revisión, el entorno, las rutas y la configuración requerida.

Resolución de problemas

Síntoma	Comprobación
No se resuelven las importaciones con alias compartidos	Ejecuta git submodule status y luego inicializa el submódulo fijado. No lo sustituyas por un checkout arbitrario de Components.
La app se inicia, pero muestra una experiencia incorrecta	Comprueba solo los campos no secretos de proyecto y modo en la configuración local efectiva. Confirma que el proyecto es de desarrollo.
Un enlace profundo redirige o abre otra pantalla	Compáralo con Rutas y enlaces profundos de Website; siguen aplicándose los controles de cuenta, ubicación, perfil, carrito y disponibilidad de productos.
Vite funciona, pero la vista previa del Worker difiere	Reproduce con pnpm build y pnpm cf:dev; el Worker añade enrutamiento, configuración en tiempo de ejecución y comportamiento SEO.
Las pruebas agotan la memoria	Usa el script pnpm test del repositorio, que aplica los límites mantenidos de memoria y workers.
Las traducciones generadas fallan en CI	Ejecuta pnpm i18n:check-generated y pnpm i18n:verify; actualiza a la vez las claves fuente y los catálogos generados.

Límites de seguridad

• Que el navegador muestre algo no significa que la API lo haya autorizado. Aplica en el contrato de servidor la identidad, la propiedad del recurso y las operaciones de modificación.
• Nunca registres ni publiques tokens de sesión, enlaces temporales de pedidos, tokens de pago, transferencias de integraciones, direcciones de clientes ni afirmaciones de proveedores.
• Mantén la recopilación de pagos dentro del componente compatible del proveedor; no añadas datos de pago sin procesar al estado de la app, URL, analítica ni diagnósticos.
• Conserva los controles de consentimiento para analítica, seguimiento y código del proyecto.
• Valida en el límite del Worker el comportamiento derivado de redirecciones y del host. No confíes en un encabezado del cliente, hostname o valor de consulta como autoridad del tenant.
• Usa la referencia de API para los contratos publicados del servidor y Integraciones y transferencias externas de Website para la responsabilidad de proveedores.

Referencias relacionadas: Referencia para desarrolladores de Website · Rutas y enlaces profundos de Website · Integraciones y transferencias externas de Website