📋 Registo de Falhas do Dispositivo

Os dispositivos Freshwater podem relatar falhas de hardware e sensores ao backend da Kropie. O sistema de registo permite que os administradores monitorizem a saúde e o estado operacional dos seus dispositivos de forma centralizada.

---

Para Desenvolvedores de Dispositivos

Se está a desenvolver firmware para dispositivos Freshwater, pode incluir um campo log opcional no payload do seu dispositivo:

Exemplo de Payload com Registo de Falha:

{
  "uuid": "seu-uuid-dispositivo",
  "key": "sua-chave-dispositivo",
  "sensor_data": {
    "temperature": 22.5,
    "humidity": 65.3,
    "pressure": 1013.25
  },
  "log": "Timeout ao ler sensor após 5 segundos"
}

Campos do Payload:

Campo	Tipo	Obrigatório	Descrição
uuid	string	Sim	Identificador único do dispositivo
key	string	Sim	Chave de autenticação do dispositivo
sensor_data	object	Sim	Leituras do sensor
log	string	Não	Mensagem de erro ou aviso do dispositivo

Exemplos de Mensagens de Registo:

• "Sensor read timeout after 5 seconds"
• "Battery voltage low: 2.8V"
• "Wi-Fi connection failed, retrying..."
• "Temperature sensor CRC error"
• "Insufficient memory to upload full dataset"

---

Para Administradores

Visualizar Registos de Dispositivos

Aceda aos registos de falhas de um dispositivo através do painel de administração:

URL: /admin/devices/{device-uuid}/logs

Exemplo:

https://seu-dominio.com/admin/devices/550e8400-e29b-41d4-a716-446655440000/logs

Informações Armazenadas

Cada registo de falha inclui as seguintes informações:

Campo	Descrição
Data/Hora	Timestamp do momento em que a falha foi reportada (formato ISO 8601 em UTC)
Mensagem	Descrição do erro ou aviso reportado pelo dispositivo
Tipo de Dispositivo	Modelo ou tipo de dispositivo (ex: Freshwater v1, Freshwater v2)
UUID do Dispositivo	Identificador único do dispositivo

Ciclo de Vida dos Registos

• Os registos são armazenados indefinidamente no sistema
• Todos os registos históricos estão disponíveis para análise
• Os registos nunca são eliminados automaticamente
• Pode consultar registos antigos para identificar padrões de falha

Padrões Comuns para Investigação

Quando investigar problemas com dispositivos, procure por:

1. Padrões Temporais - Falhas que ocorrem à mesma hora do dia
2. Falhas Recorrentes - O mesmo erro repetem-se frequentemente
3. Degradação Gradual - Aumenta a frequência de erros ao longo do tempo
4. Eventos de Hardware - Falhas súbitas que podem indicar dano físico

---

Próximos Passos

Se um dispositivo está a reportar falhas frequentes:

1. Consulte o Registo de Falhas no painel de administração
2. Identifique o Padrão - É recorrente? Intermitente? Crescente?
3. Execute Manutenção - Veja a secção Manutenção para procedimentos de limpeza e calibração
4. Reinicie o Dispositivo - Se for software, um reinício pode resolver falhas temporárias
5. Contacte o Suporte - Se o problema persistir, envie um email para [email protected] com os detalhes do dispositivo e um resumo dos registos de falha

---

Exemplo de Resposta da API

Quando consulta os registos através da API ou painel, receberá uma resposta estruturada:

{
  "data": [
    {
      "id": 1,
      "device_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "message": "Temperature sensor timeout",
      "created_at": "2025-04-22T14:35:00Z"
    },
    {
      "id": 2,
      "device_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "message": "Battery voltage low: 2.8V",
      "created_at": "2025-04-21T08:15:30Z"
    }
  ],
  "pagination": {
    "total": 47,
    "per_page": 50,
    "page": 1
  }
}

---

Dicas de Boas Práticas

• Mensagens Claras - Use mensagens de erro descritivas que facilitam a diagnóstico
• Contexto Relevante - Inclua valores (ex: "Battery: 2.8V" em vez de apenas "Battery low")
• Não Sobrecarregue - Evite registar mensagens triviais a cada leitura
• Timestamps Precisos - Certifique-se de que o dispositivo tem a hora sincronizada
• Testar em Desenvolvimento - Valide o formato do payload antes de implementar em produção