architecture

Responsabilidad Única

Definir la estructura del proyecto y patrones arquitectónicos. NO incluye UI/UX, lógica de negocio, ni optimizaciones de performance.

Estructura de Proyecto (Feature-First)

Para cada funcionalidad (feature_name), el agente debe organizar los archivos así:

lib/features/feature_name/
├── domain/
│   ├── entities/
│   ├── repositories/ (interfaces)
│   └── usecases/
├── data/
│   ├── models/
│   ├── datasources/
│   └── repositories/ (implementaciones)
└── presentation/
    ├── providers/ (Riverpod) o bloc/ (Bloc)
    ├── pages/
    └── widgets/

Stack Técnico Core

State Management

• Riverpod: Preferido para nuevos features (Notifier API, AsyncNotifier)
• Bloc: Alternativa válida (extender de Equatable para optimizar comparación de estados)

Dependency Injection

• GetIt: Registro manual de dependencias en archivo centralizado service_locator.dart
• Registrar como singleton, lazy singleton o factory según el caso

Navigation

• GoRouter: Routing declarativo con guards de autenticación
• Definir rutas en archivo centralizado
• Implementar Auth Guard usando Supabase Session

Error Handling

• fpdart: Usar tipo Either<Failure, Success> para manejo funcional de errores
• Definir Failure classes en la capa Domain
• Nunca usar print() para errores, siempre retornar Failure

Modelado de Datos

• Models (Data Layer): Incluir métodos toEntity() y fromEntity()
• Entities (Domain Layer): Clases inmutables con freezed o equatable
• Separación estricta: Models manejan JSON, Entities son puros

Testing Strategy (TDD)

Workflow TDD

Para cada feature, seguir este orden:

1. Escribir test del Use Case (usando Mocktail)
2. Implementar Use Case para que el test pase
3. Escribir test del Repository
4. Implementar Repository
5. Escribir test del Provider/Bloc
6. Implementar Provider/Bloc

Tools

• Mocktail: Para mocks y stubs
• flutter_test: Testing framework
• integration_test: Para tests E2E

Mandamientos de Código

Inmutabilidad

• Todo widget debe usar const siempre que sea posible
• Clases de estado deben ser inmutables (final fields)
• Usar freezed o equatable para value objects

Atomicidad

• Máximo una clase principal por archivo
• Si un Widget es complejo (>60 líneas), extraerlo a widgets/ de la feature
• Archivos cortos: 150-200 líneas máximo
• Priorizar composición sobre herencia

Cero Tolerancia a Warnings

• Tras generar o editar código, verificar que no existan warnings
• Lints, tipos faltantes, imports sin usar: TODO debe estar limpio
• Usar analysis_options.yaml estricto

Organización de Imports

// 1. Dart core
import 'dart:async';

// 2. Flutter
import 'package:flutter/material.dart';

// 3. Packages externos
import 'package:riverpod/riverpod.dart';

// 4. Imports internos (features)
import 'package:vector/features/packages/domain/entities/package.dart';

Protocolo de Implementación

Al solicitar una nueva funcionalidad, el agente responderá en este orden:

1. Entidad (Domain) - Definir la entidad core
2. Interfaz del Repositorio (Domain) - Contrato del repositorio
3. Casos de Uso (Domain) - Lógica de negocio pura
4. Modelo y DTOs (Data) - Mappers toEntity/fromEntity
5. Implementación del Repositorio (Data) - Conexión con datasources
6. Provider/Bloc (Presentation) - State management
7. UI Atómica (Presentation) - Widgets pequeños y reutilizables

Reglas de Separación de Capas

Domain (Núcleo)

• ✅ Entities, Use Cases, Repository Interfaces
• ❌ PROHIBIDO: Importar Flutter, paquetes de terceros (excepto fpdart/equatable)

Data

• ✅ Models, DataSources, Repository Implementations
• ✅ Puede importar: Supabase, HTTP clients, JSON serialization
• ❌ PROHIBIDO: Importar Flutter widgets

Presentation

• ✅ Providers/Bloc, Pages, Widgets
• ✅ Puede importar: Flutter, Riverpod/Bloc, Domain entities
• ❌ PROHIBIDO: Importar Models de Data directamente

File Naming Conventions

• Entities: package.dart, delivery_route.dart
• Models: package_model.dart, delivery_route_model.dart
• Repositories: package_repository.dart (interface y implementation)
• Use Cases: get_packages.dart, create_package.dart
• Providers: package_provider.dart
• Screens: packages_screen.dart, add_package_screen.dart
• Widgets: package_card.dart, status_badge.dart

Ejemplo de Feature Completa

lib/features/packages/
├── domain/
│   ├── entities/
│   │   └── package.dart
│   ├── repositories/
│   │   └── package_repository.dart
│   └── usecases/
│       ├── get_packages.dart
│       └── create_package.dart
├── data/
│   ├── models/
│   │   └── package_model.dart
│   ├── datasources/
│   │   └── package_remote_datasource.dart
│   └── repositories/
│       └── package_repository_impl.dart
└── presentation/
    ├── providers/
    │   └── package_provider.dart
    ├── pages/
    │   └── packages_screen.dart
    └── widgets/
        └── package_card.dart