From 2894c91c4dc4f9195e59a09cc376d5ac11d8937f Mon Sep 17 00:00:00 2001 From: hack_23031391_8ff9d8 <23031391@itcelaya.edu.mx> Date: Sat, 23 May 2026 02:52:34 +0000 Subject: [PATCH] =?UTF-8?q?A=C3=B1adir=2003-env.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 03-env.md.-.md | 347 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 347 insertions(+) create mode 100644 03-env.md.-.md diff --git a/03-env.md.-.md b/03-env.md.-.md new file mode 100644 index 0000000..cb19eff --- /dev/null +++ b/03-env.md.-.md @@ -0,0 +1,347 @@ +# Variables de Entorno + +Configuración de `.env` para desarrollo local y producción. + +--- + +## Backend — `.env` + +Crea `basura_backend/.env`: + +```bash +# ======================================== +# CONFIGURACIÓN DEL SIMULADOR +# ======================================== + +# Intervalo de actualización del camión (segundos) +SIM_TICK_SECONDS=10 + +# Umbral de ETA para notificar proximidad (minutos) +SIM_ETA_ALERT_MINUTES=10 + +# Multiplicador de velocidad del simulador +# 1.0 = tiempo real +# 2.0 = doble velocidad (útil para demos rápidas) +# 0.5 = mitad de velocidad (útil para debug) +SIM_SPEED_MULTIPLIER=1.0 + +# ======================================== +# BASE DE DATOS +# ======================================== + +# Ruta del archivo SQLite +DATABASE_PATH=./basura.db + +# ======================================== +# SERVIDOR +# ======================================== + +# Host (0.0.0.0 para aceptar conexiones externas) +HOST=0.0.0.0 + +# Puerto del servidor +PORT=8000 + +# Hot reload en desarrollo (True/False) +RELOAD=True + +# ======================================== +# CORS (desarrollo) +# ======================================== + +# Permitir todos los orígenes en desarrollo +# En producción, especificar dominios exactos +CORS_ORIGINS=* + +# ======================================== +# JWT (para cuando Persona A integre auth) +# ======================================== + +# Secret key para firmar tokens JWT +# CAMBIAR EN PRODUCCIÓN a una clave aleatoria fuerte +JWT_SECRET=super-secret-key-change-in-production + +# Expiración del token (minutos) +JWT_EXPIRATION_MINUTES=1440 # 24 horas + +# ======================================== +# LOGGING +# ======================================== + +# Nivel de log: DEBUG, INFO, WARNING, ERROR +LOG_LEVEL=INFO +``` + +### Usar las variables en el código + +```python +# app/core/config.py +from pydantic_settings import BaseSettings + +class Settings(BaseSettings): + sim_tick_seconds: int = 10 + sim_eta_alert_minutes: int = 10 + sim_speed_multiplier: float = 1.0 + database_path: str = "./basura.db" + host: str = "0.0.0.0" + port: int = 8000 + reload: bool = True + + class Config: + env_file = ".env" + +settings = Settings() +``` + +--- + +## Frontend — `.env` (Flutter) + +Flutter **no soporta `.env` nativamente**, pero hay opciones: + +### Opción A: Usar `flutter_dotenv` + +**1. Instalar:** +```yaml +# pubspec.yaml +dependencies: + flutter_dotenv: ^5.1.0 +``` + +**2. Crear `.env`:** +```bash +# basura_app/.env +API_BASE_URL=http://10.0.2.2:8000 +WS_BASE_URL=ws://10.0.2.2:8000 +ENVIRONMENT=development +``` + +**3. Declarar en pubspec:** +```yaml +flutter: + assets: + - .env +``` + +**4. Cargar en main.dart:** +```dart +import 'package:flutter_dotenv/flutter_dotenv.dart'; + +Future main() async { + await dotenv.load(fileName: ".env"); + runApp(ProviderScope(child: MyApp())); +} +``` + +**5. Usar en el código:** +```dart +final baseUrl = dotenv.env['API_BASE_URL'] ?? 'http://localhost:8000'; +``` + +--- + +### Opción B: Flavors (recomendado para producción) + +Permite tener **configuraciones separadas** para dev, staging, prod. + +**1. Crear archivos de configuración:** + +```dart +// lib/core/config/environment.dart +enum Environment { dev, staging, prod } + +class EnvironmentConfig { + final String apiBaseUrl; + final String wsBaseUrl; + final Environment env; + + const EnvironmentConfig({ + required this.apiBaseUrl, + required this.wsBaseUrl, + required this.env, + }); + + static const dev = EnvironmentConfig( + apiBaseUrl: 'http://10.0.2.2:8000', + wsBaseUrl: 'ws://10.0.2.2:8000', + env: Environment.dev, + ); + + static const prod = EnvironmentConfig( + apiBaseUrl: 'https://api.basura.onlinces.net', + wsBaseUrl: 'wss://api.basura.onlinces.net', + env: Environment.prod, + ); +} +``` + +**2. Crear entry points:** + +```dart +// lib/main_dev.dart +void main() { + runApp(ProviderScope( + overrides: [ + envConfigProvider.overrideWithValue(EnvironmentConfig.dev), + ], + child: MyApp(), + )); +} + +// lib/main_prod.dart +void main() { + runApp(ProviderScope( + overrides: [ + envConfigProvider.overrideWithValue(EnvironmentConfig.prod), + ], + child: MyApp(), + )); +} +``` + +**3. Correr según entorno:** +```bash +# Desarrollo +fvm flutter run -t lib/main_dev.dart + +# Producción +fvm flutter run -t lib/main_prod.dart --release +``` + +--- + +## Configuraciones específicas por entorno + +### Desarrollo Local + +**Backend:** +```bash +SIM_TICK_SECONDS=5 # Más rápido para debug +SIM_SPEED_MULTIPLIER=2.0 # Doble velocidad +LOG_LEVEL=DEBUG # Logs detallados +``` + +**Flutter:** +``` +API_BASE_URL=http://10.0.2.2:8000 # Emulador Android +WS_BASE_URL=ws://10.0.2.2:8000 +``` + +--- + +### Demo en Hackathon + +**Backend:** +```bash +SIM_TICK_SECONDS=10 # Velocidad normal +SIM_ETA_ALERT_MINUTES=5 # Notificar más rápido +SIM_SPEED_MULTIPLIER=1.5 # Un poco más rápido para demo +``` + +**Flutter:** +``` +API_BASE_URL=http://192.168.x.x:8000 # IP de la PC del presentador +WS_BASE_URL=ws://192.168.x.x:8000 +``` + +--- + +### Producción (si despliegan después del hackathon) + +**Backend:** +```bash +SIM_TICK_SECONDS=10 +SIM_ETA_ALERT_MINUTES=10 +SIM_SPEED_MULTIPLIER=1.0 +DATABASE_PATH=/var/basura/basura.db +HOST=0.0.0.0 +PORT=8000 +RELOAD=False +CORS_ORIGINS=https://basura.onlinces.net +JWT_SECRET= +LOG_LEVEL=WARNING +``` + +**Flutter:** +``` +API_BASE_URL=https://api.basura.onlinces.net +WS_BASE_URL=wss://api.basura.onlinces.net +``` + +--- + +## Secretos sensibles — **NO commitear** + +### `.gitignore` debe incluir: + +```gitignore +# Backend +basura_backend/.env +basura_backend/*.db +basura_backend/venv/ + +# Flutter +basura_app/.env +basura_app/.env.* +basura_app/build/ +basura_app/.fvm/ + +# Secretos +*.key +*.pem +*.p12 +``` + +--- + +## Provider compartido para configuración (Flutter) + +```dart +// lib/core/config/env_provider.dart +import 'package:flutter_riverpod/flutter_riverpod.dart'; +import 'environment.dart'; + +final envConfigProvider = Provider((ref) { + throw UnimplementedError('EnvConfig debe ser overridden en main.dart'); +}); + +final apiBaseUrlProvider = Provider((ref) { + return ref.watch(envConfigProvider).apiBaseUrl; +}); + +final wsBaseUrlProvider = Provider((ref) { + return ref.watch(envConfigProvider).wsBaseUrl; +}); +``` + +--- + +## Testing con diferentes configuraciones + +### Backend + +```bash +# Dev rápido +SIM_TICK_SECONDS=1 SIM_SPEED_MULTIPLIER=10.0 uvicorn app.main:app + +# Demo lento (explicar paso a paso) +SIM_TICK_SECONDS=30 uvicorn app.main:app +``` + +### Flutter + +```bash +# Probar contra backend local +fvm flutter run --dart-define=API_URL=http://10.0.2.2:8000 + +# Probar contra staging +fvm flutter run --dart-define=API_URL=https://staging.basura.net +``` + +--- + +## Siguiente paso + +- [Endpoints REST](../api/01-endpoints.md) — usar las URLs configuradas +- [WebSocket](../api/02-websocket.md) — conectar con la URL WS +- [Troubleshooting](../troubleshooting/01-errores-comunes.md) — solucionar problemas de conexión