# CLAUDE.md — Convenciones del proyecto

Servicio Python de **descarga de comprobantes electrónicos (CPE) desde Sovos/SUNAT**.
Sigue la estructura de la plantilla `~/Desarrollo/Python/plantilla-servicio/`.

## Estructura

```
main.py            # entrada delgada: while loop dirigido por scheduler.json, llama ejecutar()
core.py            # pipeline funcional: describir_servicio/obtener_datos/procesar_y_descargar/ejecutar
scheduler.py       # reutilizable (franja activa / próximo inicio a partir de scheduler.json)
logger_manager.py  # reutilizable (logging niveles + árbol; TimedRotatingFileHandler 30 días)
hana_manager.py    # reutilizable (HANA multi-schema, obtener_pendientes, marcar)
descargador_sovos.py  # específico: descarga PDF/XML en Sovos con Playwright (Firefox)
smb_transfer.py    # reutilizable (detectar/montar SMB + rsync por empresa)
config.json        # hana, rucs, consulta.dias, empresas(locked), files
scheduler.json     # HORARIOS ([hora_ini,min_ini,hora_fin,min_fin,modo]) + DIAS_ACTIVOS
.env               # SMB_* + SMB_AUTO_MOUNT + LOG_LEVEL

Dockerfile                    # imagen (Playwright+Firefox ya incluidos, CA Fortinet, rsync)
docker-compose.yml            # servicio `descarga-cpe` persistente (restart: unless-stopped)
certs/fortinet-root.crt       # CA de inspección SSL de la red (FG100FTK22018356)
```

## Reglas
1. Empresas en `config.json` con `{ nombre, schema, locked, smb_subfolder }`.
   `locked: true` = no ejecutar. Descargas en `downloads/<nombre>/`.
2. Credenciales en `.env`, nunca en git.
3. Logging con `logger_manager.get_logger(...)` y niveles info/warning/error (sin `print`).
4. `core.py` es funcional (sin clases): cada servicio reescribe `describir_servicio()`,
   `obtener_datos(empresa)` y `procesar_y_descargar(datos, dir_empresa)`;
   `main.py` siempre delgado (solo llama a `ejecutar()`; no reescribe lógica de
   negocio — su única lógica propia es el loop/scheduler de la regla 8).
5. Después de descargar PDF/XML se marca en HANA (`U_PGX_PDF`/`U_PGX_XML`) por schema.
6. Transferencia con `smb_transfer.transferir_a_smb(...)`; si el SMB no está montado
   conserva los archivos (no los borra).
7. Verificar: `python -m py_compile main.py core.py scheduler.py hana_manager.py descargador_sovos.py smb_transfer.py logger_manager.py`
   y correr `docker compose up -d descarga-cpe` (revisar con `docker compose logs -f`).
8. **Solo Docker, servicio persistente** (no hay venv nativa ni LaunchAgent/cron del
   HOST en el proyecto): `docker-compose.yml` usa `restart: unless-stopped` y
   `main.py` mantiene un `while` continuo — en cada ciclo llama a `ejecutar()`
   (pipeline de `core.py`) y luego duerme según el modo de la franja horaria activa.
   `scheduler.py` lee `scheduler.json` (releído en cada ciclo, así se pueden editar
   horarios sin reiniciar el contenedor) y responde:
     - si el día/hora actual cae dentro de una franja de `HORARIOS`, su `modo`
       (`"rapido"` → dormir 10 min, `"full"` → dormir 1 hora; mapeo fijo en
       `INTERVALOS_POR_MODO` dentro de `scheduler.py`, no en el JSON);
     - si no, el inicio de la próxima franja activa (respetando `DIAS_ACTIVOS`),
       y `main.py` duerme exactamente hasta ese instante.
   El sueño se hace en pasos de 1s (`_dormir_interrumpible`) y `main.py` registra
   handlers de `SIGINT`/`SIGTERM` para poder frenar el loop y salir limpio ante
   `docker compose stop/down`, en vez de que Docker tenga que matarlo por timeout.
   Una excepción no controlada en un ciclo se loguea (`exc_info=True`, va a
   `logs/descarga-cpe.log` con su rotación de 30 días) y el loop reintenta tras
   60s — ya no hay cron externo que reintente por nosotros.
   Como el contenedor ya no es efímero, `docker-compose.yml` limita el driver
   `json-file` de Docker (`max-size: 10m`, `max-file: 5`) para que el log propio
   del contenedor (stdout) no crezca sin límite; esto es independiente de la
   rotación de `logs/descarga-cpe.log`, que maneja `logger_manager.py`.
9. `scheduler.json` define `HORARIOS` (lista de `[hora_ini, min_ini, hora_fin,
   min_fin, modo]`, `modo` es `"rapido"` o `"full"`) y `DIAS_ACTIVOS` (0=lunes …
   6=domingo, según `datetime.weekday()`). Fuera de esas franjas y días no se
   ejecuta nada.
10. Bloqueos de red (FortiGuard Web Filter, p.ej. categoría "Finance and Banking" en
    `public-einvoicing.sovos.com`) no son bug de la app: se resuelven en el FortiGate,
    no reintentando ni parcheando el código.