# Manual — Lliria Properties Scraper

---

## ÍNDICE

1. [Arquitectura](#1-arquitectura)
2. [Requisitos](#2-requisitos)
3. [Instalación desde cero](#3-instalación-desde-cero)
4. [Arranque diario](#4-arranque-diario)
5. [Uso de la aplicación](#5-uso-de-la-aplicación)
6. [Gestión con PM2](#6-gestión-con-pm2)
7. [Scraping manual](#7-scraping-manual)
8. [Solución de problemas](#8-solución-de-problemas)

---

## 1. Arquitectura

```
XAMPP MySQL (:3306)
       │
       └──► Node.js/Express (:3000)  ◄──── Navegador
              gestionado por PM2
```

- **XAMPP** → solo para MySQL. Apache (el servidor web de XAMPP) **no se usa**.
- **Node.js/PM2** → es el servidor HTTP de la app, corre en el puerto 3000.
- **URL**: `http://localhost:3000`
- **Login**: usuario `George`, contraseña `4213`

---

## 2. Requisitos

| Software | Versión mínima | Descarga |
|----------|---------------|----------|
| XAMPP    | 8.x           | https://www.apachefriends.org |
| Node.js  | 22 LTS        | https://nodejs.org |
| PM2      | cualquiera    | `npm install -g pm2` |

---

## 3. Instalación desde cero

> Sigue estos pasos solo la primera vez, o si reinstalás el equipo.

### 3.1 — Instalar Node.js

1. Descarga el instalador LTS desde https://nodejs.org
2. Ejecuta el instalador con las opciones por defecto.
3. Verifica en PowerShell:
   ```powershell
   node --version    # v22.x.x o superior
   npm --version     # 10.x o superior
   ```

### 3.2 — Iniciar MySQL con XAMPP

1. Abre **XAMPP Control Panel**
2. Haz clic en **Start** junto a **MySQL** (verde = activo)
3. Apache **no es necesario**, puedes dejarlo parado.

### 3.3 — Crear la base de datos

1. En XAMPP Control Panel → **Admin** junto a MySQL (abre phpMyAdmin)
2. Clic en **Nueva** → nombre: `lliria_properties`, cotejamiento: `utf8mb4_unicode_ci` → **Crear**

O via SQL en phpMyAdmin → pestaña SQL:
```sql
CREATE DATABASE IF NOT EXISTS lliria_properties
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;
```

### 3.4 — Instalar y arrancar la app (solo la primera vez)

Abre PowerShell en la carpeta del proyecto y ejecuta `setup-and-start.ps1`:

```powershell
cd C:\xampp\htdocs\captajaus\lliria-properties-scraper
powershell -ExecutionPolicy Bypass -File setup-and-start.ps1
```

Esto hace automáticamente:
- Instala dependencias npm
- Instala PM2 globalmente
- Compila TypeScript a `dist/`
- Arranca la app con PM2
- Registra PM2 para que arranque al iniciar Windows

Abre el navegador en `http://localhost:3000` → Login: `George` / `4213`

---

## 4. Arranque diario

### Lo único que hay que hacer:

1. **Abrir XAMPP Control Panel**
2. **Start → MySQL** (ponerse en verde)
3. Abrir el navegador → `http://localhost:3000`

> La app ya corre en segundo plano gracias a PM2. Solo necesitas MySQL activo.

### Si reiniciaste el PC:

PM2 arranca la app automáticamente al iniciar Windows.  
Solo asegúrate de iniciar MySQL en XAMPP antes de usar la app.

### Verificar que todo está OK:

```powershell
pm2 status
# Debe mostrar: lliria-properties | online
```

---

## 5. Uso de la aplicación

### 5.1 — Acceso

| Campo    | Valor |
|----------|-------|
| URL      | http://localhost:3000 |
| Usuario  | George |
| Contraseña | 4213 |

### 5.2 — Secciones del dashboard

| Sección | URL | Descripción |
|---------|-----|-------------|
| **Inicio** | `/dashboard` | Listado de propiedades con filtros rápidos |
| **Mapa** | `/dashboard/map` | Mapa interactivo con todas las propiedades |
| **Filtros** | `/dashboard/filters` | Configura alertas por precio, zona, tipo... |
| **Analytics** | `/dashboard/analytics` | Gráficos de evolución y estadísticas |
| **Portales** | `/dashboard/portals` | Gestiona qué portales se scrapean |
| **Zonas** | `/dashboard/zones` | Define zonas geográficas de interés |

### 5.3 — Propiedades

- **Buscar**: campo de texto en la parte superior del listado
- **Filtrar**: por precio, habitaciones, metros, zona, portal
- **Favorito**: icono ♥ en cada propiedad para marcarla
- **Notas**: campo de texto editable en el detalle de cada propiedad
- **Historial de precios**: gráfico en el modal de detalle
- **Exportar a Excel**: botón en la barra superior del listado

### 5.4 — Scraping automático

El scraping se ejecuta **automáticamente cada 2 horas**.

Portales soportados: Idealista, Fotocasa, Habitaclia, Kyero, Pisos.com, Thinkspain, Trovit

Para lanzarlo manualmente desde el dashboard: botón **"Escanear ahora"** (icono radar).

### 5.5 — Alertas por email

1. Ve a **Filtros** → **Nuevo filtro**
2. Define criterios (precio, habitaciones, zona...)
3. Introduce tu email
4. Recibirás notificaciones cuando aparezcan propiedades que coincidan

---

## 6. Gestión con PM2

### Comandos básicos

```powershell
# Ver estado
pm2 status

# Ver logs en tiempo real (Ctrl+C para salir)
pm2 logs lliria-properties

# Ver últimas líneas sin quedarse "colgado"
pm2 logs lliria-properties --lines 30 --nostream

# Reiniciar (tras cambios en .env o config)
pm2 restart lliria-properties

# Parar la app
pm2 stop lliria-properties

# Volver a arrancar
pm2 start lliria-properties
```

### Actualizar tras cambios en código

```powershell
cd C:\xampp\htdocs\captajaus\lliria-properties-scraper
npx tsc
pm2 restart lliria-properties
pm2 save --force
```

### Ficheros de log

```
logs/out.log    → mensajes normales (inicio, scraping, etc.)
logs/error.log  → errores
```

Leer los últimos errores:
```powershell
Get-Content logs\error.log -Tail 20
```

---

## 7. Scraping manual

Para lanzar scraping via PowerShell (app debe estar corriendo):

```powershell
# Lanzar todo el scraping
Invoke-RestMethod -Uri "http://localhost:3000/api/scraper/run" -Method POST

# Ver estado del scheduler
Invoke-RestMethod -Uri "http://localhost:3000/api/scheduler/status"

# Ver log de scrapings recientes
Invoke-RestMethod -Uri "http://localhost:3000/api/scheduler/logs"
```

---

## 8. Solución de problemas

### La app no abre en el navegador

1. Verifica PM2:
   ```powershell
   pm2 status
   # Si está "stopped" o "errored":
   pm2 restart lliria-properties
   ```
2. Verifica que MySQL de XAMPP está activo (verde)
3. Revisa errores: `Get-Content logs\error.log -Tail 20`

### Error "Access denied for user root" o "ECONNREFUSED 3306"

MySQL no está iniciado.
1. Abre XAMPP Control Panel → Start MySQL
2. Si cambiaste la contraseña: edita `.env` y actualiza `DB_PASSWORD`

### La app se reinicia en bucle (↺ > 3 en pm2 status)

```powershell
Get-Content logs\error.log -Tail 30
```
Normalmente es MySQL no disponible o error de compilación.

### PM2 no arranca al iniciar Windows

```powershell
npm install -g pm2-windows-startup
pm2-startup install
pm2 save --force
```

### Puerto 3000 ocupado

```powershell
# Ver qué proceso usa el puerto
netstat -ano | findstr :3000
# Anota el PID y mátalo (sustituye XXXX por el número):
taskkill /PID XXXX /F
# Luego reinicia PM2:
pm2 restart lliria-properties
```

### Reinstalación completa

```powershell
cd C:\xampp\htdocs\captajaus\lliria-properties-scraper
pm2 delete lliria-properties
npm install
npx tsc
pm2 start ecosystem.config.js
pm2 save --force
```

---

*Última actualización: febrero 2026*