7.4 KiB
7.4 KiB
VoxPopuli Microservices
Plataforma de reportes comunitarios con arquitectura de microservicios usando FastAPI.
Descripción
VoxPopuli es una infraestructura de microservicios que permite a usuarios crear y reportar incidentes en la comunidad, con un sistema de calificación y visibilidad basado en votación comunitaria.
Características principales:
- API de Usuarios: Gestión de usuarios y autenticación (MySQL)
- API de Reportes: Gestión de reportes comunitarios (MongoDB)
- Sistema de calificación de usuarios (0-100)
- Sistema de visibilidad de reportes con shadowban para contenido de baja calidad
- Penalización de usuarios que crean reportes shadowbaneados
Estructura del Proyecto
VoxPopuli_Microservices/
├── src/
│ ├── domain/ # Modelos de dominio (entidades de negocio)
│ │ ├── users.py # Modelo User
│ │ └── reports.py # Modelo Report
│ ├── application/ # Capa de aplicación (use cases)
│ │ ├── ports/ # Interfaces (abstracciones)
│ │ │ ├── user_repository.py
│ │ │ └── report_repository.py
│ │ └── services/ # Casos de uso
│ │ ├── user_services.py
│ │ └── report_services.py
│ ├── infrastructure/ # Capa de infraestructura
│ │ ├── adapters/
│ │ │ └── persistence/ # Implementaciones de repositorios
│ │ │ ├── db.py # Configuración MySQL
│ │ │ ├── mongodb.py # Configuración MongoDB
│ │ │ ├── models.py # Modelos SQLAlchemy
│ │ │ ├── user_repository_sql.py
│ │ │ └── report_repository_mongo.py
│ │ └── api/ # APIs REST
│ │ ├── users/ # Microservicio de Usuarios
│ │ │ ├── app.py # Factory de la app
│ │ │ ├── router.py # Enrutador principal
│ │ │ ├── users.py # Endpoints de usuarios
│ │ │ ├── schemas.py # Esquemas Pydantic
│ │ │ └── root.py # Endpoints raíz
│ │ └── reports/ # Microservicio de Reportes
│ │ ├── app.py
│ │ ├── router.py
│ │ ├── reports.py
│ │ ├── schemas.py
│ │ └── root.py
│ ├── core/
│ │ └── config.py # Configuración de la aplicación
│ └── main.py # Punto de entrada principal
├── .env.example # Variables de entorno de ejemplo
└── requirements.txt # Dependencias de Python
Requisitos
- Python 3.10+
- MySQL 8.0+
- MongoDB 4.4+
Instalación
-
Clonar el repositorio (o extraer los archivos)
-
Crear entorno virtual:
python -m venv venv -
Activar entorno virtual:
- En Windows:
venv\Scripts\activate - En Linux/Mac:
source venv/bin/activate
- En Windows:
-
Instalar dependencias:
pip install -r requirements.txt -
Configurar variables de entorno:
cp .env.example .env # Editar .env con tus credenciales de MySQL y MongoDB -
Crear base de datos MySQL:
CREATE DATABASE voxpopuli_users CHARACTER SET utf8mb4;
Ejecución
Ejecutar ambos microservicios:
cd src
python main.py
Esto iniciará:
- API de Usuarios: http://localhost:8000
- API de Reportes: http://localhost:8001
Documentación interactiva:
- Usuarios: http://localhost:8000/docs
- Reportes: http://localhost:8001/docs
Endpoints Principales
API de Usuarios (Puerto 8000)
| Método | Endpoint | Descripción |
|---|---|---|
| POST | /users/ |
Crear usuario |
| GET | /users/{user_id} |
Obtener usuario por ID |
| GET | /users/email/{email} |
Obtener usuario por email |
| GET | /users/ |
Listar todos los usuarios |
| PUT | /users/{user_id} |
Actualizar usuario |
| DELETE | /users/{user_id} |
Eliminar usuario |
API de Reportes (Puerto 8001)
| Método | Endpoint | Descripción |
|---|---|---|
| POST | /reports/ |
Crear reporte |
| GET | /reports/{report_id} |
Obtener reporte por ID |
| GET | /reports/user/{user_id} |
Obtener reportes de un usuario |
| GET | /reports/ |
Listar todos los reportes |
| GET | /reports/shadowbanned/list |
Listar reportes shadowbaneados |
| PUT | /reports/{report_id}/visibility |
Actualizar visibilidad |
| DELETE | /reports/{report_id} |
Eliminar reporte |
Modelos de Datos
Usuario (MySQL)
- user_id: int (PK)
- nombre: str
- apellido: str
- email: str (único)
- fecha_nacimiento: datetime
- fecha_creacion: datetime
- calificacion: float (0-100)
- numero_reportes: int
- url_foto_perfil: str (opcional)
- biografia: str (opcional)
Reporte (MongoDB)
- id_reporte: str (UUID)
- id_usuario: int
- tipo_reporte: int (número que representa el tipo)
- descripcion: str
- ubicacion: str (opcional)
- visibilidad: float (0-100, basado en votación comunitaria)
- fecha_creacion: datetime
Arquitectura
La arquitectura sigue el patrón de Arquitectura Limpia (Clean Architecture):
- Domain: Modelos de negocio puros (entidades)
- Application: Lógica de negocio (casos de uso/servicios)
- Infrastructure: Adaptadores para bases de datos y APIs
Esto permite:
- Independencia de frameworks
- Facilidad de testing
- Separación de responsabilidades
- Reutilización de lógica de dominio
Ejemplo de Uso
Crear un usuario:
curl -X POST "http://localhost:8000/users/" \
-H "Content-Type: application/json" \
-d '{
"nombre": "Juan",
"apellido": "Pérez",
"email": "juan@example.com",
"fecha_nacimiento": "1990-01-15T00:00:00",
"url_foto_perfil": "https://example.com/photo.jpg",
"biografia": "Usuario de VoxPopuli"
}'
Crear un reporte:
curl -X POST "http://localhost:8001/reports/" \
-H "Content-Type: application/json" \
-d '{
"id_usuario": 1,
"tipo_reporte": 1,
"descripcion": "Bache en la calle principal",
"ubicacion": "Calle Principal, Cuadra 5"
}'
Desarrollo
Ejecutar con hot reload:
Edita src/main.py y cambia reload=False a reload=True
Testing:
(Próximamente se añadirán tests unitarios e integración)
Contribuciones
Las contribuciones son bienvenidas. Por favor:
- Fork el repositorio
- Crea una rama para tu feature (
git checkout -b feature/AmazingFeature) - Commit tus cambios (
git commit -m 'Add some AmazingFeature') - Push a la rama (
git push origin feature/AmazingFeature) - Abre un Pull Request
Licencia
Este proyecto está bajo la licencia MIT - ver archivo LICENSE para más detalles.
Autor
Desarrollado como parte de la plataforma VoxPopuli para reportes comunitarios.