====== Preguntas Frecuentes (FAQ) ======

===== Instalación y Setup =====

==== P: ¿Cómo configuro mi máquina para desarrollar en PAE? ====

**R**: Sigue [[environment-setup|environment-setup.md]]. Necesitas:
  * JDK 17
  * Android Studio
  * Android SDK 27-36
  * Git

<code bash>
./gradlew clean build  # verificar setup
</code>

==== P: ¿Qué versión de Android Studio necesito? ====

**R**: Android Studio 2023.2 o superior. Si es vieja, actualiza:
  * macOS: ''brew install android-studio''
  * Windows: descarga de developer.android.com

----

===== Compilación y Deployment =====

==== P: ¿Cómo compilo para release? ====

**R**: Ver [[build-and-deployment|build-and-deployment.md]]:

<code bash>
export KEYSTORE_PASS="tu_pass"
export KEY_PASS="tu_key_pass"

./gradlew :Machine:assembleRelease
# APK está en: build/outputs/apk/release/Machine-release.apk
</code>

==== P: ¿Por qué dice "Signing config not defined"? ====

**R**: Necesitas configurar signing en ''build.gradle.kts'':

<code kotlin>
android {
    signingConfigs {
        release {
            storeFile = file("../keystore/machine-release.jks")
            storePassword = System.getenv("KEYSTORE_PASS")
            keyAlias = "machine-key"
            keyPassword = System.getenv("KEY_PASS")
        }
    }
    buildTypes {
        release {
            signingConfig = signingConfigs["release"]
        }
    }
}
</code>

==== P: ¿Cómo instalo en dispositivo? ====

**R**:
<code bash>
# Debug
adb install build/outputs/apk/debug/Machine-debug.apk

# Release (después de release build)
adb install build/outputs/apk/release/Machine-release.apk

# Reinstalar
adb install -r build/outputs/apk/release/Machine-release.apk
</code>

----

===== Desarrollo =====

==== P: ¿Cómo agrego un nuevo módulo? ====

**R**: 
  - Crear carpeta: ''mkdir MyModule''
  - Crear ''MyModule/build.gradle.kts'':
<code kotlin>
plugins {
    id("com.android.library")
    kotlin("android")
}

android {
    namespace = "co.ada.mymodule"
    compileSdk = 36
    // ...
}

dependencies {
    implementation(project(":Contract"))
    implementation(project(":Core"))
}
</code>
  - Agregar a ''settings.gradle.kts'':
<code kotlin>
include(":MyModule")
project(":MyModule").projectDir = file("MyModule")
</code>
  - Sync: ''> Gradle → Sync Now''

==== P: ¿Cómo agrego código a Machine vs RutaPAE? ====

**R**: 
  * Machine (app Android): ''Machine/src/main/...''
  * RutaPAE (app Android): ''RutaPAE/src/main/...''
  * Lógica compartida: ''MachineDomain/'' o ''RutaPAEDomain/''
  * Datos: ''MachineData/'' o ''RutaPAEData/''

==== P: ¿Dónde agrego un nuevo estado? ====

**R**: En ''MachineDomain/src/.../state/'':
  - Crear ''MyNewState.kt''
  - Implementar interfaz ''State''
  - Agregar a lista en ''StateManager.workflow''

Ver [[developer-guide#agregar//nuevo//estado//a//machine|developer-guide.md]].

==== P: ¿Cómo agrego un endpoint HTTP? ====

**R**: En ''MachineDomain/src/.../endpoints/MachineEndpoints.kt'':
<code kotlin>
object MachineEndpoints {
    fun getMyData(): Request {
        return "${backendUrl}/api/mydata"
            .httpGet()
            .responseJson()
    }
}

// Usar
val data = MachineEndpoints.getMyData()
</code>

----

===== Testing =====

==== P: ¿Cómo escribo tests? ====

**R**: Ver [[testing-guide|testing-guide.md]]. Ejemplo unit test:

<code kotlin>
@RunWith(RobolectricTestRunner::class)
class StateManagerTest {
    @Test
    fun testStateTransition() {
        val manager = StateManager(mockRepository, mockHardware)
        manager.init(context)
        
        assertEquals("WaitingForWeight", manager.getCurrentState())
    }
}
</code>

Ejecutar:
<code bash>
./gradlew test
</code>

==== P: ¿Cómo hago UI tests? ====

**R**: Con Compose test:
<code kotlin>
@RunWith(AndroidJUnit4::class)
class LaboratoryScreenTest {
    @get:Rule
    val composeTestRule = createComposeRule()
    
    @Test
    fun testButtonVisible() {
        composeTestRule.setContent {
            LaboratoryScreen(viewModel())
        }
        composeTestRule.onNodeWithText("Capturar").assertIsDisplayed()
    }
}
</code>

----

===== P2P y Sincronización =====

==== P: ¿Cómo sincronizo entregas entre Machine y RutaPAE? ====

**R**: En RutaPAE, enqueue worker:
<code kotlin>
DeliverySyncScheduler.enqueue(context, machineId = 1L)
</code>

Esto crea una operación P2P que:
  - Descubre máquina
  - Conecta vía Wi-Fi Direct
  - Descarga entregas
  - Guarda localmente

Ver [[p2p-flow|p2p-flow.md]].

==== P: ¿Qué pasa si P2P falla? ====

**R**: Hay fallback a hotspot. Si también falla:
  * Retry automático con backoff exponencial
  * Notificación al usuario
  * Peut être reintentado manualmente

==== P: ¿Cómo sé si máquina está disponible? ====

**R**:
<code kotlin>
val p2pManager = DomainManager.p2pManager
val peers = p2pManager.discoveredMachineCandidates()
// peers contiene máquinas disponibles
</code>

----

===== Hardware =====

==== P: ¿Cómo capturo foto en Machine? ====

**R**: En StateManager:
<code kotlin>
val bitmap = Camera2Service(context).takeSelfie()
if (bitmap != null) {
    stateData.facePhoto = bitmap
    next()
} else {
    retry("Camera error")
}
</code>

Ver [[hardware-integration|hardware-integration.md]].

==== P: ¿Cómo conecto a balanza Bluetooth? ====

**R**: Requiere permissions:
<code xml>
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
</code>

Luego:
<code kotlin>
val scale = BluetoothScaleManager(context, MAC_ADDRESS)
scale.addEventListener(listener)
val weight = scale.getWeight()
</code>

==== P: ¿Cómo obtengo MAC address de balanza? ====

**R**: En dispositivo Android:
<code bash>
adb shell bluetoothctl
> devices
# lista con direcciones MAC
</code>

----

===== Database y Persistencia =====

==== P: ¿Cómo hago query vectorial a beneficiarios? ====

**R**: Usar ''findSimilar'':
<code kotlin>
val embedding = generateEmbedding(facePhoto)
val similar = BeneficiaryService.findSimilar(embedding, similarity = 0.8f)

// similar contiene top resultados por similitud
for (beneficiary in similar) {
    println("${beneficiary.name}: ${similarity}")
}
</code>

==== P: ¿Cómo agrego nuevo campo a Delivery? ====

**R**: 
  - Editar ''data class Delivery'' en ''MachineData/src/.../entities/''
  - El ORM migrará automáticamente (open-source VectorDB)

<code kotlin>
data class Delivery(
    val id: Long,
    val weight: Float,
    val nuevoCampo: String = ""  // new field
)
</code>

==== P: ¿Cómo elimino datos viejos? ====

**R**: Limpiar en background:
<code kotlin>
val oneMonthAgo = System.currentTimeMillis() - 30.days.inMilliseconds
repository.deliveries.where { it.createdAt < oneMonthAgo }
    .forEach { repository.deliveries.delete(it.id) }
</code>

----

===== Seguridad =====

==== P: ¿Cómo protejo credenciales sensitivas? ====

**R**: Ver [[security-and-privacy|security-and-privacy.md]]:

<code kotlin>
// Guardar tokens de forma segura
val encryptedPrefs = EncryptedSharedPreferences.create(context, ...)
encryptedPrefs.edit().putString("api_token", token).apply()

// Leer
val token = encryptedPrefs.getString("api_token", null)
</code>

==== P: ¿Cómo evito logging de datos sensibles? ====

**R**: Usar logger personalizado:
<code kotlin>
// ❌ Malo
Log.d("API", "Token: $token")

// ✅ Bueno
Log.d("API", "User authenticated")

// ✅ Mejor
SecureLogger.logToken(token)  // oculta la mayoría
</code>

==== P: ¿Mi app necesita certificate pinning? ====

**R**: Sí, en producción. Configurar:
<code kotlin>
val certificatePinner = CertificatePinner.Builder()
    .add("backend.api.com", "sha256/AAAAAAA...")
    .build()
</code>

----

===== Performance =====

==== P: ¿Cómo optimizo búsqueda de beneficiarios? ====

**R**: Este es el cuello de botella típico. Soluciones:
  - Índice vectorial HNSW (ya implementado in VectorDB)
  - Caché de resultados recientes
  - Limitar K nearest neighbors

==== P: ¿Por qué la app está lenta? ====

**R**: Causas comunes:
  - Operación BD en main thread - usar ''withContext(Dispatchers.IO)''
  - Búsqueda sobre muchas fotos - implementar paginación
  - Memory leak - usar Android Profiler
  - Compilación debug - agregar -Xmx4g en gradle.properties

Ver [[troubleshooting|troubleshooting.md#app-muy-lenta]].

----

===== Debugging =====

==== P: ¿Cómo veo logs en Android Studio? ====

**R**: Abrir Logcat:
<code>
Android Studio → View → Tool Windows → Logcat
</code>

Filtrar:
<code bash>
Filter: "StateManager"  # solo líneas con StateManager
</code>

O vía terminal:
<code bash>
adb logcat | grep StateManager
</code>

==== P: ¿Cómo seteo breakpoint? ====

**R**: Click en número de línea (izquierda):
<code>
1. Marcar breakpoint (punto rojo)
2. Run → Debug 'Machine' (Shift+F9)
3. App pausa cuando llega a línea
4. F9 para continuar
5. F10 para step over
6. F11 para step into
</code>

==== P: App crashea pero sin error visible? ====

**R**: Ver logcat completo:
<code bash>
adb logcat | tail -100
</code>

O usar Android Profiler:
<code>
Android Studio → View → Tool Windows → Profiler
</code>

----

===== Errores comunes =====

==== P: "Gradle sync failed" ====

**R**: 
<code bash>
./gradlew clean
rm -rf .gradle
./gradlew build
</code>

Ver [[troubleshooting|troubleshooting.md#gradle-sync-failed]].

==== P: "No such key: deliveries" ====

**R**: No synchronized gradle. Falta ''sync'':
<code>
Android Studio: File → Sync Now

O terminal:
./gradlew clean build
</code>

==== P: "Camera permission denied" ====

**R**: Solicitar en runtime (API 23+):
<code kotlin>
if (ContextCompat.checkSelfPermission(context, Manifest.permission.CAMERA) 
    != PackageManager.PERMISSION_GRANTED) {
    ActivityCompat.requestPermissions(activity, arrayOf(Manifest.permission.CAMERA), 100)
}
</code>

==== P: "Bluetooth connection failed" ====

**R**: 
  - Verificar device está pareado
  - Permisos solicitados
  - MAC address correcto
  - Dispositivo no está dormido

Ver [[troubleshooting|troubleshooting.md#bluetooth-connection-refused]].

----

===== Mejores prácticas =====

==== P: ¿Cuándo usar Flow vs StateFlow? ====

**R**:
  * **Flow**: observable, emite datos secuencialmente, puede estar vacío
  * **StateFlow**: siempre tiene estado actual, último valor disponible

<code kotlin>
// Flow: observable stream
val deliveriesFlow: Flow<List<Delivery>> = ...

// StateFlow: estado actual
val currentState = MutableStateFlow<State>(State.Idle)
currentState.value  // acceder estado actual
</code>

==== P: ¿Cuándo usar suspend vs async? ====

**R**:
  * **suspend**: función que puede pausarse (estructura lineal)
  * **async**: inicia tarea concurrent (necesita .await())

<code kotlin>
// suspend: simple
suspend fun getData(): String = repository.getString()

// async: paralelismo
val result1 = async { repository.getString() }
val result2 = async { repository.getInt() }
// esperar ambas
val r1 = result1.await()
val r2 = result2.await()
</code>

==== P: ¿Cómo organizo código nuevo? ====

**R**: Seguir estructura:
<code>
co.ada.MODULE/
├── screens/       # UI Composables (si app)
├── viewmodels/    # ViewModel (si app)
├── domain/
│   ├── managers/  # orquestadores
│   └── services/  # lógica
├── data/
│   ├── entities/  # modelos BD
│   └── repository/ # CRUD
└── di/            # inyección
</code>

----

===== Contribución =====

==== P: ¿Cómo contribuyo code? ====

**R**: 
  - Fork / branch
  - Hacer cambios + tests
  - Push
  - Pull request con descripción

Ver [[best-practices|best-practices.md#version-control]].

==== P: ¿Qué estándares de código? ====

**R**: Ver [[best-practices|best-practices.md]]:
  * Usar nombres descriptivos
  * One responsibility per class/function
  * Test coverage mínimo 70%
  * Sin hardcoded secrets
  * Lint checks pasan

----

===== Contacto y Soporte =====

==== P: ¿Dónde reporto bugs? ====

**R**: Issues en GitHub con:
  * Descripción clara
  * Steps para reproducir
  * Log/stack trace
  * Ambiente (dispositivo, OS, versión app)

==== P: ¿Dónde veo roadmap? ====

**R**: Proyectos en GitHub. Planificación trimestral.

==== P: ¿Cómo pido una feature? ====

**R**: Abrir discussion en GitHub con:
  * Caso de uso
  * Por qué es importante
  * Impacto estimado

----

===== Recursos =====

  * [[start|Documentación completa]]
  * [[adr-architecture-decisions|Architecture Decision Records]]
  * [[best-practices|Best practices]]
  * [[troubleshooting|Troubleshooting]]
  * [[glossary|Glosario]]
  * [[api-reference|API Reference]]