hechakuaa_bot/README.md

Pedrito Hechakuaa

Monitor de notificaciones del Poder Judicial de Paraguay vía Telegram.

Te avisa cuando aparecen notificaciones nuevas en tu cuenta del sistema del PJ.

Setup en 5 pasos

1. Prerequisitos

• Python 3.12+
• Una cuenta en Telegram
• Un bot de Telegram creado con @BotFather
• Tu chat_id de Telegram (obtenerlo con @userinfobot)
• Credenciales del sistema del PJ (apps.csj.gov.py)

2. Instalar

# Entrar a la carpeta del proyecto
cd pedrito-hechakuaa

# Instalar dependencias (recomendado: uv)
pip install uv
uv sync

3. Configurar

# Copiar el template
cp .env.example .env

# Generar una clave de cifrado (guardarla en un lugar seguro también)
uv run python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
# Copiar el resultado en FERNET_KEY= dentro de .env

# Editar .env y completar:
# - FERNET_KEY (la que generaste arriba)
# - TELEGRAM_BOT_TOKEN (de @BotFather)
# - TELEGRAM_CHAT_ID (de @userinfobot)

4. Cifrar las credenciales del PJ

uv run python scripts/cifrar_credenciales.py

Te va a pedir la cédula y contraseña del PJ, las cifra con Fernet, y actualiza PJ_USUARIO_ENC y PJ_PASSWORD_ENC en tu .env. Nunca escribe las credenciales en plano.

5. Arrancar

uv run python main.py

El bot va a:

1. Conectarse al PJ y revisar tus notificaciones actuales
2. Mandarte un mensaje en Telegram con el estado inicial
3. Revisar cada hora en horario hábil (lunes-viernes, 7-18h)
4. Avisarte en Telegram cuando aparezca algo nuevo

Comandos de Telegram

Comando	Función
/start	Ver estado del bot
/notif	Revisar notificaciones ahora (no esperar la próxima hora)
/estado	Ver último chequeo y estadísticas
/ayuda	Lista de comandos

Correr como servicio (opcional)

Si querés que corra en background en tu Mac o en un servidor:

Con screen (más simple):

screen -S pedrito
python main.py
# Ctrl+A, D para detach
# screen -r pedrito para volver

Con systemd en Linux:

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

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

[Install]
WantedBy=multi-user.target

sudo systemctl enable pedrito
sudo systemctl start pedrito

Seguridad

• Las credenciales del PJ se cifran con Fernet (AES-128-CBC con HMAC)
• .env nunca se commitea (está en .gitignore)
• El bot solo responde al TELEGRAM_CHAT_ID que configuraste
• El bot es read-only: nunca acusa notificaciones ni tiene efectos procesales

Migración a v1

Cuando estés listo para la arquitectura completa (multi-tenant, LLM conversacional, web de onboarding), ver el directorio ../pedrito-hechakuaa/ con el diseño completo.

La v0 está pensada para migrar incrementalmente: cada módulo tiene el mismo contrato que su equivalente en v1.