# Documentador

Crawler CLI para recorrer un sitio web y generar una captura de pantalla por cada página interna válida.

## Requisitos

- Python 3.11+
- Playwright para Python

## Instalación

```bash
cd /Applications/MAMP/htdocs/CAPSULA_LABS/documentador
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m playwright install chromium
```

## Uso

### Interfaz web

Abre:

```text
http://localhost:8888/CAPSULA_LABS/documentador/
```

Flujo recomendado:

1. En `Documentar`, escribe el `Nombre del output`.
2. Pega la `URL base`.
3. Ajusta `Máximo de páginas` y `Profundidad`.
4. Si el sitio requiere sesión, marca `Este sitio requiere login`.
5. Presiona `Documentar sitio`.
6. Si se abre Chromium, inicia sesión, espera que el sitio quede dentro y presiona `Ya estoy logueado, continuar`. El crawler seguirá solo.

Los resultados aparecen en `Outputs` y se pueden abrir como reporte, PDF, Word, capturas o ZIP.
Si un output antiguo tiene PDF pero todavía no tiene Word, usa `Generar Word` en la lista de outputs.

### CLI

```bash
python main.py --base-url https://ejemplo.cl --run-name sitio-cliente --max-pages 50 --max-depth 2
```

Parámetros principales:

- `--base-url`: URL base obligatoria.
- `--run-name`: nombre descriptivo opcional para la carpeta de salida.
- `--max-pages`: máximo de páginas a visitar. Default: `100`.
- `--max-depth`: profundidad máxima. Default: `3`.
- `--output-dir`: directorio de salida. Default: `output`.
- `--exclude-patterns`: patrones adicionales a excluir.
- `--include-patterns`: patrones opcionales que deben estar presentes en la ruta.
- `--allowed-domains`: dominios extra permitidos además del dominio base.
- `--headless` / `--no-headless`: modo headless. Default: `--headless`.
- `--full-page` / `--no-full-page`: captura de página completa. Default: `--full-page`.
- `--timeout-ms`: timeout por página. Default: `15000`.
- `--storage-state`: archivo de sesión Playwright guardada para sitios con login.

## Autenticación manual

Para sitios con login, usa la casilla `Este sitio requiere login` en la pestaña `Documentar`.
La interfaz web abre Chromium, guarda la sesión y ejecuta el crawler usando ese perfil.
El output incluirá una captura `Antes del login` y luego las capturas `Después del login`.

El flujo CLI avanzado también soporta perfiles guardados:

Las sesiones se guardan como perfil persistente y también como respaldo `storage_state`:

```text
sessions/<nombre>.json
sessions/<nombre>_profile/
```

No se guardan passwords en los outputs.

## Salida

Cada ejecución crea una carpeta. Si se usa `--run-name`, el nombre queda directo. Si ya existe, se crea una variante `__2`, `__3`, etc.

```text
output/<nombre>/
├── manifest.json
├── capturas.pdf
├── capturas.docx
├── reporte.html
├── run.log
└── screenshots/
```

`manifest.json` contiene `url`, `depth`, `status`, `screenshot`, `title`, `http_status`, `visited_at`, `load_time_ms` y `error`.

`reporte.html` contiene un índice y las capturas del sitio. Se puede abrir en el navegador e imprimir o guardar como PDF.

`capturas.pdf` contiene todas las capturas exitosas en un PDF multipágina.

`capturas.docx` contiene el mismo índice y capturas en formato Word editable.

También se genera `output/<nombre>.zip` con todos los archivos de la ejecución.

## Exclusiones por defecto

Rutas:

- `/admin`
- `/login`
- `/logout`
- `/cart`
- `/checkout`
- `/buscar`

Archivos:

- `.pdf`
- `.jpg`
- `.jpeg`
- `.png`
- `.gif`
- `.svg`
- `.webp`
- `.zip`
- `.xml`

Query params de tracking:

- `utm_*`
- `fbclid`
- `gclid`