hechakuaa_bot/CLAUDE.md

# Pedrito Hechakuaa — Instrucciones para Claude Code

## Qué es esto

Pedrito Hechakuaa: un bot de Telegram que monitorea notificaciones pendientes
en el sistema judicial de Paraguay (`apps.csj.gov.py`) y avisa cuando aparece
algo nuevo. Uso propio de un solo abogado (single-tenant).

**Scope estricto de la v0:**
- Login al PJ + polling de notificaciones pendientes
- Diff vs snapshot anterior → solo notifica lo nuevo
- Telegram como canal de salida
- Correr en local o VPS con docker-compose

**Fuera del scope de v0 (no agregar sin consulta explícita):**
- Motor de reglas de plazos
- LLM / conversación libre
- Multi-tenant
- Web de onboarding
- Actuaciones de expedientes (es v1)
- Acuse de notificaciones (nunca en MVP)

---

## ⚠️ Invariantes de seguridad — NUNCA se violan, aunque sea v0

```
✅ Credenciales cifradas con Fernet en .env — desencriptar en memoria, usar, descartar
✅ .env en .gitignore desde el primer commit
✅ Todo log pasa por scrub() en utils/sanitize.py antes de escribirse
✅ Audit trail mínimo: quién hizo qué, cuándo, resultado — SIN payload sensible
✅ El bot solo responde al TELEGRAM_CHAT_ID configurado (no es público)

❌ PUT /Notificaciones/{id}/recibir — NUNCA. Acusa notificaciones, efecto procesal irreversible
❌ Password, bearer token, o cualquier credencial en logs (ni en DEBUG)
❌ print() para debug — SIEMPRE usar logger
❌ .env con valores reales en el repo
```

**`scrub()`** (`from utils.sanitize import scrub`): función en `utils/sanitize.py` que recibe cualquier
string y reemplaza patrones sensibles (tokens, credenciales) antes de loggear.
Toda llamada a `logger.*()` con datos externos pasa por acá.

---

## Arquitectura

```
main.py               ← entrypoint, arranca bot + poller en paralelo
config.py             ← Settings via pydantic-settings (ÚNICA fuente de config)
csj_client.py         ← HTTP client del PJ (login + notificaciones, read-only)
poller.py             ← loop de polling + diff + dispara alertas
telegram_bot.py       ← envía mensajes y maneja /comandos básicos
storage.py            ← snapshot en JSON local (sin DB por ahora)
utils/
  sanitize.py         ← credential_scrubber() — NUNCA loggear sin pasar por acá
```

---

## Stack (sin cambios hasta nuevo aviso)

| Capa | Tecnología |
|------|-----------|
| Lenguaje | Python 3.12 con type hints estrictos |
| HTTP client | `httpx` async |
| Bot | `python-telegram-bot v21` async |
| Scheduler | `APScheduler 3` |
| Cifrado | `cryptography` (Fernet) |
| Config | `pydantic-settings` |
| Logging | `structlog` (JSON en prod, ConsoleRenderer en dev) |

Sin Playwright. Sin Postgres. Sin Redis. Sin LLM. Sin Docker por ahora (opcional).

**No introducir librerías fuera de esta lista sin justificación explícita.**

---

## Sistema judicial target

**URL base**: `https://apps.csj.gov.py`
**Docs**: `docs/reconocimiento/SISTEMA_NUEVO_RECON.md` y `MANUAL_SANITIZADO.md`

### Flujo de autenticación (confirmado por reconocimiento)

```
1. GET https://apps.csj.gov.py/login
   → Cookie: cookiesession1={hex32}

2. POST https://apps.csj.gov.py/autenticador/login
   Headers: Cookie: cookiesession1={hex32}
   Body JSON: {"usuario": "{cedula}", "clave": "{password}", "temporal": false}
   → bearerToken (TTL 1h), refreshToken, timestampExpiracionUtc

3. Todos los requests siguientes llevan:
   Cookie: cookiesession1={hex32}
   Authorization: Bearer {bearerToken}
   usuario-rol: 16   ← 16 = Abogados
```

### Endpoints de notificaciones (confirmados)

```
GET /api/gestion-partes/Notificaciones/CantidadNotificacionesPorRecibir
→ int (cantidad de notificaciones pendientes)

GET /api/gestion-partes/Notificaciones/PorRecibir?offset=0&cantidad=50
→ lista de NotificacionPendiente
```

### Campos relevantes de NotificacionPendiente

```json
{
  "codNotificacionOrigen": 1234567,
  "nroExpedienteNumero": 1234,
  "nroExpedienteAnio": 2024,
  "caratula": "Rodríguez c/ Municipalidad Capital",
  "descripcionActuacion": "Auto Interlocutorio",
  "descripcionTipoActuacion": "Providencia",
  "fecha": "2026-05-20",
  "juzgado": "1er Juzgado Civil Capital",
  "permisoFirmado": "JWT...",
  "codCasoJudicial": 103708,
  "origen": 0
}
```

---

## Estados de conversación

El bot es simple pero tiene estados implícitos que deben manejarse explícitamente:

```
UNREGISTERED          → usuario no autorizado (responder a cualquier message)
REGISTERED_IDLE       → autorizado, sin operación en curso (estado normal)
CHECKING              → revisión de notificaciones en curso (no disparar otra)
ERROR_AUTH            → fallo de auth del PJ (bot pausado hasta intervención)
ERROR_PASSWORD_TEMP   → password temporal detectada (bot pausado)
```

---

## Manejo de errores — mensajes accionables

**Nunca**: "Error inesperado" o mensajes técnicos al usuario.
**Siempre**: qué pasó + qué puede hacer el usuario.

| Situación | Mensaje al abogado |
|-----------|-------------------|
| Login fallido por credenciales | "No pude conectarme al PJ. Las credenciales podrían haber cambiado. Contactá al administrador." |
| Password temporal | "Tu contraseña del PJ es temporal. Cambiala en apps.csj.gov.py y luego reiniciá Pedrito Hechakuaa." |
| Error de red transitorio | "No pude conectarme al sistema judicial. Voy a reintentar en la próxima ronda ({hora})." |
| 5 errores consecutivos | "El sistema del PJ estuvo inaccesible por un tiempo. Si el problema persiste, revisá apps.csj.gov.py directamente." |

Emojis con criterio: ✅ éxito, ❌ error, ⚠️ advertencia, ⏳ procesando. No decorativos.

---

## Estructura del snapshot (storage.py)

JSON local en `data/snapshot.json`:
```json
{
  "last_check": "2026-05-20T10:00:00Z",
  "notificaciones_vistas": [1234567, 1234568, 1234569]
}
```
Solo guardamos los IDs (`codNotificacionOrigen`) ya notificados.
Diff: cualquier ID en la respuesta del PJ que no esté en esta lista = novedad.

---

## Comandos de Telegram

- `/start` — muestra estado del bot
- `/notif` — revisa notificaciones ahora (no espera al siguiente polling)
- `/estado` — último check, cantidad de notificaciones activas
- `/ayuda` — lista comandos
- `/exp <número>` — detalle de expediente por número (ej: `/exp 198` o `/exp 198/2026`)
- `/exp <texto>` — busca expedientes por carátula (ej: `/exp rodríguez`)

---

## Formato de mensajes al abogado

### Notificación proactiva nueva
```
📋 Nueva notificación judicial

{caratula}
Exp. {numero}/{anio} — {juzgado}

Tipo: {descripcionActuacion}
Fecha: {fecha formateada DD/MM/YYYY}

⚠️ Para acusar esta notificación entrá directamente
en https://apps.csj.gov.py
```

### Sin novedades (solo cuando el abogado lo pide con /notif)
```
✅ Sin novedades desde las {hora} de hoy.
Tenés {N} notificaciones pendientes en total.
```

---

## Iniciativa agéntica — clasificación de cambios

| Nivel | Tipo de cambio | Acción |
|-------|---------------|--------|
| 1 | Refactor interno, naming, código muerto | Ejecutar libremente |
| 2 | Cambio visible en mensajes del bot o UX conversacional | Ejecutar y reportar |
| 3 | Seguridad, credenciales, dependencias nuevas, scope del bot | **Consultar antes** |

**Argumentos NO válidos para evitar consulta de Nivel 3:**
- "Es una mejora de legibilidad"
- "Es trivial de revertir"
- "Resuelve un bug menor"

---

## Definition of Done — cada feature o fix

- [ ] Happy path funciona en ejecución real (`python main.py`)
- [ ] Credenciales no aparecen en logs (verificar con `LOG_LEVEL=DEBUG`)
- [ ] Maneja desconexión del PJ con retry + mensaje claro al usuario
- [ ] Maneja timeout de sesión: relogin automático transparente
- [ ] Maneja datos vacíos (cero notificaciones, response inesperado)
- [ ] `credential_scrubber()` usado en cualquier log con datos externos
- [ ] Type hints completos en funciones nuevas o modificadas
- [ ] Sin `print()` en código nuevo

---

## Alerta especial: fragilidad del cliente HTTP

El `csj_client.py` es la parte más probable de romperse. Ante cualquier reporte
de "el cliente funciona", verificar:
- ¿Se probó con credenciales reales o con mocks?
- ¿Los campos del JSON del PJ son los actuales o los del último test?
- ¿El timeout fue suficiente para la red real?

Ante cambio de schema del PJ: actualizar `csj_client.py` y documentar en
`OBSERVATIONS.md` qué cambió y cuándo.

---

## Archivos del proyecto

| Archivo | Propósito |
|---------|-----------|
| `CLAUDE.md` | Este archivo — reglas para Claude Code |
| `OBSERVATIONS.md` | Hallazgos durante el desarrollo (crear si no existe) |
| `TECH_DEBT.md` | Deuda técnica anotada (crear si no existe) |
| `data/snapshot.json` | Estado persistido del poller |

---

## Cómo arrancar

```bash
# Setup (una sola vez)
pip install uv && uv sync
cp .env.example .env
# Completar .env: FERNET_KEY, TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID

# Cifrar credenciales del PJ
python scripts/cifrar_credenciales.py

# Arrancar
python main.py

# Tests
pytest
pytest -k "poller" -v
pytest --co -q   # solo listar tests sin correr
```

---

## Cómo migrar de v0 a v1

La v0 está diseñada para migración incremental:

- `csj_client.py` → `app/scraper/` con el mismo contrato de métodos
- `storage.py` → Postgres con el mismo interface
- `config.py` → se expande con más settings
- `telegram_bot.py` → `app/bot/channels/telegram/`
- `poller.py` → `app/poller/`
- `utils/sanitize.py` → se mantiene igual

No es código desechable.