onlinces/hackathon-acapulquitos-boys-c201275836cb46a5a486451f9caa83f5

Fork 0

Table of Contents

Configurar el Backend (Módulo B)

1. Clonar o descargar el módulo
2. Crear entorno virtual (recomendado)
3. Instalar dependencias
4. Verificar la estructura
5. Configurar variables de entorno (opcional)
6. Inicializar la base de datos
7. Verificar que el servidor funciona

Health check
Documentación interactiva

8. Probar el simulador

Arrancar el camión
Verificar estado del camión
Consultar ETA de un domicilio

9. Probar WebSocket

Opción A: Con wscat (línea de comandos)
Opción B: Con Postman

10. Probar notificación de avería
11. Ver la base de datos (opcional)

Con DB Browser for SQLite
Con línea de comandos

12. Detener el servidor
13. Troubleshooting

"Address already in use"
"No module named 'app'"
"Table already exists"
WebSocket se desconecta inmediatamente

Siguiente paso

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Configurar el Backend (Módulo B)

Guía paso a paso para levantar el servidor FastAPI.

1. Clonar o descargar el módulo

Si el backend ya está en el repo:

cd hackathon-acapulquitos-boys
git pull origin dev
cd basura_backend

Si descargaste el ZIP del módulo B:

unzip basura_backend.zip
cd basura_backend

2. Crear entorno virtual (recomendado)

# Crear venv
python -m venv venv

# Activar
# Linux/macOS:
source venv/bin/activate

# Windows:
venv\Scripts\activate

# Tu terminal ahora debe mostrar (venv) al inicio

3. Instalar dependencias

pip install -r requirements.txt

Esto instala:

fastapi — framework web
uvicorn — servidor ASGI
websockets — soporte WebSocket
apscheduler — scheduler para el simulador
python-jose — JWT (para cuando Persona A integre auth)
passlib — hashing de passwords
pydantic — validación de datos

4. Verificar la estructura

tree -L 3 app/

Deberías ver:

app/
├── core/
│   └── config.py
├── db/
│   └── database.py
├── domain/
│   ├── entities/
│   └── interfaces/
├── data/
│   └── repositories/
├── services/
│   ├── simulador.py
│   └── ws_manager.py
├── use_cases/
│   └── obtener_eta.py
├── api/routes/
│   └── eta_router.py
└── main.py

5. Configurar variables de entorno (opcional)

Crea un archivo .env en la raíz de basura_backend/:

# .env
SIM_TICK_SECONDS=10              # Intervalo del simulador (segundos)
SIM_ETA_ALERT_MINUTES=10         # Umbral para notificar proximidad
SIM_SPEED_MULTIPLIER=1.0         # Velocidad del simulador (1.0 = normal)

DATABASE_PATH=./basura.db        # Ruta del SQLite
HOST=0.0.0.0
PORT=8000
RELOAD=True                      # Hot reload en desarrollo

Si no creas .env, se usan los valores por defecto del código.

6. Inicializar la base de datos

El backend autocrea la BD y el seed al arrancar por primera vez.

# Primera vez — crea basura.db y tablas
uvicorn app.main:app --reload

Verás en la consola:

INFO:     Base de datos inicializada
INFO:     Seed de demo creado: RUTA-01 con 5 waypoints
INFO:     Uvicorn running on http://127.0.0.1:8000

La BD se crea con:

1 usuario demo
1 domicilio asignado a RUTA-01
5 puntos de ruta (waypoints) en Celaya, Guanajuato
4 templates de notificaciones
Preferencias de notificación por defecto

7. Verificar que el servidor funciona

Health check

curl http://localhost:8000/health
# Respuesta: {"status": "ok"}

Documentación interactiva

Abre en el navegador:

http://localhost:8000/docs

Deberías ver Swagger UI con todos los endpoints.

8. Probar el simulador

Arrancar el camión

curl -X POST http://localhost:8000/admin/route/RUTA-01/start

Respuesta:

{
  "message": "Ruta RUTA-01 iniciada",
  "route_id": "RUTA-01",
  "status": "EN_RUTA"
}

Verificar estado del camión

curl http://localhost:8000/admin/route/RUTA-01/status

Respuesta:

{
  "route_id": "RUTA-01",
  "current_position_id": 2,
  "status": "EN_RUTA",
  "last_update": "2026-05-22T19:30:00"
}

El current_position_id incrementa cada 10 segundos (configurable en .env).

Consultar ETA de un domicilio

curl http://localhost:8000/eta/1

Respuesta:

{
  "address_id": 1,
  "route_id": "RUTA-01",
  "status": "EN_RUTA",
  "eta_minutos": 22,
  "ventana": {
    "inicio": "7:20 pm",
    "fin": "7:35 pm"
  },
  "mensaje": "El camión está en camino. Llegada estimada: 7:20 pm – 7:35 pm."
}

9. Probar WebSocket

Opción A: Con wscat (línea de comandos)

Instalar:

npm install -g wscat

Conectar:

wscat -c ws://localhost:8000/ws/1

Deberías empezar a recibir eventos cada vez que el ETA cambia:

{
  "tipo": "aproximandose",
  "address_id": 1,
  "eta_minutos": 8,
  "mensaje": "El camión llega en ~8 minutos. Saca tu basura ahora.",
  "hora_utc": "2026-05-22T19:35:00"
}

Opción B: Con Postman

Nueva pestaña → selecciona WebSocket Request
URL: ws://localhost:8000/ws/1
Conectar
Los mensajes aparecen en el panel inferior

10. Probar notificación de avería

curl -X POST http://localhost:8000/alerts/breakdown \
  -H "Content-Type: application/json" \
  -d '{"route_id": "RUTA-01"}'

Si tienes wscat conectado, recibes:

{
  "tipo": "falla_mecanica",
  "address_id": 1,
  "eta_minutos": null,
  "mensaje": "El camión de tu zona presenta una falla mecánica. Te avisaremos cuando se resuelva.",
  "hora_utc": "2026-05-22T19:40:00"
}

El simulador se detiene automáticamente cuando hay avería.

11. Ver la base de datos (opcional)

Con DB Browser for SQLite

Descarga sqlitebrowser.org
Abre basura.db
Navega por las tablas

Con línea de comandos

sqlite3 basura.db

# Dentro de sqlite3:
.tables                    # Lista todas las tablas
SELECT * FROM rutas;       # Ver rutas
SELECT * FROM truck_status; # Ver estado del camión
SELECT * FROM notificaciones; # Ver log de notificaciones
.quit

12. Detener el servidor

En la terminal donde corre uvicorn:

Ctrl + C

El simulador se detiene automáticamente.

13. Troubleshooting

"Address already in use"

El puerto 8000 ya está ocupado.

Solución:

# Cambiar puerto
uvicorn app.main:app --reload --port 8001

# O matar el proceso en el puerto
# Linux/macOS:
lsof -ti:8000 | xargs kill -9

# Windows:
netstat -ano | findstr :8000
taskkill /PID <PID> /F

"No module named 'app'"

Estás corriendo uvicorn desde la carpeta incorrecta.

Solución:

# Debes estar en basura_backend/
cd basura_backend
uvicorn app.main:app --reload

"Table already exists"

La BD ya fue creada y el código intenta recrearla.

Solución:

# Borrar la BD y dejar que se recree
rm basura.db
uvicorn app.main:app --reload

WebSocket se desconecta inmediatamente

CORS o problema de red.

Solución: Verifica que Flutter esté usando la IP correcta:

// Si estás en emulador Android, usa:
ws://10.0.2.2:8000/ws/1

// Si estás en dispositivo físico, usa la IP de tu PC:
ws://192.168.x.x:8000/ws/1

Siguiente paso

Configurar Flutter — integrar los módulos C y D
Endpoints REST completos
WebSocket protocol