316 lines
14 KiB
Markdown
316 lines
14 KiB
Markdown
# Mi Ruta Limpia
|
|
|
|
> **Sistema de Notificación Inteligente y Privada de Recolección de Residuos**
|
|
> Hackathon LINCEHACK · Gobierno de Celaya
|
|
|
|
---
|
|
|
|
## 📑 Tabla de contenidos
|
|
|
|
1. [Problemática](#-problemática)
|
|
2. [Solución](#-solución)
|
|
3. [Características principales](#-características-principales)
|
|
4. [Stack tecnológico](#-stack-tecnológico)
|
|
5. [Arquitectura](#-arquitectura)
|
|
6. [Instalación rápida](#-instalación-rápida)
|
|
7. [Credenciales demo](#-credenciales-demo)
|
|
8. [Estructura del proyecto](#-estructura-del-proyecto)
|
|
9. [Privacidad por diseño](#-privacidad-por-diseño)
|
|
10. [Documentación adicional](#-documentación-adicional)
|
|
|
|
---
|
|
|
|
## 🎯 Problemática
|
|
|
|
En Celaya, la ciudadanía no sabe con certeza cuándo el camión recolector pasará por su domicilio. Esto provoca:
|
|
|
|
- Basura sacada demasiado **temprano** o **tarde**
|
|
- Acumulación cuando el camión ya pasó
|
|
- Problemas de salud pública: fauna nociva, malos olores, infecciones
|
|
- Molestias vecinales por basura en la calle
|
|
|
|
**La solución no puede ser un GPS público:** exponer la ruta completa del camión es un riesgo operativo (gente persigue al camión) y de privacidad.
|
|
|
|
---
|
|
|
|
## 💡 Solución
|
|
|
|
Una aplicación móvil que:
|
|
|
|
- Indica **hora aproximada de llegada** del camión a tu domicilio registrado
|
|
- Envía **notificaciones** sobre cambios operativos y retrasos
|
|
- Educa sobre **separación de residuos**
|
|
- Permite **reportar incidencias** con folio oficial
|
|
- Tiene 3 vistas: **Ciudadano**, **Empleado operativo** y **Administrador**
|
|
|
|
Todo bajo un principio **innegociable de Privacidad por Diseño**:
|
|
**el ciudadano solo ve la información de su zona, nunca el mapa completo del camión ni rutas de otros.**
|
|
|
|
---
|
|
|
|
## ✨ Características principales
|
|
|
|
### 👤 Vista Ciudadano
|
|
- 🏠 Múltiples domicilios con etiquetas (Casa, Trabajo, etc.)
|
|
- ⏰ ETA por ventana horaria (ej. *"Entre 7:20 y 7:35"*) — **sin coordenadas del camión**
|
|
- 📊 Barra de progreso de ruta sin exponer ubicación
|
|
- ✓ Confirmación *"¿Ya pasó la basura?"* con opción de deshacer
|
|
- ⭐ Calificación del servicio (1-5 estrellas)
|
|
- 📋 Reportes con **folio único** (`MRL-YYYYMMDD-XXXXXX`)
|
|
- 📤 Compartir reporte como comprobante
|
|
- 🌱 Educación ambiental con 4 categorías, datos de impacto y puntos de acopio
|
|
- 📅 Horarios por domicilio
|
|
|
|
### 👮 Vista Empleado Operativo
|
|
- 🚛 Reportes operativos (camión no arrancó, falla mecánica, accidente, obstáculo, etc.) con folio `OP-YYYYMMDD-XXXXXX`
|
|
- 🔥 **Racha de puntualidad** (días consecutivos)
|
|
- 💰 **Bonos** por puntualidad ($50 MXN/día puntual)
|
|
- 🏆 Próximo bono con cuenta regresiva
|
|
- 📅 Horario preestablecido con descansos técnicos
|
|
- 💬 Mensajes motivacionales rotativos
|
|
- ❌ **Sin acceso** a reportes ciudadanos (403 Forbidden)
|
|
|
|
### 🛡️ Vista Administrador
|
|
- 📊 Dashboard con KPIs en vivo (ciudadanos, domicilios, reportes 24h, calificación promedio)
|
|
- 📈 Gráficas de reportes por estado y por tipo
|
|
- 📋 Gestión de reportes ciudadanos (cambiar PENDIENTE → EN_PROCESO → RESUELTO → CERRADO)
|
|
- 👥 Gestión de usuarios y cambio de roles
|
|
- 🚛 Vista de flotilla (62 camiones)
|
|
- ⭐ Feedback ciudadano agregado
|
|
|
|
---
|
|
|
|
## 🛠️ Stack tecnológico
|
|
|
|
### Backend
|
|
- **Python 3.13** con **FastAPI 0.115**
|
|
- **SQLAlchemy 2.0** + **SQLite** (escalable a PostgreSQL)
|
|
- **JWT** (python-jose) + **bcrypt** para autenticación
|
|
- **Pydantic v2** para validación
|
|
- **PyTZ** para manejo correcto de zonas horarias (Celaya/CST)
|
|
|
|
### Frontend
|
|
- **React Native 0.74** con **Expo SDK 51**
|
|
- **React 18.2** + **React Navigation 6**
|
|
- **expo-linear-gradient**, **@expo/vector-icons**, **react-native-svg**
|
|
- **AsyncStorage** para persistencia local
|
|
- **react-native-url-polyfill** para compatibilidad WHATWG URL
|
|
|
|
### DevOps
|
|
- **Watchman** para file watching en macOS
|
|
- **Metro** bundler (Expo CLI)
|
|
- Migraciones manuales con SQL inline en seeds
|
|
|
|
---
|
|
|
|
## 🏗️ Arquitectura
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ FRONTEND (Expo) │
|
|
│ │
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|
│ │ CIUDADANO │ │ EMPLEADO │ │ ADMIN │ │
|
|
│ │ 5 tabs │ │ 3 tabs │ │ 4 tabs │ │
|
|
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
|
│ │ │ │ │
|
|
│ └────────────────┼──────────────────┘ │
|
|
│ │ │
|
|
│ fetch + AsyncStorage (JWT) │
|
|
└──────────────────────────┼───────────────────────────────────────┘
|
|
│ HTTPS REST
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ BACKEND (FastAPI) │
|
|
│ │
|
|
│ Routers: │
|
|
│ /api/v1/auth — login, register, OAuth, /me │
|
|
│ /api/v1/addresses — CRUD de domicilios + geo-routing │
|
|
│ /api/v1/eta — cálculo de ETA privado │
|
|
│ /api/v1/reports — reportes ciudadanos │
|
|
│ /api/v1/admin — endpoints restringidos a ADMIN │
|
|
│ /api/v1/staff — endpoints para EMPLEADO/ADMIN │
|
|
│ │
|
|
│ Middleware: │
|
|
│ - JWT auth (HTTPBearer) │
|
|
│ - RBAC (require_admin, require_staff) │
|
|
│ - CORS │
|
|
│ │
|
|
│ Services: │
|
|
│ - eta_service: simulación temporal de la flotilla │
|
|
│ - auth_service: hash, verify, JWT │
|
|
└──────────────────────────┼───────────────────────────────────────┘
|
|
│
|
|
┌──────────┴───────────┐
|
|
▼ ▼
|
|
┌──────────────┐ ┌───────────────┐
|
|
│ SQLite │ │ routes.json │
|
|
│ │ │ (mock GPS) │
|
|
│ 6 tablas: │ │ │
|
|
│ - users │ │ 15 rutas con │
|
|
│ - addresses │ │ waypoints + │
|
|
│ - reports │ │ timestamps │
|
|
│ - op_reports│ └───────────────┘
|
|
│ - ratings │
|
|
│ - trucks │
|
|
└──────────────┘
|
|
```
|
|
|
|
Ver detalles en [`docs/ARQUITECTURA.md`](docs/ARQUITECTURA.md).
|
|
|
|
---
|
|
|
|
## 🚀 Instalación rápida
|
|
|
|
### Prerequisitos
|
|
- **Node.js 20 LTS** (NO usar 22+)
|
|
- **Python 3.11+**
|
|
- **macOS** o **Linux** (instrucciones probadas en macOS con Xcode + iOS Simulator)
|
|
|
|
### Backend
|
|
|
|
```bash
|
|
cd backend
|
|
python3 -m venv venv
|
|
source venv/bin/activate
|
|
pip install -r requirements.txt
|
|
cp .env.example .env
|
|
|
|
# Poblar BD con datos demo + masivos
|
|
python seed_massive.py
|
|
|
|
# Arrancar API
|
|
uvicorn main:app --reload --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
API disponible en `http://localhost:8000` · Docs interactivos en `http://localhost:8000/docs`
|
|
|
|
### Frontend
|
|
|
|
```bash
|
|
cd frontend
|
|
ulimit -n 65536 # macOS file descriptors
|
|
npm install
|
|
npx expo start --clear
|
|
|
|
# Presiona 'i' para iOS simulator | 'w' para web | escanea QR con Expo Go
|
|
```
|
|
|
|
> ⚠️ La URL del backend está en [`frontend/src/constants/config.js`](frontend/src/constants/config.js). Cámbiala si tu IP local no es `10.82.68.125`.
|
|
|
|
Ver guía completa en [`docs/INSTALACION.md`](docs/INSTALACION.md).
|
|
|
|
---
|
|
|
|
## 🔑 Credenciales demo
|
|
|
|
| Rol | Email | Contraseña | Acceso |
|
|
|-----|-------|-----------|--------|
|
|
| 🧑 Ciudadano | `demo@celaya.gob.mx` | `Celaya2026` | 5 pestañas: Inicio, Horarios, Educación, Reportes, Perfil |
|
|
| 👮 Empleado | `empleado@celaya.gob.mx` | `Empleado2026` | 3 pestañas: Inicio (puntualidad), Reportes operativos, Cuenta |
|
|
| 🛡️ Admin | `admin@celaya.gob.mx` | `Admin2026` | 4 pestañas: Dashboard, Reportes ciudadanos, Usuarios, Cuenta |
|
|
|
|
La BD tiene además **202 usuarios totales, 302 domicilios, 280 reportes ciudadanos, 150 reportes operativos, 220 calificaciones y 62 camiones** generados con `seed_massive.py`.
|
|
|
|
---
|
|
|
|
## 📂 Estructura del proyecto
|
|
|
|
```
|
|
mi-ruta-limpia/
|
|
├── README.md ← este archivo
|
|
├── docs/
|
|
│ ├── ARQUITECTURA.md ← decisiones técnicas
|
|
│ ├── MANUAL_USUARIO.md ← guía visual por pantalla
|
|
│ ├── API.md ← referencia REST
|
|
│ ├── INSTALACION.md ← guía paso a paso
|
|
│ └── PRESENTACION.md ← script de demo
|
|
│
|
|
├── backend/
|
|
│ ├── main.py ← entry point + CORS + routers
|
|
│ ├── requirements.txt
|
|
│ ├── seed.py ← seed básico (3 usuarios)
|
|
│ ├── seed_massive.py ← seed con 200+ usuarios y datos
|
|
│ └── app/
|
|
│ ├── config.py ← settings (JWT, DB)
|
|
│ ├── database.py ← SQLAlchemy session
|
|
│ ├── models/ ← User, Address, Report, OperationalReport, Truck, ServiceRating
|
|
│ ├── schemas/ ← Pydantic v2
|
|
│ ├── routers/ ← auth, addresses, eta, reports, admin, staff
|
|
│ ├── services/ ← auth_service, eta_service
|
|
│ └── data/routes.json ← 15 rutas mock
|
|
│
|
|
└── frontend/
|
|
├── App.js
|
|
├── index.js ← polyfill + entry
|
|
├── package.json
|
|
├── babel.config.js
|
|
├── app.json
|
|
├── assets/ ← logos, hero-eco, splash, icons
|
|
└── src/
|
|
├── constants/ ← colors, config
|
|
├── context/ ← AuthContext (JWT + role)
|
|
├── navigation/ ← AppNavigator (routing por rol)
|
|
├── components/ ← AppHeader, GoogleGIcon
|
|
├── services/api.js ← fetch + interceptors
|
|
└── screens/
|
|
├── auth/ ← Login, Register
|
|
├── HomeScreen.js ← ciudadano (5 tabs)
|
|
├── SchedulesScreen.js
|
|
├── ReportsScreen.js
|
|
├── ProfileScreen.js
|
|
├── EducationScreen.js
|
|
├── staff/ ← empleado (3 tabs)
|
|
│ ├── StaffDashboard.js
|
|
│ └── StaffReports.js
|
|
└── admin/ ← admin (4 tabs)
|
|
├── AdminDashboard.js
|
|
├── AdminReports.js
|
|
├── AdminUsers.js
|
|
└── AdminProfile.js
|
|
```
|
|
|
|
---
|
|
|
|
## 🔒 Privacidad por diseño
|
|
|
|
Este es el **principio innegociable** del reto del hackathon. Cumplimos así:
|
|
|
|
| Riesgo | Mitigación |
|
|
|--------|-----------|
|
|
| Ciudadanos persiguiendo camiones | El endpoint `/eta/address/:id` **nunca devuelve coordenadas del camión**. Solo: status, mensaje, eta_minutes, window_start/end, progress% |
|
|
| Snooping de otras rutas | El usuario solo puede consultar sus propios `address_id`. El backend valida `Address.user_id == JWT.user_id` |
|
|
| Exposición de información operativa | Las rutas de los demás camiones no son visibles ni siquiera con manipulación del request |
|
|
| Confianza en la app | La interfaz **desalienta explícitamente** perseguir al camión (`"Por tu seguridad, no persigas al camión"`) |
|
|
| Datos sensibles | Contraseñas con bcrypt · JWT firmado con HS256 · ningún PII se expone en logs |
|
|
|
|
Ver [`docs/ARQUITECTURA.md#privacidad-por-diseño`](docs/ARQUITECTURA.md) para el análisis completo.
|
|
|
|
---
|
|
|
|
## 📚 Documentación adicional
|
|
|
|
| Documento | Para quién | Contenido |
|
|
|-----------|------------|-----------|
|
|
| [`docs/ARQUITECTURA.md`](docs/ARQUITECTURA.md) | Jueces técnicos | Decisiones de diseño, algoritmo ETA, RBAC, BD, simulación |
|
|
| [`docs/MANUAL_USUARIO.md`](docs/MANUAL_USUARIO.md) | Usuarios finales | Guía visual por pantalla y flujo |
|
|
| [`docs/API.md`](docs/API.md) | Desarrolladores | Referencia REST completa con ejemplos |
|
|
| [`docs/INSTALACION.md`](docs/INSTALACION.md) | Equipo de operaciones | Setup paso a paso, troubleshooting |
|
|
| [`docs/PRESENTACION.md`](docs/PRESENTACION.md) | Equipo presentador | Script de demo para los 5-10 min del pitch |
|
|
|
|
---
|
|
|
|
## 🏆 Equipo
|
|
|
|
**LINCEHACK 2026** — Hackathon Gobierno de Celaya
|
|
|
|
---
|
|
|
|
## 📝 Licencia
|
|
|
|
Proyecto desarrollado para fines educativos en el marco del hackathon LINCEHACK. Datos de Celaya son referenciales.
|
|
|
|
---
|
|
|
|
🌱 *Celaya, es la esperanza.*
|