310
MODERATION_API.md
Normal file
310
MODERATION_API.md
Normal file
@@ -0,0 +1,310 @@
|
||||
# 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
|
||||
## 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
|
||||
Reference in New Issue
Block a user