# TIP — Threat Intelligence Platform

> Plataforma centralizada de monitoreo e inteligencia de amenazas sobre Telegram.

---

## Tabla de Contenidos

1. [Descripción General](#descripción-general)
2. [Arquitectura del Sistema](#arquitectura-del-sistema)
3. [Microservicios](#microservicios)
4. [Flujo del Alimentador](#flujo-del-alimentador)
5. [Requisitos Previos](#requisitos-previos)
6. [Instalación y Configuración](#instalación-y-configuración)
7. [Gestión de Backups](#gestión-de-backups)
8. [Troubleshooting](#troubleshooting)

---

## Descripción General

**TIP (Threat Intelligence Platform)** es una plataforma de monitoreo en tiempo real diseñada para capturar, analizar y gestionar mensajes de grupos y canales de Telegram. Mediante reglas configurables basadas en expresiones regulares, el sistema detecta patrones sospechosos, genera alertas automáticas y mantiene un registro auditable de todas las operaciones.

### Características Principales

- **Monitoreo en tiempo real**: Captura automática de mensajes desde grupos y canales de Telegram
- **Detección basada en reglas**: Expresiones regulares configurables para identificar patrones de interés
- **Gestión de alertas**: Ciclo de vida completo — Pendiente → En Curso → Resuelta — con historial de notas
- **Auditoría integral**: Registro de IP, usuario y timestamp en cada operación del sistema
- **Exportación de reportes**: Generación de PDFs con trazabilidad completa al cerrar una alerta
- **Estadísticas en tiempo real**: Dashboards con métricas, heatmaps y análisis de actividad
- **Control de acceso por roles**: Administradores y Operadores con permisos diferenciados
- **Sistema de backups**: Exportación e importación de bases de datos, configuración y sesiones de Telegram

---

## Arquitectura del Sistema

TIP está compuesto por **4 microservicios** y **2 bases de datos** independientes, orquestados con Docker Compose y expuestos a través de un proxy NGINX con SSL.

```
╔══════════════════════════════════════════════════════════════════════════════════╗
║                                   INTERNET                                       ║
╚══════════════════════════════════════════════╦═══════════════════════════════════╝
                                               ║ HTTPS :443 / HTTP :80
                              ╔════════════════╩════════════════╗
                              ║           NGINX Proxy           ║
                              ║     Terminación SSL · Routing   ║
                              ╚══════╦══════════╦═══════╦═══════╝
                                     ║          ║       ║
                      ╔══════════════╝    ╔═════╝   ╔══=╩═════════════╗
                      ▼                   ▼         ▼                 ▼
             ╔════════════════╗  ╔══════════════╗  ╔══════════════╗  ╔═══════════════╗
             ║    Frontend    ║  ║  API Feeder  ║  ║  API Users   ║  ║Backup Service ║
             ║   Streamlit    ║  ║   FastAPI    ║  ║   FastAPI    ║  ║   FastAPI     ║
             ║   Python 3.11  ║  ║  Python 3.11 ║  ║  Python 3.11 ║  ║  Python 3.11  ║
             ║    :8501       ║  ║    :8000     ║  ║    :8090     ║  ║    :8099      ║
             ╚═══════╦════════╝  ╚══════╦═══════╝  ╚══════╦═══════╝  ╚═══════╦═══════╝
                     ║                  ║                  ║                  ║
              HTTP   ║         ╔════════╩══════╗           ║                  ║
              REST   ╠         ║   Telegram    ║           ║                  ║
                     ║         ║  API (MTProto)║           ║                  ║
                     ║         ╚═══════════════╝           ║                  ║
                     ║                  ║                  ║          ╔═══════╩══════╗
                     ║         ╔════════╩═══════╗  ╔═══════╩══════╗   ║  /config/... ║
                     ╚═════════║  MariaDB :3306 ║  ║MariaDB :3307 ║   ║   (volumes)  ║
                               ║  DB: feeder    ║  ║  DB: users   ║   ╚══════════════╝
                               ╚════════════════╝  ╚══════════════╝
```

### Comunicación entre Servicios

| Origen | Destino | Protocolo | Propósito |
|--------|---------|-----------|-----------|
| Frontend | API Feeder | HTTP/REST | Alertas, mensajes, reglas, grupos, estadísticas |
| Frontend | API Users | HTTP/REST | Login, gestión de usuarios |
| Frontend | Backup Service | HTTP/REST | Estado y descarga de backups |
| API Feeder | Telegram | MTProto (Telethon) | Captura de mensajes y adjuntos |
| API Feeder | API Feeder (interno) | HTTP/REST | Persistencia de mensajes vía `api_implementations.py` |
| Backup Service | MariaDB Feeder | TCP/MySQL | mysqldump para backup |
| Backup Service | MariaDB Users | TCP/MySQL | mysqldump para backup |
| NGINX | Todos los servicios | HTTP (reverse proxy) | Enrutamiento y terminación SSL |

### Seguridad

- **JWT compartido**: Todos los microservicios validan tokens con la misma `SECRET_KEY`
- **Roles**: `admin` y `operator` con controles en cada endpoint
- **Rate limiting**: Registro público limitado a 5 peticiones/minuto (SlowAPI)
- **HTTPS**: Terminación SSL en NGINX con soporte TLSv1.2 y TLSv1.3

---

## Microservicios

### 1. Frontend — Streamlit

**Propósito**: Interfaz de usuario para el monitoreo y gestión de la plataforma.

**Lenguaje**: Python **3.11**

**Ubicación**: `/frontend`

| Librería | Versión | Propósito |
|----------|---------|-----------|
| Streamlit | ≥ 1.28.0 | Framework web reactivo |
| Requests | ≥ 2.31.0 | Cliente HTTP hacia las APIs |
| Pandas | ≥ 2.0.0 | Manipulación de datos en dashboards |
| ReportLab | ≥ 3.6.0 | Generación de reportes PDF |
| Matplotlib | ≥ 3.7.0 | Gráficos estáticos auxiliares |

**Funcionalidades**:
- Panel de inicio con métricas y estado del alimentador
- Gestión de alertas con notas, cambio de estado y exportación PDF
- Búsqueda avanzada de mensajes con filtros por texto, grupo, remitente y fecha
- Descarga de adjuntos directamente desde Telegram
- Exploración de remitentes con historial de mensajes
- Estadísticas con gráficos de línea, barras, heatmaps y ranking de senders
- Panel de administración para gestión de usuarios, auditoría y backups

---

### 2. API Feeder — FastAPI

**Propósito**: Backend principal. Captura mensajes de Telegram, evalúa reglas y sirve los datos al Frontend.

**Lenguaje**: Python **3.11**

**Ubicación**: `/app`

| Librería | Versión | Propósito |
|----------|---------|-----------|
| FastAPI | 0.104.1 | Framework REST asíncrono |
| Uvicorn | 0.24.0 | Servidor ASGI |
| Telethon | 1.28.5 | Cliente MTProto para Telegram |
| SQLAlchemy | 2.0.23 | ORM |
| PyMySQL | 1.1.0 | Driver MySQL/MariaDB |
| Pydantic | 2.11.9 | Validación y serialización |
| Alembic | 1.11.1 | Migraciones de base de datos |
| python-jose | 3.3.0 | Generación y validación de JWT |
| python-dotenv | 1.0.0 | Gestión de variables de entorno |
| httpx | latest | Cliente HTTP asíncrono |
| aiofiles | 23.2.1 | I/O asíncrono de archivos |
| Requests | 2.32.5 | Cliente HTTP síncrono (integraciones internas) |

**Endpoints principales**:

| Grupo | Método | Ruta | Descripción |
|-------|--------|------|-------------|
| Messages | POST | `/messages/` | Crear mensaje + evaluar reglas |
| Messages | GET | `/messages/search/` | Búsqueda con filtros |
| Alerts | GET | `/alerts/` | Listar con filtros |
| Alerts | POST | `/alerts/{id}/resolve` | Cerrar alerta |
| Alerts | POST | `/alerts/{id}/in-progress` | Marcar en curso |
| Rules | POST | `/rules/` | Crear regla (con apply_to_history) |
| Groups | PATCH | `/groups/{id}/update-position` | Actualizar cursor de mensajes |
| Attachments | GET | `/attachments/{id}/download` | Descargar adjunto desde Telegram |
| Audit | GET | `/audit/` | Consultar logs de auditoría |
| Stats | GET | `/stats/` | Métricas y estadísticas agregadas |
| Manage | POST | `/manage/` | Agregar grupo/canal de Telegram |
| Manage | GET | `/manage/init-session` | Iniciar autenticación Telegram |
| Manage | POST | `/manage/verify-code` | Verificar código de autenticación |

---

### 3. API Users — FastAPI

**Propósito**: Gestión de usuarios, autenticación y auditoría de cambios de permisos.

**Lenguaje**: Python **3.11**

**Ubicación**: `/usuarios`

| Librería | Versión | Propósito |
|----------|---------|-----------|
| FastAPI | 0.104.1 | Framework REST |
| Uvicorn | 0.24.0 | Servidor ASGI |
| SQLAlchemy | 2.0.23 | ORM |
| PyMySQL | 1.1.2 | Driver MySQL/MariaDB |
| Pydantic | 2.5.0 | Validación de datos |
| passlib[bcrypt] | 1.7.4 | Hash seguro de contraseñas |
| bcrypt | 4.0.1 | Backend de hashing |
| python-jose | 3.3.0 | JWT |
| SlowAPI | latest | Rate limiting en endpoints públicos |
| python-multipart | 0.0.6 | Formularios multipart |

**Endpoints principales**:

| Método | Ruta | Descripción |
|--------|------|-------------|
| POST | `/api/v1/login` | Autenticación — devuelve JWT |
| GET | `/api/v1/users/` | Listar usuarios (admin) |
| GET | `/api/v1/users/pending` | Usuarios pendientes de aprobación |
| POST | `/api/v1/users/common` | Registro público (rate-limited) |
| PUT | `/api/v1/users/{id}` | Actualizar datos |
| PATCH | `/api/v1/users/{id}/role` | Cambiar rol |
| POST | `/api/v1/users/{id}/activate` | Activar usuario |
| GET | `/api/v1/logs/users` | Historial de modificaciones |

---

### 4. Backup Service — FastAPI

**Propósito**: Centraliza la generación y verificación de backups del sistema completo.

**Lenguaje**: Python **3.11**

**Ubicación**: `/backup_service`

| Librería | Versión | Propósito |
|----------|---------|-----------|
| FastAPI | 0.104.1 | Framework REST |
| Uvicorn | 0.24.0 | Servidor ASGI |
| python-jose | 3.3.0 | Validación JWT (mismo SECRET_KEY) |
| mysqldump / mysqladmin | sistema | Dump de bases de datos (instalados en Dockerfile) |

**Endpoints**:

| Método | Ruta | Descripción |
|--------|------|-------------|
| GET | `/backup` | Genera y descarga ZIP con los componentes seleccionados |
| GET | `/backup/status` | Estado de cada componente sin generar backup |
| GET | `/health` | Verificación de salud del servicio |

**Componentes exportables**:
- `databases/` — mysqldump de las bases de datos Feeder y Users
- `config/` — nginx.conf y docker-compose.yml
- `ssl/` — Certificados SSL
- `telegram_sessions/` — Archivos `.session` de autenticación de Telegram

---

## Flujo del Alimentador

El **Feeder** (alimentador) es el núcleo de captura del sistema. Se ejecuta en un hilo de fondo independiente al inicio de la API y opera en ciclos continuos.

```
┌─────────────────────────────────────────────────────────────────────────┐
│  INICIO DE LA API (startup_event)                                        │
│  └─► Lanza run_sync_scraper() en thread separado via asyncio.to_thread  │
└──────────────────────────────┬──────────────────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────────────────┐
│  CICLO PRINCIPAL (run_sync_scraper)                                       │
│                                                                           │
│  ┌─ INICIO DEL CICLO ──────────────────────────────────────────────────┐ │
│  │                                                                     │ │
│  │  1. TelegramChatSingleton.get_scraper()                             │ │
│  │     └─► ¿Existe instancia singleton?                                │ │
│  │           ├─ NO → TelegramClientManager.connect()                  │ │
│  │           │        └─► Busca session_*.session en /telegram_sessions│ │
│  │           │             Autentica con Telethon (MTProto)            │ │
│  │           └─ SÍ → Reutiliza cliente existente                      │ │
│  │                                                                     │ │
│  │  2. scraper.add_chats()                                             │ │
│  │     └─► GET /groups/ → obtiene todos los grupos activos             │ │
│  │          Para cada grupo:                                           │ │
│  │           └─► Consulta Telegram con get_entity(id)                 │ │
│  │                Actualiza nombre, tipo y descripción en la DB        │ │
│  │                                                                     │ │
│  │  3. scraper.feeder_loop()                                           │ │
│  │     └─► Para cada grupo en la DB:                                   │ │
│  │                                                                     │ │
│  │          a) set_chat_id(group_id)                                   │ │
│  │             └─► Configura el canal objetivo en Telethon             │ │
│  │                                                                     │ │
│  │          b) self.first_id = group.message_position                  │ │
│  │             └─► Lee el cursor del último mensaje procesado          │ │
│  │                                                                     │ │
│  │          c) refresh_chat()                                          │ │
│  │             └─► GetHistoryRequest(min_id=first_id)                  │ │
│  │                  Descarga en lotes de 100 solo mensajes nuevos      │ │
│  │                                                                     │ │
│  │          d) get_and_post_message_info()                             │ │
│  │             │                                                       │ │
│  │             ├─► _preload_senders()                                  │ │
│  │             │    └─► Para cada sender_id único:                     │ │
│  │             │          GET /senders/{id} → ¿existe?                 │ │
│  │             │          NO → get_entity(id) en Telegram              │ │
│  │             │               POST /senders/ → crea el remitente      │ │
│  │             │                                                       │ │
│  │             └─► Para cada mensaje descargado:                       │ │
│  │                  │                                                  │ │
│  │                  ├─► Extrae: id, content, date, sender_id,          │ │
│  │                  │   group_id, media (adjunto si existe)            │ │
│  │                  │                                                  │ │
│  │                  ├─► POST /messages/ (API interna)                  │ │
│  │                  │    │                                             │ │
│  │                  │    └─► Endpoint crea el mensaje y:               │ │
│  │                  │         Para cada regla activa:                  │ │
│  │                  │          └─► re.search(regex, content)           │ │
│  │                  │               ¿Coincide? → crea Alert(status=open)│ │
│  │                  │                                                  │ │
│  │                  └─► Si tiene adjunto → POST /attachments/          │ │
│  │                                                                     │ │
│  │          e) act_message_position(group_id, last_message_id)        │ │
│  │             └─► PATCH /groups/{id}/update-position                  │ │
│  │                  Actualiza el cursor para el próximo ciclo          │ │
│  │                                                                     │ │
│  │  4. Fin del ciclo → sleep(200 segundos)                             │ │
│  └─────────────────────────────────────────────────────────────────────┘ │
│                                                                           │
│  ⚠️  Si ocurre una excepción en cualquier punto:                          │
│       └─► scraper_status["last_error"] = str(e)                          │
│            sleep(60 segundos)                                             │
│            El singleton mantiene el cliente → intento de reconexión       │
└──────────────────────────────────────────────────────────────────────────┘
```

### Descarga de Adjuntos (bajo demanda)

Cuando un usuario descarga un adjunto desde la UI, se sigue un flujo independiente para no interferir con el ciclo del Feeder:

```
Frontend
  └─► GET /attachments/{id}/download
        │
        ├─► Obtiene metadata del adjunto (group_id, message_id)
        │
        ├─► TelegramChatSingleton.get_tmp_scraper()
        │    └─► Crea un TelegramClientManager temporal
        │         Copia el .session file a un archivo temporal
        │         Lanza un thread dedicado con su propio event loop
        │
        └─► download_attachment_to_buffer(group_id, message_id)
             └─► client.get_messages(group_id, ids=message_id)
                  client.download_media(message, file=BytesIO())
                  Devuelve los bytes → StreamingResponse al Frontend
                  Elimina la sesión temporal al finalizar
```

### Configuración del Ciclo

Los parámetros del ciclo se pueden ajustar directamente en `app/main.py`:

```python
scraper_config = {
    "cicle_time": 200,   # segundos entre ciclos (recomendado ≥ 200 para evitar flood)
    "error_delay": 60,   # segundos de espera tras un error antes de reintentar
}
```

---

## Requisitos Previos

### Hardware Mínimo

| Recurso | Mínimo | Recomendado |
|---------|--------|-------------|
| CPU | 2 núcleos | 4 núcleos |
| RAM | 4 GB | 8 GB |
| Almacenamiento | 20 GB | 50 GB+ |

### Software Requerido

| Componente | Versión Mínima | Instalación |
|-----------|----------------|-------------|
| Docker | 20.10+ | https://docs.docker.com/engine/install/ |
| Docker Compose | 1.29+ | Incluido en Docker Desktop |
| Git | 2.20+ | https://git-scm.com/downloads |
| jq (solo Linux/macOS) | 1.6+ | `sudo apt install jq` o `brew install jq` |

> **Nota sobre Python**: El proyecto utiliza **Python 3.11** en todos los microservicios. La versión está declarada en cada `Dockerfile` (`FROM python:3.11-slim`). No es necesario tener Python instalado localmente; Docker lo gestiona de forma aislada.

### Credenciales Necesarias

- **Telegram API ID y API Hash**: Obtener en https://my.telegram.org/apps con la cuenta que se usará para el monitoreo
- **Número de teléfono** de esa cuenta (formato internacional, ej: `+5491112345678`)
- Acceso a los grupos/canales de Telegram que se desean monitorear

---

## Instalación y Configuración

### Paso 1 — Clonar el Repositorio

```bash
git clone https://github.com/tu-usuario/tip.git
cd tip
```

### Paso 2 — Crear el Archivo `.env`

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

Edita `.env` con tus valores reales:

```env
# ── TELEGRAM ────────────────────────────────────────────────────────────
# Obtener en https://my.telegram.org/apps
TELEGRAM_API_ID=123456789
TELEGRAM_API_HASH=abcdef0123456789abcdef0123456789
TELEGRAM_TELEPHONE=+5491112345678

# ── SEGURIDAD ────────────────────────────────────────────────────────────
# Clave compartida entre todos los microservicios (mínimo 20 caracteres)
# Generar con: openssl rand -hex 32
SECRET_KEY=reemplazar_con_clave_secreta_minimo_32_chars

# ── BASES DE DATOS ───────────────────────────────────────────────────────
DB_ROOT_PASS_FEEDER=password_feeder
DB_ROOT_PASS_USERS=password_users

# ── ADMIN (creado automáticamente en el primer inicio) ──────────────────
ADMIN_EMAIL=admin@tudominio.com
ADMIN_PASSWORD=contraseña_admin_segura
```

### Paso 3 — Configurar `docker-compose.yml`

```bash
cp docker-compose_example.yml docker-compose.yml
```

Reemplaza los valores marcados con `YOUR-*`:

```yaml
# Contraseñas de bases de datos
database:
  environment:
    MYSQL_ROOT_PASSWORD: password_feeder       # ← cambiar

database_users:
  environment:
    MYSQL_ROOT_PASSWORD: password_users        # ← cambiar

# URLs de conexión a las bases de datos
api:
  environment:
    DATABASE_URL: mariadb+pymysql://root:password_feeder@database:3306/feeder
    TELEGRAM_API_ID: TU_API_ID
    TELEGRAM_API_HASH: TU_API_HASH
    TELEGRAM_TELEPHONE: TU_TELEFONO
    SECRET_KEY: TU_SECRET_KEY

api_users:
  environment:
    DATABASE_URL: mariadb+pymysql://root:password_users@database_users:3307/users
    SECRET_KEY: TU_SECRET_KEY       # ← debe ser la misma que api
    ADMIN_EMAIL: admin@tudominio.com
    ADMIN_PASSWORD: contraseña_admin

# URLs para el backup service
backup:
  environment:
    FEEDER_DATABASE_URL: mariadb+pymysql://root:password_feeder@database:3306/feeder
    USERS_DATABASE_URL: mariadb+pymysql://root:password_users@database_users:3307/users
    SECRET_KEY: TU_SECRET_KEY
```

### Paso 4 — Configurar NGINX

```bash
mkdir -p nginx/ssl
cp nginx/nginx.conf_example nginx/nginx.conf
```

Edita `nginx/nginx.conf` y reemplaza `localhost` con tu dominio:

```nginx
server_name tu_dominio.com;
```

Para **desarrollo local sin SSL**, comenta el bloque HTTPS y usa solo el bloque HTTP.

**Para producción con Let's Encrypt**:

```bash
# Instalar certbot (fuera de Docker)
sudo apt install certbot

# Generar certificados
sudo certbot certonly --standalone -d tu_dominio.com

# Copiar al directorio del proyecto
sudo cp /etc/letsencrypt/live/tu_dominio.com/fullchain.pem ./nginx/ssl/
sudo cp /etc/letsencrypt/live/tu_dominio.com/privkey.pem   ./nginx/ssl/
sudo chown $(whoami):$(whoami) ./nginx/ssl/*
```

### Paso 5 — Iniciar los Contenedores

```bash
# Construir imágenes e iniciar todos los servicios
docker compose up -d --build

# Verificar que todos estén corriendo
docker compose ps
```

Resultado esperado:

```
NAME            SERVICE         STATUS
feeder_api      api             running
users_api       api_users       running
frontend        frontend        running
backup_service  backup          running
feeder_db       database        running (healthy)
users_db        database_users  running (healthy)
nginx_proxy     nginx           running
```

```bash
# Ver logs en tiempo real
docker compose logs -f api api_users
```

### Paso 6 — Autenticar la Sesión de Telegram

La primera vez (o tras reinstalación) es necesario autenticar el cliente de Telegram:

1. Accede a la UI como **admin**: https://tu_dominio.com
2. Ve a **Panel de Administración** → **Sistema** → **Alimentador**
3. Haz clic en **Iniciar Nueva Sesión**
4. Revisa el código de verificación que llegó a tu cuenta de Telegram
5. Ingrésalo en el campo correspondiente (más la contraseña 2FA si aplica)
6. El alimentador se activará automáticamente

### Paso 7 — Agregar Grupos a Monitorear

1. Ve a **Grupos y Canales** → **Agregar grupo**
2. Abre el grupo en Telegram Web (`web.telegram.org`)
3. Copia la URL completa (contiene el ID: `.../#-100XXXXXXXXX`)
4. Pégala en el campo y haz clic en **Agregar Grupo**
5. El sistema valida el acceso contra Telegram y lo registra

---

## Gestión de Backups

### Generar un Backup

#### Desde la UI

1. Accede como **admin**
2. Ve a **Panel de Administración** → **Sistema** → **Backup del Sistema**
3. Selecciona los componentes a incluir
4. Haz clic en **⬇️ Generar y Descargar Backup**
5. Guarda el archivo `tip_backup_YYYYMMDD_HHMMSS.zip` en lugar seguro

#### Desde la línea de comandos

```bash
# Primero, obtener un token JWT (reemplazar por tus credenciales)
TOKEN=$(curl -s -X POST http://localhost:8090/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@tudominio.com","password":"tu_password"}' \
  | jq -r '.access_token')

# Solicitar el backup
curl -X GET \
  "http://localhost:8099/backup?include_db=true&include_config=true&include_ssl=true&include_sessions=true" \
  -H "Authorization: Bearer $TOKEN" \
  -o "tip_backup_$(date +%Y%m%d_%H%M%S).zip"
```

---

### Restaurar un Backup

> ⚠️ **ADVERTENCIA**: La restauración sobrescribe datos existentes. Asegúrate de que es lo que necesitas antes de continuar.

#### Windows (PowerShell)

```powershell
# 1. Coloca el archivo tip_backup_*.zip en la raíz del proyecto
# 2. Abre PowerShell como Administrador y navega al directorio
cd C:\ruta\al\proyecto

# 3. Habilitar ejecución de scripts (si no está habilitado)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 4. Ejecutar el script
.\restore_backup.ps1
```

#### Linux / macOS (Bash)

```bash
# 1. Coloca el archivo tip_backup_*.zip en la raíz del proyecto
# 2. Dar permisos de ejecución al script
chmod +x restore_backup.sh

# 3. Ejecutar el script
./restore_backup.sh
```

#### ¿Qué hace el script de restauración?

```
INICIO
  │
  ├─ 1. Solicita confirmación al usuario
  │
  ├─ 2. Localiza el tip_backup_*.zip más reciente en el directorio actual
  │
  ├─ 3. Extrae el contenido en ./temp_restore/
  │
  ├─ 4. Lee manifest.json → identifica componentes incluidos y advertencias
  │
  ├─ 5. Obtiene credenciales de las bases de datos desde docker-compose.yml
  │
  ├─ 6. Por cada componente en el manifiesto:
  │     ├─ database:feeder  → levanta feeder_db y restaura el .sql
  │     ├─ database:users   → levanta users_db y restaura el .sql
  │     ├─ config:*         → copia nginx.conf y/o docker-compose.yml
  │     ├─ ssl              → copia certificados a ./nginx/ssl/
  │     └─ telegram_sessions → copia .session a ./app/telegram_sessions/
  │
  ├─ 7. Muestra las advertencias registradas en el manifiesto
  │
  ├─ 8. Elimina ./temp_restore/
  │
  └─ 9. Pregunta si desea reiniciar los contenedores (docker compose down && up)
```

#### Dependencias del Script

| Dependencia | Windows | Linux/macOS |
|-------------|---------|-------------|
| Docker + Docker Compose | ✅ Requerido | ✅ Requerido |
| jq | No requerido (usa PowerShell nativo) | ✅ `sudo apt install jq` |

---

### Buenas Prácticas de Backup

- **Frecuencia**: Realiza backups diarios en producción, especialmente antes de actualizaciones
- **Validación**: Prueba la restauración en un entorno de prueba periódicamente
- **Almacenamiento externo**: Guarda copias en un servidor remoto o servicio de almacenamiento (S3, OneDrive, etc.)
- **Encriptación**: Si el backup contiene sesiones o datos sensibles, encríptalo antes de transferirlo:
  ```bash
  # Linux/macOS
  openssl enc -aes-256-cbc -salt -in tip_backup_*.zip -out tip_backup_encrypted.zip

  # Descifrar
  openssl enc -d -aes-256-cbc -in tip_backup_encrypted.zip -out tip_backup_restored.zip
  ```

---

## Troubleshooting

### Los contenedores no inician

```bash
# Ver logs completos de todos los servicios
docker compose logs

# Ver logs de un servicio en particular
docker compose logs api
docker compose logs database

# Reconstruir imágenes sin caché
docker compose down
docker compose up -d --build --force-recreate
```

### Error de conexión a la base de datos

```bash
# Verificar que MariaDB está aceptando conexiones
docker compose exec database mysql -u root -p -e "SELECT 1;"

# Verificar conectividad entre contenedores
docker compose exec api ping database
```

### El alimentador aparece como inactivo

```bash
# Verificar si hay archivos de sesión de Telegram
docker compose exec api ls -la /app/telegram_sessions/

# Si no hay sesión o está corrupta, eliminarla y autenticar de nuevo desde la UI
docker compose exec api rm -f /app/telegram_sessions/session_*
# Luego: Panel de Administración → Sistema → Iniciar Nueva Sesión
```

### NGINX devuelve 502 Bad Gateway

```bash
# Verificar que los servicios upstream estén corriendo
docker compose ps

# Validar la configuración de NGINX
docker compose exec nginx nginx -t

# Ver logs de NGINX
docker compose logs nginx
```

### Las alertas no se generan automáticamente

```bash
# Verificar que existen reglas activas
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/rules/

# Verificar que el feeder está capturando mensajes
docker compose logs api | grep -E "Feeding|Cycle|feeder_loop"

# Verificar que no hay errores de regex en las reglas
docker compose logs api | grep -i "regex\|WARN"
```

---

## Estructura del Proyecto

```
tip/
├── app/                        # API Feeder
│   ├── alembic/                # Migraciones de base de datos
│   ├── integrations/           # Cliente Telegram (chats.py, api_implementations.py)
│   ├── routers/                # Endpoints REST
│   ├── main.py                 # Entry point + scraper loop
│   ├── models.py               # Modelos SQLAlchemy
│   ├── schemas.py              # Schemas Pydantic
│   ├── auth.py                 # JWT helpers
│   └── audit.py                # Logger de auditoría
├── usuarios/                   # API Users
│   ├── main.py
│   ├── models.py
│   ├── schemas.py
│   ├── crud.py
│   ├── services.py
│   └── dependencies.py
├── frontend/                   # UI Streamlit
│   ├── app.py
│   ├── src/
│   │   ├── api.py              # Cliente HTTP hacia las APIs
│   │   ├── auth.py             # Login / sesión
│   │   └── pages/
│   │       ├── dashboard.py
│   │       └── views/          # alerts, messages, rules, groups, stats, ...
│   └── .streamlit/
│       ├── config.toml         # Tema visual
│       └── secrets.toml
├── backup_service/             # Backup Service
│   ├── main.py
│   ├── requirements.txt
│   └── Dockerfile
├── nginx/
│   ├── nginx.conf              # Configuración del proxy (generada desde el ejemplo)
│   └── ssl/                    # Certificados SSL (excluidos del repo)
├── Dockerfile                  # Imagen API Feeder
├── Dockerfile_users            # Imagen API Users
├── Dockerfile_frontend         # Imagen Frontend
├── docker-compose.yml          # Orquestación (generado desde el ejemplo)
├── docker-compose_example.yml  # Plantilla de configuración
├── entrypoint.sh               # Ejecuta migraciones Alembic antes de iniciar la API
├── restore_backup.sh           # Script de restauración (Linux/macOS)
├── restore_backup.ps1          # Script de restauración (Windows)
├── requirements.txt            # Dependencias API Feeder
├── requirements_users.txt      # Dependencias API Users
├── requirements_frontend.txt   # Dependencias Frontend
└── .gitignore
```

---

*Plataforma desarrollada para uso interno — Municipio de Paraná.*