Added everything
This commit is contained in:
Juan M. Ley
237
readme.md
237
readme.md
@@ -1,3 +1,234 @@
|
||||
# VOX POPULI
|
||||
## INFRAESTRUCTURA PARA "VOZ CIUDADANA"
|
||||
#### Proyecto de HOKZAAP SOFTWARE S. de R.L. de C.V.
|
||||
# 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.
|
||||
|
||||
Reference in New Issue
Block a user