235 lines
7.4 KiB
Markdown
235 lines
7.4 KiB
Markdown
# 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
|
|
|
|
1. **Clonar el repositorio** (o extraer los archivos)
|
|
|
|
2. **Crear entorno virtual**:
|
|
```bash
|
|
python -m venv venv
|
|
```
|
|
|
|
3. **Activar entorno virtual**:
|
|
- En Windows:
|
|
```bash
|
|
venv\Scripts\activate
|
|
```
|
|
- En Linux/Mac:
|
|
```bash
|
|
source venv/bin/activate
|
|
```
|
|
|
|
4. **Instalar dependencias**:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
5. **Configurar variables de entorno**:
|
|
```bash
|
|
cp .env.example .env
|
|
# Editar .env con tus credenciales de MySQL y MongoDB
|
|
```
|
|
|
|
6. **Crear base de datos MySQL**:
|
|
```sql
|
|
CREATE DATABASE voxpopuli_users CHARACTER SET utf8mb4;
|
|
```
|
|
|
|
## Ejecución
|
|
|
|
### Ejecutar ambos microservicios:
|
|
```bash
|
|
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)
|
|
```python
|
|
- 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)
|
|
```python
|
|
- 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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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:
|
|
1. Fork el repositorio
|
|
2. Crea una rama para tu feature (`git checkout -b feature/AmazingFeature`)
|
|
3. Commit tus cambios (`git commit -m 'Add some AmazingFeature'`)
|
|
4. Push a la rama (`git push origin feature/AmazingFeature`)
|
|
5. 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.
|