Temperaturas

Temperaturas de frio e de confeção, medidas por uma pessoa ou comunicadas por um sensor — três coleções, e o que as distingue.

A temperatura é a medição de que depende uma inspeção de segurança alimentar, e a aplicação regista-a de três maneiras. Parecem-se umas com as outras e significam coisas diferentes, por isso vale a pena acertar na distinção antes de construir o que quer que seja sobre qualquer uma delas.

Coleção	Âmbito	Quem fez a medição
`temperature-records`	`temperature-records:read`	Uma pessoa, num frigorífico ou num congelador, durante um turno identificado.
`temperature-readings`	`temperature-readings:read`	Um sensor, sozinho, sem ninguém presente.
`cooking-temperature-records`	`cooking-temperature-records:read`	Uma pessoa, num equipamento de confeção — um forno, um armário de manutenção a quente.

As três partilham o envelope de instantâneo: id, deleted, capturedAt, receivedAt, sequence e os restantes ficam ao lado do data descrito abaixo.

`temperature-records`

Um controlo manual feito num equipamento de cadeia de frio. Um registo por leitura, por equipamento, por turno.

Campo	Tipo	Significado
`timestamp`	string, obrigatório	Quando a leitura foi feita, em milissegundos desde a época Unix, em forma de cadeia de caracteres.
`value`	number, obrigatório	A temperatura em si.
`unit`	string, obrigatório	`CELSIUS` em todos os registos que vimos. Leia-o em vez de o assumir.
`shift`	string, obrigatório	O serviço a que pertence — `MORNING`, `EVENING`. Em maiúsculas.
`equipmentId`	string, obrigatório	O equipamento medido.
`correctiveActions`	string[]	O que foi feito quando a leitura estava fora do intervalo. Vazio quando não foi preciso nada.
`userId`	string \| null	O funcionário que a fez, quando a aplicação registou um.

{
  "id": "48a30f0b-ccc0-4d18-8404-525b16ecaaa6",
  "collection": "temperature-records",
  "deleted": false,
  "capturedAt": "1789772570338",
  "receivedAt": "1789772802108",
  "sequence": "1",
  "data": {
    "timestamp": "1789768800000",
    "value": -14.4,
    "unit": "CELSIUS",
    "shift": "MORNING",
    "equipmentId": "84ce5c13-3237-40d4-901a-cbba59a6406f",
    "userId": "2774953d-8d9b-4a68-8ec4-1209edd90777"
  }
}

value é uma leitura, não um veredito. Nada no registo diz se ela era aceitável: isso depende do min e do max do equipamento, que tem de ler à parte e que o restaurante pode alterar. Um registo feito a -14,4 °C é um problema num frigorífico e é normal num congelador.

correctiveActions é texto livre, escrito durante o serviço na língua do restaurante. Conte-o se quiser; não construa uma enumeração a partir dele.

`temperature-readings`

A mesma medição, comunicada por uma sonda sem fios em vez de por uma pessoa. O mesmo formato, menos os dois campos que só fazem sentido quando houve um humano envolvido: não há shift nem userId.

Campo	Tipo	Significado
`timestamp`	string, obrigatório	Quando o sensor comunicou, em milissegundos desde a época Unix, em forma de cadeia de caracteres.
`value`	number, obrigatório	A temperatura.
`unit`	string, obrigatório	Como acima.
`equipmentId`	string, obrigatório	O equipamento que o sensor vigia.
`correctiveActions`	string[]	Preenchido depois, por uma pessoa, quando se atuou sobre um alerta.

Estes chegam ao ritmo do próprio sensor, por isso um restaurante movimentado produz muitos mais destes do que de registos manuais — dimensione as suas consultas periódicas para o volume, e não para o número de pessoas.

Qual foi o sensor que comunicou não está na leitura. A ligação vive na coleção sensors, cujo sensorEquipmentId aponta de volta para o equipamento — atenção ao nome, não é equipmentId.

`cooking-temperature-records`

Uma pessoa a medir um equipamento de confeção em vez de um de frio. Idêntico a temperature-records, exceto que aponta para equipamento de confeção.

Campo	Tipo	Significado
`timestamp`	string, obrigatório	Quando a leitura foi feita.
`value`	number, obrigatório	A temperatura.
`unit`	string, obrigatório	Como acima.
`shift`	string, obrigatório	O serviço a que pertence.
`cookingEquipmentId`	string, obrigatório	O equipamento de confeção medido — não `equipmentId`.
`correctiveActions`	string[]	O que foi feito a respeito de uma leitura fora do intervalo.
`userId`	string \| null	Quem a fez.

O nome do campo é a única diferença que morde: um cliente que leia aqui equipmentId recebe undefined, em silêncio, e um gráfico sem equipamento nenhum.

Ler as três em conjunto

Um painel que responda a «este frigorífico esteve dentro do intervalo hoje» quer temperature-records e temperature-readings reunidos pelo equipmentId, com os limiares vindos de equipment. Três percursos, unidos do seu lado — não há endpoint que o faça por si.

Duas coisas a implementar desde o início:

Ordene por capturedAt, não por receivedAt. Um tablet numa câmara frigorífica carrega quando encontra sinal, por isso o registo de uma leitura das 09:00 pode chegar às 14:00. A página do envelope conta a história toda.
A ausência não prova nada. Uma leitura em falta pode significar que o controlo foi saltado, ou que o dispositivo ainda não a carregou. Não produza uma taxa de execução a partir desta API e lhe chame conformidade — veja a nota de aviso.