Saltar a contenido

0001. Stack, dependencias y herramientas de calidad de la app móvil

Estado: Propuesto; complementado por ADR 0006 Fecha: 2026-11-02 Autor: David Garcia Módulo(s) afectado(s): pubspec.yaml, pubspec.lock, analysis_options.yaml, lib/ Complementado por: ADR 0006 — DTO generados por un script propio desde el contrato OpenAPI

Contexto

La app CRM para el canal TAT (tienda a tienda) la usa el promotor en la calle: agenda del día, check-in y check-out de visitas, pedidos de preventa y requerimientos, contra crm-svc-fuerza-ventas, crm-svc-clientes y core-svc-identidad. El proyecto nace con flutter create, y el core-frontend web ya separa estado del servidor, estado de interfaz y formularios con una librería cada uno. La primera versión trabaja en línea; el modo sin conexión llega después (ADR 0004).

Decisión

  • Flutter estable (3.47) y Dart ^3.13, Android e iOS. Sin web ni escritorio: la web ya es core-frontend.
  • Una librería por responsabilidad, equivalente a la del frontend:
Necesidad Elección Equivale en web a
Estado e inyección flutter_riverpod TanStack Query + Zustand
Navegación go_router (rutas declarativas y guards) React Router
HTTP dio, una instancia por servicio con interceptores Axios
Tokens flutter_secure_storage (Keychain / Keystore) tokenStorage
Formularios Form de Flutter + validadores propios React Hook Form + Zod
Ids del dispositivo uuid (v7), ADR 0004 —
Ubicación geolocator —
Montos y cantidades decimal (ADR 0013) —
  • Elegidas, pero se instalan con el modo sin conexión (ADR 0004): drift sobre SQLite para la base local y connectivity_plus para despertar el envío al recuperar red. No se discuten de nuevo; sólo se agregan cuando haya qué guardar en el teléfono.
  • Generación de código sólo donde ahorra errores: riverpod_generator con build_runner (y drift_dev cuando entre Drift). Los DTO de los servicios los genera un script propio (ADR 0006).
  • Calidad: flutter analyze con flutter_lints más reglas estrictas (strict-casts, strict-raw-types, strict-inference), dart format, y flutter test (unidad y widgets). Se versiona pubspec.lock.
  • Una dependencia nueva requiere una necesidad concreta y se registra en un ADR si cambia el stack.

Alternativas descartadas

  • React Native / Expo — reutilizaría TypeScript del frontend, pero el proyecto ya arrancó en Flutter y la base SQLite tipada y el rendimiento en equipos de gama baja (habituales en TAT) son mejores con Drift.
  • Bloc — más ceremonia (eventos, estados) por pantalla; Riverpod cubre estado del servidor, de interfaz e inyección con una sola herramienta.
  • Isar / Hive para la base local — sin SQL ni transacciones con migraciones explícitas, que la cola de salida necesitará.
  • http en lugar de dio — sin interceptores para el token y la renovación de sesión.
  • shared_preferences para los tokens — quedan en texto plano.
  • Instalar Drift desde ya — una dependencia sin uso que el ADR tendría que justificar; entra cuando haya base local.

Consecuencias

  • build_runner es parte del flujo: tras cambiar providers se ejecuta dart run build_runner build, y los *.g.dart se versionan.
  • Riverpod es el corazón de la app: cambiarlo después es caro.
  • Flutter y Dart van en versiones muy recientes; parte de la documentación de terceros puede estar desactualizada.

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.