Actualizaciones y versiones
Orden correcto para actualizar backend, escritorio y móvil, cómo verificar protocolo y contrato, y qué hacer con clientes atrasados.
Actualizar ElVendedor no es instalar tres archivos: backend, escritorio y móvil comparten un protocolo y un contrato de datos. Al terminar esta página sabrás en qué orden actualizar, cómo comprobar que las versiones encajan y cómo sacar a un cliente de un estado bloqueado sin romper sus datos.
Orden recomendado
- Backend primero, sin subir todavía la baseline de app. Publica el contrato, la política y los límites nuevos; los clientes viejos siguen sincronizando.
- Escritorio, que es el hub LAN y quien firma facturas.
- Móvil, que es el que más rápido se propaga entre vendedores y cajeros.
- Cierre: cuando la mayoría de los equipos ya corra la versión nueva,
sube
SYNC_MINIMUM_APP_VERSIONy, si corresponde, enciendeLICENSING_ENFORCE_SYNC_GATE.
Subir la baseline antes de actualizar la flota deja a los clientes viejos con
sync_app_version_too_old, un error no reintentable.
Qué versión se mueve en cada repo
| Repo | Dónde | Cuándo cambia |
|---|---|---|
| Backend | APP_VERSION en .env y .env.example |
Cada release de producto |
| Backend | SYNC_PROTOCOL_VERSION / SYNC_SUPPORTED_PROTOCOL_VERSIONS |
Solo si cambia el protocolo de forma incompatible |
| Backend | SYNC_CONTRACT_VERSION |
Solo con cambios incompatibles de payload |
| Escritorio | package.json → version (hoy 2.1.6) |
Cada release |
| Móvil | package.json → version, versionName |
Cada release |
| Móvil | versionCode |
Cada APK instalado encima |
Los tres repos deben llevar el mismo vX.Y.Z de producto. SYNC_CONTRACT_VERSION
sube en los tres a la vez, y una misma versión de contrato debe significar lo
mismo en todos.
Verificar protocolo y contrato
El cliente móvil y el escritorio declaran SYNC_CONTRACT_VERSION = 1; el
backend lo publica en el bootstrap junto al protocolo:
{
"sync_version": 1,
"contract_version": 1,
"compatibility": {
"policy": "minimum_version",
"enforced": true,
"server_app_version": "2.1.6",
"required_app_version": null,
"minimum_app_version": "2.1.6"
}
}Lectura correcta:
sync_versionfuera deSYNC_SUPPORTED_PROTOCOL_VERSIONS→ nada sincroniza. Hay que actualizar el cliente que quedó atrás.contract_versionmayor que el del cliente → el cliente está viejo (sync_contract_version_too_new); menor → el servidor está viejo (sync_contract_version_too_old). Ambos cortan el sync.compatibility.enforced: falsesignifica que el servidor no valida la versión de app; solo el protocolo.required_app_versionsolo llega conpolicy = same_version.
Comprobación rápida desde el servidor:
php artisan tinker --execute="
\$svc = app(App\Support\Sync\SyncCompatibility::class);
echo 'policy: '.\$svc->appPolicy().PHP_EOL;
echo 'minimum_app_version: '.(\$svc->minimumAppVersion() ?? 'null').PHP_EOL;
echo 'protocol_version: '.\$svc->currentProtocolVersion().PHP_EOL;
"Si un cliente quedó atrás
| Código | Significado | Qué hacer |
|---|---|---|
sync_protocol_version_mismatch |
El cliente habla otro protocolo | Actualizar el cliente |
sync_client_app_version_missing |
No envía X-Client-App-Version |
Cliente muy viejo: actualizar |
sync_app_version_too_old |
Está por debajo de la baseline | Actualizar o bajar la baseline (decisión de producto) |
sync_contract_version_too_new |
Cliente con contrato más nuevo | Actualizar el backend |
business_data_reset_required |
El negocio se limpió en backoffice | El cliente borra datos locales y re-bootstrapea |
Si la actualización del cliente no es posible de inmediato, la vía temporal es
ampliar la política: explicit_list con las versiones que sí pueden sincronizar,
o none mientras se diagnostica. none es un interruptor de desarrollo: no lo
dejes activo en producción. Recuerda regenerar la caché de configuración al
cambiar .env.
Migraciones y ventana de mantenimiento
php artisan migrate --forceAntes de migrar, respalda la base de datos y anota el .env vigente (política,
versiones). La práctica para el cliente, tomada de la guía de instalación, es
actualizar fuera del horario de venta y con la caja del día ya cerrada.
Pendiente de validación
El repositorio no documenta un procedimiento de respaldo de la base ni una
ventana de mantenimiento estándar. Confirma con el Lead qué backup se exige
antes de un migrate en producción y quién autoriza la ventana.
Rollback
- Backend: revierte el despliegue y restaura el
.envanterior (política y versiones); despuésphp artisan config:cachesi usas caché de configuración. - Escritorio: instala la versión anterior encima. No hay actualizaciones automáticas ni servidor de updates, y el perfil local se conserva.
- Móvil: reinstala el APK anterior; el
versionCodedebe poder instalarse (ver Despliegue de la app móvil). - Contrato: si subiste
SYNC_CONTRACT_VERSIONpor error, vuelve atrás y verifica que ningún cliente haya adoptado el contrato nuevo. No reescribas historia ni fuerces push para "deshacer" un release: publica una versión nueva.
Política de versiones soportadas
| Política | Uso |
|---|---|
minimum_version |
Recomendada en producción y staging; no bloquea por parches |
explicit_list |
Rollout por olas o betas concretas |
same_version |
Lockdown puntual; default del config, no de un release normal |
none |
Solo desarrollo |
Bajar la baseline es una decisión de producto explícita, no un ajuste operativo. La matriz de qué versión de cliente habla con qué backend y protocolo está en Compatibilidad.
Siguiente paso
¿Falta algo o encontraste un error?
Ayúdanos a mejorar esta documentación con tu experiencia real.
Escribir a soporte