# Pedrito Hechakuaa — Manual de usuario

**Pedrito Hechakuaa** es un bot de Telegram que revisa tu cuenta del sistema judicial del Poder Judicial de Paraguay (`apps.csj.gov.py`) y te avisa cuando aparecen notificaciones nuevas. También podés consultar el estado de cualquier expediente directamente desde Telegram.

---

## ¿Qué hace exactamente?

- Revisa tus notificaciones pendientes en el PJ cada hora, de lunes a viernes entre las 7:00 y las 18:00 (hora de Asunción).
- Te manda un mensaje por Telegram cuando aparece algo nuevo.
- Te deja consultar el detalle de cualquier expediente por número o por carátula.
- **No acusa notificaciones.** Pedrito Hechakuaa es de solo lectura — nunca toca nada que tenga efecto procesal. Para acusar, entrás vos directamente a `apps.csj.gov.py`.

---

## Instalación y configuración

### Lo que necesitás antes de empezar

- Python 3.12 o superior instalado
- Una cuenta en Telegram
- Un bot de Telegram creado (lo creás vos, gratis, en 2 minutos)
- Tu chat ID de Telegram
- Las credenciales del sistema del PJ (cédula y contraseña)

---

### Paso 1 — Verificar Python

Abrí la terminal y ejecutá:

```bash
python3 --version
```

Tiene que decir `3.12.x` o superior. Si dice `3.11` o menos, instalá Python 3.12 desde [python.org](https://www.python.org) o con `brew install python@3.12` en Mac.

> Si no tenés Python 3.12 pero sí tenés `uv` instalado, no hay problema — `uv` descarga la versión correcta automáticamente.

---

### Paso 2 — Instalar uv

`uv` es el gestor de dependencias que usa el proyecto. Si no lo tenés:

```bash
pip install uv
```

Verificar que quedó instalado:

```bash
uv --version
```

---

### Paso 3 — Instalar dependencias

Dentro de la carpeta del proyecto:

```bash
uv sync
```

Esto crea un entorno virtual e instala todo. Tarda entre 30 y 60 segundos la primera vez.

---

### Paso 4 — Configurar el archivo .env

```bash
cp .env.example .env
```

Abrí el `.env` con cualquier editor de texto y completá los cuatro valores obligatorios:

**4a. Generar la FERNET_KEY**

Esta clave cifra tus credenciales del PJ. Ejecutá esto en la terminal y copiá el resultado:

```bash
uv run python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
```

Pegalo en el `.env` en la línea `FERNET_KEY=`.

> Guardala también en un lugar seguro (gestor de contraseñas, por ejemplo). Si perdés esta clave, tendrás que volver a cifrar las credenciales del PJ.

**4b. Crear el bot de Telegram y obtener el token**

1. Abrí Telegram y buscá **@BotFather**
2. Mandále `/newbot`
3. Seguí las instrucciones: te va a pedir un nombre y un username para el bot
4. Al final te da un token con este formato: `123456789:AAFxxx...`
5. Pegalo en el `.env` en la línea `TELEGRAM_BOT_TOKEN=`

**4c. Obtener tu chat ID**

1. En Telegram buscá **@userinfobot**
2. Mandále cualquier mensaje
3. Te responde con tu ID numérico (algo como `98765432`)
4. Pegalo en el `.env` en la línea `TELEGRAM_CHAT_ID=`

El `.env` debería quedar así (los demás valores podés dejarlos comentados):

```
FERNET_KEY=tu-clave-generada
TELEGRAM_BOT_TOKEN=123456789:AAFxxx...
TELEGRAM_CHAT_ID=98765432
PJ_USUARIO_ENC=
PJ_PASSWORD_ENC=
```

---

### Paso 5 — Cifrar las credenciales del PJ

```bash
uv run python scripts/cifrar_credenciales.py
```

El script te pide:

- Tu **cédula de identidad** (la que usás para entrar a `apps.csj.gov.py`)
- Tu **contraseña del PJ** (no se muestra mientras escribís)

Las cifra con tu FERNET_KEY y actualiza automáticamente `PJ_USUARIO_ENC` y `PJ_PASSWORD_ENC` en tu `.env`. La contraseña en texto plano nunca se guarda en ningún lado.

---

### Paso 6 — Arrancar el bot

```bash
uv run python main.py
```

Lo que debería pasar:

1. El bot se conecta al PJ y revisa tus notificaciones actuales
2. Abrís Telegram, buscás tu bot por su username, y le mandás `/start`
3. El bot responde con el estado inicial
4. A partir de ahí, te avisa automáticamente cuando aparezca algo nuevo

---

## Comandos disponibles

| Comando | Qué hace |
|---------|---------|
| `/start` | Muestra el estado del bot y los comandos disponibles |
| `/notif` | Revisa las notificaciones ahora mismo, sin esperar la próxima hora |
| `/estado` | Muestra el último chequeo y cuántas notificaciones tiene registradas |
| `/ayuda` | Lista todos los comandos |
| `/exp 198` | Busca el expediente número 198 (sin filtrar por año) |
| `/exp 198/2026` | Busca el expediente 198 del año 2026 |
| `/exp carlos` | Busca expedientes que tengan "carlos" en la carátula |

---

## Cómo se ven las notificaciones

Cuando aparece una notificación nueva, el bot te manda esto:

```
📋 Nueva notificación judicial

Rodríguez c/ Municipalidad Capital
Exp. 1234/2024 — 1er Juzgado Civil Capital

Tipo: Auto Interlocutorio
Fecha: 20/05/2026

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

El botón **"Ir al sistema del PJ"** te lleva directo a la pantalla de notificaciones.

---

## Cómo se ve la consulta de expediente

**Con un único resultado** (`/exp 198/2026`):

```
📂 Exp. 198/2026
Rodríguez c/ Municipalidad Capital
1era Circunscripción | Activo

Últimas actuaciones:
• 20/05/2026 — Auto Interlocutorio: Resolución N° 123
• 15/05/2026 — Providencia: Autos y vistos
• 10/05/2026 — Notificación: Cédula de notificación

(15 actuaciones en total)
```

**Con múltiples resultados** (`/exp rodriguez`):

```
Se encontraron 3 expedientes para "rodriguez":

1. Exp. 198/2026 — Rodríguez c/ Municipalidad Capital
   1era Circunscripción | Activo

2. Exp. 456/2025 — Rodríguez Díaz c/ Empresa SA
   1era Circunscripción | Archivado

3. ...

Para ver detalle: /exp {numero}/{anio}
```

**Sin resultados** (`/exp 999999/1900`):

```
No encontré expedientes para "999999/1900".
Probá con la carátula o con número/año.
```

---

## Horario de monitoreo automático

El bot revisa el PJ **cada hora**, pero solo en horario hábil:

- **Días**: lunes a viernes
- **Horario**: 7:00 a 18:00 (hora de Asunción, UTC-4)

Fuera de ese horario, el bot no molesta. Si querés revisar en cualquier momento (finde, feriado, madrugada), usá `/notif`.

---

## Correr como servicio en segundo plano

Si no querés tener la terminal abierta todo el tiempo:

**Con screen (la opción más simple):**

```bash
screen -S pedrito
uv run python main.py
# Presioná Ctrl+A y luego D para dejar el bot corriendo en segundo plano
# Para volver: screen -r pedrito
```

**Con systemd (en un servidor Linux):**

```ini
# /etc/systemd/system/pedrito.service
[Unit]
Description=Pedrito Hechakuaa — monitor judicial
After=network.target

[Service]
Type=simple
WorkingDirectory=/ruta/al/proyecto
ExecStart=/usr/bin/python3 main.py
Restart=on-failure
RestartSec=30

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl enable pedrito
sudo systemctl start pedrito
```

---

## Solución de problemas comunes

### El bot no arranca

| Error | Causa | Solución |
|-------|-------|---------|
| `ModuleNotFoundError` | Faltan dependencias | Correr `uv sync` de nuevo en la carpeta del proyecto |
| `ValidationError` o campo vacío | `.env` incompleto | Verificar que `FERNET_KEY`, `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, `PJ_USUARIO_ENC` y `PJ_PASSWORD_ENC` estén completos |
| `FERNET_KEY inválida` | La clave tiene espacios o fue copiada mal | Regenerar con `python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"` |
| `PJ_USUARIO_ENC no se pudo descifrar` | Cambiaste la `FERNET_KEY` después de cifrar | Volver a correr `scripts/cifrar_credenciales.py` con la key actual |

### El bot arranca pero no responde en Telegram

- Verificar que `TELEGRAM_CHAT_ID` sea **tu** ID personal (el de la cuenta que va a usar el bot), no el ID del bot.
- Asegurate de haberle mandado `/start` primero desde tu cuenta de Telegram.

### El bot arranca pero falla al conectarse al PJ

- **Login fallido (401):** las credenciales están incorrectas. Volver a correr `scripts/cifrar_credenciales.py`.
- **Password temporal:** la contraseña del PJ es temporal. Entrá a `apps.csj.gov.py`, cambiala, y reiniciá el bot.
- **Error de red:** el sistema del PJ tiene intermitencias. El bot va a reintentar automáticamente en la próxima ronda.

### Los campos de una notificación aparecen vacíos o con valores raros

El formato exacto de los responses del PJ puede diferir de lo documentado (el sistema tiene actualizaciones frecuentes). En ese caso, copiá el mensaje de error del log y consultá con el equipo técnico — se resuelve en minutos.

---

## Seguridad — lo que hace el sistema para proteger tus datos

- Las credenciales del PJ se cifran con AES-128 (Fernet) antes de guardarse. Nunca quedan en texto plano.
- El `.env` con las credenciales cifradas está excluido del repositorio de código (`.gitignore`).
- El bot solo responde a tu `TELEGRAM_CHAT_ID`. Si alguien más encuentra el bot por su nombre, no puede usarlo.
- Pedrito Hechakuaa nunca acusa notificaciones ni ejecuta ninguna acción con efecto procesal. Es un lector.

---

## Actualizaciones de credenciales del PJ

Si cambiás la contraseña del PJ, simplemente volvés a correr:

```bash
uv run python scripts/cifrar_credenciales.py
```

Y reiniciás el bot. No hace falta tocar nada más.

---

*Pedrito Hechakuaa — uso personal, single-tenant.*