@saulwade/swl-ses 1.0.0

package/reglas/lenguajes/kotlin/patrones.md

@@ -0,0 +1,201 @@
+# Regla: Patrones de Arquitectura Kotlin
+
+Esta regla define los patrones obligatorios para estructurar código Kotlin en Android
+y backend (Ktor/Spring). La arquitectura limpia con coroutines y Flow es el estándar.
+
+---
+
+## Coroutines y Flow para async/reactive
+
+- Todo código asíncrono usa `suspend` functions o `Flow`. Sin `AsyncTask`, `Thread` ni callbacks.
+- `Flow` para streams de datos que cambian en el tiempo (lista de items, estados de UI).
+- `StateFlow` para estado que siempre tiene un valor actual (reemplaza `LiveData`).
+- `SharedFlow` para eventos de un solo disparo (navegación, mensajes de error).
+
+```kotlin
+// MAL — LiveData expone detalles de Android en el dominio
+class PedidoRepository {
+    fun obtenerPedidos(): LiveData<List<Pedido>> = ...
+}
+
+// BIEN — Flow es independiente del framework
+class PedidoRepository {
+    fun obtenerPedidos(): Flow<List<Pedido>> = flow {
+        emit(dao.obtenerTodos())
+    }
+}
+```
+
+---
+
+## Repository pattern con interfaces
+
+Toda fuente de datos se abstrae detrás de una interfaz.
+El dominio depende de la interfaz, no de la implementación concreta.
+
+```kotlin
+// Interfaz en la capa de dominio
+interface PedidoRepository {
+    suspend fun obtenerPorId(id: UUID): Pedido?
+    fun obtenerTodos(): Flow<List<Pedido>>
+    suspend fun guardar(pedido: Pedido)
+}
+
+// Implementación en la capa de datos
+class PedidoRepositoryImpl(
+    private val dao: PedidoDao,
+    private val api: PedidoApi,
+) : PedidoRepository {
+    override suspend fun obtenerPorId(id: UUID): Pedido? =
+        dao.buscarPorId(id)?.toDomain()
+}
+```
+
+---
+
+## Use cases / interactors para lógica de negocio
+
+Cada acción de negocio tiene su propio use case. Un use case = una responsabilidad.
+El ViewModel llama al use case; no contiene lógica de negocio.
+
+```kotlin
+// BIEN — use case con responsabilidad única
+class CrearPedidoUseCase(
+    private val pedidoRepo: PedidoRepository,
+    private val inventarioRepo: InventarioRepository,
+) {
+    suspend operator fun invoke(items: List<ItemPedido>): Result<Pedido> {
+        if (items.isEmpty()) return Result.failure(IllegalArgumentException("Sin items"))
+        val disponible = inventarioRepo.verificarDisponibilidad(items)
+        if (!disponible) return Result.failure(StockInsuficienteException())
+        val pedido = Pedido.crear(items)
+        pedidoRepo.guardar(pedido)
+        return Result.success(pedido)
+    }
+}
+
+// MAL — lógica de negocio en el ViewModel
+class PedidoViewModel(private val repo: PedidoRepository) : ViewModel() {
+    fun crearPedido(items: List<ItemPedido>) {
+        if (items.isEmpty()) { /* lógica aquí — MAL */ }
+        viewModelScope.launch { repo.guardar(...) }
+    }
+}
+```
+
+---
+
+## Sealed classes para estados de UI
+
+```kotlin
+sealed class UiState<out T> {
+    object Loading : UiState<Nothing>()
+    data class Success<T>(val data: T) : UiState<T>()
+    data class Error(val mensaje: String, val causa: Throwable? = null) : UiState<Nothing>()
+}
+
+// ViewModel expone StateFlow de UiState
+class PedidoViewModel(private val obtenerPedidos: ObtenerPedidosUseCase) : ViewModel() {
+    private val _uiState = MutableStateFlow<UiState<List<Pedido>>>(UiState.Loading)
+    val uiState: StateFlow<UiState<List<Pedido>>> = _uiState.asStateFlow()
+
+    init {
+        cargarPedidos()
+    }
+
+    private fun cargarPedidos() {
+        viewModelScope.launch {
+            obtenerPedidos()
+                .onStart { _uiState.value = UiState.Loading }
+                .catch { e -> _uiState.value = UiState.Error(e.message ?: "Error") }
+                .collect { pedidos -> _uiState.value = UiState.Success(pedidos) }
+        }
+    }
+}
+```
+
+---
+
+## Dependency Injection con Hilt (Android) o Koin
+
+Preferir **Hilt** en proyectos Android nuevos por su integración con el compilador.
+**Koin** es aceptable en proyectos multiplatforma o Ktor.
+
+```kotlin
+// Hilt — módulo de provisión
+@Module
+@InstallIn(SingletonComponent::class)
+object RepositorioModule {
+    @Provides
+    @Singleton
+    fun providePedidoRepository(dao: PedidoDao): PedidoRepository =
+        PedidoRepositoryImpl(dao)
+}
+
+// ViewModel con Hilt
+@HiltViewModel
+class PedidoViewModel @Inject constructor(
+    private val obtenerPedidos: ObtenerPedidosUseCase,
+) : ViewModel()
+```
+
+---
+
+## Jetpack Compose: remember, LaunchedEffect, derivedStateOf
+
+```kotlin
+@Composable
+fun PantallaPedidos(viewModel: PedidoViewModel = hiltViewModel()) {
+    val uiState by viewModel.uiState.collectAsStateWithLifecycle()
+
+    // remember: cálculos costosos que no deben recalcularse en cada recomposición
+    val pedidosOrdenados = remember(uiState) {
+        if (uiState is UiState.Success) {
+            (uiState as UiState.Success).data.sortedByDescending { it.fecha }
+        } else emptyList()
+    }
+
+    // derivedStateOf: valor derivado de otro estado, evita recomposiciones en cascada
+    val hayPedidos by remember { derivedStateOf { pedidosOrdenados.isNotEmpty() } }
+
+    // LaunchedEffect: efectos de un solo disparo atados al ciclo de vida del composable
+    LaunchedEffect(Unit) {
+        viewModel.eventos.collect { evento ->
+            when (evento) {
+                is Evento.NavegacionDetalle -> navController.navigate(...)
+            }
+        }
+    }
+}
+```
+
+---
+
+## Clean Architecture: capas y dependencias
+
+```
+presentation/   — Composables, ViewModels, UiState
+    |
+    v
+domain/         — UseCases, interfaces de Repository, modelos de dominio
+    |
+    v
+data/           — implementaciones de Repository, DAOs, API clients, mappers
+```
+
+La capa `domain` NO importa nada de `presentation` ni `data`.
+Los modelos de datos de Room o Retrofit NO se exponen a la capa de presentación.
+Usar mappers explícitos entre capas.
+
+---
+
+## Checklist de patrones Kotlin antes de abrir PR
+
+- [ ] Sin callbacks: todo async usa suspend o Flow
+- [ ] Repositories tienen interfaz en dominio e implementación en datos
+- [ ] Lógica de negocio en use cases, no en ViewModels ni Repositories
+- [ ] Estados de UI representados con sealed class (Loading/Success/Error)
+- [ ] ViewModels exponen StateFlow, no MutableStateFlow público
+- [ ] DI configurada con Hilt o Koin, sin instanciación manual de dependencias
+- [ ] Composables con remember/derivedStateOf para evitar recomposiciones
+- [ ] Capas de Clean Architecture sin dependencias inversas

package/reglas/lenguajes/kotlin/seguridad.md

@@ -0,0 +1,202 @@
+# Regla: Seguridad en Kotlin / Android
+
+Esta regla es OBLIGATORIA para todo código Kotlin en Android o backend.
+Los errores de seguridad en mobile son especialmente costosos: los APKs son
+descargables y analizables por cualquier actor malicioso.
+
+---
+
+## ProGuard/R8: ofuscación obligatoria en release
+
+R8 (sucesor de ProGuard) es la herramienta de ofuscación, shrinking y optimización
+integrada en Gradle. Debe estar habilitada en todos los builds de release.
+
+```kotlin
+// build.gradle.kts — Android
+android {
+    buildTypes {
+        release {
+            isMinifyEnabled = true      // ofuscar y reducir código
+            isShrinkResources = true    // eliminar recursos no usados
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro"
+            )
+        }
+    }
+}
+```
+
+Verificar que las reglas de ProGuard no excluyen clases sensibles innecesariamente.
+Los modelos de datos serializados con Retrofit/Gson/Moshi necesitan reglas explícitas.
+
+---
+
+## EncryptedSharedPreferences para datos sensibles locales
+
+`SharedPreferences` guarda datos en texto plano. NUNCA almacenar tokens, IDs de sesión
+ni datos personales en SharedPreferences sin cifrado.
+
+```kotlin
+// MAL — texto plano, legible con adb o en dispositivos rooteados
+sharedPreferences.edit().putString("access_token", token).apply()
+
+// BIEN — cifrado con EncryptedSharedPreferences (Jetpack Security)
+val masterKey = MasterKey.Builder(context)
+    .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
+    .build()
+
+val prefs = EncryptedSharedPreferences.create(
+    context,
+    "prefs_seguras",
+    masterKey,
+    EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
+    EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM,
+)
+prefs.edit().putString("access_token", token).apply()
+```
+
+---
+
+## No almacenar secretos en BuildConfig
+
+Los valores en `BuildConfig` quedan en el DEX y son extraíbles con herramientas
+como `jadx` o `apktool`. Un atacante puede recuperar la API key en minutos.
+
+```kotlin
+// MAL — la key queda en el APK descompilado
+buildConfigField("String", "API_KEY", "\"sk-prod-abc123\"")
+
+// BIEN — la key se obtiene del servidor en runtime, autenticando al usuario primero
+// El backend actua como proxy: el cliente nunca toca la API key directamente
+```
+
+Para claves que el cliente DEBE conocer (ej: clave pública de SDK de pagos):
+usar Android Keystore + certificate pinning como defensa adicional.
+
+---
+
+## Certificate Pinning en OkHttp
+
+Sin certificate pinning, un atacante con un certificado CA fraudulento puede
+interceptar el tráfico HTTPS (man-in-the-middle).
+
+```kotlin
+// BIEN — pinning por clave pública (más flexible que hash del certificado)
+val certificatePinner = CertificatePinner.Builder()
+    .add("api.miapp.com", "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=")
+    .add("api.miapp.com", "sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=") // backup pin
+    .build()
+
+val okHttpClient = OkHttpClient.Builder()
+    .certificatePinner(certificatePinner)
+    .build()
+```
+
+Incluir SIEMPRE un pin de respaldo (backup pin) para permitir rotación de certificados
+sin dejar la app sin servicio. Documentar el proceso de rotación de pins.
+
+---
+
+## SQL con Room: queries parametrizados
+
+Room previene SQL injection por defecto cuando se usan los parámetros correctamente.
+NUNCA construir queries con concatenación de strings.
+
+```kotlin
+// MAL — SQL injection posible
+@Dao
+interface PedidoDao {
+    @RawQuery
+    fun buscarPorEstatus(query: SupportSQLiteQuery): List<Pedido>
+}
+// Uso peligroso: SimpleSQLiteQuery("SELECT * FROM pedidos WHERE estatus = '$estatus'")
+
+// BIEN — parámetro tipado, Room lo escapa automáticamente
+@Dao
+interface PedidoDao {
+    @Query("SELECT * FROM pedidos WHERE estatus = :estatus")
+    suspend fun buscarPorEstatus(estatus: String): List<Pedido>
+}
+```
+
+---
+
+## Autenticación biométrica con BiometricPrompt
+
+```kotlin
+// BIEN — BiometricPrompt con manejo correcto de resultados
+fun autenticarConBiometria(actividad: FragmentActivity, onExito: () -> Unit) {
+    val executor = ContextCompat.getMainExecutor(actividad)
+    val callback = object : BiometricPrompt.AuthenticationCallback() {
+        override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
+            onExito()
+        }
+        override fun onAuthenticationError(código: Int, mensaje: CharSequence) {
+            // Registrar error, NO exponer detalles al usuario
+            logger.warn("Biometric error $codigo")
+        }
+        override fun onAuthenticationFailed() {
+            // Intento fallido — no bloquear todavía, BiometricPrompt maneja reintentos
+        }
+    }
+
+    BiometricPrompt(actividad, executor, callback).authenticate(
+        BiometricPrompt.PromptInfo.Builder()
+            .setTitle("Confirmar identidad")
+            .setNegativeButtonText("Cancelar")
+            .setAllowedAuthenticators(BiometricManager.Authenticators.BIOMETRIC_STRONG)
+            .build()
+    )
+}
+```
+
+---
+
+## Network Security Config y validación de deep links
+
+```xml
+<!-- res/xml/network_security_config.xml -->
+<network-security-config>
+    <base-config cleartextTrafficPermitted="false">
+        <trust-anchors>
+            <certificates src="system" />
+        </trust-anchors>
+    </base-config>
+    <!-- Solo en debug — nunca en release -->
+    <debug-overrides>
+        <trust-anchors>
+            <certificates src="user" />
+        </trust-anchors>
+    </debug-overrides>
+</network-security-config>
+```
+
+```kotlin
+// Validar deep links — nunca confiar en el scheme/host sin verificar
+override fun onCreate(savedInstanceState: Bundle?) {
+    super.onCreate(savedInstanceState)
+    val uri = intent?.data ?: return
+    if (uri.host != "miapp.com" || uri.scheme != "https") {
+        logger.warn("Deep link invalido: $uri")
+        finish()
+        return
+    }
+    val pedidoId = uri.getQueryParameter("pedido_id")
+        ?.let { UUID.fromString(it) }  // lanza si no es UUID válido
+        ?: run { finish(); return }
+}
+```
+
+---
+
+## Checklist de seguridad Kotlin antes de abrir PR
+
+- [ ] R8/ProGuard habilitado en builds de release
+- [ ] Sin `SharedPreferences` sin cifrar para datos sensibles
+- [ ] Sin secretos en `BuildConfig` o strings.xml
+- [ ] Certificate pinning configurado con pin de respaldo
+- [ ] Queries de Room con parámetros tipados (sin concatenación de strings)
+- [ ] Deep links validados en host y scheme antes de procesar parámetros
+- [ ] `clearTextTrafficPermitted="false"` en network security config
+- [ ] Biometric auth usa `BiometricPrompt`, no APIs deprecadas

package/reglas/lenguajes/kotlin/testing.md

@@ -0,0 +1,236 @@
+# Regla: Testing en Kotlin
+
+Esta regla es OBLIGATORIA para todo código Kotlin nuevo o modificado.
+Las coroutines y los flows requieren herramientas específicas para testearse
+correctamente. Un test de coroutine sin `runTest` no es determinista.
+
+---
+
+## Stack de testing obligatorio
+
+| Herramienta | Propósito |
+|------------|----------|
+| JUnit 5 | Framework base de tests |
+| MockK | Mocking idiomático para Kotlin (no Mockito) |
+| Turbine | Testing de `Flow` con `test {}` API |
+| kotlinx-coroutines-test | `runTest`, `TestDispatcher`, `advanceUntilIdle` |
+| Kover | Cobertura de código (reemplaza JaCoCo para Kotlin) |
+| Compose UI Test | Testing de Composables con `createComposeRule` |
+
+```kotlin
+// build.gradle.kts — dependencias de test
+dependencies {
+    testImplementation("org.junit.jupiter:junit-jupiter:5.10.2")
+    testImplementation("io.mockk:mockk:1.13.10")
+    testImplementation("app.cash.turbine:turbine:1.1.0")
+    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.8.0")
+    androidTestImplementation("androidx.compose.ui:ui-test-junit4")
+}
+```
+
+---
+
+## runTest y TestDispatcher para coroutines
+
+`runTest` es el único punto de entrada correcto para tests de suspend functions.
+Reemplaza `runBlocking` en tests — maneja los virtual timers del test framework.
+
+```kotlin
+// MAL — runBlocking no controla el tiempo virtual ni los dispatchers de coroutines
+@Test
+fun `obtener usuario por id retorna usuario correcto`() = runBlocking {
+    val resultado = repositorio.obtenerPorId(uuid)
+    assertEquals("Juan", resultado?.nombre)
+}
+
+// BIEN — runTest con dispatcher controlado
+@Test
+fun `obtener usuario por id retorna usuario correcto`() = runTest {
+    val resultado = repositorio.obtenerPorId(uuid)
+    assertEquals("Juan", resultado?.nombre)
+}
+
+// BIEN — StandardTestDispatcher para controlar avance del tiempo
+@Test
+fun `cargando pedidos emite loading luego success`() = runTest {
+    val dispatcher = StandardTestDispatcher(testScheduler)
+    val viewModel = PedidoViewModel(obtenerPedidosUseCase, dispatcher)
+
+    val estados = mutableListOf<UiState<*>>()
+    val job = launch { viewModel.uiState.collect { estados.add(it) } }
+
+    advanceUntilIdle()
+
+    assertEquals(UiState.Loading, estados.first())
+    assertIs<UiState.Success<*>>(estados.last())
+    job.cancel()
+}
+```
+
+---
+
+## Turbine para testing de Flow
+
+```kotlin
+// MAL — collect en test puede colgarse o perder emisiones
+@Test
+fun `flujo emite pedidos`() = runTest {
+    val emisiones = mutableListOf<List<Pedido>>()
+    val job = launch { repositorio.obtenerTodos().collect { emisiones.add(it) } }
+    job.cancel()
+    assertTrue(emisiones.isNotEmpty())
+}
+
+// BIEN — Turbine provee API declarativa y determinista
+@Test
+fun `flujo emite lista de pedidos`() = runTest {
+    repositorio.obtenerTodos().test {
+        val pedidos = awaitItem()
+        assertEquals(3, pedidos.size)
+        cancelAndIgnoreRemainingEvents()
+    }
+}
+
+// BIEN — verificar múltiples emisiones en orden
+@Test
+fun `estado transiciona de loading a success`() = runTest {
+    viewModel.uiState.test {
+        assertIs<UiState.Loading>(awaitItem())
+        val success = awaitItem()
+        assertIs<UiState.Success<*>>(success)
+        cancelAndIgnoreRemainingEvents()
+    }
+}
+```
+
+---
+
+## MockK para mocks idiomáticos en Kotlin
+
+```kotlin
+// Configuración típica con MockK
+@ExtendWith(MockKExtension::class)
+class CrearPedidoUseCaseTest {
+
+    @MockK
+    private lateinit var pedidoRepo: PedidoRepository
+
+    @MockK
+    private lateinit var inventarioRepo: InventarioRepository
+
+    private lateinit var crearPedido: CrearPedidoUseCase
+
+    @BeforeEach
+    fun setup() {
+        crearPedido = CrearPedidoUseCase(pedidoRepo, inventarioRepo)
+    }
+
+    @Test
+    fun `crear pedido con items disponibles retorna pedido creado`() = runTest {
+        // Given
+        val items = listOf(ItemPedido(productoId = uuid, cantidad = 2))
+        coEvery { inventarioRepo.verificarDisponibilidad(items) } returns true
+        coJustRun { pedidoRepo.guardar(any()) }
+
+        // When
+        val resultado = crearPedido(items)
+
+        // Then
+        assertTrue(resultado.isSuccess)
+        coVerify(exactly = 1) { pedidoRepo.guardar(any()) }
+    }
+}
+```
+
+---
+
+## Patrón Given-When-Then
+
+Todos los tests siguen el patrón Given-When-Then con comentarios explícitos.
+
+```kotlin
+@Test
+fun `crear pedido sin items retorna error de validación`() = runTest {
+    // Given
+    val itemsVacios = emptyList<ItemPedido>()
+
+    // When
+    val resultado = crearPedido(itemsVacios)
+
+    // Then
+    assertTrue(resultado.isFailure)
+    assertIs<IllegalArgumentException>(resultado.exceptionOrNull())
+}
+```
+
+---
+
+## Cobertura con Kover
+
+```kotlin
+// build.gradle.kts
+plugins {
+    id("org.jetbrains.kotlinx.kover") version "0.7.6"
+}
+
+koverReport {
+    filters {
+        excludes {
+            classes("**/di/**", "**/*Module*", "**/*_Factory*")
+        }
+    }
+    verify {
+        rule {
+            bound { minValue = 80 }
+        }
+    }
+}
+```
+
+---
+
+## Testing de Composables
+
+```kotlin
+class PantallaPedidosTest {
+
+    @get:Rule
+    val composeTestRule = createComposeRule()
+
+    @Test
+    fun `muestra lista de pedidos cuando estado es success`() {
+        // Given
+        val pedidos = listOf(Pedido(id = uuid, total = 150.0))
+        val estado = UiState.Success(pedidos)
+
+        // When
+        composeTestRule.setContent {
+            PantallaPedidos(uiState = estado)
+        }
+
+        // Then
+        composeTestRule.onNodeWithText("$150.00").assertIsDisplayed()
+    }
+
+    @Test
+    fun `muestra indicador de carga cuando estado es loading`() {
+        composeTestRule.setContent {
+            PantallaPedidos(uiState = UiState.Loading)
+        }
+        composeTestRule.onNodeWithTag("loading_indicator").assertIsDisplayed()
+    }
+}
+```
+
+---
+
+## Checklist de testing Kotlin antes de abrir PR
+
+- [ ] Tests de coroutines usan `runTest`, no `runBlocking`
+- [ ] Tests de Flow usan Turbine (`flow.test { }`)
+- [ ] Mocks creados con MockK, no con Mockito
+- [ ] `coEvery`/`coVerify` para suspend functions mockeadas
+- [ ] Patrón Given-When-Then con comentarios explícitos
+- [ ] Cobertura >= 80% verificada con Kover
+- [ ] Tests de Composables con `createComposeRule`
+- [ ] Sin `Thread.sleep()` ni delays fijos en tests