docs: add setup guide with 3-step demo path

2026-05-23 01:06:16 -06:00
parent fa44503311
commit 451e005c30
1 changed files with 179 additions and 0 deletions
--- a/SETUP.md
+++ b/SETUP.md
@@ -0,0 +1,179 @@
+# Setup & Demo Path
+
+## 1. Backend (Python FastAPI)
+
+### Requisitos
+- Python 3.11+
+- pip
+
+### Setup
+```bash
+cd server
+python -m venv venv
+source venv/Scripts/activate  # Windows: venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+### Configurar .env
+```bash
+cp .env.example .env
+# Editar .env con:
+SECRET_KEY=tu-secret-key-cambiar-en-produccion
+SUPABASE_URL=https://qckndtzudciejpnwqfzt.supabase.co
+SUPABASE_ANON_KEY=sb_publishable_FQR0WXK6joM043Qve9gz3A_pJfAH...
+SUPABASE_SERVICE_KEY=sb_secret_2y3a_...
+```
+
+### Correr
+```bash
+python -m uvicorn app.main:app --reload --port 8000
+```
+
+Servidor en: http://localhost:8000
+Docs: http://localhost:8000/docs
+
+---
+
+## 2. Flutter (Frontend)
+
+### Requisitos
+- Flutter 3.44+
+- Android Studio / Xcode (para emulador)
+
+### Setup
+```bash
+flutter pub get
+```
+
+### Correr
+```bash
+flutter run -d windows  # o -d chrome, -d emulator-5554
+```
+
+---
+
+## 3. Demo Path (3 pasos)
+
+### Paso 1: Register
+```bash
+curl -X POST http://localhost:8000/auth/register \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "demo@basura.app",
+    "phone": "4611234567",
+    "password": "demo123"
+  }'
+```
+
+**Respuesta:**
+```json
+{
+  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "token_type": "bearer",
+  "user_id": "uuid-aqui"
+}
+```
+
+Guardar `access_token`.
+
+---
+
+### Paso 2: Create Address
+```bash
+curl -X POST http://localhost:8000/addresses/ \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_TOKEN_AQUI" \
+  -d '{
+    "lat": 20.5285,
+    "lng": -100.7980,
+    "alias": "Casa",
+    "address_text": "Celaya, Gto"
+  }'
+```
+
+**Respuesta:**
+```json
+{
+  "id": 1,
+  "user_id": "uuid",
+  "alias": "Casa",
+  "lat": 20.5285,
+  "lng": -100.7980,
+  "route_id": "RUTA-01"
+}
+```
+
+Guardar `address_id`.
+
+---
+
+### Paso 3: Get ETA
+```bash
+curl -X GET http://localhost:8000/eta/1 \
+  -H "Authorization: Bearer YOUR_TOKEN_AQUI"
+```
+
+**Respuesta:**
+```json
+{
+  "address_id": 1,
+  "route_id": "RUTA-01",
+  "status": "EN_RUTA",
+  "eta_minutos": 15,
+  "ventana": {
+    "inicio": "10:00 AM",
+    "fin": "10:15 AM"
+  },
+  "mensaje": "El camión está en camino. Llegada estimada: 10:00 AM – 10:15 AM.",
+  "cached": false
+}
+```
+
+---
+
+## 4. Flutter Test (UI)
+
+1. **Login**: email=`demo@basura.app`, password=`demo123`
+2. **Home**: Debe mostrar 2 botones:
+   - 📚 Guía de Reciclaje
+   - 🚚 Rutas & ETA
+3. **Rutas**: Click en 🚚 → Ver ETA de la ruta RUTA-01
+4. **Guía**: Click en 📚 → Ver categorías de reciclaje
+
+---
+
+## 5. Deploy en Railway
+
+### Crear proyecto Railway
+```bash
+npm i -g @railway/cli
+railway login
+railway init
+```
+
+### Configurar variables de entorno en Railway Dashboard
+```
+SUPABASE_URL=...
+SUPABASE_ANON_KEY=...
+SUPABASE_SERVICE_KEY=...
+SECRET_KEY=...
+```
+
+### Deploy
+```bash
+railway up
+```
+
+Backend en vivo: `https://your-railway-project.up.railway.app`
+
+---
+
+## Troubleshooting
+
+| Problema | Solución |
+|----------|----------|
+| `ModuleNotFoundError: No module named 'app'` | Estar en carpeta `server/` |
+| `SUPABASE connection refused` | Verificar SUPABASE_URL y keys en .env |
+| `JWT token invalid` | Token expiró o SECRET_KEY no coincide |
+| `Flutter pub get error` | Eliminar `pubspec.lock` y correr `flutter clean` |
+