Relatórios de Presença

Três relatórios voltados para identificar padrões problemáticos de frequência dos alunos ao longo do tempo. Cada relatório retorna uma lista de alunos ordenada pela métrica principal.

:::info
Todos os endpoints operam no contexto de uma unidade e consideram apenas matrículas ativas.
:::

Endpoints

Método	Rota	Scope	Descrição
GET	`/v1/reports/most-absences`	`reports:read`	Quem anda faltando? — alunos com mais ausências no período
GET	`/v1/reports/most-late`	`reports:read`	Quem anda chegando atrasado? — atrasos em entradas
GET	`/v1/reports/most-early-exits`	`reports:read`	Quem anda saindo adiantado? — saídas antes do horário

GET /v1/reports/most-absences

Lista alunos com mais ausências no período. Considera o total de aulas agendadas e o total de presenças de entrada; a diferença é a quantidade de faltas.

Parâmetros (query)

Param	Tipo	Default	Descrição
`period`	number	`30`	Janela em dias retroativos. Aceita `7`, `14`, `30`, `60`, `90`, `180`, `365`.
`shift`	`MORNING` \| `AFTERNOON` \| `NIGHT`	—	Filtra por turno.
`search`	string	—	Busca por nome ou email.
`minAbsences`	number	`max(1, round(period*2/7))`	Mínimo de faltas para o aluno aparecer. Default ≈ 2 ocorrências por semana.
`page`	number	`1`
`limit`	number	`30`	Max 100.

Exemplo

curl "https://api.gdredu.com/v1/reports/most-absences?period=30&minAbsences=5" \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "x-branch-id: 770e8400-e29b-41d4-a716-446655440000"

Resposta (200)

{
  "students": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "João da Silva",
      "email": "[email protected]",
      "gradeName": "1º Ano EM",
      "className": "Turma 1A",
      "scheduledOccurrences": 22,
      "entries": 15,
      "absences": 7,
      "attendanceRate": 68.18
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 30,
    "total": 12,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

Campo	Descrição
`scheduledOccurrences`	Aulas esperadas no período.
`entries`	Total de entradas registradas.
`absences`	`max(0, scheduledOccurrences - entries)`.
`attendanceRate`	`entries / scheduledOccurrences * 100`.

Ordenação: absences DESC.

GET /v1/reports/most-late

Lista alunos com mais atrasos de entrada no período. Atraso = entrada registrada depois do horário previsto de início da aula.

Parâmetros (query)

Param	Tipo	Default	Descrição
`period`	number	`30`	Janela em dias.
`shift`	`MORNING` \| `AFTERNOON` \| `NIGHT`	—	Filtra por turno.
`search`	string	—	Busca por nome ou email.
`minLate`	number	`max(1, round(period*2/7))`	Mínimo de atrasos.
`page`	number	`1`
`limit`	number	`30`	Max 100.

Resposta (200)

{
  "students": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "Maria Oliveira",
      "email": "[email protected]",
      "gradeName": "2º Ano EM",
      "className": "Turma 2B",
      "lateArrivals": 8,
      "averageDelayMinutes": 12,
      "entries": 18,
      "scheduledOccurrences": 22,
      "attendanceRate": 81.82
    }
  ],
  "pagination": { "page": 1, "limit": 30, "total": 5, "totalPages": 1, "hasNext": false, "hasPrev": false }
}

Campo	Descrição
`lateArrivals`	Quantas entradas atrasadas.
`averageDelayMinutes`	Média dos atrasos em minutos (arredondado).

Ordenação: lateArrivals DESC.

GET /v1/reports/most-early-exits

Lista alunos com mais saídas adiantadas no período. Saída adiantada = saída registrada antes do horário previsto de fim da aula.

Parâmetros (query)

Param	Tipo	Default	Descrição
`period`	number	`30`	Janela em dias.
`shift`	`MORNING` \| `AFTERNOON` \| `NIGHT`	—	Filtra por turno.
`search`	string	—	Busca por nome ou email.
`minEarlyExits`	number	`max(1, round(period*2/7))`	Mínimo de saídas adiantadas.
`page`	number	`1`
`limit`	number	`30`	Max 100.

Resposta (200)

{
  "students": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "Carlos Souza",
      "email": "[email protected]",
      "gradeName": "9º Ano",
      "className": "Turma 9A",
      "earlyExits": 6,
      "averageAdvanceMinutes": 18,
      "exits": 18,
      "scheduledOccurrences": 22,
      "exitRate": 81.82
    }
  ],
  "pagination": { "page": 1, "limit": 30, "total": 3, "totalPages": 1, "hasNext": false, "hasPrev": false }
}

Campo	Descrição
`earlyExits`	Quantas saídas adiantadas.
`averageAdvanceMinutes`	Média de quanto antes (em minutos, arredondado).
`exitRate`	`exits / scheduledOccurrences * 100`.

Ordenação: earlyExits DESC, averageAdvanceMinutes DESC.

Conceitos importantes

Mínimo padrão

O valor padrão de minAbsences/minLate/minEarlyExits é calculado como Math.max(1, round(period*2/7)) — basicamente, ~2 ocorrências por semana. Por exemplo:

`period`	`min<X>` default
`7`	`2`
`14`	`4`
`30`	`9`
`60`	`17`
`90`	`26`

Isso filtra alunos com baixo ruído de sinal. Ajuste manualmente se necessário (ex: minAbsences=1 para ver todos).

Tolerância de pontualidade

A classificação de atraso/saída adiantada usa a tolerância padrão de 15 minutos. Esse valor pode ser configurado por turma.