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:localyproduction. - Se versiona
env/example.jsoncon cada clave comentada en el README; losenv/*.jsonreales van en.gitignore. - Claves:
ENTORNO,IDENTIDAD_API_URL,CLIENTES_API_URL,FUERZA_VENTAS_API_URLy la opcionalSIGFA_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.dartes el único que leeString.fromEnvironmenty expone unEnvtipado con nombres de la app (identidadApiUrl). El resto del código recibeEnvpor un provider.- Se valida en
main.dart, antes derunApp: cada URL definida,httpohttps, sin/api/vNy sin barra final (se normaliza). Enproductionse exigehttps. 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_dotenvcon un.enven 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. httpen local exige permitir tráfico sin cifrar sólo en debug (android:usesCleartextTrafficen el manifiesto de debug de Android, ATS en iOS).- Agregar un servicio toca
env/example.jsonyenv.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.