====== Guía de referencia para desarrolladores ======

===== Acceso rápido a componentes clave =====

==== Machine: Flujo de captura de entrega ====

**Archivo de entrada**: ''Machine/src/main/java/co/ada/paemachine/screens/LaboratoryScreen.kt''

<code kotlin>
// Usuario presiona botón
Button("Capturar") {
    viewModel.startCapture()
}

// ViewModel delega
fun startCapture() {
    stateManager.init(context) // Inicia máquina de estados
}
</code>

**Máquina de estados**: ''MachineDomain/src/main/java/co/ada/domain/state/''

<code>
StateManager.kt
├── init() : Boolean
├── cycle() : StateResult
├── getCurrentState(): String
└── states.toMutableList()
    ├── WaitingForWeightState.kt
    ├── CaptureImagesState.kt
    ├── CaptureFaceState.kt
    ├── ComparingWeightsState.kt
    ├── GenerateEmbeddingState.kt
    ├── VerifyInDatabaseState.kt
    ├── SaveDeliveryState.kt
    └── WaitForWeightRemovedState.kt
</code>

**Cambios de estado emitidos**: ''MachineDomain/src/main/java/co/ada/domain/emitters/''

<code kotlin>
StateNameEmitter.emit(currentState) // "CapturingFace"
StateMessageEmitter.emit(message)   // "Por favor espere..."
</code>

**UI observa en Composable**:

<code kotlin>
LaunchedEffect {
    StateNameEmitter.collect { stateName ->
        updateUI(stateName)
    }
}
</code>

----

==== RutaPAE: Sincronización de máquinas ====

**Punto de entrada**: ''RutaPAE/src/main/java/co/ada/rutapae/screens/MachineListScreen.kt''

<code kotlin>
Button("Sincronizar") {
    onSyncClicked() // enqueue worker
}

private fun onSyncClicked() {
    DeliverySyncScheduler.enqueue(
        context,
        machineId = 1L,
        machineDatabase = machineForeignId
    )
}
</code>

**Worker**: ''RutaPAE/src/main/java/co/ada/rutapae/workers/DeliverySyncWorker.kt''

<code kotlin>
class DeliverySyncWorker : CoroutineWorker() {
    override suspend fun doWork(): Result {
        // Inicializa dominio
        val initialized = DomainManager.init(context)
        
        // Accede a P2PManager
        val manager = DomainManager.p2pManager ?: return Result.retry()
        
        // Sincroniza entregas
        val result = manager.syncDeliveriesFromMachine(
            machineId,
            machineDatabaseId
        )
        
        return if (result.success) Result.success() else Result.retry()
    }
}
</code>

**Dominio**: ''RutaPAEDomain/src/main/java/co/ada/rutapaedomain/''

<code>
DomainManager.kt (singleton)
├── init(context): Boolean
├── close(context): Boolean
└── p2pManager: P2PManager

P2PManager.kt
├── discoverableMachineIds(): Set<String>
├── discoveredMachineCandidates(): Set<P2PPeer>
├── connectMachine(machineId): P2PGestor?
├── connectMachineHotspot(ssid): P2PGestor?
└── syncDeliveriesFromMachine(): SyncDeliveriesResult
</code>

**Persistencia**: ''RutaPAEData/src/main/java/co/ada/rutapaedata/''

<code kotlin>
DeliveryService.createDeliveries(deliveries: List<Delivery>) {
    // Repository.deliveries.create(delivery)
    // INSERT INTO Delivery(...)
}

MachineService.updateMachine(machine: Machine) {
    // Repository.machines.update(machine)
}
</code>

----

===== Servicios de datos =====

==== MachineData ====

**Ubicación**: ''MachineData/src/main/java/co/ada/data/services/''

<code kotlin>
object DeliveryService {
    fun getAll(): List<Delivery>
    fun create(delivery: Delivery): Delivery
    fun update(delivery: Delivery): Boolean
    fun delete(id: Long): Boolean
}

object BeneficiaryService {
    fun getAll(): List<Beneficiary>
    fun create(beneficiary: Beneficiary): Beneficiary
    fun findSimilar(embedding: FloatArray, similarity: Float = 0.7f): List<Beneficiary>
    fun update(beneficiary: Beneficiary): Boolean
}

object MachineEnrollmentShiftService {
    fun getById(id: Long): MachineEnrollmentShift?
    fun create(shift: MachineEnrollmentShift): MachineEnrollmentShift
}
</code>

==== RutaPAEData ====

**Ubicación**: ''RutaPAEData/src/main/java/co/ada/rutapaedata/services/''

<code kotlin>
object MachineService {
    fun getAll(): List<Machine>
    fun getById(id: Long): Machine?
    fun create(machine: Machine): Machine
    fun update(machine: Machine): Boolean
}

object DeliveryService {
    fun getAll(): List<Delivery>
    fun getByMachineId(machineId: Long): List<Delivery>
    fun create(delivery: Delivery): Delivery
    fun createMany(deliveries: List<Delivery>): List<Delivery>
}
</code>

----

===== Conexión P2P =====

==== Descubrimiento de máquinas ====

<code>
RutaPAE                    DirectLink              Machine
(cliente)                  (broadcast)             (servidor)
   │                           │                       │
   ├─ P2PManager               │                       │
   │  .discoverableMachineIds() ├───► broadcast peers ───►
   │                           │                       │
   │  List<String>             ◄─── Device A, B, C ◄──┤
   │◄───────────────────────────┤                       │
</code>

==== Conexión a máquina ====

<code kotlin>
// RutaPAE
val p2pGestor = p2pManager.connectMachine(machineId = 1L)
    ?: return // conexión fallida

// Ahora disponible
p2pGestor.connection.peer.get("/p2p/machine")
</code>

==== Endpoints disponibles en Machine P2P ====

<code>
GET /p2p/machine
    ├─ P2PMachineState (máquina actual)

GET /p2p/machine/deliveries/{campusId}/{shiftId}
    ├─ P2PDeliveriesPageResponse (entregas paginadas)

GET /p2p/machine/configuration
    ├─ P2PMachineConfiguration (config de máquina)

POST /p2p/machine/configuration
    └─ actualiza configuración

DELETE /p2p/machine/deliveries/{deliveryId}
    └─ marca entrega como confirmada en remoto
</code>

----

===== Modelos principales =====

==== Entidades de base de datos ====

=== Delivery ===

<code kotlin>
@DataTable("Delivery")
data class Delivery(
    @PrimaryKey
    val id: Long = 0,
    
    val weight: Float = 0f,
    val beneficiaryPhotoPath: String? = null,
    val alimentPhotoPath: String? = null,
    val similarity: Float = 0f,
    val processTimeMs: Long = 0L,
    
    val serverDeliveryId: String? = null,
    val synchronized: Boolean = false,
    val createdAt: Long = 0L
)
</code>

=== Beneficiary ===

<code kotlin>
@DataTable("Beneficiary")
data class Beneficiary(
    @PrimaryKey
    val id: Long = 0,
    
    @VectorColumn(dimensions = 512, distanceMetric = DistanceMetric.COSINE)
    val embedding: FloatArray,
    
    val name: String,
    val remoteBeneficiaryId: String? = null,
    val enrollmentId: String? = null,
    val lastRecognitionAtMs: Long = 0L
)
</code>

=== Machine (RutaPAE) ===

<code kotlin>
@DataTable("Machine")
data class Machine(
    @PrimaryKey
    val id: Long = 0,
    
    val machineId: String,
    val name: String,
    val machineStatus: P2PMachineStatus = P2PMachineStatus.Inactive,
    val unsyncedDeliveries: Long = 0,
    val localSyncedDeliveries: Long = 0
)
</code>

==== Modelos P2P (Contract) ====

<code kotlin>
data class P2PMachineState(
    val id: String = "",
    val name: String = "",
    val unsyncedDeliveries: Long = 0,
    val serverSyncedDeliveries: Long = 0,
    val status: String = "Inactive" // Active, Inactive, Error
)

data class P2PDeliveryData(
    val id: String,
    val weight: Float,
    val beneficiaryPhoto: String? = null, // URL
    val alimentPhoto: String? = null,     // URL
    val similarity: Float = 0f,
    val processTimeMs: Long = 0L
)
</code>

----

===== Configuración de proyecto =====

==== Settings ====

**Ubicación**: ''settings.gradle.kts''

<code kotlin>
include(
    ":Machine",
    ":RutaPAE",
    ":MachineDomain",
    ":MachineData",
    ":RutaPAEDomain",
    ":RutaPAEData",
    ":Contract",
    ":DirectLink",
    ":VectorialDB",
    ":ComputerVision",
    ":Core"
)
</code>

==== Versiones ====

**Ubicación**: ''gradle/libs.versions.toml''

<code>
[versions]
kotlin = "2.3.10"
compose = "1.5.4"
min-sdk = "27"
compile-sdk = "36"
jvm-target = "17"
</code>

==== Android (min/target) ====

  * **minSdk**: 27 (Android 8.1)
  * **targetSdk**: 36 (Android 15)
  * **compileSdk**: 36.1

----

===== Testing =====

==== Estructura recomendada ====

<code>
Machine/src/
├── main/
│   └── java/co/ada/paemachine/
│       ├── screens/
│       ├── viewmodels/
│       └── di/
│
├── test/
│   └── java/co/ada/paemachine/
│       ├── viewmodels/
│       └── ...
│
└── androidTest/
    └── java/co/ada/paemachine/
        ├── screens/
        └── ...
</code>

==== Testing del StateManager ====

<code kotlin>
@Test
fun testStateTransition() {
    val manager = StateManager(
        repository = mockRepository,
        hardware = mockHardware
    )
    
    manager.init(mockContext)
    // assert state is WaitingForWeight
}
</code>

==== Testing de servicios ====

<code kotlin>
@Test
fun testBeneficiarySearch() {
    val service = BeneficiaryService
    val results = service.findSimilar(embedding, similarity = 0.8f)
    
    assertTrue(results.isNotEmpty())
}
</code>

----

===== Debugging =====

==== Logs ====

**Core logging**: ''Core/src/main/java/co/ada/core/logging/''

<code kotlin>
Logger.d("StateManager", "Transitioning to ${state.name}")
Logger.e("P2PManager", "Connection failed: $error")
Logger.i("DeliveryService", "Delivery saved: $deliveryId")
</code>

==== Debug points ====

**Machine**: Observa emisores en Logcat

<code>
adb logcat | grep StateNameEmitter
adb logcat | grep DeliverySyncUiEmitter
</code>

**RutaPAE**: Verifica logs de Worker

<code>
adb logcat | grep DeliverySyncWorker
adb logcat | grep P2PManager
</code>

----

===== Common Tasks =====

==== Agregar nuevo estado a Machine ====

  - Crear: ''MachineDomain/src/.../state/MyNewState.kt''
  - Implementar interfaz ''State''
  - Agregar a lista en ''StateManager.workflow''
  - Emitir cambios vía ''StateNameEmitter''

==== Agregar nuevo servicio de datos ====

  - Crear: ''MachineData/src/.../services/MyService.kt''
  - Implementar CRUD
  - Usar ''Repository.myTable.create/update/delete()''
  - Mapear entidades si es necesario

==== Cambiar endpoints HTTP ====

  - Editar: ''MachineDomain/src/.../endpoints/MachineEndpoints.kt''
  - Actualizar URL base si es necesario (Fuel)
  - Actualizar modelos de respuesta si cambia schema
  - Actualizar mapping en servicios

==== Agregar nueva ruta P2P ====

  - En Machine, agregar endpoint: ''Machine/src/.../p2p/P2PMachine.kt''
  - En Contract, agregar modelo: ''Contract/src/.../models/''
  - Usar en RutaPAE: ''P2PManager.syncXxx()''

----

===== Referencias rápidas =====

^ Tarea ^ Archivo ^ Función ^
| Ver estado actual | ''MachineDomain/.../StateManager.kt'' | ''getCurrentState()'' |
| Emitir evento UI | ''MachineDomain/.../emitters/StateNameEmitter.kt'' | ''emit(name)'' |
| Buscar beneficiarios | ''MachineData/.../BeneficiaryService.kt'' | ''findSimilar()'' |
| Guardar entrega | ''MachineData/.../DeliveryService.kt'' | ''create()'' |
| Conectar P2P | ''RutaPAEDomain/.../P2PManager.kt'' | ''connectMachine()'' |
| Sincronizar entregas | ''RutaPAEDomain/.../P2PManager.kt'' | ''syncDeliveriesFromMachine()'' |
| Configurar Database | ''gradle/libs.versions.toml'' | versiones SDK |
| Ver modelos P2P | ''Contract/src/.../models/'' | estructuras P2P |
| Emitir progreso sync | ''RutaPAE/.../emitters/DeliverySyncUiEmitter.kt'' | ''update()'' |
| Enqueue sync worker | ''RutaPAE/.../DeliverySyncScheduler.kt'' | ''enqueue()'' |