105 lines
3.8 KiB
Markdown
105 lines
3.8 KiB
Markdown
# 🚛 BasuraApp — HackOnLinces 2026
|
|
|
|
Sistema de notificación inteligente y privada de recolección de residuos para la ciudadanía de Celaya, Guanajuato.
|
|
|
|
## 🎯 Problemática
|
|
|
|
Los ciudadanos no saben con certeza cuándo pasará el camión recolector, lo que genera basura en la calle fuera de horario, problemas de salud pública y fauna nociva.
|
|
|
|
## ✅ Solución
|
|
|
|
App móvil que notifica la hora aproximada de llegada del camión **sin exponer la ruta completa**, bajo un principio de **Privacidad por Diseño**.
|
|
|
|
## 🏗️ Arquitectura
|
|
Frontend (React Native / Expo)
|
|
↓ JWT + HTTPS + WebSocket
|
|
API Gateway + Auth (FastAPI)
|
|
↓ RBAC por domicilio
|
|
┌──────────────────────────────────────┐
|
|
│ ETA Service │ Simulator │ WS │
|
|
│ (cálculo) │ (cron job) │ Server│
|
|
└──────────────────────────────────────┘
|
|
↓
|
|
PostgreSQL — Usuario → Domicilio → Zona → Ruta
|
|
## 🔒 Privacidad por Diseño
|
|
|
|
- El usuario **solo ve** la ventana de llegada de su ruta asignada
|
|
- La API valida en cada request que el `usuario` solo accede a su `domicilio`
|
|
- **Prohibido**: mapa en tiempo real, rastreo del camión, explorar rutas ajenas
|
|
- Mensajería preventiva: la app desalienta sacar basura fuera de horario
|
|
|
|
## 📱 Funcionalidades MVP
|
|
|
|
- [x] Registro e inicio de sesión con JWT (email o teléfono)
|
|
- [x] Múltiples domicilios por usuario (casa y trabajo)
|
|
- [x] Alta de domicilio con combobox de colonias y código postal
|
|
- [x] ETA con ventana de llegada (±7 min)
|
|
- [x] Simulador de rutas — cron job cada 2 min avanza 15 rutas
|
|
- [x] WebSockets para ETA en tiempo real (fallback a polling cada 2 min)
|
|
- [x] 3 eventos de notificación: ROUTE_START, TRUCK_PROXIMITY, ROUTE_COMPLETED
|
|
- [x] Notificaciones configurables por tipo
|
|
- [x] Alertas operativas — retrasos y fallas mecánicas en tiempo real
|
|
- [x] Guía de separación de residuos (funciona offline)
|
|
- [x] RBAC — cada usuario solo consulta su ruta
|
|
- [x] Buzón de reportes con 4 categorías
|
|
- [x] Persistencia de sesión con AsyncStorage
|
|
- [x] Pull to refresh y auto-refresh
|
|
- [x] APK nativo compilado con EAS Build
|
|
|
|
## 🛠️ Stack Tecnológico
|
|
|
|
| Capa | Tecnología |
|
|
|------|-----------|
|
|
| Frontend | React Native + Expo SDK 54 |
|
|
| Backend | Python 3.12 + FastAPI |
|
|
| Tiempo real | WebSockets (FastAPI) |
|
|
| Auth | JWT (python-jose + passlib) |
|
|
| Base de datos | PostgreSQL + SQLAlchemy |
|
|
| Simulador | APScheduler (cron job cada 2 min) |
|
|
| Build nativo | EAS Build (Expo) |
|
|
| Control de versiones | Gitea (git.onlinces.net) |
|
|
|
|
## 🚀 Cómo correr el proyecto
|
|
|
|
### Backend
|
|
```bash
|
|
cd backend
|
|
python3 -m venv venv
|
|
source venv/bin/activate
|
|
pip install -r requirements.txt
|
|
uvicorn main:app --reload --port 8000 --host 0.0.0.0
|
|
```
|
|
|
|
### Frontend
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npx expo start
|
|
```
|
|
|
|
### Documentación de la API
|
|
Disponible en `http://localhost:8000/docs` (Swagger UI)
|
|
|
|
## 📊 Datasets utilizados
|
|
|
|
- `data/rutas.json` — 15 rutas con 8 posiciones GPS cada una
|
|
- `data/colonias-rutas.json` — mapeo colonia → ruta + horario estimado
|
|
- `data/notificaciones.json` — 3 eventos de notificación push
|
|
|
|
## 🔌 Endpoints principales
|
|
|
|
| Método | Endpoint | Descripción |
|
|
|--------|----------|-------------|
|
|
| POST | `/auth/register` | Registro con email o teléfono |
|
|
| POST | `/auth/login` | Login con JWT |
|
|
| POST | `/domicilios` | Alta de domicilio |
|
|
| GET | `/domicilios` | Listar domicilios del usuario |
|
|
| GET | `/eta/{domicilio_id}` | Ventana de llegada ETA |
|
|
| POST | `/reportes` | Buzón de retroalimentación |
|
|
| POST | `/alertas/operativa` | Crear alerta de retraso/falla |
|
|
| GET | `/alertas/operativa/activa` | Consultar alerta activa |
|
|
| WS | `/ws/eta/{domicilio_id}` | ETA en tiempo real vía WebSocket |
|
|
|
|
## 👤 Equipo
|
|
|
|
- **hack_21031301_c761d3** — HackOnLinces 2026 |