swiftenprofundidad/android-enterprise-rules

---

alwaysApply: true

Android Rules - Kotlin/Jetpack Compose

ANTES de implementar CUALQUIER cosa:

Fundamentos (heredados de goldrules.md):

✅ Siempre responder en español ✅ Actúa como un Arquitecto de Soluciones y Software Designer ✅ Seguir siempre flujo BDD->TDD - Feature files → Specs (JUnit5, Espresso) → Implementación ✅ En producción ni un mocks ni un spies - Todo real de APIs y persistencia (Room, SharedPreferences) ✅ No poner comentarios en el código - Nombres autodescriptivos ✅ Analizar estructura existente - Módulos, interfaces, dependencias, Gradle ✅ Verificar que NO viole SOLID (SRP, OCP, LSP, ISP, DIP) ✅ No Singleton - Usar Inyección de Dependencias (Hilt/Dagger) ✅ Seguir Clean Architecture - Domain → Data → Presentation ✅ Early returns - Guard clauses, evitar if/else anidados ✅ Comprobar que compile ANTES de sugerir - Gradle build sin errores

Kotlin 100%:

✅ NO Java en código nuevo - Kotlin para todo ✅ Kotlin 1.9+ - Usar features modernas del lenguaje ✅ Coroutines - async/await, NO callbacks ✅ Flow - Streams de datos reactivos ✅ Sealed classes - Para estados y resultados (Success, Error, Loading) ✅ Data classes - Para DTOs y modelos ✅ Extension functions - Extender funcionalidad sin herencia ✅ Scope functions - let, run, apply, also, with apropiadamente ✅ Null safety - NO !! (force unwrap), usar ?, ?:, let, requireNotNull

Jetpack Compose (UI Declarativo):

✅ Compose 100% - NO XML layouts en código nuevo ✅ Composable functions - @Composable para UI ✅ State hoisting - Elevar estado al nivel apropiado ✅ remember - Para mantener estado entre recomposiciones ✅ rememberSaveable - Sobrevive process death ✅ derivedStateOf - Cálculos derivados de state ✅ LaunchedEffect - Side effects con lifecycle ✅ DisposableEffect - Cleanup cuando Composable sale de composición ✅ Recomposition - Composables deben ser idempotentes ✅ Modifier - Orden importa (padding antes que background) ✅ Preview - @Preview para ver UI sin correr app

Material Design 3:

✅ Material 3 components - Button, Card, TextField, etc. ✅ Theme - Color scheme, typography, shapes ✅ Dark theme - Soportar desde día 1 (isSystemInDarkTheme()) ✅ Adaptive layouts - Responsive design (WindowSizeClass) ✅ Motion - Animaciones consistentes con Material guidelines ✅ Accessibility - semantics, contentDescription

Architecture (MVVM + Clean):

✅ MVVM - Model-View-ViewModel ✅ Single Activity - Múltiples Composables/Fragments, no Activities ✅ Navigation Component - Jetpack Navigation para Compose ✅ ViewModel - androidx.lifecycle.ViewModel ✅ StateFlow/SharedFlow - Para exponer estado del ViewModel ✅ Repository pattern - Abstraer acceso a datos ✅ Use Cases - Lógica de negocio encapsulada ✅ Mapper - Convertir entre DTOs y domain models

Arquitectura Feature-First + DDD + Clean + Event-Driven (Android):

✅ Feature-first - Cada feature es un Bounded Context, aislado ✅ Clean por feature - presentation → application → domain, data → domain ✅ DDD - entidades, value objects, repositorios, eventos de dominio ✅ Navegación event-driven cuando el modelo crezca (event bus + router) ✅ Shared Kernel - Tipos mínimos compartidos entre features

apps/android/
  features/
    auth/
      domain/
      application/
      data/
      presentation/
      navigation/
  shared/
    kernel/
    design-system/
  navigation/
    event-bus/
    routes/

Clean Architecture en Android:

app/
  domain/
    model/                 # Order, User (domain models)
    repository/            # OrderRepository interface
    usecase/               # CreateOrderUseCase
  data/
    remote/
      api/                 # Retrofit API service
      dto/                 # API response DTOs
    local/
      dao/                 # Room DAOs
      entity/              # Room entities
    repository/            # OrderRepositoryImpl
    mapper/                # DTO ↔ Domain mappers
  presentation/
    ui/
      orders/
        OrdersScreen.kt    # Composable
        OrdersViewModel.kt # ViewModel
      components/          # Reusable Composables
    navigation/            # Navigation graph
    theme/                 # Material 3 theme
  di/                      # Hilt modules

Dependency Injection (Hilt):

✅ Hilt - DI framework (NO manual factories) ✅ @HiltAndroidApp - Application class ✅ @AndroidEntryPoint - Activity, Fragment, ViewModel ✅ @Inject constructor - Constructor injection ✅ @Module + @InstallIn - Provide dependencies ✅ @Provides - Para interfaces o third-party ✅ @Binds - Para implementaciones de interfaces (más eficiente) ✅ @Singleton - Solo para recursos globales (DB, API client) ✅ @ViewModelScoped - Para dependencias de ViewModel

Coroutines (Async):

✅ suspend functions - Para operaciones async ✅ viewModelScope - Scope de ViewModel, cancelado automáticamente ✅ lifecycleScope - Scope de Activity/Fragment ✅ Dispatchers - Main (UI), IO (network/disk), Default (CPU) ✅ withContext - Cambiar dispatcher ✅ async/await - Paralelismo ✅ supervisorScope - Errores no cancelan otros jobs ✅ try-catch - Manejo de errores en coroutines

Flow (Reactive Streams):

✅ StateFlow - Hot stream, siempre tiene valor, para estado ✅ SharedFlow - Hot stream, puede no tener valor, para eventos ✅ Flow builders - flow { emit() }, flowOf(), asFlow() ✅ Operators - map, filter, combine, flatMapLatest, catch ✅ collect - Terminal operator para consumir Flow ✅ collectAsState - En Compose para observar Flow ✅ stateIn - Convertir cold Flow a hot StateFlow

Networking (Retrofit):

✅ Retrofit - REST client ✅ OkHttp - HTTP client con interceptors ✅ Moshi/Gson - JSON serialization (Moshi preferido) ✅ suspend functions - En API service ✅ Interceptors - Logging, auth tokens, error handling ✅ Error handling - Custom sealed class Result<T> ✅ Retry logic - Exponential backoff ✅ Certificate pinning - SSL pinning para seguridad

Persistence (Room):

✅ Room - SQLite wrapper type-safe ✅ @Entity - Tablas ✅ @Dao - Data Access Objects con suspend functions ✅ @Database - Database class abstracta ✅ Flow<T> - Queries observables ✅ @TypeConverter - Para tipos custom (Date, List, etc.) ✅ Migrations - Versionado de schema ✅ @Transaction - Para operaciones multi-query

State Management:

✅ ViewModel - Sobrevive configuration changes ✅ StateFlow - Estado mutable observable ✅ UiState sealed class - Loading, Success, Error states ✅ Single source of truth - ViewModel es la fuente ✅ Immutable state - data class + copy() ✅ State hoisting - Elevar estado en Compose

Navigation:

✅ Navigation Compose - androidx.navigation:navigation-compose ✅ NavHost - Container de navegación ✅ NavController - Controla navegación ✅ Routes - Strings para destinos ✅ Arguments - Pasar datos entre pantallas ✅ Deep links - Soporte para URLs ✅ Bottom navigation - Material 3 NavigationBar

Image Loading:

✅ Coil - Async image loading (recomendado para Compose) ✅ Glide - Alternativa, más maduro ✅ Caching - Memory + Disk cache ✅ Transformations - Resize, crop, blur ✅ Placeholders - Mientras carga ✅ Error handling - Fallback images

Testing:

✅ JUnit5 - Framework de testing (preferido sobre JUnit4) ✅ MockK - Mocking library para Kotlin ✅ Turbine - Testing de Flows ✅ Compose UI Test - Testing de Composables ✅ Espresso - UI testing (si usas Fragments) ✅ Robolectric - Unit tests con Android framework ✅ Truth - Assertions más legibles ✅ Coroutines Test - runTest, TestDispatcher ✅ Coverage >80% - Objetivo 95% en lógica crítica

Testing Structure:

✅ test/ - Unit tests (JVM) ✅ androidTest/ - Instrumented tests (Device/Emulator) ✅ AAA pattern - Arrange, Act, Assert ✅ Given-When-Then - BDD style ✅ Test doubles - Fakes > Mocks para repositories

Ejemplos mínimos:

viewModelScope.launch {
  val result = repository.load()
  _uiState.value = uiState.value.copy(data = result)
}

@Composable
fun Screen(uiState: UiState) {
  LazyColumn {
    items(uiState.items) { item -> Text(item.title) }
  }
}

@HiltViewModel
class ScreenViewModel @Inject constructor(
  private val repository: Repository
) : ViewModel()

Security:

✅ EncryptedSharedPreferences - Para datos sensibles ✅ Keystore - Claves criptográficas ✅ SafetyNet/Play Integrity - Verificar integridad del dispositivo ✅ Root detection - Prevenir uso en dispositivos rooted ✅ ProGuard/R8 - Ofuscación de código en release ✅ Network Security Config - Certificate pinning ✅ Biometric auth - BiometricPrompt API

Performance:

✅ LazyColumn/LazyRow - Virtualización de listas ✅ Paging 3 - Paginación de datos grandes ✅ WorkManager - Background tasks ✅ Baseline Profiles - Optimización de startup ✅ App startup - androidx.startup para lazy init ✅ LeakCanary - Detección de memory leaks ✅ Android Profiler - CPU, Memory, Network profiling

Compose Performance:

✅ Stability - Composables estables recomponen menos ✅ remember - Evitar recrear objetos ✅ derivedStateOf - Cálculos caros solo cuando cambia input ✅ LaunchedEffect keys - Controlar cuándo se relanza effect ✅ Immutable collections - kotlinx.collections.immutable ✅ Skip recomposition - Parámetros inmutables o estables

Accessibility:

✅ TalkBack - Screen reader de Android ✅ contentDescription - Para imágenes y botones ✅ semantics - En Compose para accesibilidad ✅ Touch targets - Mínimo 48dp ✅ Color contrast - WCAG AA mínimo ✅ Text scaling - Soportar font scaling del sistema

Localization (i18n):

✅ strings.xml - Por idioma (values-es, values-en) ✅ Plurals - values/plurals.xml ✅ RTL support - start/end en lugar de left/right ✅ String formatting - %1$s, %2$d para argumentos ✅ DateFormat - Fechas localizadas ✅ NumberFormat - Números, monedas localizados

Gradle (Build):

✅ Kotlin DSL - build.gradle.kts (preferido sobre Groovy) ✅ Version catalogs - libs.versions.toml para dependencias ✅ buildSrc - Para lógica compartida de build ✅ Build types - debug, release, staging ✅ Product flavors - Para variantes de app ✅ Build variants - Combinación de build type + flavor ✅ Dependency management - Versiones consistentes

Multi-module:

✅ Feature modules - :feature:orders, :feature:users ✅ Core modules - :core:network, :core:database, :core:ui ✅ App module - Composición final ✅ Clear dependencies - Feature → Core, NO Feature → Feature ✅ Dynamic features - Para app bundles grandes (opcional)

CI/CD:

✅ GitHub Actions / GitLab CI - Pipelines ✅ Gradle tasks - ./gradlew assembleDebug, test ✅ Lint - ./gradlew lint (warnings = errores) ✅ Detekt - Static analysis para Kotlin ✅ Firebase App Distribution - Beta testing ✅ Play Console - Production deployment

Logging:

✅ Timber - Logging library ✅ Log levels - e (error), w (warn), i (info), d (debug) ✅ NO logs en producción - if (BuildConfig.DEBUG) Timber.d() ✅ Crashlytics - Firebase para crash reporting ✅ Analytics - Firebase Analytics o custom

Configuration:

✅ BuildConfig - Constantes en tiempo de compilación ✅ gradle.properties - Configuración de build ✅ local.properties - API keys (NO subir a git) ✅ secrets-gradle-plugin - Para API keys seguras ✅ Environment variables - Para CI/CD

Anti-patterns a EVITAR:

❌ Java en código nuevo - Solo Kotlin ❌ XML layouts - Usar Jetpack Compose ❌ Force unwrapping (!!) - Usar ?, ?:, let ❌ Context leaks - No referencias a Activity en objetos long-lived ❌ God Activities - Single Activity + Composables ❌ Hardcoded strings - Usar strings.xml ❌ AsyncTask - Deprecated, usar Coroutines ❌ RxJava en nuevo código - Usar Flow ❌ findViewById - View Binding o Compose ❌ Singletons everywhere - Usar Hilt DI

Jetpack Libraries:

✅ ViewModel - androidx.lifecycle:lifecycle-viewmodel-ktx ✅ Navigation - androidx.navigation:navigation-compose ✅ Room - androidx.room:room-ktx ✅ WorkManager - androidx.work:work-runtime-ktx ✅ Paging - androidx.paging:paging-compose ✅ DataStore - androidx.datastore:datastore-preferences (reemplazo de SharedPreferences) ✅ Hilt - com.google.dagger:hilt-android ✅ Compose BOM - androidx.compose:compose-bom

Específicas para RuralGO Mobile:

✅ Compartir DTOs con backend - TypeScript → Kotlin codegen (quicktype, OpenAPI) ✅ Repository pattern - OrdersRep