Initial commit

docs/ARQUITECTURA.md

@@ -0,0 +1,318 @@
+# Arquitectura técnica
+
+> Documento técnico para evaluación. Decisiones de diseño, algoritmos clave y consideraciones de privacidad/seguridad.
+
+---
+
+## 1. Visión general
+
+**Mi Ruta Limpia** es una arquitectura **cliente–servidor REST** con simulación de eventos en el backend para emular telemetría de la flotilla, sin requerir GPS real.
+
+```
+[App móvil RN] ↔ HTTPS/REST + JWT ↔ [FastAPI] ↔ SQLite + routes.json (mock)
+```
+
+### Por qué esta arquitectura
+
+| Decisión | Razón |
+|----------|-------|
+| **FastAPI** (Python) | Validación automática con Pydantic, OpenAPI docs gratis, async-ready, productivo en hackathon |
+| **SQLite** (no PostgreSQL) | Zero-config, suficiente para hackathon, migración a PG es trivial (cambiar `DATABASE_URL`) |
+| **JSON mock para rutas** | Cumple el requisito de "simular eventos sin telemetría real" sin complejidad innecesaria |
+| **JWT** stateless | No requiere sesión en servidor, escalable horizontalmente |
+| **React Native + Expo** | Multiplataforma (iOS, Android, web) con un solo código |
+| **fetch sobre axios** | Axios rompe en RN nueva arquitectura por `URL.protocol` strict mode |
+
+---
+
+## 2. Backend — Estructura por capas
+
+```
+app/
+├── config.py        ← Settings con pydantic-settings (env vars)
+├── database.py      ← SQLAlchemy engine + sessionmaker
+├── models/          ← ORM (capa de datos)
+├── schemas/         ← Pydantic (capa de validación / serialización)
+├── routers/         ← Endpoints HTTP (capa de presentación)
+└── services/        ← Lógica de negocio (capa de dominio)
+```
+
+**Patrón:** los routers solo orquestan. Toda la lógica real vive en `services/`. Los modelos no contienen lógica.
+
+### Inyección de dependencias (FastAPI `Depends`)
+
+```python
+# Cada endpoint declara qué necesita:
+@router.get("/eta/address/{id}")
+def get_eta(
+    id: int,
+    db: Session = Depends(get_db),       ← BD sesión
+    user = Depends(get_current_user),     ← JWT validado
+):
+    ...
+```
+
+Esto permite testear cada endpoint con mocks fácilmente.
+
+---
+
+## 3. Modelo de datos
+
+```
+users (id, email, phone, full_name, hashed_password, role, oauth_*, push_token, is_active)
+  │
+  ├──< addresses (id, user_id, label, street, colony, lat, lng, route_id, is_default)
+  │       │
+  │       ├──< reports (id, user_id, address_id, folio, report_type, description, status, created_at)
+  │       │
+  │       └──< service_ratings (id, user_id, address_id, rating, comment, created_at)
+  │
+  └──< operational_reports (id, employee_id, folio, category, severity, route_id, truck_id, status, ...)
+
+trucks (id, unit_number, plate, model, year, status, route_id, base, odometer_km, fuel_level_pct, ...)
+```
+
+### Roles (RBAC)
+- **`CIUDADANO`** — default. Solo accede a `/auth`, `/addresses` (suyos), `/eta` (suyos), `/reports` (suyos)
+- **`EMPLEADO`** — accede a `/staff/*` (su propio dashboard, sus reportes operativos). NO accede a `/admin/*`
+- **`ADMIN`** — accede a todo, incluyendo `/admin/*` (gestión de reportes ciudadanos y usuarios)
+
+### Migraciones
+Por simplicidad de hackathon, las migraciones se hacen con `Base.metadata.create_all()` + `ALTER TABLE` inline en `seed.py`. En producción se debe usar **Alembic**.
+
+---
+
+## 4. Algoritmo ETA — núcleo del sistema
+
+### Problema
+Dado un domicilio (lat, lng) y la hora actual, calcular cuándo pasará el camión **sin exponer su ubicación real**.
+
+### Datos de entrada
+[`backend/app/data/routes.json`](../backend/app/data/routes.json) — 15 rutas, cada una con 8 waypoints, cada waypoint con:
+- `lat`, `lng`
+- `timestamp` (template, se reinterpreta cada día)
+- `speed`
+
+### Algoritmo (`app/services/eta_service.py`)
+
+```python
+def get_eta(route_id, user_lat, user_lng):
+    route = load_route(route_id)
+    now = datetime.now(CELAYA_TZ)
+    
+    # 1. Construir horario del día con base en los timestamps templates
+    first_t = today_at(parse(route.positions[0].timestamp))
+    last_t  = today_at(parse(route.positions[-1].timestamp))
+    
+    # 2. Determinar fase
+    if now < first_t:   return PROGRAMADO    # no ha empezado
+    if now > last_t:    return PASO          # ya terminó
+    
+    # 3. Encontrar entre qué dos waypoints está el camión ahora
+    current_idx = find_segment(route, now)
+    
+    # 4. Encontrar el waypoint más cercano al domicilio del usuario
+    closest_idx = argmin(haversine(user, w) for w in route.positions)
+    
+    # 5. Comparar
+    if current_idx > closest_idx:   return PASO         # ya pasó
+    if current_idx == closest_idx:  return LLEGANDO     # muy cerca
+    
+    # 6. Calcular ventana horaria
+    user_time = today_at(parse(route.positions[closest_idx].timestamp))
+    eta_minutes = (user_time - now).minutes
+    
+    return {
+        'status': 'EN_CAMINO',
+        'message': f'Entre las {user_time - 8min} y {user_time + 8min}',
+        'eta_minutes': eta_minutes,
+        'progress': elapsed_pct(now, first_t, last_t),
+    }
+```
+
+### Por qué este enfoque
+- **No requiere telemetría real:** los timestamps son el "schedule" diario; la posición actual se infiere de la hora
+- **Privacy by design built-in:** la API jamás devuelve `lat`/`lng` del camión
+- **Predecible:** el ciudadano sabe el rango horario, no un punto exacto
+- **Tolerante a tráfico:** las ventanas (`±8 minutos`) absorben la variabilidad
+
+### Geo-routing automático
+Cuando un ciudadano registra un domicilio sin `route_id`, `assign_route(lat, lng)` calcula el waypoint más cercano de todas las rutas y asigna la ruta correspondiente (algoritmo: distancia Haversine en O(n) con n=15·8=120 waypoints).
+
+---
+
+## 5. Seguridad
+
+### Autenticación
+- **bcrypt** con cost factor 12 para hashing
+- **JWT** firmado con HS256, expira en 7 días
+- El token incluye `sub` (user_id) y `role`
+- Los endpoints sensibles validan el token con `HTTPBearer` + dependency
+
+### Autorización (RBAC)
+Tres dependencies en `routers/deps.py`:
+
+```python
+get_current_user → cualquier rol autenticado
+require_staff    → EMPLEADO o ADMIN (devuelve 403 si no)
+require_admin    → solo ADMIN (devuelve 403 si no)
+```
+
+Probado con curl:
+```bash
+# Ciudadano → /admin/stats → HTTP 403 ✓
+# Empleado  → /admin/reports → HTTP 403 ✓
+# Empleado  → /staff/dashboard → HTTP 200 ✓
+```
+
+### Pasos adicionales para producción
+- [ ] Refresh tokens
+- [ ] Rate limiting (slowapi)
+- [ ] HTTPS obligatorio
+- [ ] CORS estricto (no `*`)
+- [ ] Logs auditables (sin PII)
+- [ ] Rotación de `SECRET_KEY`
+- [ ] 2FA opcional
+
+---
+
+## 6. Privacidad por Diseño
+
+| Requisito hackathon | Cómo se cumple |
+|---------------------|----------------|
+| "**PROHIBIDO el seguidor de ruta activo**" | El endpoint `/eta/address/:id` **nunca** devuelve `lat`/`lng` del camión. Solo: status, mensaje, ventana horaria, progreso% |
+| "**PROHIBIDO el snooping**" | El backend valida `Address.user_id == current_user.id` en cada petición. Si intentas consultar `/eta/address/999` y no te pertenece → 404 |
+| "**Visión de túnel: solo tu ruta**" | El cliente solo recibe `route_name` (texto), nunca el polyline de la ruta |
+| "**Mensajería preventiva**" | Banner explícito en HomeScreen: *"Por tu seguridad, no persigas al camión. ¡Saca tu basura con tiempo!"* |
+
+### Verificación
+```bash
+# Login como demo (id=1)
+curl -X POST .../auth/login -d '{"email":"demo@celaya.gob.mx","password":"Celaya2026"}'
+
+# Intentar acceder a un domicilio ajeno (id=999)
+curl -H "Authorization: Bearer $TOKEN" .../eta/address/999
+# → HTTP 404 "Domicilio no encontrado"
+```
+
+---
+
+## 7. Simulación de eventos
+
+Cumple el requisito *"Dado que no tendrán acceso a la telemetría real, deberán simular el avance de la ruta"*.
+
+### Estrategia
+1. **`routes.json`** contiene 15 rutas con 8 waypoints + timestamps cada una
+2. Los timestamps son **templates relativos**: se reinterpretan cada día
+3. **`eta_service.py`** los proyecta a la fecha actual y calcula la posición simulada por interpolación temporal
+4. **No hay cron job ni websockets** — la simulación es **stateless y on-demand**
+
+### Ventaja
+Cualquier petición al backend, en cualquier momento del día, devuelve un ETA coherente con la "hora del camión" sin necesidad de procesos en background.
+
+### Migración a telemetría real
+Para producción con GPS real, solo cambiar `eta_service.get_eta()` para que:
+1. Lea la posición actual del camión desde una tabla `truck_positions` (alimentada por GPS real)
+2. Compare contra el waypoint del usuario
+3. Devuelva la misma estructura de respuesta — **el cliente no cambia**
+
+---
+
+## 8. Frontend — Arquitectura
+
+### Routing por rol
+```
+LoginScreen
+   ↓ (login exitoso)
+AuthContext.user.role
+   ├── 'CIUDADANO' → CitizenTabs (5 pestañas)
+   ├── 'EMPLEADO'  → EmployeeTabs (3 pestañas)
+   └── 'ADMIN'     → AdminTabs (4 pestañas)
+```
+
+### Estado
+- **AuthContext** global (React Context) — guarda `user` + métodos `login/logout/register`
+- **AsyncStorage** persistente — guarda el JWT entre sesiones
+- **Estado local por pantalla** (`useState`) — listas, modales, formularios
+- **No usamos Redux/Zustand** — overkill para este alcance
+
+### Networking
+- **`fetch`** nativo en lugar de axios (compatibilidad con RN nueva arq.)
+- **Interceptor de auth**: `services/api.js` añade el `Authorization: Bearer` automáticamente y limpia el token en 401
+- **No hay polling agresivo**: el cliente solo refresca al pull-to-refresh o navegar
+
+### Polyfills críticos
+- `react-native-url-polyfill/auto` — reemplaza `global.URL` con la implementación WHATWG completa **antes** de que Expo cargue. Solución al bug *"URL.protocol is not implemented"* en RN 0.74
+
+---
+
+## 9. Decisiones de UX
+
+### Tipografía y color
+- **Color guinda institucional** `#7B1A2E` (extraído del logo del Gobierno de Celaya)
+- **Acento dorado** `#C8960C` para etiquetas de sección, evocando el slogan "ES GRANDE POR TI"
+- **Encabezado guinda detrás de la dynamic island** en todas las pestañas — efecto de marca premium
+- Tipografía: pesos 800-900 para títulos, 600 para subtítulos, 400 para cuerpo
+
+### Patrón de pantalla repetido
+Todas las pantallas post-login siguen:
+```
+AppHeader (guinda + "Mi Ruta Limpia")
+↓
+Hero (gradient o imagen con título grande)
+↓
+[Etiqueta dorada UPPERCASE] + [Título grande sección]
+↓
+Cards / contenido
+```
+
+### Microinteracciones
+- Pull-to-refresh en listas
+- Confirmación "ya pasó" con opción **deshacer** (persistente por día/domicilio en AsyncStorage)
+- Modales bottom-sheet para formularios largos
+- Toast/Alert nativo para feedback
+
+---
+
+## 10. Limitaciones conocidas
+
+| Limitación | Por qué | Mitigación |
+|------------|---------|------------|
+| Sin push notifications reales | Requiere Firebase Cloud Messaging y certificados | El esquema `push_token` en User está listo; solo falta integrar FCM |
+| Sin OAuth real | Requiere SDK de Google/Facebook/Apple | El endpoint `/auth/oauth` está implementado; solo falta integrar el SDK del lado del cliente |
+| Sin PDF de reportes | Requiere `expo-print` o servicio externo | Implementamos compartir como texto formateado con `Share` nativo |
+| BD no escala a millones | SQLite no es para producción | Cambiar `DATABASE_URL` a PostgreSQL — toda la app sigue funcionando |
+| Simulación, no GPS real | Cumple el requisito del hackathon | Endpoint listo para reemplazar con telemetría real |
+
+---
+
+## 11. Sugerencias del brief que SÍ cumplimos
+
+| Sugerencia del reto | Estado |
+|--------------------|:------:|
+| Consumo inteligente de APIs geográficas (geocodificación solo en registro, cálculos internos) | ✅ |
+| Cálculo interno de distancias (Haversine en Python) | ✅ |
+| Notificaciones asíncronas listas para FCM | ✅ (esquema preparado) |
+| Arquitectura por capas (lógica/datos separados) | ✅ |
+| API REST limpia | ✅ |
+| Multiplataforma (iOS, Android, Web) | ✅ |
+| Manejo eficiente de estado | ✅ (sin polling, refresh manual) |
+| Indexación geoespacial básica | ✅ (assign_route por proximidad) |
+| Autenticación JWT | ✅ |
+| RBAC | ✅ (3 niveles) |
+
+---
+
+## 12. Métricas del proyecto
+
+| Métrica | Valor |
+|---------|------:|
+| Archivos backend | 27 |
+| Archivos frontend (src/) | 22 |
+| Líneas de código backend | ~1,800 |
+| Líneas de código frontend | ~3,500 |
+| Endpoints REST | 28 |
+| Modelos de datos | 6 |
+| Pantallas | 14 (5 ciudadano + 3 empleado + 4 admin + 2 auth) |
+| Componentes reusables | 2 (AppHeader, GoogleGIcon) |
+| Datos en BD (seed_massive) | 202 usuarios · 302 domicilios · 280 reportes · 150 op-reportes · 62 camiones · 220 calificaciones |