Control de versiones de la app

Los administradores pueden configurar la versión mínima soportada y la más reciente de las apps de iOS/Android desde /system/app-versions, y cada cliente (iOS, Android — la web no tiene un concepto de control de versión) puede consultar al iniciar si debe forzar una actualización o mostrar un aviso opcional de "actualización disponible".

Esto se construyó sobre iosAppVersion/androidAppVersion/webAppVersion/minSupportedIosVersion/minSupportedAndroidVersion/iosStoreLink/androidStoreLink — columnas que existen en SystemSetting desde la primera migración (20220111010310-create-config-app.js) pero que nunca se habían expuesto en GraphQL ni las leía ningún manager hasta ahora. No se necesitaron columnas nuevas en la base de datos.

Checklist de implementación

Configuración de administrador (/system/app-versions, requiere MANAGE_APP_VERSIONS)

• Ver los umbrales actuales para ambas plataformas (adminGetAppVersionSettings)
• Actualizar uno o más umbrales — solo se cambian los campos proporcionados (adminUpdateAppVersionSettings), cubriendo por plataforma (iOS/Android):
  • la versión más reciente disponible (aviso opcional de "actualización disponible", no obligatorio)
  • la versión mínima soportada (por debajo de esta, checkAppVersion reporta forceUpdate: true)
  • el enlace de la tienda que se muestra a un usuario que debe/debería actualizar
  • además de un campo webAppVersion solo informativo (la app web no tiene control de versión hoy)

Verificación de cliente al iniciar (sin autenticación)

• checkAppVersion(platform: AppPlatform!, currentVersion: String!) — compara la versión reportada por la app que llama contra los umbrales configurados y devuelve {forceUpdate, updateAvailable, latestVersion, minSupportedVersion, storeLink}. La comparación de versiones es numérica por segmento separado por puntos (2.9 < 2.10), no una comparación de texto plano — ver apps/backend/utils/semver.util.js. Devuelve forceUpdate: false, updateAvailable: false cuando aún no se ha configurado ningún umbral para esa plataforma (instalación nueva), en lugar de lanzar un error.

apps/ios todavía no está conectado para llamar a esto — eso es una tarea futura separada, deliberadamente fuera de alcance por ahora. La query ya existe de punta a punta específicamente para que esté lista cuando comience ese trabajo: packages/apollo-swift (el paquete de codegen de Swift para iOS) ya lee su schema/operaciones de los mismos archivos que apollo-web (packages/graphql/schema/schema.web.graphqls + packages/graphql/operations/Web/**/*.graphql), así que checkAppVersion — definida una sola vez en packages/graphql/operations/Web/AppVersion/CheckAppVersion.graphql — ya es recogida por ambos. Ver CLAUDE.md para la regla permanente que esto establece: las futuras queries/mutations pensadas para iOS/Android deben agregarse a packages/graphql/operations/Web/ (el schema de cliente compartido) incluso antes de tocar apps/ios en sí, para que el contrato de backend esté listo antes del trabajo real de integración móvil.

Dónde vive esto

Backend

• apps/backend/graphql/types/app-version.type.js — schema de checkAppVersion de cara al cliente (enum AppPlatform, tipo AppVersionStatus)
• apps/backend/graphql/types/admin/app-version-admin.type.js — schema de configuración de administrador
• apps/backend/graphql/resolvers/app-version.resolver.js / graphql/resolvers/admin/app-version-admin.resolver.js
• apps/backend/managers/app-version.manager.js — un solo manager respalda tanto el editor de administrador como la verificación de cliente (la misma fila de SystemSetting)
• apps/backend/data-access-services/admin/app-version-settings.access-service.js — lectura/escritura de la fila singleton, mismo patrón que payout-settings.access-service.js
• apps/backend/utils/semver.util.js — comparador numérico de versiones separadas por puntos (no existe la dependencia npm semver en este código)

Frontend — apps/frontend-admin/src/app/system/app-versions/page.tsx + AppVersionsContent.tsx. Entrada de navegación protegida por el permiso MANAGE_APP_VERSIONS (o super_admin), el mismo patrón que la sección de Pagos protegida por MANAGE_PAYOUTS.

Permiso — MANAGE_APP_VERSIONS, agregado al catálogo real de permisos en admin-user.manager.js#getAdminPermissions junto a MANAGE_PAYOUTS/MANAGE_PROMOTIONS.

Referencia técnica de GraphQL

# Administrador (requiere MANAGE_APP_VERSIONS)
query AppVersionSettings {
  adminGetAppVersionSettings {
    id iosAppVersion androidAppVersion webAppVersion
    minSupportedIosVersion minSupportedAndroidVersion
    iosStoreLink androidStoreLink
  }
}

mutation UpdateAppVersionSettings($input: AppVersionSettingsInput!) {
  adminUpdateAppVersionSettings(input: $input) { id iosAppVersion minSupportedIosVersion }
}

# Cliente (sin autenticación - verificación al iniciar en iOS/Android; aún no se llama desde ningún lado)
query CheckAppVersion($platform: AppPlatform!, $currentVersion: String!) {
  checkAppVersion(platform: $platform, currentVersion: $currentVersion) {
    forceUpdate updateAvailable latestVersion minSupportedVersion storeLink
  }
}