# 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.