# 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.

Source: https://developers.backresto.com/pt/docs/temperatures

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 | Scope | 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](https://developers.backresto.com/pt/docs/facilities), 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 snapshot](https://developers.backresto.com/pt/docs/collections): `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](https://developers.backresto.com/pt/docs/facilities) 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. |

```json
{
  "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](https://developers.backresto.com/pt/docs/facilities), 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`](https://developers.backresto.com/pt/docs/facilities), 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](https://developers.backresto.com/pt/docs/facilities).

| 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 dá problemas: 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:

- **Faça os relatórios por `capturedAt`, sincronize 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](https://developers.backresto.com/pt/docs/collections) 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](https://developers.backresto.com/pt/docs/support).