Saltar a contenido

0003. Estructura de carpetas de lib/ y test/

Estado: Propuesto; complementado por ADR 0006 Fecha: 2026-11-02 Autor: David Garcia Módulo(s) afectado(s): lib/, test/, docs/ Complementa a: ADR 0002 Complementado por: ADR 0006 — openapi/, tool/ y core/network/generated/

Contexto

El ADR 0002 fija los niveles y sus reglas; falta el árbol concreto, para que cada archivo tenga un lugar sin discutirlo en cada tarea. Los nombres siguen el español del dominio, como en los servicios y la web.

Decisión

lib/
├── main.dart                 # Arranque: lee el entorno y monta ProviderScope.
├── app/                      # app.dart (MaterialApp.router), router/ (rutas y guard
│                             #   de sesión), tema/, shell/ (barra inferior).
├── core/
│   ├── config/               # Entorno validado (--dart-define-from-file).
│   ├── network/              # Un Dio por servicio, interceptor de sesión, errores
│   │                         #   {"detail"} de FastAPI → mensajes, y generated/<servicio>/
│   │                         #   con los DTO generados (ADR 0006).
│   ├── storage/              # Único punto que sabe dónde están los tokens.
│   ├── widgets/              # UI genérica (estado vacío, error, etiqueta de estado).
│   └── utils/                # Fechas con zona y utc_offset, ids, formatos, JWT (sólo lectura).
├── shared/
│   ├── sesion/               # Usuario, empresa y promotor de la sesión.
│   ├── catalogos/            # Catálogos de fuerza de ventas que usan varios módulos.
│   └── ubicacion/            # Posición actual para check-in y pedidos.
├── modules/
│   ├── auth/                 # Login en dos pasos, cambio de contraseña, salir.
│   ├── cartera/              # Clientes y locales del promotor (crm-svc-clientes).
│   ├── visitas/              # Agenda, check-in y check-out (fuerza de ventas).
│   ├── pedidos/              # Preventa: borrador, confirmar, cancelar.
│   └── requerimientos/       # Requerimientos de la visita y su atención.
└── pages/
    └── mi_ruta/              # Inicio: agenda + pedidos + requerimientos del día.

Cada módulo repite la misma forma; se crean sólo las carpetas que use:

modules/<dominio>/
├── api/          # Funciones HTTP tipadas con los DTO generados.
├── models/       # Modelos que usa la UI.
├── <dominio>_repository.dart
├── providers/    # Providers de Riverpod (consultas y acciones).
├── widgets/      # Componentes propios del dominio.
├── pages/        # Pantallas del dominio.
├── routes.dart   # Rutas propias, ensambladas en app/router/.
└── <dominio>.dart  # API pública del módulo.
  • test/ replica el árbol de lib/; los ADR viven en docs/adr/ con numeración local, y se citan los de otros repositorios con su nombre («ADR 0031 de fuerza de ventas»).
  • Archivos en snake_case; un archivo por clase pública relevante.

Alternativas descartadas

  • Un paquete Dart por módulo (monorepo con melos) — aísla de verdad, pero multiplica pubspec y tiempos de build para un equipo pequeño.
  • Nombres en inglés — rompe la correspondencia con los dominios del backend (visitas, pedidos, promotores).
  • Crear ya las carpetas del modo sin conexión — carpetas vacías que nadie sabe cuándo se llenan.

Consecuencias

  • Con el modo sin conexión llegan core/database/ (la base Drift), core/sync/ (la cola de salida) y local/ en cada módulo; se agregan con el ADR que lo decida.
  • Los módulos de cobros y productos se agregan con la misma plantilla cuando lleguen sus servicios.

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.