# Contexto del Proyecto — Sistema de Recolección Inteligente y Privada de Residuos

> **Documento para compartir con asistentes de IA (Claude, ChatGPT, etc.)**  
> Última actualización: Mayo 2026  
> Equipo: 4 personas, hackathon, stack principal Flutter + FastAPI

---

## 1. ¿Qué estamos construyendo?

Una **app móvil (Flutter)** que notifica a los ciudadanos cuándo llegará el camión recolector a su domicilio **sin revelar la ubicación del camión en tiempo real ni mostrar el mapa completo de la ruta**. Incluye educación sobre separación de residuos mediante una mascota de IA y gestión de cambios operativos (fallas mecánicas, reasignaciones de rutas). Tres roles: ciudadano, chofer, admin.

### El problema que resuelve
La gente no sabe cuándo pasará el camión → saca la basura demasiado temprano/tarde → problemas de salud pública. La solución obvia (GPS en vivo del camión) es un riesgo de seguridad y uso inadecuado. Nuestra app balancea información útil con privacidad operativa.

### Alcance del MVP
- **7 colonias** de Celaya, Gto. mapeadas a **6 rutas** (datos provistos en JSON).
- Notificaciones push en 3 momentos: ruta inicia, camión cerca (~15 min), servicio finalizado.
- Validación de domicilio con OCR de recibo (luz/agua) que se borra tras extraer la dirección.
- Mascota IA interactiva + guía offline de separación de residuos.
- Feedback ciudadano + quiz post-recolección.
- Panel admin con mapa (única vista que ve coordenadas) y gestión de reasignaciones.

---

## 2. Reglas innegociables (Privacidad por Diseño)

Estas son las **prohibiciones del reto** convertidas en requisitos de código. Cualquier feature que las viole se rechaza:

1. **NUNCA se devuelven coordenadas del camión al ciudadano.** Solo texto: `"Llega en ~15 min"` / `"7:20–7:35 p.m."`.
2. **NUNCA hay un mapa con el camión moviéndose** en la vista ciudadana (prohibido el *route tracker*).
3. **Visión de túnel:** el ciudadano solo ve su ruta asignada. Cero visibilidad de colonias vecinas u otros usuarios (anti-*snooping*).
4. La ubicación del camión **solo existe en el panel admin** (para troubleshooting).
5. **Mensajería preventiva:** textos que desalientan sacar basura fuera de horario o perseguir la unidad.
6. Quejas hacia la unidad **no exponen** la identidad del chofer (solo "unidad 101"; el admin sí ve quién la conduce).
7. Los recibos (validación de domicilio) **no se almacenan crudos**: se procesan, se valida, se guarda solo `verified=true` y se **borra** la imagen.

**Implementación técnica del túnel:**
- Backend: Row Level Security (RLS) de Supabase — el ciudadano físicamente no puede leer `route_positions` ni domicilios ajenos aunque evada la API.
- Frontend: notificaciones FCM por **topic de ruta** (`topic_RUTA-01`) — cada ciudadano se suscribe solo al topic de su `routeId`.

---

## 3. Stack tecnológico (y por qué)

| Capa | Tecnología | Razón |
|------|------------|-------|
| **Frontend móvil** | Flutter + Riverpod (estado) + `dio` (HTTP) + `go_router` | Multiplataforma iOS/Android con un solo código. Riverpod evita polling excesivo. |
| **Backend / API** | Python + FastAPI | REST async, rápida de escribir, separa lógica de negocio de datos. |
| **Base de datos** | PostgreSQL (vía Supabase); PostGIS opcional | El mapeo colonia→ruta es directo (JSON), así que no necesitamos point-in-polygon. PostGIS solo si quieren validar por polígono en el futuro. |
| **Auth + RBAC** | Supabase Auth (JWT) + Row Level Security (RLS) | RLS aplica el túnel **a nivel de BD**, no solo en código — aunque alguien evada la API, la BD niega el acceso. |
| **Almacenamiento** | Supabase Storage | Para subir recibo temporalmente. Se borra tras validación. |
| **Simulación** | APScheduler (FastAPI cron job) | Avanza `positionId` de cada ruta (1→8) y dispara notificaciones. No hace falta cálculo geoespacial. |
| **Push** | Firebase Cloud Messaging (FCM) | Asíncrono, ligero, integración nativa con Flutter. |
| **Mascota IA** | API de Claude/Gemini con system prompt sobre separación | El chat educativo. Guía estática (JSON local) funciona offline. |
| **OCR validación** | Tesseract o modelo de visión en backend | Extrae dirección del recibo, compara, descarta imagen. |
| **Deploy** | Cloud Run / Render (backend scale-to-zero) + Supabase | Escala a cero en valles de inactividad. |

---

## 4. Datos provistos (la base real del proyecto)

Nos entregaron 3 archivos JSON que **definen el modelo y simplifican la implementación**:

### `rutas.json` (15 rutas, usamos 6)
- Cada ruta tiene un `routeId` (ej. `"RUTA-01"`), `truckId` (101–115), y **8 posiciones fijas** (`positionId` 1→8) con lat/lng, velocidad y timestamp.
- Todas salen y regresan al **Relleno Sanitario** (`20.5111, -100.9037`) — posición 1 = posición 8.
- Velocidad = 0 en posición 5 (punto más lejano / vuelta).
- Estas coordenadas **solo se usan en el panel admin** — nunca se mandan al ciudadano.

### `notificaciones.json` (motor de eventos)
Define los 3 eventos que **NO se calculan por distancia**, sino por **cambio de `positionId`**:

| Evento | Se dispara cuando | Mensaje (resumen) |
|--------|-------------------|-------------------|
| `ROUTE_START` | `positionId` pasa de 1 → 2 | Salió del relleno rumbo a tu sector |
| `TRUCK_PROXIMITY` | `positionId` llega a 4 | A menos de 15 min; saca tus bolsas |
| `ROUTE_COMPLETED` | `positionId` llega a 8 | Servicio del día finalizado |

### `colonias-rutas.json` (el puente colonia → ruta)
Mapea cada colonia a un `routeId` + horario. **Esto es el "túnel":** ciudadano → colonia → `routeId` → solo eventos de ESA ruta.

**Alcance del MVP (7 colonias / 6 rutas):**

| Colonia | routeId | Turno |
|---------|---------|-------|
| Zona Centro | RUTA-01 | Matutino |
| Las Arboledas | RUTA-01 | Matutino |
| San Juanico | RUTA-03 | Matutino |
| Los Olivos | RUTA-04 | Matutino |
| **Rancho Seco** | **RUTA-05** | **Vespertino** ← única vespertina; úsenla para demostrar reasignación |
| Las Insurgentes | RUTA-12 | Matutino |
| Trojes | RUTA-13 | Matutino |

En el registro, el ciudadano **elige su colonia de un dropdown** (no geocodificación). Eso le asigna su `routeId` y resuelve el túnel sin PostGIS.

---

## 5. Modelo de datos (jerarquía: Usuario → Domicilio → Colonia → Ruta)

```sql
users            (id, email/phone, role: 'citizen'|'driver'|'admin')
addresses        (id, user_id, label, calle, colonia, route_id,
                  verified BOOL, verified_method, verified_at)
colonias         (id, nombre, route_id, horario_estimado, turno)
routes           (id 'RUTA-01'..'RUTA-13', name, truck_id, 
                  turno: 'matutino'|'vespertino',
                  status: 'pendiente'|'en_ruta'|'completada'|'diferida'|'reasignada',
                  current_position_id INT)   -- el "avance" simulado vive aquí (1-8)
route_positions  (route_id, position_id, lat, lng, speed, ts)  
                 -- de rutas.json; ⚠️ SOLO panel admin (RLS)
units            (id 101.., plate, status)        -- 1:1 con driver y con route
drivers          (id, user_id, unit_id)           -- cada chofer = 1 unidad
collection_events(id, route_id, address_id, status, collected_at)
feedback         (id, user_id, address_id, type, target_unit_id,
                  message, rating, created_at)     -- target = unidad, NO chofer
notifications    (id, user_id, route_id, type, payload, sent_at)
route_changes    (id, route_id, from_unit, to_unit, reason, created_at)
```

**Cambio clave:** el estado del camión NO es una coordenada calculada en vivo, sino el campo `current_position_id` (1–8). Las coordenadas de `route_positions` solo las consume el panel admin.

---

## 6. Cómo funciona la simulación (el corazón del sistema)

La simulación NO calcula distancias ni ETA por geolocalización. Es un **índice que avanza** + disparadores de eventos.

### El cron job (APScheduler en FastAPI)
```python
# El "estado" de cada ruta es solo en qué positionId va (1-8).
estado = { "RUTA-01": 1, "RUTA-03": 1, "RUTA-04": 1,
           "RUTA-05": 1, "RUTA-12": 1, "RUTA-13": 1 }

def tick():                       # corre cada N segundos (APScheduler)
    for route_id, pos in estado.items():
        if pos < 8:
            nueva = pos + 1
            estado[route_id] = nueva          # = routes.current_position_id en BD
            disparar_si_aplica(route_id, pos, nueva)

def disparar_si_aplica(route_id, antes, ahora):
    # Lee notificaciones.json y dispara según el cambio de positionId
    if antes == 1 and ahora == 2: push(route_id, "ROUTE_START")
    elif ahora == 4:              push(route_id, "TRUCK_PROXIMITY")
    elif ahora == 8:              push(route_id, "ROUTE_COMPLETED")
```

### El túnel vía FCM topics
```python
# La push solo va a quienes están en esa ruta (no broadcast).
def push(route_id, evento):
    payload = NOTIFICACIONES[evento]["pushPayload"]   # de notificaciones.json
    fcm.send_to_topic(f"topic_{route_id}", payload)    # ej. "topic_RUTA-01"
# El ciudadano se suscribe SOLO al topic de su routeId → nunca recibe de otra ruta.
# El payload solo lleva texto (title/body); JAMÁS lat/lng.
```

### ETA sin coordenadas (endpoint ciudadano)
```python
# GET /eta?address_id=123  (ciudadano)
route = get_route_for_address(address_id)   # derivado de colonia
pos = route.current_position_id

if pos < 4:      mensaje = "El camión va en camino a tu sector"
elif pos == 4:   mensaje = "Llega en aproximadamente 15 minutos"
elif pos < 8:    mensaje = "Está atendiendo tu zona; saca tus bolsas"
else:            mensaje = "Servicio del día finalizado"

# Devuelve SOLO texto:
return {"mensaje": mensaje, "status": route.status}
# NUNCA coordenadas.
```

### RLS (el túnel a nivel de BD)
```sql
-- El ciudadano SOLO ve sus domicilios (refuerzo del túnel):
CREATE POLICY citizen_own_addresses ON addresses
  FOR SELECT USING (auth.uid() = user_id);

-- route_positions (coordenadas): sin policy para citizen = sin acceso. Solo admin:
CREATE POLICY admin_route_positions ON route_positions
  FOR SELECT USING (
    (SELECT role FROM users WHERE id = auth.uid()) = 'admin'
  );
```

---

## 7. Lógica de turnos y reasignación

De las notas del equipo:
- Una ruta es **matutina O vespertina**, nunca ambas.
- Ruta **matutina** que no se completó → se **difiere** al día siguiente + **notifica**.
- Ruta **vespertina** que la unidad no puede atender → la **reemplaza una unidad de mañana** (ya libre) + **notifica**. (Rancho Seco / RUTA-05 es el caso de demo.)
- Cada cambio escribe en `route_changes` y dispara FCM con evento `reasignacion`/`retraso` al topic de la ruta.

---

## 8. Reparto del equipo (4 personas)

| Persona | Bloque | Responsabilidad |
|---------|--------|-----------------|
| **P1 (Líder)** | Setup + Backend & Seguridad | Inicializar Flutter/backend, arquitectura API REST, JWT, RBAC/RLS, schema, validación de domicilio (OCR + privacidad). |
| **P2** | Simulación + Notificaciones + Datos | Carga de los 3 JSON, simulación por `positionId` (cron), motor de eventos/FCM, lógica de turnos/reasignación, endpoint de ETA por texto. |
| **P3** | Frontend Ciudadano (Flutter) | Registro, alta/validación de domicilios (dropdown colonia), vista ETA, suscripción FCM al topic de su ruta, buzón de retroalimentación, quiz de satisfacción. |
| **P4** | Frontend Admin + Chofer + Mascota IA | Paneles admin (mapa de posiciones, única vista con coordenadas) y chofer (marcar avance, reportar falla), mascota interactiva (LLM), guía de separación offline (JSON local). |

**Pair programming:** VS Code Live Share. Parejas sugeridas: P1↔P2 (backend/datos) y P3↔P4 (Flutter).

---

## 9. Estructura de archivos del monorepo

```
ONLINESHACK/                      <- raíz del repo (git aquí)
├── .gitignore                    <- raíz (cubre Flutter + Python)
├── README.md
├── PLAN.md                       <- el checklist del proyecto
├── claude.md                     <- este archivo
├── recolecta_app/                <- Flutter
│   ├── lib/
│   │   ├── core/                 (theme, network/dio_client, auth, constants)
│   │   ├── features/             (auth, addresses, eta, notifications,
│   │   │                          separation_guide, feedback, admin, driver)
│   │   └── shared/               (widgets reutilizables)
│   ├── assets/
│   │   └── .env                  <- (opcional) config pública: API_BASE_URL, anon key
│   ├── pubspec.yaml
│   └── ...
└── backend/                      <- FastAPI
    ├── app/
    │   ├── api/                  (routers: auth, addresses, routes, eta, feedback, admin)
    │   ├── core/                 (config, security/jwt, deps)
    │   ├── schemas/              (DTOs Pydantic)
    │   ├── services/             (simulation, notifications, reassignment, ocr)
    │   ├── data/                 <- los 3 JSON provistos
    │   │   ├── colonias-rutas.json
    │   │   ├── notificaciones.json
    │   │   └── rutas.json
    │   └── db/                   (session, seed.py)
    ├── secrets/
    │   └── firebase-adminsdk.json   <- ignorado
    ├── .env                      <- secretos reales (ignorado)
    ├── .env.example              <- plantilla (versionada)
    ├── requirements.txt
    └── main.py
```

---

## 10. Secretos y `.env`

**Backend `.env` (secretos reales, nunca al cliente):**
```bash
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_ANON_KEY=eyJ...         # llave pública; puede ir al cliente
SUPABASE_SERVICE_ROLE_KEY=eyJ... # llave secreta; SOLO backend
JWT_SECRET=xxx
FIREBASE_CREDENTIALS_PATH=./secrets/firebase-adminsdk.json
SIMULATION_TICK_SECONDS=10
```

**Flutter `.env` (SOLO config pública, viaja en el .apk/.ipa):**
```bash
API_BASE_URL=http://10.0.2.2:8000   # 10.0.2.2 = localhost desde emulador Android
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_ANON_KEY=eyJ...            # llave anon: pública por diseño
```

**Principio:** cualquier cosa que meta en Flutter es extraíble → no es secreto. Los secretos reales (service_role, admin SDK) viven únicamente en el backend.

---

## 11. Decisiones arquitectónicas clave (y por qué)

1. **Supabase RLS en vez de RBAC solo en código:** aunque alguien evada la API (bug, exploit), la BD niega el acceso. Es "defense in depth" para Privacidad por Diseño.

2. **Simulación por `positionId` en vez de cálculo geoespacial:** los datos provistos ya definen 8 posiciones fijas con timestamps. Avanzar un índice es trivial, y los eventos salen de `notificaciones.json` sin cálculos. Evita complejidad innecesaria.

3. **FCM por topic de ruta en vez de push individual:** escala mejor (un mensaje llega a todos los ciudadanos de la ruta). El túnel se resuelve en la suscripción: cada quien solo está en `topic_{su_routeId}`.

4. **Dropdown de colonia en vez de geocodificación:** los datos ya mapean colonia→ruta. Geocodificar sería redundante y costaría llamadas a API. El dropdown es más rápido, más barato y suficiente para el MVP.

5. **OCR + borrado del recibo:** cumple "Privacidad por Diseño" literalmente — la imagen nunca persiste. Solo queda `verified=true` + método + timestamp.

6. **Guía offline + chat IA:** la guía estática (JSON embebido en Flutter) garantiza que funcione sin red. El chat con LLM es la capa extra cuando hay conexión.

---

## 12. Endpoints clave del backend

### Ciudadano (autenticado, rol `citizen`)
- `POST /auth/register` — registro con email/teléfono
- `POST /auth/login` — devuelve JWT
- `GET /colonias` — lista para el dropdown (nombre + horario)
- `POST /addresses` — dar de alta domicilio (calle + colonia elegida → deriva `route_id`)
- `POST /addresses/{id}/verify` — sube recibo, OCR extrae dirección, compara, borra imagen, guarda `verified=true`
- `GET /eta?address_id=X` — devuelve `{mensaje, status}` SIN coordenadas
- `POST /feedback` — queja/rating hacia la unidad (NO chofer)

### Chofer (rol `driver`)
- `GET /routes/mine` — su ruta/unidad asignada
- `POST /collections/{route_id}` — marcar recolección en un domicilio
- `POST /incidents` — reportar falla mecánica (dispara reasignación)

### Admin (rol `admin`)
- `GET /routes` — todas las rutas + `current_position_id`
- `GET /routes/{id}/positions` — las 8 coordenadas de `route_positions` (⚠️ única vista con lat/lng)
- `POST /routes/{id}/reassign` — reasignar ruta a otra unidad + dispara FCM
- `GET /drivers` — lista de choferes + su unidad

---

## 13. Checklist de validación de privacidad (antes de cada demo)

Antes de mostrar cualquier feature, revisar:
- [ ] ¿El endpoint del ciudadano devuelve coordenadas? → ❌ rechazado
- [ ] ¿Hay un mapa con el camión moviéndose en vista ciudadana? → ❌ rechazado
- [ ] ¿El ciudadano puede pedir datos de otra ruta u otro usuario? → ❌ debe fallar (RLS)
- [ ] ¿Las quejas exponen el nombre/ID del chofer? → ❌ solo `target_unit_id`
- [ ] ¿El recibo del ciudadano quedó almacenado en BD o storage? → ❌ debe estar borrado
- [ ] ¿Los mensajes desalientan sacar basura fuera de horario? → ✅ validar textos

---

## 14. Comandos útiles de arranque

### Flutter
```bash
cd recolecta_app
flutter pub get
flutter run   # Android: conectar emulador o dispositivo
```

### Backend
```bash
cd backend
python -m venv .venv && source .venv/bin/activate  # (Windows: .venv\Scripts\activate)
pip install -r requirements.txt
# Crear .env copiando .env.example y llenando valores
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### Simulación (una vez el backend esté corriendo)
El cron de APScheduler arranca automáticamente con el backend si está configurado. Para forzar un tick manual desde consola Python:
```python
from app.services.simulation import tick
tick()  # avanza current_position_id de cada ruta y dispara eventos
```

---

## 15. Para la demo (guion de 5–7 min)

1. **Registro + validación de domicilio** (mostrar que el recibo se borra).
2. **Correr la simulación acelerada** (tick cada 5 segundos): llega `ROUTE_START` → `TRUCK_PROXIMITY` → `ROUTE_COMPLETED`. Resaltar: **sin mapa, sin ubicación**, solo texto.
3. **Mascota IA** enseñando a separar residuos + guía offline.
4. **Falla de unidad en Rancho Seco (RUTA-05 vespertina)** → reasignación a unidad matutina → notificación al ciudadano.
5. **Panel admin** con el mapa de las 8 posiciones (contraste: solo admin ve coordenadas).
6. **Quiz post-recolección** + queja a la unidad (sin exponer chofer).
7. **Diapositiva de arquitectura** + cómo cada decisión cumple Privacidad por Diseño.

---

**Fin del contexto. Este documento debe ir al repo como `claude.md` para que el equipo lo comparta con sus asistentes de IA.**