VoxPopuli/MODERATION_API.md

# API de Moderación - VoxPopuli

## Descripción General

La API de Moderación es un microservicio complementario integrado al proyecto VoxPopuli que proporciona funcionalidades de moderación de contenido y gestión de usuarios. Utiliza arquitectura hexagonal y se comunica mediante **RabbitMQ** para mantener bajo acoplamiento con el resto del sistema.

## Características Principales

### 1. **Eliminación de Reportes**
- Permite a moderadores eliminar reportes del sistema
- Evento: `moderation.delete_report`
- Endpoint: `POST /moderation/reports/delete`

### 2. **Cierre de Cuentas**
- Cierre permanente o temporal de cuentas de usuario
- Evento: `moderation.close_account`
- Endpoint: `POST /moderation/accounts/close`

### 3. **Baneo de Usuarios**
- Ban permanente o temporal (en días)
- Evento: `moderation.ban_user`
- Endpoint: `POST /moderation/users/ban`

### 4. **Advertencias**
- Registra advertencias contra usuarios
- Evento: `moderation.warn_user`
- Endpoint: `POST /moderation/users/warn`

### 5. **Revisión de Contenido**
- Aprueba, rechaza o solicita más información sobre reportes
- Evento: `moderation.review_content`
- Endpoint: `POST /moderation/content/review`

## Arquitectura

### Componentes

```
┌─────────────────────────────────────────────────────────┐
│             API REST de Moderación (FastAPI)             │
│         Puerto 8003 - Endpoints de moderación            │
└──────────────┬──────────────────────────────────────────┘
               │ Envía eventos
               ▼
     ┌─────────────────────┐
     │  RabbitMQ Queue     │
     │ moderation_queue    │
     └──────────┬──────────┘
                │ Consume
                ▼
     ┌─────────────────────────┐
     │ Moderation Consumer     │
     │ (Thread - background)   │
     └──────────┬──────────────┘
                │ Ejecuta acciones
                ▼
     ┌──────────────────────────┐
     │ MongoDB                  │
     │ - moderation_actions     │
     │ - moderation_logs        │
     └──────────────────────────┘
```

### Capas de la Arquitectura

```
domain/
└── moderations.py              # Entidades de negocio: ModerationAction, ModerationLog

application/
├── ports/
│   └── moderation_repository.py    # Interfaz de persistencia
└── services/
    └── moderation_services.py      # Use cases: DeleteReport, CloseAccount, etc.

infrastructure/
├── adapters/
│   ├── moderation_repository_mongo.py  # Implementación MongoDB
│   └── rabbitmq/
│       └── messages.py              # Esquemas de eventos RabbitMQ
├── api/
│   └── moderations/
│       ├── app.py                # Aplicación FastAPI
│       ├── router.py              # Rutas principales
│       ├── moderations.py         # Endpoints
│       ├── schemas.py             # Validación Pydantic
│       └── root.py                # Rutas raíz
└── consumers/
    └── moderation_consumer.py     # Consumidor de eventos

main.py                            # Punto de entrada (integración)
```

## Integración con RabbitMQ

### Flujo de Eventos

1. **Cliente envía solicitud HTTP** a API de Moderación
2. **Servicio valida** la solicitud
3. **Servicio envía evento** a cola `moderation_queue` en RabbitMQ
4. **Consumer escucha** la cola en background
5. **Consumer procesa** el evento y ejecuta acciones
6. **Sistema persiste** en MongoDB

### Implementación de ModerationConsumer

El `ModerationConsumer` está integrado en `main.py` ejecutándose como un thread daemon:

```python
# En main.py
moderations_consumer_thread = threading.Thread(
    target=run_moderations_consumer, 
    daemon=True, 
    name="Moderations-Consumer"
)
```

### Mensajes de Evento

Todos los eventos se envían a través de `RabbitMQSender`:

```json
{
    "action_id": "uuid-aqui",
    "event_type": "moderation.delete_report",
    "moderator_id": 123,
    "report_id": "report-uuid",
    "reason": "Contenido violento",
    "description": "Publicación violenta contra usuarios",
    "timestamp": "2026-05-04T10:30:00"
}
```

## Endpoints API

### 1. Eliminación de Reporte
```http
POST /moderation/reports/delete HTTP/1.1
Content-Type: application/json

```

**Respuesta:**
```json
{
    "status": "success",
    "message": "Reporte marcado para eliminación",
    "action_id": "action-uuid"
}
```

### 2. Cierre de Cuenta
```http
POST /moderation/accounts/close HTTP/1.1
Content-Type: application/json

```

### 3. Baneo de Usuario
```http
POST /moderation/users/ban HTTP/1.1
Content-Type: application/json

```

### 4. Advertencia
```http
POST /moderation/users/warn HTTP/1.1
Content-Type: application/json

```

### 5. Revisión de Contenido
```http
POST /moderation/content/review HTTP/1.1
Content-Type: application/json

```

## Ejecución

### Iniciar todo el sistema
```bash
python src/main.py
```

Esto iniciará:
- ✓ API de Usuarios (puerto 8000)
- ✓ API de Reportes (puerto 8001)
- ✓ API de Notificaciones (puerto 8002)
- ✓ **API de Moderación (puerto 8003)**
- Consumer de Usuarios
- Consumer de Reportes
- Consumer de Notificaciones
- **Consumer de Moderación**

### Acceder a documentación
- Moderación: http://localhost:8003/docs

## Persistencia

La API de Moderación almacena datos en **MongoDB** con dos colecciones:

### `moderation_actions`
Almacena todas las acciones de moderación:
```javascript
{
    "action_id": "uuid",
    "moderator_id": 123,
    "action_type": "delete_report",
    "target_type": "report",
    "target_id": "report-uuid",
    "reason": "Contenido inapropiado",
    "status": "pending",
    "fecha_creacion": "2026-05-04T10:30:00",
    "fecha_ejecucion": null,
    ...
}
```

### `moderation_logs`
Registro auditable de todas las operaciones:
```javascript
{
    "log_id": "uuid",
    "action_id": "action-uuid",
    "moderator_id": 123,
    "resultado": "success",
    "fecha_log": "2026-05-04T10:30:00",
    "ip_moderator": "192.168.1.100"
}
```

## Integración Sin Cambios Significativos

Esta API fue diseñada para integrarse sin modificar el código existente:

✓ **No modifica** `docker-compose.yaml` (usa instancias RabbitMQ existentes)
✓ **No modifica** APIs existentes (Usuarios, Reportes, Notificaciones)
✓ **No modifica** consumidores existentes
✓ **Comunicación desacoplada** via RabbitMQ
✓ **Base de datos independiente** (MongoDB)
✓ **Puerto separado** (8003)

## Extensibilidad

Para agregar nuevas acciones de moderación:

1. **Crear Use Case** en `application/services/moderation_services.py`
2. **Crear evento** en `infrastructure/adapters/rabbitmq/messages.py`
3. **Agregar endpoint** en `infrastructure/api/moderations/moderations.py`
4. **Manejar evento** en `consumers/moderation_consumer.py`

## Requisitos

- Python 3.8+
- FastAPI
- Pydantic
- pika (RabbitMQ client)
- pymongo (MongoDB driver)
- MongoDB instancia
- RabbitMQ instancia

## Seguridad

### Recomendaciones Implementadas
- ✓ Validación de entrada con Pydantic
- ✓ Logs auditables de todas las acciones
- ✓ Soporte para IP del moderador
- ✓ Eventos inmutables en RabbitMQ
- ✓ Estados de acción para auditoría

### Recomendaciones Futuras
- Implementar autenticación JWT para moderadores
- Rate limiting por moderador
- Notificaciones a usuarios afectados
- Dashboard de auditoría