ElVendedorDocs

Diagnóstico y soporte técnico

Método para aislar un incidente entre cliente, backend, red y licencia; qué logs leer, qué comandos ejecutar y qué evidencia pedir antes de escalar.

Para implementadores5 min de lecturaActualizado el 16 de noviembre de 2026

El error que reporta un cliente casi nunca es el problema: «no sincroniza» puede ser una licencia vencida, un token de otro negocio o un puerto cerrado. Este método ordena la investigación para que no reinicies cosas al azar ni pidas datos que no necesitas.

1. Identificar la pieza

Síntoma Pieza probable Primera prueba
La app no abre o pierde datos locales Cliente Revisa el equipo, el espacio en disco y la versión instalada.
Falla solo en un equipo Cliente o red de ese equipo Compara con otro equipo del mismo negocio.
Falla en todos los equipos del negocio Backend, licencia o cuenta Prueba el bootstrap con un token del negocio.
Falla en todos los negocios Backend o infraestructura Comprueba /up y los logs del servidor.
Solo en el restaurante Red local o hub Prueba GET /api/restaurant/hub/health.
Todo funciona pero no sube nada Licencia o permisos Lee el último error.code del cliente.

2. Recoger versión y evidencias

Sin versiones no hay diagnóstico. Pide siempre:

  • Versión de app del cliente (app_version), versión de protocolo (sync_version) y versión de contrato (contract_version).
  • request_id de la petición fallida: el backend lo devuelve en meta.request_id de toda respuesta JSON.
  • Código de error real (error.code), estado HTTP, hora exacta con zona horaria y el device_id.
  • El estado de licencia que muestra el cliente (status, is_usable, days_remaining, blocked).

En escritorio, la vista de sincronización exporta el reporte de diagnóstico a JSON (last_attempt_at, last_success_at, last_result, last_error_code, last_http_status, last_pushed_count, last_pulled_count, outbox_issues y el bloque license). Ese archivo es la mejor evidencia inicial.

3. Logs y comandos del backend

El backend registra en storage/logs/laravel.log (LOG_CHANNEL=stack, pila single). Sigue el archivo mientras reproduces el fallo:

cd /ruta/al/el-vendedor-back
tail -f storage/logs/laravel.log

Busca el request_id del cliente en el archivo o en las respuestas:

grep -n "<request_id>" storage/logs/laravel.log | tail -n 20

Comprueba la configuración de compatibilidad activa antes de culpar al cliente:

php artisan tinker --execute="
  \$svc = app(App\Support\Sync\SyncCompatibility::class);
  echo 'policy: '.\$svc->appPolicy().PHP_EOL;
  echo 'enforced: '.json_encode(\$svc->isAppPolicyEnforced()).PHP_EOL;
  echo 'required: '.(\$svc->requiredAppVersion() ?? 'null').PHP_EOL;
  echo 'minimum: '.(\$svc->minimumAppVersion() ?? 'null').PHP_EOL;
  echo 'protocol: '.\$svc->currentProtocolVersion().PHP_EOL;
"

Si el problema es de datos y no de red, revisa los eventos estancados del negocio: GET /api/v1/sync/failed-events devuelve total_failed y el desglose per_entity; el reproceso es potestad del dueño.

Después de cambiar `.env`

php artisan config:cache. Un config:clear olvidado explica más «cambios que no aplican» de los que admite cualquier informe.

4. Logs del cliente y de Electron

  • Escritorio: usa el reporte de diagnóstico de la vista de sincronización. Es la fuente más fiable porque incluye versiones, contadores y el motivo real del último fallo.
  • Si el usuario reporta que la ventana se cierra o no arranca, pide la salida de la consola del proceso y la versión exacta del instalador.

Pendiente de validación

  • El repositorio del escritorio no documenta una ruta de archivo de log de Electron ni un comando de recolección. Confirma con el equipo de escritorio dónde quedan los logs de producción antes de pedirlos al cliente; mientras tanto, usa el reporte de la vista de sync.

5. Pruebas de conectividad

# Salud del backend
curl -s -o /dev/null -w "%{http_code}\n" https://mi-servidor.example/up

# Bootstrap con el token del negocio
curl -s https://mi-servidor.example/api/v1/sync/bootstrap \
  -H "Authorization: Bearer <token>" \
  -H "X-Sync-Version: 1" \
  -H "X-Client-App-Version: 2.1.6"

Interpretación rápida: 401/403 es token o ability; 409 con code de versión es política de compatibilidad; 409 con business_data_reset_required es reset de negocio; 200 con datos correctos deja el problema del lado del cliente o de su red. Si /up falla, el incidente es de infraestructura y no se resuelve desde el negocio.

6. Checklist de datos a pedir

  1. Nombre del negocio y device_id del equipo afectado.
  2. Versión de la app y sistema operativo del equipo.
  3. Captura o texto del mensaje de error, con hora.
  4. Reporte de diagnóstico exportado (escritorio) o pantalla de sync (móvil).
  5. ¿Solo un equipo o todos? ¿Desde cuándo?
  6. ¿Cambió algo: actualización, red, router, permisos, licencia?
  7. Estado de licencia que muestra el cliente.

7. Escalar con evidencia

Un ticket escalado sin evidencia vuelve. Incluye: versiones de app, protocolo y contrato; request_id; código de error y estado HTTP; el fragmento del log con la traza; los pasos exactos para reproducirlo; y qué probaste ya. Si tocaste el servidor (gate de licencia, política de compatibilidad, caché de configuración), dilo explícitamente.

Incidentes frecuentes

Síntoma Causa Solución
Push 409, sync_protocol_version_missing Cliente viejo que no envía X-Sync-Version. Actualiza la app.
Push 409, sync_app_version_too_old Política minimum_version y cliente por debajo del mínimo. Actualiza o sube la política con criterio.
Push 403, license_invalid Licencia no vigente y gate encendido. Renueva en backoffice; apaga el gate si es masivo.
Rechazos retryable: false repetidos Dato inválido: código duplicado, número repetido, permiso. Corrige el dato; el reintento no lo arregla.
409 business_data_reset_required El negocio se limpió en el servidor. Borra datos locales y outbox, y relanza bootstrap.
El equipo sincroniza pero no ve datos de otro Entidad fuera de X-Client-Entities o filtro de capacidad. Revisa la matriz por cliente y fuerza un pull.
Escritorio en «solo-local» Licencia no usable o bootstrap fallido. Revisa license y el bootstrap antes de tocar datos.
Comandas que no llegan POS o posId distinto, o red del local. Compara configuración del hub y del móvil.

Siguiente paso

↑↓ para navegar · Enter para abrir · Esc para cerrar