diff --git a/01-backend.md.-.md b/01-backend.md.-.md new file mode 100644 index 0000000..2c19085 --- /dev/null +++ b/01-backend.md.-.md @@ -0,0 +1,356 @@ +# 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: +```bash +cd hackathon-acapulquitos-boys +git pull origin dev +cd basura_backend +``` + +Si descargaste el ZIP del módulo B: +```bash +unzip basura_backend.zip +cd basura_backend +``` + +--- + +## 2. Crear entorno virtual (recomendado) + +```bash +# 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 + +```bash +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 + +```bash +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/`: + +```bash +# .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. + +```bash +# 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 +```bash +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 +```bash +curl -X POST http://localhost:8000/admin/route/RUTA-01/start +``` + +Respuesta: +```json +{ + "message": "Ruta RUTA-01 iniciada", + "route_id": "RUTA-01", + "status": "EN_RUTA" +} +``` + +### Verificar estado del camión +```bash +curl http://localhost:8000/admin/route/RUTA-01/status +``` + +Respuesta: +```json +{ + "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 +```bash +curl http://localhost:8000/eta/1 +``` + +Respuesta: +```json +{ + "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: +```bash +npm install -g wscat +``` + +Conectar: +```bash +wscat -c ws://localhost:8000/ws/1 +``` + +Deberías empezar a recibir eventos cada vez que el ETA cambia: +```json +{ + "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 + +1. Nueva pestaña → selecciona **WebSocket Request** +2. URL: `ws://localhost:8000/ws/1` +3. Conectar +4. Los mensajes aparecen en el panel inferior + +--- + +## 10. Probar notificación de avería + +```bash +curl -X POST http://localhost:8000/alerts/breakdown \ + -H "Content-Type: application/json" \ + -d '{"route_id": "RUTA-01"}' +``` + +Si tienes `wscat` conectado, recibes: +```json +{ + "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 + +1. Descarga [sqlitebrowser.org](https://sqlitebrowser.org/) +2. Abre `basura.db` +3. Navega por las tablas + +### Con línea de comandos + +```bash +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:** +```bash +# 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 /F +``` + +### "No module named 'app'" +Estás corriendo `uvicorn` desde la carpeta incorrecta. + +**Solución:** +```bash +# 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:** +```bash +# 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: +```dart +// 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](02-frontend.md) — integrar los módulos C y D +- [Endpoints REST completos](../api/01-endpoints.md) +- [WebSocket protocol](../api/02-websocket.md)