| # Documentación del Frontend |
|
|
| Este documento describe la arquitectura, las rutas, los estados, los hooks y los componentes principales del frontend React + TypeScript ubicado en `frontend/`. |
|
|
| --- |
|
|
| ## 1. Visión general |
|
|
| El frontend está construido con: |
|
|
| - React 19 |
| - TypeScript |
| - Vite |
| - React Router DOM |
| - Zustand para estado global |
| - @tanstack/react-query para consultas asíncronas |
| - Tailwind CSS para estilos |
| - Arquitectura basada en características (`features`) |
|
|
| La carpeta principal de la aplicación es `frontend/src`. |
|
|
| --- |
|
|
| ## 2. Estructura de carpetas clave |
|
|
| - `src/main.tsx` - punto de entrada, configuración de router y React Query |
| - `src/App.tsx` - rutas principales de la aplicación |
| - `src/store` - estado global con Zustand |
| - `src/api` - cliente y funciones de API centralizadas |
| - `src/hooks` - hooks reutilizables del frontend |
| - `src/features` - features organizadas por dominio |
| - `src/utils` - utilidades compartidas |
| - `src/types.ts` - tipos globales de la aplicación |
|
|
| --- |
|
|
| ## 3. Rutas principales |
|
|
| `src/App.tsx` define las rutas: |
|
|
| - `/` → `RoomSetup` |
| - `/visualizer` → `RoomVisualizer` |
| - `/settings` → `SettingsPage` |
| - `*` → redirección a `/` |
|
|
| --- |
|
|
| ## 4. Estado global (Zustand) |
|
|
| `src/store/useAppStore.ts` almacena: |
|
|
| - `previewImage` - URL de la imagen cargada |
| - `uploadMessage` - estado de mensaje de subida |
| - `openProductId` - producto seleccionado en `RoomVisualizer` |
| - `viewMode` - vista actual de productos en el visualizador (`grid` o `list`) |
|
|
| Funciones disponibles: |
|
|
| - `setPreviewImage` |
| - `setUploadMessage` |
| - `setOpenProductId` |
| - `setViewMode` |
| - `reset` |
|
|
| --- |
|
|
| ## 5. Cliente API centralizado |
|
|
| `src/api/client.ts` incluye: |
|
|
| - `DEV_API_BASE` y `API_BASE` para la URL del backend |
| - `getApiBase` / `buildApiUrl` para construir endpoints |
| - `fetchClientConfig` para obtener configuración de cliente |
| - `uploadRoomImage` para subir imágenes al servidor |
| - `startSession` para iniciar una sesión remota |
|
|
| Esta capa permite mantener la URL del backend en un solo lugar y soportar un token de desarrollo automático. |
|
|
| --- |
|
|
| ## 6. Hooks compartidos |
|
|
| ### `src/hooks/useUploadImage.ts` |
|
|
| - Maneja la subida de imágenes al backend |
| - Controla `isUploading` y `uploadError` |
| - Envuelve `uploadRoomImage` del cliente API |
|
|
| --- |
|
|
| ## 7. Tipos globales |
|
|
| `src/types.ts` declara tipos comunes como: |
|
|
| - `ClientData` |
| - `RouteItem` |
| - `Product` |
|
|
| El tipo `Product` se usa en el visualizador para productos de catálogo. |
|
|
| --- |
|
|
| ## 8. Feature: Room Setup |
|
|
| ### Archivos |
|
|
| - `src/features/roomSetup/RoomSetup.tsx` |
| - `src/features/roomSetup/roomSetupHooks.ts` |
| - `src/features/roomSetup/RoomSetupComponents.tsx` |
| - `src/data/roomSetupData.ts` |
|
|
| ### Comportamiento |
|
|
| `RoomSetup` es la página principal donde el usuario puede: |
|
|
| - subir una imagen arrastrando o seleccionando archivo |
| - ver una vista previa de la imagen |
| - iniciar la navegación hacia el visualizador |
| - ver habitaciones de demostración filtrables |
|
|
| ### `useRoomSetup` |
|
|
| Este hook abstrae toda la lógica de: |
|
|
| - drag & drop |
| - selección de archivos |
| - subida de imagen |
| - gestión de estados de carga |
| - navegación con `useNavigate` |
|
|
| ### Componentes auxiliares |
|
|
| - `FilterButton` - botón de filtrado por categoría |
| - `RoomCard` - tarjeta de habitación de demostración |
|
|
| --- |
|
|
| ## 9. Feature: Room Visualizer |
|
|
| ### Archivos |
|
|
| - `src/features/roomVisualizer/RoomVisualizer.tsx` |
| - `src/features/roomVisualizer/roomVisualizerHooks.ts` |
| - `src/features/roomVisualizer/roomVisualizerData.ts` |
| - `src/features/roomVisualizer/ProductCards.tsx` |
|
|
| ### Comportamiento |
|
|
| `RoomVisualizer` muestra: |
|
|
| - la imagen subida por el usuario |
| - controles de zoom y arrastre de la imagen |
| - lista / grid de productos para aplicar en la habitación |
| - selección de producto y detalles asociados |
|
|
| ### `useRoomVisualizer` |
|
|
| Extrae la lógica de visualización de productos: |
|
|
| - modo de vista (`grid` / `list`) |
| - búsqueda y filtros básicos |
| - producto seleccionado |
| - manejo de selección de producto |
| - agrupación en chunks para renderizar grillas |
|
|
| ### Datos de productos |
|
|
| - `roomVisualizerData.ts` contiene el catálogo de productos estáticos usados en la vista. |
|
|
| ### Componentes |
|
|
| - `ProductGroupCard` - renderiza un grupo de 3 productos en grid |
| - `IndividualProductCard` - renderiza un producto en modo lista |
|
|
| --- |
|
|
| ## 10. Feature: Settings |
|
|
| ### Archivo |
|
|
| - `src/features/settings/SettingsPage.tsx` |
|
|
| ### Comportamiento |
|
|
| La página de configuración permite al usuario: |
|
|
| - definir la URL base de la API |
| - activar / desactivar la lista de rutas en el viewer |
| - definir token de desarrollo automático |
|
|
| ### Soporte de almacenamiento |
|
|
| `src/utils/settings.ts` gestiona: |
|
|
| - carga de `localStorage` |
| - guardado de configuración |
| - valores por defecto |
|
|
| --- |
|
|
| ## 11. Componentes comunes |
|
|
| - `src/components/ui/LoadingScreen.tsx` - pantalla de carga reutilizable |
|
|
| --- |
|
|
| ## 12. Flujo principal de la app |
|
|
| 1. Usuario entra en `/` |
| 2. Sube una imagen en `RoomSetup` |
| 3. Se crea una vista previa y se almacena en Zustand |
| 4. Se navega a `/visualizer` |
| 5. `RoomVisualizer` usa la imagen y muestra productos |
| 6. El usuario filtra, busca y selecciona productos |
| 7. `SettingsPage` permite ajustar la API y opciones de la app |
|
|
| --- |
|
|
| ## 13. Cómo ejecutar el frontend |
|
|
| Desde `frontend/`: |
|
|
| ```bash |
| npm install |
| npm run dev |
| ``` |
|
|
| Construcción de producción: |
|
|
| ```bash |
| npm run build |
| ``` |
|
|
| --- |
|
|
| ## 14. Posibles mejoras futuras |
|
|
| - mover `roomVisualizerProducts` a una API real o servicio de datos |
| - extraer más componentes presentacionales del visualizador |
| - usar React Query para cargar configuración del cliente en lugar de gestión manual |
| - añadir tests unitarios para hooks y componentes |
| - normalizar rutas y nombres de features |
|
|
| --- |
|
|
| ## 15. Observaciones adicionales |
|
|
| - La base API se controla desde `VITE_API_BASE_URL` o `DEV_API_BASE` en desarrollo. |
| - La aplicación usa `queryClient` de React Query, aunque hoy solo se usa para potenciales fetches futuros. |
| - El estado global es ligero y se usa principalmente para compartir imagen previa, modo de vista y selección de producto. |
|
|
