====== Flujo de sincronización HTTP (paso a paso) ======

===== Propósito =====

Explicar el flujo real de sincronización HTTP en ''Machine'' y ''RutaPAE'', incluyendo orden de pasos, condiciones de ejecución y cómo esto impacta la visualización de jornadas en ''ShiftSelectionScreen''.

===== Flujo HTTP en Machine (''Client.runSyncInternal'') =====

==== 1. Precondiciones ====

Antes de iniciar una sincronización completa:

  - Se valida conectividad a internet.
  - Se evita ejecución concurrente (''syncRunning'' + ''runningSyncJob'').
  - Se reinician señales de progreso (''SyncProgressDetailsEmitter.reset()'' y ''SyncProgressEmitter'').
  - Se asegura ''machineId'' remoto (''Machine.ensureRemoteMachineId''), registrando máquina si hace falta (''POST /machines'').

==== 2. Orden de etapas (sincronización completa) ====

Dentro de ''runSyncInternal'' el orden es:

  - ''SyncMachineEnrollment'' (bloqueante, primero).
  - En paralelo:
    * ''SyncDeliveries'' (sin timeout por etapa interna).
    * ''SyncBeneficiaries'' (sin timeout dentro de este tramo paralelo).
  - ''SyncDeliveryGoals'' (posterior al paralelo).
  - ''SyncLogs'' como best-effort (opcional, no bloquea éxito global).

Si cualquiera de las etapas críticas falla, se corta la corrida y el progreso vuelve a ''Waiting''.

==== 3. Endpoints usados en cada etapa ====

  * ''SyncMachineEnrollment'':
    * ''GET /machine-enrollments?page={p}&size={s}&machineId={id}&machine.id={id}''
  * ''SyncBeneficiaries'':
    * ''GET /beneficiaries-enrollments?...&campusOfferIds={ids}''
    * ''GET /photos/{beneficiaryId}/beneficiary?nameFrom=machine''
  * ''SyncDeliveries'':
    * ''POST /deliveries/data''
    * ''POST /deliveries/photos''
  * ''SyncDeliveryGoals'':
    * ''GET /minuta-menu-dues/delivery-goals?since={d}&until={d}&campusId={id}''
  * ''SyncLogs'':
    * ''POST /logs''

===== Reglas de ejecución periódica (''ClientSyncService'') =====

''ClientSyncService'' ejecuta ticks periódicos:

  - Siempre corre health-check por intervalo (''POST /health-checks'').
  - Solo permite sincronización completa si:
    * hay internet, y
    * **no** hay jornada activa (''MachineEnrollmentService.getActive() == null'').
  - Si internet se recupera y no hay jornada activa, dispara sync inmediata.

Esto evita impactar la experiencia de operación durante una jornada abierta.

===== Filtrado de jornadas en ''ShiftSelectionScreen'' =====

El detalle completo de cómo se construye y filtra la lista de jornadas visibles se documenta aparte en:

  * [[ada:howto:sicoferp:factory:new-migracion-sicoferp:machine:filtrado-de-jornadas-en-shift-selection|Filtrado De Jornadas En Shift Selection]]

Resumen rápido:

  - ''ShiftSelectionScreen'' refresca desde eventos locales de DB.
  - ''OperationalShiftService'' agrupa y consolida jornadas locales en ''OperationalShift''.
  - ''MachineEnrollmentService'' deduplica y preserva consistencia de referencias.
  - La UI pagina solo renderizado (chunk local), no paginación HTTP.

===== Flujo HTTP en RutaPAE (resumen) =====

''RutaPAEDomain.network.request.SyncDeliveries'' ejecuta:

  - Subida de datos:
    * ''POST /deliveries/data''
  - Subida de fotos:
    * ''POST /deliveries/photos''
  - Marcado local como sincronizada (no borra automáticamente por defecto en ese flujo).

Puede usar URL por entrega (''delivery.url'', ''delivery.photosUrl'') o fallback al host por defecto.

===== Errores y recuperación relevantes =====

  * Conflicto ''208'' en datos de entrega se trata como “ya existe” (no necesariamente fatal).
  * ''404'' en fotos puede ser inconsistencia eventual; se reintenta con backoff.
  * Pérdida de internet durante sync pausa/cancela etapa según contexto.
  * Si backend “pierde” la máquina (404/410 o patrón equivalente), se intenta recrear ''machineId'' remoto.

===== Fuentes de verdad =====

  * ''MachineDomain/src/main/java/co/ada/domain/network/Client.kt''
  * ''MachineDomain/src/main/java/co/ada/domain/network/ClientSyncService.kt''
  * ''MachineDomain/src/main/java/co/ada/domain/network/request/SyncMachineEnrollment.kt''
  * ''MachineDomain/src/main/java/co/ada/domain/network/request/SyncBeneficiaries.kt''
  * ''MachineDomain/src/main/java/co/ada/domain/network/request/SyncDeliveries.kt''
  * ''MachineDomain/src/main/java/co/ada/domain/network/request/SyncDeliveryGoals.kt''
  * ''MachineDomain/src/main/java/co/ada/domain/network/request/SyncLogs.kt''
  * ''RutaPAEDomain/src/main/java/co/ada/rutapaedomain/network/request/SyncDeliveries.kt''

===== Ultima verificacion =====

  * Fecha: ''2026-04-23''
  * Verificado contra implementación actual de sincronización HTTP y filtrado de jornadas en pantalla.