Upload 2 files

app.py

@@ -64,6 +64,8 @@ def run_pipeline(
     entry_wait_ms: int,
     lang: str,
     send_telegram: bool,
+    diagnostic_mode: bool,
+    stop_on_first_block: bool,
     probably_rented_threshold: int,
     not_seen_threshold: int,
 ) -> tuple[str, str | None, str | None, str | None, str]:
@@ -91,11 +93,18 @@ def run_pipeline(
             wait_ms=int(wait_ms),
             entry_wait_ms=int(entry_wait_ms),
             lang=lang,
+            diagnostic_mode=bool(diagnostic_mode),
+            stop_on_first_block=bool(stop_on_first_block),
             log_fn=lambda msg: _append_log(logs, msg),
         )
         current_xlsx = scrape_result["current_xlsx"]
         df = scrape_result["dataframe"]
         districts_queried = scrape_result.get("districts_queried", [])
+        run_status = scrape_result.get("run_status", "unknown")
+        blocked_entries_count = int(scrape_result.get("blocked_entries_count", 0))
+        zero_real_result_entries_count = int(scrape_result.get("zero_real_result_entries_count", 0))
+        unknown_empty_entries_count = int(scrape_result.get("unknown_empty_entries_count", 0))
+        skip_neon = bool(diagnostic_mode) or (blocked_entries_count > 0 and len(df) == 0)
 
         debug_zip = zip_debug_folder(output_dir)
         if debug_zip:
@@ -106,7 +115,16 @@ def run_pipeline(
         
 
         _append_log(logs, "[2/6] Preparando persistencia incremental en Neon...")
-        if get_database_url():
+        if skip_neon:
+            stats = {
+                "inserted": 0, "updated": 0, "unchanged": 0, "reactivated": 0,
+                "missing_updated": 0, "probably_rented": 0, "snapshots": 0,
+            }
+            if diagnostic_mode:
+                _append_log(logs, "[DIAG] Modo diagnóstico activo: se omite Neon.")
+            else:
+                _append_log(logs, "[BLOCK] Se omite Neon porque hubo bloqueo y no se obtuvieron anuncios reales.")
+        elif get_database_url():
             with connect() as conn:
                 run_id = create_run(
                     conn,
@@ -121,6 +139,12 @@ def run_pipeline(
                         "space_runtime": "huggingface-docker",
                         "probably_rented_threshold": probably_rented_threshold,
                         "not_seen_threshold": not_seen_threshold,
+                        "diagnostic_mode": diagnostic_mode,
+                        "stop_on_first_block": stop_on_first_block,
+                        "run_status": run_status,
+                        "blocked_entries_count": blocked_entries_count,
+                        "zero_real_result_entries_count": zero_real_result_entries_count,
+                        "unknown_empty_entries_count": unknown_empty_entries_count,
                     },
                 )
                 stats = upsert_listings(
@@ -131,7 +155,7 @@ def run_pipeline(
                     probably_rented_threshold=int(probably_rented_threshold),
                     not_seen_threshold=int(not_seen_threshold),
                 )
-                finish_run(conn, run_id, stats, status="success")
+                finish_run(conn, run_id, stats, status="partial_blocked" if blocked_entries_count else "success")
 
                 incremental_xlsx = str(output_dir / f"base_incremental_idealista_neon_{ts}.xlsx")
                 export_incremental_excel(conn, incremental_xlsx)
@@ -157,8 +181,12 @@ def run_pipeline(
         _append_log(logs, "[3/6] Archivos Excel generados.")
         summary = (
             "Consulta Idealista finalizada.\n"
+            f"Estado técnico: {run_status}\n"
             f"Anuncios encontrados: {len(df)}\n"
             f"Distritos consultados: {len(districts_queried)}\n"
+            f"Bloqueos DataDome: {blocked_entries_count}\n"
+            f"Cero resultados reales: {zero_real_result_entries_count}\n"
+            f"Páginas vacías desconocidas: {unknown_empty_entries_count}\n"
             f"Nuevos insertados: {stats.get('inserted', 0)}\n"
             f"Actualizados: {stats.get('updated', 0)}\n"
             f"Reactivados: {stats.get('reactivated', 0)}\n"
@@ -181,8 +209,12 @@ def run_pipeline(
 
         status_md = (
             "### Resultado\n"
+            f"- **Estado técnico:** {run_status}\n"
             f"- **Anuncios encontrados:** {len(df)}\n"
             f"- **Distritos consultados:** {len(districts_queried)}\n"
+            f"- **Bloqueos DataDome:** {blocked_entries_count}\n"
+            f"- **Cero resultados reales:** {zero_real_result_entries_count}\n"
+            f"- **Páginas vacías desconocidas:** {unknown_empty_entries_count}\n"
             f"- **Nuevos insertados en Neon:** {stats.get('inserted', 0)}\n"
             f"- **Actualizados en Neon:** {stats.get('updated', 0)}\n"
             f"- **Reactivados:** {stats.get('reactivated', 0)}\n"
@@ -262,6 +294,14 @@ def build_app() -> gr.Blocks:
         
                 lang = gr.Dropdown(label="Idioma URL", choices=["es", "pt"], value="es")
                 send_telegram = gr.Checkbox(label="Enviar resultados por Telegram", value=True)
+                diagnostic_mode = gr.Checkbox(
+                    label="Modo diagnóstico: no persistir en Neon aunque haya base configurada",
+                    value=True,
+                )
+                stop_on_first_block = gr.Checkbox(
+                    label="Cortar corrida completa al primer bloqueo DataDome",
+                    value=True,
+                )
 
         with gr.Accordion("Parámetros de desplazamiento", open=False):
             gr.Markdown("La categoría de velocidad se calcula cuando el anuncio llega a `probably_rented`: 1 corrida visible = muy rápido; 2-3 = rápido; 4-6 = normal; 7-10 = lento; 11+ = muy lento. Este criterio está calibrado para ejecución cada tercer día.")
@@ -297,6 +337,8 @@ def build_app() -> gr.Blocks:
                 entry_wait_ms,
                 lang,
                 send_telegram,
+                diagnostic_mode,
+                stop_on_first_block,
                 probably_rented_threshold,
                 not_seen_threshold,
             ],

scraper.py

@@ -380,6 +380,62 @@ def detect_block_status(html: str, body_text: str = "") -> dict:
     }
 
 
+
+
+def classify_page_state(diagnosis: dict) -> str:
+    """Clasifica la página sin confundir bloqueo con cero resultados reales."""
+    flags = diagnosis.get("flags", {}) or {}
+    selector_counts = diagnosis.get("selector_counts", {}) or {}
+    positive_selectors = sum(1 for v in selector_counts.values() if isinstance(v, int) and v > 0)
+
+    if flags.get("blocked") or flags.get("datadome") or flags.get("captcha_iframe"):
+        return "blocked_datadome"
+    if flags.get("access"):
+        return "access_denied"
+    if positive_selectors > 0:
+        return "ok_listings"
+    if flags.get("no_results"):
+        return "zero_real_results"
+    return "unknown_empty_page"
+
+
+def make_diagnostic_row(
+    *,
+    entry_index: int | None,
+    input_url: str,
+    page_no: int,
+    diagnosis: dict,
+    status: str,
+    html_path: str | None = None,
+    png_path: str | None = None,
+) -> dict:
+    flags = diagnosis.get("flags", {}) or {}
+    counts = diagnosis.get("selector_counts", {}) or {}
+    return {
+        "ts_utc": datetime.now(timezone.utc).isoformat(),
+        "entry_index": entry_index,
+        "input_url": input_url,
+        "page_no": page_no,
+        "status": status,
+        "title": diagnosis.get("title"),
+        "final_url": diagnosis.get("url"),
+        "cookies": flags.get("cookies"),
+        "captcha": flags.get("captcha"),
+        "access": flags.get("access"),
+        "no_results": flags.get("no_results"),
+        "datadome": flags.get("datadome"),
+        "idealista_blocked": flags.get("idealista_blocked"),
+        "captcha_iframe": flags.get("captcha_iframe"),
+        "blocked": flags.get("blocked"),
+        "article_item_count": counts.get("article.item"),
+        "article_data_element_id_count": counts.get("article[data-element-id]"),
+        "item_info_container_count": counts.get(".item-info-container"),
+        "data_element_id_count": counts.get("[data-element-id]"),
+        "html_path": html_path,
+        "screenshot_path": png_path,
+        "body_sample": (diagnosis.get("body_text") or "")[:1200].replace("\n", " "),
+    }
+
 def diagnose_page(page, page_no, log_fn=print) -> dict:
     try:
         title = page.title()
@@ -477,27 +533,48 @@ def wait_for_list_or_dump(
     debug_dir="debug",
     log_fn=print,
     debug_prefix: str | None = None,
-):
+    input_url: str | None = None,
+    entry_index: int | None = None,
+) -> dict:
+    """Espera listado o genera diagnóstico estructurado.
+
+    Devuelve un dict con status. Ya no devuelve True/False/"blocked",
+    porque eso impedía distinguir bloqueo, cero resultados reales y página vacía desconocida.
+    """
     debug_dir = Path(debug_dir)
     debug_dir.mkdir(parents=True, exist_ok=True)
 
     prefix = debug_prefix or "entry_unknown"
+    input_url = input_url or getattr(page, "url", None) or ""
 
     try:
         page.wait_for_selector(LISTING_SELECTOR_COMBINED, timeout=25000)
-        log_fn(f"[OK] Listado detectado en página {page_no}.")
-        return True
+        diagnosis = diagnose_page(page, page_no, log_fn=log_fn)
+        status = classify_page_state(diagnosis)
+        log_fn(f"[OK] Estado de página {page_no}: {status}.")
+        return {
+            "status": status,
+            "diagnosis": diagnosis,
+            "diagnostic_row": make_diagnostic_row(
+                entry_index=entry_index,
+                input_url=input_url,
+                page_no=page_no,
+                diagnosis=diagnosis,
+                status=status,
+            ),
+        }
 
     except PWTimeout:
         diagnosis = diagnose_page(page, page_no, log_fn=log_fn)
         html = diagnosis.get("html", "")
-        flags = diagnosis.get("flags", {})
+        status = classify_page_state(diagnosis)
 
         html_path = debug_dir / f"debug_{prefix}_page{page_no}.html"
         png_path = debug_dir / f"debug_{prefix}_page{page_no}.png"
+        json_path = debug_dir / f"debug_{prefix}_page{page_no}_diagnostic.json"
 
         try:
-            html_path.write_text(html, encoding="utf-8")
+            html_path.write_text(html, encoding="utf-8", errors="replace")
             log_fn(f"[DEBUG] HTML guardado en: {html_path}")
         except Exception as e:
             log_fn(f"[DEBUG] No se pudo guardar HTML debug: {e}")
@@ -508,13 +585,38 @@ def wait_for_list_or_dump(
         except Exception as e:
             log_fn(f"[DEBUG] No se pudo guardar screenshot: {e}")
 
-        if flags.get("blocked"):
+        row = make_diagnostic_row(
+            entry_index=entry_index,
+            input_url=input_url,
+            page_no=page_no,
+            diagnosis=diagnosis,
+            status=status,
+            html_path=str(html_path),
+            png_path=str(png_path),
+        )
+
+        try:
+            json_path.write_text(json.dumps(row, ensure_ascii=False, indent=2), encoding="utf-8")
+            log_fn(f"[DEBUG] Diagnóstico JSON guardado en: {json_path}")
+        except Exception as e:
+            log_fn(f"[DEBUG] No se pudo guardar diagnóstico JSON: {e}")
+
+        if status == "blocked_datadome":
             log_fn("[BLOCK] Idealista devolvió bloqueo/DataDome en lugar de listados.")
             log_fn("[BLOCK] Se detiene esta URL para no insistir contra el bloqueo.")
-            return "blocked"
+        elif status == "zero_real_results":
+            log_fn("[INFO] La página parece devolver cero resultados reales, no bloqueo.")
+        else:
+            log_fn(f"[WARN] Sin listado detectable en página {page_no}. Estado: {status}.")
 
-        log_fn(f"[WARN] Sin listado detectable en página {page_no}.")
-        return False
+        return {
+            "status": status,
+            "diagnosis": diagnosis,
+            "diagnostic_row": row,
+            "html_path": str(html_path),
+            "png_path": str(png_path),
+            "json_path": str(json_path),
+        }
 
 def get_next_url_from_page(page) -> str | None:
     a = page.query_selector('a[rel="next"]')
@@ -553,10 +655,13 @@ def fetch_pages_playwright(
     debug_dir: Path | None = None,
     log_fn: LogFn | None = None,
     entry_index: int | None = None,
-) -> list[dict]:
+) -> dict:
     items: list[dict] = []
+    diagnostics: list[dict] = []
     log = log_fn or print
     debug_path = debug_dir or Path("debug")
+    final_status = "unknown_empty_page"
+
     with sync_playwright() as p:
         browser = p.chromium.launch(headless=headless, args=["--disable-blink-features=AutomationControlled"])
         context = browser.new_context(
@@ -573,100 +678,125 @@ def fetch_pages_playwright(
         seen_urls: set[str] = set()
         seen_first_ids: set[str] = set()
 
-        for _ in range(1, max_pages + 1):
-            safe_goto(page, current_url, wait_until="domcontentloaded", timeout=30000)
-        
-            # Espera adicional para páginas dinámicas.
-            # Si Idealista deja peticiones abiertas, networkidle puede fallar;
-            # por eso no detenemos el scraper si falla esta espera.
-            try:
-                page.wait_for_load_state("networkidle", timeout=15000)
-            except Exception:
-                pass
-        
-            accept_cookies_if_needed(page, log_fn=log)
-                    
-            # Pequeña espera después de cookies, porque el modal puede ocultar resultados.
-            page.wait_for_timeout(2000)
-        
-            # Scroll progresivo para forzar carga de elementos diferidos/lazy load.
-            page.evaluate("window.scrollTo(0, document.body.scrollHeight * 0.25)")
-            page.wait_for_timeout(1000)
-        
-            page.evaluate("window.scrollTo(0, document.body.scrollHeight * 0.60)")
-            page.wait_for_timeout(1000)
-        
-            page.evaluate("window.scrollTo(0, document.body.scrollHeight * 0.95)")
-            page.wait_for_timeout(1500)
+        try:
+            for _ in range(1, max_pages + 1):
+                safe_goto(page, current_url, wait_until="domcontentloaded", timeout=30000)
 
-            curr_num = get_page_number_from_url(page.url)
-            debug_prefix = f"entry{entry_index}" if entry_index is not None else "entry_unknown"
-            
-            wait_status = wait_for_list_or_dump(
-                page,
-                curr_num,
-                debug_dir=debug_path,
-                log_fn=log,
-                debug_prefix=debug_prefix,
-            )
-            
-            if wait_status == "blocked":
-                log(f"[BLOCK] Se detiene la entrada {debug_prefix} por bloqueo Idealista/DataDome.")
-                return []
-            
-            if wait_status is False:
-                log(f"[WARN] Sin listado detectable en página {curr_num}. Se detiene este distrito.")
-                break
-            if page.url in seen_urls:
-                _log(log_fn, f"[STOP] URL repetida: {page.url}")
-                break
-            seen_urls.add(page.url)
+                try:
+                    page.wait_for_load_state("networkidle", timeout=15000)
+                except Exception:
+                    pass
 
-            batch = parse_listing_html(page.content())
-            if not batch:
-                _log(log_fn, f"[STOP] Página {curr_num} sin anuncios.")
-                break
+                accept_cookies_if_needed(page, log_fn=log)
+                page.wait_for_timeout(2000)
 
-            first_id = batch[0].get("listing_id")
-            if first_id and first_id in seen_first_ids:
-                _log(log_fn, f"[STOP] Primer listing repetido en p{curr_num}; posible bucle.")
-                break
-            if first_id:
-                seen_first_ids.add(first_id)
+                try:
+                    page.evaluate("window.scrollTo(0, document.body.scrollHeight * 0.25)")
+                    page.wait_for_timeout(1000)
+                    page.evaluate("window.scrollTo(0, document.body.scrollHeight * 0.60)")
+                    page.wait_for_timeout(1000)
+                    page.evaluate("window.scrollTo(0, document.body.scrollHeight * 0.95)")
+                    page.wait_for_timeout(1500)
+                except Exception as e:
+                    log(f"[DEBUG] No se pudo hacer scroll progresivo: {e}")
+
+                curr_num = get_page_number_from_url(page.url)
+                debug_prefix = f"entry{entry_index}" if entry_index is not None else "entry_unknown"
+
+                wait_result = wait_for_list_or_dump(
+                    page,
+                    curr_num,
+                    debug_dir=debug_path,
+                    log_fn=log,
+                    debug_prefix=debug_prefix,
+                    input_url=current_url,
+                    entry_index=entry_index,
+                )
+                page_status = wait_result.get("status", "unknown_empty_page")
+                diagnostics.append(wait_result.get("diagnostic_row", {"status": page_status, "input_url": current_url}))
 
-            for it in batch:
-                it["page_hint"] = curr_num
-                pos = it.get("position_in_page") or 0
-                # Supone 30 anuncios por página como aproximación operativa para ordenar globalmente.
-                it["global_position"] = ((curr_num - 1) * 30) + int(pos)
+                if page_status == "blocked_datadome":
+                    log(f"[BLOCK] Se detiene la entrada {debug_prefix} por bloqueo Idealista/DataDome.")
+                    final_status = "blocked_datadome"
+                    break
 
-            items.extend(batch)
-            _log(log_fn, f"[OK] Página {curr_num}: {len(batch)} anuncios.")
+                if page_status == "access_denied":
+                    log(f"[BLOCK] Se detiene la entrada {debug_prefix} por acceso denegado.")
+                    final_status = "access_denied"
+                    break
 
-            next_url = get_next_url_from_page(page)
-            if not next_url:
-                break
-            next_num = get_page_number_from_url(next_url)
-            if next_num <= curr_num:
-                _log(log_fn, f"[STOP] Paginación no avanza ({curr_num}→{next_num}).")
-                break
-            current_url = next_url
-            
-            base_wait = max(int(wait_ms), 5000)
-            jitter = random.uniform(0.70, 1.60)
-            real_wait_ms = int(base_wait * jitter)
-            
-            log(
-                f"[WAIT] Pausa entre páginas: {real_wait_ms / 1000:.1f}s "
-                f"(base={wait_ms}ms, jitter={jitter:.2f})."
-            )
-            
-            page.wait_for_timeout(real_wait_ms)
+                if page_status == "zero_real_results":
+                    log(f"[INFO] Cero resultados reales detectados en página {curr_num}.")
+                    final_status = "zero_real_results"
+                    break
 
-        context.close()
-        browser.close()
-    return items
+                if page_status != "ok_listings":
+                    log(f"[WARN] Sin listado detectable en página {curr_num}. Estado: {page_status}.")
+                    final_status = page_status
+                    break
 
+                if page.url in seen_urls:
+                    _log(log_fn, f"[STOP] URL repetida: {page.url}")
+                    final_status = "repeated_url"
+                    break
+                seen_urls.add(page.url)
+
+                batch = parse_listing_html(page.content())
+                if not batch:
+                    _log(log_fn, f"[STOP] Página {curr_num} con selector, pero sin anuncios parseables.")
+                    final_status = "parse_empty_after_selector"
+                    break
+
+                first_id = batch[0].get("listing_id")
+                if first_id and first_id in seen_first_ids:
+                    _log(log_fn, f"[STOP] Primer listing repetido en p{curr_num}; posible bucle.")
+                    final_status = "repeated_first_listing"
+                    break
+                if first_id:
+                    seen_first_ids.add(first_id)
+
+                for it in batch:
+                    it["page_hint"] = curr_num
+                    pos = it.get("position_in_page") or 0
+                    it["global_position"] = ((curr_num - 1) * 30) + int(pos)
+
+                items.extend(batch)
+                final_status = "ok_listings"
+                _log(log_fn, f"[OK] Página {curr_num}: {len(batch)} anuncios.")
+
+                next_url = get_next_url_from_page(page)
+                if not next_url:
+                    break
+                next_num = get_page_number_from_url(next_url)
+                if next_num <= curr_num:
+                    _log(log_fn, f"[STOP] Paginación no avanza ({curr_num}→{next_num}).")
+                    break
+                current_url = next_url
+
+                base_wait = max(int(wait_ms), 5000)
+                jitter = random.uniform(0.70, 1.60)
+                real_wait_ms = int(base_wait * jitter)
+
+                log(
+                    f"[WAIT] Pausa entre páginas: {real_wait_ms / 1000:.1f}s "
+                    f"(base={wait_ms}ms, jitter={jitter:.2f})."
+                )
+                page.wait_for_timeout(real_wait_ms)
+        finally:
+            context.close()
+            browser.close()
+
+    if items and final_status == "blocked_datadome":
+        final_status = "partial_blocked"
+    elif items:
+        final_status = "ok_listings"
+
+    return {
+        "items": items,
+        "status": final_status,
+        "diagnostics": diagnostics,
+        "pages_seen": len(diagnostics),
+    }
 
 def sanitize_filename(stem: str) -> str:
     return re.sub(r"[^a-zA-Z0-9_\-\.]+", "_", stem).strip("_") or "consulta"
@@ -718,6 +848,8 @@ def run_scrape_job(
     wait_ms: int = 30000,
     entry_wait_ms: int = 90000,
     lang: str = DEFAULT_LANG,
+    diagnostic_mode: bool = False,
+    stop_on_first_block: bool = True,
     log_fn: LogFn | None = None,
 ) -> dict:
     input_xlsx_path = Path(input_xlsx_path)
@@ -732,8 +864,15 @@ def run_scrape_job(
         raise ValueError("El Excel de entrada no contiene URLs ni slugs válidos en la primera columna.")
 
     _log(log_fn, f"[INFO] Entradas detectadas: {len(entries)}")
+    if diagnostic_mode:
+        _log(log_fn, "[DIAG] Modo diagnóstico activo: se generará evidencia y app.py evitará persistencia.")
+
     master: list[dict] = []
     districts_queried: list[str] = []
+    diagnostics_rows: list[dict] = []
+    blocked_entries: list[str] = []
+    zero_real_result_entries: list[str] = []
+    unknown_empty_entries: list[str] = []
     per_district_dir = output_dir / "out_por_distrito"
     per_district_dir.mkdir(parents=True, exist_ok=True)
 
@@ -743,11 +882,11 @@ def run_scrape_job(
             _log(log_fn, f"[WARN] Entrada vacía o inválida: {entry!r}")
             continue
         district_slug = extract_slug_from_url(base_url)
-        
+
         safe_stem = sanitize_filename(district_slug)
         _log(log_fn, f"\n[RUN] {idx}/{len(entries)} · {entry} → {base_url}")
 
-        data = fetch_pages_playwright(
+        fetch_result = fetch_pages_playwright(
             base_url,
             max_pages=max_pages,
             wait_ms=wait_ms,
@@ -757,13 +896,22 @@ def run_scrape_job(
             log_fn=log_fn,
             entry_index=idx,
         )
-        if data:
+        data = fetch_result.get("items", [])
+        entry_status = fetch_result.get("status", "unknown_empty_page")
+        diagnostics_rows.extend(fetch_result.get("diagnostics", []))
+
+        if entry_status == "blocked_datadome":
+            blocked_entries.append(district_slug)
+            _log(log_fn, f"[BLOCK] El distrito {district_slug} queda como blocked_datadome; NO se marca como consultado.")
+        elif entry_status == "zero_real_results":
+            zero_real_result_entries.append(district_slug)
+            districts_queried.append(district_slug)
+            _log(log_fn, f"[INFO] El distrito {district_slug} sí se marca como consultado: cero resultados reales.")
+        elif data:
             districts_queried.append(district_slug)
         else:
-            _log(
-                log_fn,
-                f"[WARN] El distrito {district_slug} no se marcará como consultado porque no se obtuvieron anuncios."
-            )
+            unknown_empty_entries.append(district_slug)
+            _log(log_fn, f"[WARN] El distrito {district_slug} no se marcará como consultado. Estado: {entry_status}.")
 
         scraped_at = datetime.now(timezone.utc).isoformat()
         for it in data:
@@ -778,36 +926,73 @@ def run_scrape_job(
         district_df.to_csv(per_district_dir / f"idealista_{safe_stem}_{ts}.csv", index=False, encoding="utf-8")
         district_df.to_excel(per_district_dir / f"idealista_{safe_stem}_{ts}.xlsx", index=False)
         master.extend(data)
-        
+
+        if entry_status == "blocked_datadome" and stop_on_first_block:
+            _log(log_fn, "[BLOCK] stop_on_first_block=True: se corta la corrida completa.")
+            break
+
         if idx < len(entries):
             base_sleep = max(int(entry_wait_ms), 30000) / 1000
             jitter = random.uniform(0.75, 1.50)
             sleep_seconds = base_sleep * jitter
-        
+
             _log(
                 log_fn,
                 f"[WAIT] Pausa entre URLs/distritos: {sleep_seconds:.1f}s "
                 f"(base={entry_wait_ms}ms, jitter={jitter:.2f})."
             )
-        
+
             time.sleep(sleep_seconds)
 
     master_df = clean_dataframe(pd.DataFrame(master)) if master else clean_dataframe(pd.DataFrame())
+    diagnostics_df = pd.DataFrame(diagnostics_rows)
     current_xlsx = output_dir / f"{name_no_ext}_consulta_actual_{ts}.xlsx"
     current_csv = output_dir / f"{name_no_ext}_consulta_actual_{ts}.csv"
     current_json = output_dir / f"{name_no_ext}_consulta_actual_{ts}.json"
+    diagnostics_csv = output_dir / f"{name_no_ext}_diagnostico_{ts}.csv"
+    diagnostics_json = output_dir / f"{name_no_ext}_diagnostico_{ts}.json"
+
+    with pd.ExcelWriter(current_xlsx, engine="openpyxl") as writer:
+        master_df.to_excel(writer, index=False, sheet_name="consulta_actual")
+        diagnostics_df.to_excel(writer, index=False, sheet_name="diagnostico_corrida")
 
-    master_df.to_excel(current_xlsx, index=False)
     master_df.to_csv(current_csv, index=False, encoding="utf-8")
     current_json.write_text(json.dumps(master, ensure_ascii=False, indent=2), encoding="utf-8")
+    diagnostics_df.to_csv(diagnostics_csv, index=False, encoding="utf-8")
+    diagnostics_json.write_text(json.dumps(diagnostics_rows, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    if blocked_entries and not master:
+        run_status = "blocked_datadome"
+    elif blocked_entries and master:
+        run_status = "partial_blocked"
+    elif zero_real_result_entries and not master:
+        run_status = "zero_real_results"
+    elif unknown_empty_entries and not master:
+        run_status = "unknown_empty_page"
+    else:
+        run_status = "success"
+
     _log(log_fn, f"\n[OK] Consulta finalizada. Anuncios encontrados: {len(master_df)}")
+    _log(log_fn, f"[DIAG] Estado de corrida: {run_status}")
+    _log(log_fn, f"[DIAG] Bloqueos DataDome: {len(blocked_entries)}")
+    _log(log_fn, f"[DIAG] Cero resultados reales: {len(zero_real_result_entries)}")
 
     return {
         "timestamp": ts,
         "entries_count": len(entries),
         "rows_count": len(master_df),
         "dataframe": master_df,
+        "diagnostics_dataframe": diagnostics_df,
         "districts_queried": sorted(set(districts_queried)),
+        "run_status": run_status,
+        "blocked_entries": sorted(set(blocked_entries)),
+        "blocked_entries_count": len(set(blocked_entries)),
+        "zero_real_result_entries": sorted(set(zero_real_result_entries)),
+        "zero_real_result_entries_count": len(set(zero_real_result_entries)),
+        "unknown_empty_entries": sorted(set(unknown_empty_entries)),
+        "unknown_empty_entries_count": len(set(unknown_empty_entries)),
+        "diagnostics_csv": str(diagnostics_csv),
+        "diagnostics_json": str(diagnostics_json),
         "current_xlsx": str(current_xlsx),
         "current_csv": str(current_csv),
         "current_json": str(current_json),