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.
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_idde la petición fallida: el backend lo devuelve enmeta.request_idde toda respuesta JSON.- Código de error real (
error.code), estado HTTP, hora exacta con zona horaria y eldevice_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.logBusca el request_id del cliente en el archivo o en las respuestas:
grep -n "<request_id>" storage/logs/laravel.log | tail -n 20Comprueba 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
- Nombre del negocio y
device_iddel equipo afectado. - Versión de la app y sistema operativo del equipo.
- Captura o texto del mensaje de error, con hora.
- Reporte de diagnóstico exportado (escritorio) o pantalla de sync (móvil).
- ¿Solo un equipo o todos? ¿Desde cuándo?
- ¿Cambió algo: actualización, red, router, permisos, licencia?
- 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
¿Falta algo o encontraste un error?
Ayúdanos a mejorar esta documentación con tu experiencia real.
Escribir a soporte