refactor: implement full remediation plan

- Rewrite .gitignore from scratch (was corrupted with null bytes)
- Purge sensitive/generated files from git history via filter-branch
- Remove dead code: checkpoint.py, test_checkpoint.py, unused config key
- Fix session.py: release lock before sleeping in _enforce_min_interval
- Fix index.py: cache DataFrame to avoid re-reading Excel per batch
- Fix worker.py: add logging.exception, use urlencode for URLs
- Fix gui.py: correct slider defaults, rename retry_delay var, consistent formatting
- Update README: Python 3.13, document GUI/headless/config.yaml
- Split dev deps into requirements-dev.txt
- Change output.dir to output/ and create directory
- Add tests/__init__.py and new tests for caching + lock behavior

All 44 tests pass.

Author: codedrifter-mx

.gitignore

@@ -1,33 +1,99 @@
-# Web Scrapper de servidorespublicos.gob.mx
+# Auto-Servidores
 
-Un script de Python que consulta y verifica si los servidores públicos tienen declaración anual actualizada.
+Herramienta Python para consultar de forma masiva el API de DeclaraNet y verificar si los servidores públicos tienen declaraciones anuales actualizadas.
 
 ## Requisitos
 
-* Python 3.10
-* Última versión de Chrome
-* Windows (Linux pendiente)
+- **Python 3.13**
+- Windows, Linux o macOS
 
-## Uso del script
+## Instalación
 
-1. Instala las librerías:
-`
-pip install -r requirements.txt
-`
+1. Clona el repositorio y entra al directorio:
+   ```bash
+   git clone <url-del-repo>
+   cd auto-servidores
+   ```
 
-2. Coloca tus archivos Excel de origen dentro de la carpeta /seed, la 1ª columna debe ser "Nombres", la 2ª debe ser "RFC", de lo contrario fallará
+2. Crea un entorno virtual (recomendado):
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # Linux/macOS
+   venv\Scripts\activate     # Windows
+   ```
 
-3. Ejecuta:
-`
-python .\main.py
-`
+3. Instala las dependencias:
+   ```bash
+   pip install -r requirements.txt
+   ```
 
-## Cómo funciona
-El script lee los nombres y RFCs desde seed.xlsx, navega al sitio web de servidorespublicos.gob.mx, e intenta encontrar y descargar los documentos de declaración anual de cada servidor público listado. Utiliza Chrome en modo headless para navegar el sitio, lo que significa que Chrome se ejecuta en segundo plano sin una ventana visible.
+Para desarrollo y pruebas, instala también:
+```bash
+pip install -r requirements-dev.txt
+```
+
+## Uso
+
+### Modo GUI (recomendado)
+
+```bash
+python gui.py
+```
+
+Abre una interfaz gráfica donde puedes:
+- Arrastrar o seleccionar archivos Excel de origen
+- Ajustar tamaño de lote, trabajadores máximos y parámetros de rate limit
+- Ver logs en tiempo real y barra de progreso
+
+### Modo headless (sin GUI)
+
+```bash
+python main.py --no-gui
+```
+
+## Formato de archivos de origen
+
+Coloca tus archivos Excel (`.xlsx`) dentro de la carpeta `seed/`.
+
+**No deben tener fila de encabezado.** La primera columna debe contener los nombres y la segunda columna los RFCs.
+
+| A | B |
+|---|---|
+| JUAN PEREZ GARCIA | BEGX123456X01 |
+| MARIA LOPEZ HDEZ | BEGX654321X02 |
+
+## Configuración
+
+Todos los parámetros son configurables desde `config.yaml`:
+
+- `api.base_url`: URL base del servicio DeclaraNet
+- `api.max_retries` / `api.retry_base_delay`: Reintentos y espera exponencial
+- `rate_limit.max_concurrent`: Conexiones simultáneas máximas
+- `rate_limit.min_interval`: Intervalo mínimo entre requests
+- `rate_limit.cooldown_base` / `cooldown_max`: Backoff exponencial al recibir 429
+- `processing.batch_size`: Tamaño de lote para leer del Excel
+- `processing.max_workers`: Tareas concurrentes máximas
+- `output.dir`: Carpeta de salida (por defecto `output/`)
 
 ## Salida
-El script creará dos archivos Excel:
 
-ENCONTRADAS.xlsx: Contiene los detalles de los servidores públicos cuyas declaraciones fueron encontradas y descargadas exitosamente.
-NO_ENCONTRADAS.xlsx: Contiene los detalles de los servidores públicos cuyas declaraciones no fueron encontradas.
-Cada archivo incluirá los nombres, RFCs y otros detalles relevantes extraídos durante el proceso de scraping.
+El programa genera dos archivos Excel por cada archivo de origen:
+
+- `{nombre}_ENCONTRADOS.xlsx`: Servidores con declaraciones encontradas
+- `{nombre}_NO_ENCONTRADOS.xlsx`: Servidores no encontrados o sin declaración
+
+Los archivos se guardan en la carpeta configurada en `output.dir`.
+
+## Caché
+
+Las respuestas del API se almacenan en SQLite (`.cache/api_cache.db`) con TTL configurable. Esto acelera re-ejecuciones y reduce la carga sobre el servidor.
+
+## Tests
+
+```bash
+pytest tests/ -v
+```
+
+## Licencia
+
+Uso interno. El proyecto consulta datos públicos de servidores públicos mexicanos a través de la plataforma DeclaraNet.

README.md

@@ -4,12 +4,19 @@ api:
     search: /declaranet/consulta-servidores-publicos/buscarsp
     history: /declaranet/consulta-servidores-publicos/historico
   default_coll_name: 100
-  timeout: 30
-  max_retries: 3
+  timeout: 60
+  max_retries: 5
+  retry_base_delay: 2.0
 cache:
   enabled: true
   db_path: .cache/api_cache.db
   ttl_seconds: 3600
+rate_limit:
+  max_concurrent: 10
+  min_interval: 0.15
+  cooldown_base: 5.0
+  cooldown_max: 60.0
+  inter_batch_delay: 1.5
 filters:
   years_to_check:
   - 2025
@@ -18,10 +25,9 @@ filters:
     tipoDeclaracion: MODIFICACION
     institucionReceptora: INSTITUTO MEXICANO DEL SEGURO SOCIAL
 processing:
-  batch_size: 200
-  max_workers: 200
-  checkpoint_interval: 25
+  batch_size: 25
+  max_workers: 10
 output:
-  dir: .
+  dir: output/
   found_suffix: _ENCONTRADOS
   not_found_suffix: _NO_ENCONTRADOS