Saltar a contenido

0005. Configuración por archivo de entorno, validada al arrancar

Estado: Propuesto Fecha: 2026-11-02 Autor: David Garcia Módulo(s) afectado(s): core/config/, env/, main.dart, .gitignore

Contexto

La app necesita la URL de cada servicio (core-svc-identidad, crm-svc-clientes, crm-svc-fuerza-ventas) y cambia de valores entre el equipo del desarrollador y producción. Flutter fija esos valores al compilar: una URL mal escrita compila bien y recién falla en el teléfono, como en la web antes de su ADR 0005. En el emulador de Android, además, localhost es el propio emulador, no la máquina del desarrollador.

Decisión

  • Un archivo JSON por entorno en env/, pasado con --dart-define-from-file=env/<entorno>.json. Dos entornos, como los servicios: local y production.
  • Se versiona env/example.json con cada clave comentada en el README; los env/*.json reales van en .gitignore.
  • Claves: ENTORNO, IDENTIDAD_API_URL, CLIENTES_API_URL, FUERZA_VENTAS_API_URL y la opcional SIGFA_API_URL (API de SIGFA, prueba interna como en la web; sin ella no se toman pedidos, ADR 0013), todas sin /api/v1 (lo agrega el cliente, ADR 0008).
  • core/config/env.dart es el único que lee String.fromEnvironment y expone un Env tipado con nombres de la app (identidadApiUrl). El resto del código recibe Env por un provider.
  • Se valida en main.dart, antes de runApp: cada URL definida, http o https, sin /api/vN y sin barra final (se normaliza). En production se exige https. Se acumulan todos los errores en un solo mensaje; en debug se lanza, en release se muestra una pantalla de configuración inválida en lugar de la app.
  • Nada secreto en el entorno: todo lo que va en el binario se puede extraer de la APK. Las claves de terceros que lleguen (p. ej. mapas) se restringen por paquete en su consola.

Alternativas descartadas

  • flutter_dotenv con un .env en assets — el archivo viaja legible dentro de la app y se lee en tiempo de ejecución, sin validación al compilar.
  • Flavors de Android e iOS desde ya — permiten instalar local y producción a la vez, pero suman configuración nativa que todavía nadie pidió; se retoman si se necesitan dos apps instaladas.
  • URLs fijas en el código — obligan a editar código para cambiar de entorno.

Consecuencias

  • Para correr la app: flutter run --dart-define-from-file=env/local.json. La configuración del IDE (VS Code, Android Studio) no se versiona: cada uno agrega ese argumento a la suya, como explica el README.
  • En el emulador de Android las URLs locales usan 10.0.2.2; en un teléfono físico, la IP de la máquina en la red. Se documenta en el ejemplo.
  • http en local exige permitir tráfico sin cifrar sólo en debug (android:usesCleartextTraffic en el manifiesto de debug de Android, ATS en iOS).
  • Agregar un servicio toca env/example.json y env.dart.

Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.