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:

# 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:

{
    "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

POST /moderation/reports/delete HTTP/1.1
Content-Type: application/json

{
    "moderator_id": 123,
    "report_id": "report-uuid",
    "reason": "Contenido inapropiado",
    "description": "Spam repetitivo"
}

Respuesta:

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

2. Cierre de Cuenta

POST /moderation/accounts/close HTTP/1.1
Content-Type: application/json

{
    "moderator_id": 123,
    "user_id": 456,
    "reason": "Violación de términos de servicio",
    "description": "Múltiples bans previos",
    "is_permanent": true
}

3. Baneo de Usuario

POST /moderation/users/ban HTTP/1.1
Content-Type: application/json

{
    "moderator_id": 123,
    "user_id": 456,
    "reason": "Comportamiento abusivo",
    "duration_days": 30,
    "description": "Ban temporal de 30 días"
}

4. Advertencia

POST /moderation/users/warn HTTP/1.1
Content-Type: application/json

{
    "moderator_id": 123,
    "user_id": 456,
    "reason": "Primera violación de comunidad",
    "description": "Lenguaje ofensivo"
}

5. Revisión de Contenido

POST /moderation/content/review HTTP/1.1
Content-Type: application/json

{
    "moderator_id": 123,
    "report_id": "report-uuid",
    "action": "approve",
    "reason": "Contenido legítimamente reportado",
    "notes": "Proceder con eliminación del contenido"
}

Ejecución

Iniciar todo el sistema

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:

{
    "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:

{
    "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