# Convenciones del proyecto web_scraping

Reglas operativas para todo control de navegador y extracción web del proyecto. Aplican a la app
`script_navegador`, a los scripts YAML y a cualquier función del dominio `browser` que se use desde
aquí. Construido 100% sobre Linux nativo (sin WSL/Windows).

> Nota: estas son **convenciones** (cómo se trabaja), no datos. Los datos extraídos (pliegos,
> RFPs, listados) van en `vaults/` cuando empecemos a capturar.

## 1. Tamaño de ventana fijo

Todo navegador se lanza con un tamaño de ventana explícito y estable. Por defecto `1366x768`
(resolución de portátil muy común → menos sospechosa que un viewport raro).

- Motivo: reproducibilidad de selectores/screenshots y menor superficie de fingerprinting (un
  viewport común y consistente es menos señalable que uno aleatorio por sesión).
- Implementación: `script-navegador launch --width 1366 --height 768` (flags `--window-size` a
  Chrome). Nunca lanzar sin tamaño definido.

## 2. Carpeta de usuario dedicada del proyecto

Siempre se define un `user-data-dir` propio del proyecto, nunca el perfil real del usuario por
defecto (evita locks y contaminación de la sesión personal).

- Ruta por defecto: `~/.local/share/web_scraping/chrome-profile`.
- Implementación: `script-navegador launch --profile <dir>` (default ya apunta ahí).
- El perfil es persistente entre ejecuciones (cookies, login, estado de extensiones).

## 3. Flujo headless: primero visible, luego headless

Se empieza desarrollando **con ventana visible** (`headless=false`) para ver lo que pasa y depurar
selectores junto al humano. Solo cuando un flujo está estandarizado y probado se pasa a
`headless=true` para correrlo desatendido/en lote.

- Default de `launch`: `headless=false`.
- Promoción a headless: pasar `--headless` una vez el script YAML del flujo es estable.

## 4. Esperas inteligentes + pequeños sleeps aleatorios

Nunca `sleep` ciegos fijos como mecanismo de sincronización. Se espera a **condiciones reales**:

- `readyState=complete` (`cdp_wait_load`).
- **Red en reposo** (`cdp_wait_idle`): nº de peticiones HTTP/WS en vuelo == 0 durante N ms
  (señal "network idle"). Es inmune a extensiones que mutan el DOM y a animaciones JS. Timeout
  corto (8s) porque páginas con polling/websockets persistentes pueden no llegar nunca a 0.
- Selector presente (`cdp_wait_element`).

Sobre esas esperas se añaden **micro-pausas aleatorias < 500 ms** (`jitter`) entre acciones, para
imitar el ritmo humano (anti-detección). El random es complemento, no sustituto, de la espera real.

> Histórico: `cdp_wait_idle` usó al principio la longitud de `innerHTML` como señal de quietud,
> pero con extensiones como Dark Reader (que reinyecta estilos sin parar) el DOM nunca se
> estabilizaba y la espera agotaba siempre el timeout. Por eso se migró a network-idle.

## 5. Captura de datos vía extensión mitm (web_proxy)

El tráfico se puede capturar con la infraestructura `web_proxy` (mitmproxy + extensión de toggle
ya presente en `/etc/chromium.d/`). Por eso los navegadores se lanzan con `--keep-extensions`
(no `--disable-extensions`): la extensión de captura debe seguir cargada.

- mitmweb corre en `127.0.0.1:8081`; el proxy de captura en `:8889`.
- Las capturas rotan a `~/captures` (ver `rotate_capture_flows.py`).
- El toggle del proxy es per-perfil; activarlo en el perfil del proyecto cuando se quiera capturar.

## 6. Movimientos de ratón + clics realistas

Las interacciones (click, drag) deben simular trayectorias humanas (curvas, aceleración, micro-
desvíos), no saltos instantáneos a coordenadas. **Stack decidido: Go puro** — curvas Bézier sobre
`Input.dispatchMouseEvent` como funciones del registry (`cdp_move_mouse_human`, `cdp_click_human`),
sin dependencias externas. **Integrado y por defecto** (script_navegador v0.2.0): el comando `click` y
la acción `click` del runner YAML usan Bézier sin pedir nada. Opt-out con `--instant` (CLI) o
`instant: true` (paso YAML) cuando el elemento no tiene bounding box visible y conviene el click directo.

## 7. Proxys rotativos (Decodo) — futuro

Más adelante se integrarán proxys residenciales rotativos con **Decodo** (antes Smartproxy) para
distribuir las peticiones y evitar bloqueos por IP. Pendiente de implementar (ver
`## Pendientes`).

## 8. CDP siempre activo en el navegador del usuario — futuro / decisión de seguridad

Objetivo: poder usar las capacidades de automatización sobre el **chromium que el usuario usa a
diario** mientras navega, modificando el launcher (`/etc/chromium.d/`) para que todo chromium
nazca con CDP activado.

**APLICADO** (2026-06-05): fragmento `/etc/chromium.d/cdp` con
`--remote-debugging-port=9222 --remote-allow-origins=*`, **sin** `--remote-debugging-address=0.0.0.0`
→ el puerto bindea solo en loopback (127.0.0.1), no accesible desde la red. Todo chromium que el
usuario abra a partir de ahora nace con CDP. (El chromium ya abierto antes del cambio no tiene CDP
hasta reiniciarlo.)

Reproducible entre PCs con la función del registry `apply_chromium_cdp_flag_bash_browser` (no
editar el fragmento a mano):

```bash
fn run apply_chromium_cdp_flag                 # escribe /etc/chromium.d/cdp (loopback 9222, idempotente)
fn run apply_chromium_cdp_flag --dry-run       # previsualiza sin tocar nada
fn run apply_chromium_cdp_flag --remove        # desactiva CDP global
# --network añade --remote-debugging-address=0.0.0.0 (expone a la red: riesgo, ver Gotchas)
```

> Coordinación de puertos: el chromium diario ocupa el 9222 global. Para sesiones de automatización
> con perfil dedicado, lanzar en OTRO puerto: `script-navegador launch --port 9333`. Dos procesos
> chromium no pueden compartir el mismo `--remote-debugging-port`.

> ⚠️ Implicación de seguridad: con CDP abierto, **cualquier proceso local del usuario** puede
> controlar el navegador y leer cookies/sesiones autenticadas. El bind solo-local evita acceso
> desde la red, pero NO protege de procesos locales. Aceptado conscientemente para este equipo
> de un solo usuario. No replicar en máquinas compartidas/multiusuario.

## 9. Perfiles nuevos: solo uBlock Origin Lite

Al **preparar un perfil de usuario nuevo** para automatización (clonando del perfil real del
usuario), se conserva **únicamente uBlock Origin Lite** (`ddkjiahejlhfcafbddmgiahcphecmpfh`) y se
eliminan el resto de extensiones del usuario.

- Motivo: uBlock reduce ruido (anuncios, trackers) → páginas más limpias y rápidas de scrapear.
  Las demás estorban la automatización:
  - **Dark Reader**: reinyecta estilos sin parar → rompe esperas por DOM y oscurece screenshots.
  - **NoScript**: bloquea JavaScript → rompe SPAs y scraping de contenido dinámico.
  - **OneTab**: interfiere con la gestión de pestañas.
- La extensión de captura `web_proxy` es **aparte**: se carga globalmente vía `/etc/chromium.d/`
  (no es una extensión del perfil), por lo que esta regla no la toca. uBlock + web_proxy conviven.

### Dos mecanismos (sistema + clonado)

1. **Política de sistema (primario)** — `/etc/chromium/policies/managed/extensions.json` con
   `ExtensionInstallForcelist` fuerza la instalación de extensiones en **cualquier perfil** de
   chromium del equipo. Reducido el 2026-06-05 a **solo uBlock Origin Lite**
   (`ddkjiahejlhfcafbddmgiahcphecmpfh`). Antes forzaba 4 (uBlock + Dark Reader + NoScript +
   OneTab). Esto garantiza que todo perfil nuevo —lo cree quien lo cree— nazca solo con uBlock,
   sin pasos extra. Backup del original en `extensions.json.bak.20260605`.
   - ⚠️ Afecta también el perfil diario del usuario: al reiniciar chromium, las extensiones que
     ya no están en la forcelist se desinstalan.
   - Editar requiere `sudo` (`pass claude/sudo`).
   - Reproducible entre PCs con la función del registry `apply_chromium_extension_policy_bash_browser`
     (no editar el JSON a mano): escribe la forcelist de forma idempotente con backup automático.

     ```bash
     # Forzar solo uBlock Origin Lite en todos los perfiles
     fn run apply_chromium_extension_policy --keep ddkjiahejlhfcafbddmgiahcphecmpfh
     fn run apply_chromium_extension_policy --keep ddkjiahejlhfcafbddmgiahcphecmpfh --dry-run
     ```

2. **Clonado con filtro (secundario)** — `prepare_chrome_profile --src ~/.config/chromium
   --dst <perfil_proyecto>` clona un perfil existente (cookies, sesiones) conservando solo la
   whitelist de extensiones (`--keep <id>`, default uBlock). Útil cuando se quiere arrancar de
   una copia del perfil real; la base de extensiones ya la garantiza la política de sistema.

---

## Pendientes (decisiones abiertas)

| # | Tema | Estado |
|---|---|---|
| 7 | Proxys rotativos con Decodo | Futuro, sin empezar |

## Estado de implementación

| Regla | Estado | Dónde |
|---|---|---|
| 1. Tamaño de ventana fijo | ✅ | `script-navegador launch --width/--height` (default 1366x768) |
| 2. Carpeta de usuario del proyecto | ✅ | `--profile` (default `~/.local/share/web_scraping/chrome-profile`) |
| 3. Flujo headless visible→true | ✅ convención | `launch` default `headless=false` |
| 4. Esperas inteligentes + jitter | ✅ | `cdp_wait_load`+`cdp_wait_idle` (network-idle)+`jitter()` |
| 5. Captura mitm | ✅ infra | `--keep-extensions` + `web_proxy` |
| 6. Ratón/clics realistas | ✅ | `cdp_move_mouse_human` + `cdp_click_human`; default en `script-navegador click` y runner YAML (opt-out `--instant` / `instant: true`) |
| 7. Proxys rotativos Decodo | ⏳ | futuro |
| 8. CDP global en chromium usuario | ✅ | `/etc/chromium.d/cdp` aplicado (loopback 9222) |
| 9. Perfiles nuevos solo uBlock | ✅ | `prepare_chrome_profile --src ~/.config/chromium --dst <perfil>` |