Compatibilidad de versiones
Qué versión de producto, protocolo y contrato habla cada pieza, qué combinaciones se aceptan y qué política aplica el backend.
Tres números gobiernan la compatibilidad y se confunden con facilidad: la versión de producto (qué app instalaste), el protocolo de sync (cómo se habla) y el contrato de datos (qué forma tienen los payloads). Esta página fija los valores vigentes y qué pasa cuando no coinciden.
Versiones vigentes
| Elemento | Valor vigente | Dónde se declara |
|---|---|---|
| Versión de producto | 2.1.6 |
package.json del móvil y del escritorio; versionName de Android |
| Protocolo de sync | 1 |
SYNC_PROTOCOL_VERSION; cabecera X-Sync-Version |
| Contrato de datos | 1 |
SYNC_CONTRACT_VERSION en servidor; SYNC_CONTRACT_VERSION en ambos clientes |
| Versión de app del backend | 2.1.6 |
APP_VERSION (por defecto, 2.1.6 en .env.example) |
| Política de app | minimum_version |
SYNC_APP_COMPATIBILITY_POLICY |
| Mínimo aceptado | 2.1.6 |
SYNC_MINIMUM_APP_VERSION |
| Formatos de cursor | v2-serial, v3-server-version |
pull_contract.cursor_formats |
El backend no publica una versión de producto propia en su manifiesto: la única
versión que anuncia es APP_VERSION, y es la que compara con la de los clientes.
Cómo se negocia
Protocolo. El cliente envía X-Sync-Version; debe estar en
supported_sync_versions. Si falta o no está soportado, el servidor responde
409 con sync_protocol_version_missing o sync_protocol_version_mismatch. No
es reintentable.
Contrato de datos. El bootstrap anuncia contract_version y el cliente lo
compara con el suyo: si el servidor es mayor, la app está vieja
(sync_contract_version_too_new); si es menor, el servidor está viejo
(sync_contract_version_too_old). Ambos errores los emite el cliente.
Versión de app. Solo se valida si compatibility.enforced es true, según
compatibility.policy.
| Política | Regla | required_app_version |
|---|---|---|
none |
No se comprueba la versión de la app | null |
same_version |
Igual a required_app_version |
se emite |
minimum_version |
Mayor o igual a minimum_app_version |
null |
explicit_list |
Presente en compatible_app_versions |
null |
Compatibilidad con servidores antiguos. Si no viaja policy, el cliente la
infiere de la presencia de required_app_version; si no viaja enforced, asume
true para same_version. Si el servidor no envía contract_version, se asume
1.
Combinaciones
| Combinación | Resultado |
|---|---|
Móvil 2.1.6 + escritorio 2.1.6 + backend APP_VERSION=2.1.6, política minimum_version |
Aceptada: es la configuración de referencia del release |
Cliente anterior al mínimo (minimum_version) |
Bloqueado con sync_app_version_too_old; no reintentable |
| Cliente posterior al mínimo | Aceptado; el servidor no exige igualdad |
| Cliente con protocolo distinto | Bloqueado con sync_protocol_version_mismatch |
| Servidor con contrato mayor que el del cliente | Bloqueado con sync_contract_version_too_new (actualizar la app) |
| Servidor con contrato menor que el del cliente | Bloqueado con sync_contract_version_too_old |
Servidor antiguo sin contract_version ni policy |
Se asume contrato 1 y se infiere la política |
Cliente antiguo sin X-Client-Entities |
El servidor sirve todas las entidades; el cliente registra diagnóstico por las que no aplica |
Pendiente de validación
No hay publicada una matriz histórica de combinaciones intermedias (por ejemplo 2.1.5 con backend 2.1.6). Lo anterior describe el contrato y sus pruebas de compatibilidad, no una certificación de cada par posible. Antes de afirmar que una combinación concreta funciona en producción, valídala con el responsable de release.
Variables del backend
| Variable | Por defecto | Efecto |
|---|---|---|
APP_VERSION |
2.1.6 |
Versión de producto que anuncia el servidor |
SYNC_PROTOCOL_VERSION |
1 |
Protocolo que habla el servidor |
SYNC_SUPPORTED_PROTOCOL_VERSIONS |
1 |
Lista de protocolos aceptados (CSV) |
SYNC_CONTRACT_VERSION |
1 |
Versión del contrato de datos |
SYNC_APP_COMPATIBILITY_POLICY |
minimum_version |
Política de versión de app |
SYNC_MINIMUM_APP_VERSION |
2.1.6 |
Mínimo aceptado con minimum_version |
SYNC_REQUIRED_APP_VERSION |
vacío | Solo se usa con same_version |
SYNC_COMPATIBLE_APP_VERSIONS |
vacío | Lista blanca con explicit_list |
La cadena de respaldo de la versión exigida es
SYNC_REQUIRED_APP_VERSION → SYNC_CURRENT_APP_VERSION → APP_VERSION. Si
ninguna tiene valor, la política no se aplica.
Políticas recomendadas según entorno:
| Entorno | Política | Variable adicional |
|---|---|---|
| Desarrollo | none |
— |
| Staging | minimum_version |
SYNC_MINIMUM_APP_VERSION=<baseline> |
| Producción estable | minimum_version |
SYNC_MINIMUM_APP_VERSION=<baseline> |
| Despliegue gradual | explicit_list |
SYNC_COMPATIBLE_APP_VERSIONS=<lista> |
| Bloqueo estricto | same_version |
SYNC_REQUIRED_APP_VERSION=<exacta> |
Verificar la configuración
php artisan tinker --execute="
\$c = app(App\Support\Sync\SyncCompatibility::class);
echo 'policy: '.\$c->appPolicy().PHP_EOL;
echo 'enforced: '.json_encode(\$c->isAppPolicyEnforced()).PHP_EOL;
echo 'minimum: '.(\$c->minimumAppVersion() ?? 'null').PHP_EOL;
echo 'protocol: '.\$c->currentProtocolVersion().PHP_EOL;
"Después de cambiar variables de entorno, limpia la caché de configuración
(php artisan config:clear en desarrollo, php artisan config:cache en
producción). La respuesta de GET /api/v1/sync/bootstrap muestra el bloque
compatibility efectivo, que es lo que ve el cliente.
Política de soporte
- La versión soportada es la 2.1.6 en móvil y escritorio, contra un backend
con protocolo
1y contrato1. - Subir la versión mínima deja fuera a los equipos que no actualicen: con
minimum_versionel corte es inmediato y no reintentable, así que conviene desplegar la app primero y subir el mínimo después. - Un cambio de forma de payload sube
SYNC_CONTRACT_VERSION; añadir entidades o campos opcionales no la sube. - Un cambio que rompe el protocolo sube
SYNC_PROTOCOL_VERSIONy, si hay flota antigua, se amplíaSYNC_SUPPORTED_PROTOCOL_VERSIONSdurante la transición.
Pendiente de validación
Los repositorios no publican etiquetas de versión: al día de esta revisión
git tag no devuelve ninguna en móvil, escritorio ni backend, y el backend no
tiene versión de producto en su manifiesto. Por tanto no se puede responder «qué
backend corresponde a esta app» consultando el repositorio. El checklist de
release de cada repo exige etiquetar y registrar la matriz; hasta que se
publique, la correspondencia se valida a mano con el equipo de release.
Siguiente paso
- Contrato formal de datos: Contrato de sincronización v1.
- Operación del día a día: Sincronización en producción.
- Despliegue del servicio: Despliegue del backend.
¿Falta algo o encontraste un error?
Ayúdanos a mejorar esta documentación con tu experiencia real.
Escribir a soporte