📋 API de Chamadas - Documentação Completa

Sistema completo de gerenciamento de chamadas de alunos
Registro, consulta e controle de presença de alunos em aulas com suporte a justificativas, rascunhos e níveis hierárquicos

📋 Visão Geral

O que é este sistema?

Um sistema completo de gerenciamento de chamadas de alunos que permite:

• Registro de presença: Ausente (0), Presente (1) ou Justificado (2)
• Justificativas: Campo obrigatório para justificados, opcional para ausentes
• Rascunhos: Permite salvar chamadas como rascunho antes de concluir
• Níveis hierárquicos: Vinculação com instituição, unidade, turma e horário
• Controle de data: Validação de datas conforme permissão do usuário
• Pesquisa avançada: Filtros por data, mês/ano, usuário, presença e nível hierárquico

Por que você precisa disto?

🏗️ Arquitetura

Fluxo de Dados

Controller (ChamadasController)
    ↓
Service (ChamadaService)
    ↓
Repository (ChamadaRepository)
    ↓
Database (AdminDbContext → Tabela Chamadas)

Componentes Principais

• ChamadasController: Endpoints REST para operações CRUD
• ChamadaService: Lógica de negócio e validações
• ChamadaRepository: Acesso a dados e queries
• Chamada (Entity): Entidade de domínio
• DTOs: Objetos de transferência de dados (Request/Response)

🔧 Componentes

Controller: ChamadasController

Responsável por:

• Receber requisições HTTP
• Validar autenticação e autorização
• Chamar o Service apropriado
• Retornar respostas HTTP padronizadas

Service: ChamadaService

Responsável por:

• Validações de negócio (data, justificativa, duplicidade)
• Controle de permissões (Professor vs Admin Global)
• Orquestração de operações
• Tratamento de erros e logging

Repository: ChamadaRepository

Responsável por:

• Queries otimizadas no banco de dados
• Filtros dinâmicos e paginação
• Validação de duplicidade

Entidade: Chamada

Estrutura da entidade:

• Id: Identificador único (int, auto-incremento)
• ChamadaId: ID que agrupa múltiplos registros criados no mesmo POST (int, gerado por sequence thread-safe)
• UsuarioId: ID do aluno (string, 450 caracteres)
• Presenca: Status (int: 0=Ausente, 1=Presente, 2=Justificado)
• Justificativa: Texto opcional (string, 200 caracteres)
• NivelHierarquico: JSON com níveis (instituicaoId, unidadeId, turmaId, horarioId)
• DataChamada: Data da chamada (DATE)
• Rascunho: Indica se é rascunho (bool, default: true)
• Ativo: Indica se está ativo (bool, default: true)
• Campos de auditoria: UsuarioCriacao, Criacao, UsuarioAtualizacao, Atualizacao

🌐 Endpoints

GET /api/Chamadas

Descrição: Pesquisa chamadas com filtros e paginação. Retorna dados agrupados por ChamadaId, onde cada grupo contém arrays de informações (id, usuario, presenca, justificativa) e campos fixos compartilhados (rascunho, ativo, dataChamada, nivelHierarquico, campos de auditoria).

Observação: A paginação conta grupos únicos (ChamadaId), não registros individuais. Todos os registros do mesmo ChamadaId compartilham os mesmos valores de campos fixos.

Comportamento Padrão: Por padrão, o endpoint retorna apenas chamadas ativas (Ativo=true). Para visualizar chamadas inativas, passe explicitamente o parâmetro Ativo=false na query string.

Parâmetros de Query:

Resposta (200 OK):

{
  "data": [
    {
      "chamadaId": 5,
      "id": [1, 2, 3],
      "usuario": ["user123", "user456", "user789"],
      "presenca": [1, 0, 2],
      "justificativa": [null, null, "Faltou por motivo médico"],
      "rascunho": false,
      "ativo": true,
      "dataChamada": "2026-01-06",
      "nivelHierarquico": {
        "horarioId": [1]
      },
      "criacao": "2026-01-06T10:00:00",
      "atualizacao": "2026-01-06T10:05:00",
      "usuarioCriacao": "prof123",
      "usuarioAtualizacao": "prof123"
    },
    {
      "chamadaId": 6,
      "id": [4, 5],
      "usuario": ["user111", "user222"],
      "presenca": [1, 1],
      "justificativa": [null, null],
      "rascunho": true,
      "ativo": true,
      "dataChamada": "2026-01-07",
      "nivelHierarquico": {
        "turmaId": [2]
      },
      "criacao": "2026-01-07T08:00:00",
      "atualizacao": null,
      "usuarioCriacao": "prof456",
      "usuarioAtualizacao": null
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalPages": 1,
    "totalRecords": 2,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

Estrutura do Response Agrupado:

• chamadaId: ID que agrupa múltiplos registros criados no mesmo POST
• id: Array de IDs dos registros individuais
• usuario: Array de IDs de usuários (alunos)
• presenca: Array de status de presença (0=Ausente, 1=Presente, 2=Justificado)
• justificativa: Array de justificativas (pode conter null)
• rascunho: Status de rascunho compartilhado entre todos os registros do grupo
• ativo: Status ativo compartilhado entre todos os registros do grupo
• dataChamada: Data da chamada compartilhada entre todos os registros do grupo
• nivelHierarquico: Nível hierárquico compartilhado entre todos os registros do grupo
• Campos de auditoria (criacao, atualizacao, usuarioCriacao, usuarioAtualizacao) compartilhados entre todos os registros do grupo

Importante: A paginação conta grupos únicos (ChamadaId), não registros individuais. O campo totalRecords representa o número de grupos, não o número total de registros.

GET /api/Chamadas/{id}

Descrição: Obtém uma chamada por ID

Parâmetros:

• id (path): ID da chamada (int)

Resposta (200 OK): Objeto ChamadaResponse

{
  "id": 1,
  "chamadaId": 5,
  "usuarioId": "user123",
  "presenca": 1,
  "justificativa": null,
  "ativo": true,
  "dataChamada": "2026-01-06",
  "rascunho": false,
  "nivelHierarquico": {
    "horarioId": [1]
  },
  "criacao": "2026-01-06T10:00:00",
  "atualizacao": null,
  "usuarioCriacao": "prof123",
  "usuarioAtualizacao": null
}

Resposta (404 Not Found): "Chamada não encontrada"

POST /api/Chamadas

Descrição: Cria uma ou múltiplas chamadas em lote (processamento em lote). O processamento é totalmente atômico: se qualquer registro falhar na validação, nenhum registro será criado e o erro específico do usuário que falhou será retornado.

Atomicidade: Todas as chamadas são validadas antes de qualquer criação. Se qualquer validação falhar, a operação é abortada imediatamente e nenhuma chamada é criada. Se todas as validações passarem, todas as chamadas são criadas dentro de uma transação única, garantindo que ou todas são criadas ou nenhuma é criada.

Body (JSON):

{
  "usuarioIds": ["user123", "user456", "user789"],
  "presenca": [1, 0, 2],
  "justificativa": [null, null, "Atestado médico"],
  "dataChamada": "2026-01-06",
  "rascunho": false,
  "nivelHierarquico": {
    "horarioId": [1]
  }
}

Resposta (201 Created): Objeto CriarChamadasResponse quando todas as chamadas foram criadas com sucesso

{
  "sucessos": [
    {
      "id": 1,
      "chamadaId": 5,
      "usuarioId": "user123",
      "presenca": 1,
      "justificativa": null,
      "dataChamada": "2026-01-06",
      "rascunho": false,
      "ativo": true,
      "nivelHierarquico": {
        "horarioId": [1]
      }
    },
    {
      "id": 2,
      "chamadaId": 5,
      "usuarioId": "user456",
      "presenca": 0,
      "justificativa": null,
      "dataChamada": "2026-01-06",
      "rascunho": false,
      "ativo": true,
      "nivelHierarquico": {
        "horarioId": [1]
      }
    }
  ],
  "erros": [],
  "totalProcessado": 2,
  "totalSucesso": 2,
  "totalErro": 0
}

Resposta (400 Bad Request): Retornado quando qualquer registro falha na validação. A mensagem de erro indica o usuário específico que falhou e o motivo. Nenhuma chamada é criada quando há erro.

{
  "status": false,
  "message": "Erro ao criar chamada para o usuário user456: A data da chamada não pode ser futura.",
  "data": {
    "sucessos": [],
    "erros": [
      {
        "indice": 1,
        "usuarioId": "user456",
        "mensagem": "A data da chamada não pode ser futura."
      }
    ],
    "totalProcessado": 2,
    "totalSucesso": 0,
    "totalErro": 1
  }
}

Comportamento Atômico: Se qualquer registro falhar na validação, a operação é abortada imediatamente e nenhuma chamada é criada. O erro retornado indica especificamente qual usuário falhou e o motivo. Isso garante integridade dos dados e evita estados inconsistentes.

Nota: Os arrays usuarioIds, presenca e justificativa devem ter o mesmo tamanho. Cada posição dos arrays corresponde a um registro individual na tabela chamadas.

PUT /api/Chamadas/chamadaId/{chamadaId}

Descrição: Atualiza todas as chamadas de um mesmo ChamadaId (processamento em lote). Permite editar todos os registros de um mesmo ChamadaId de uma vez, usando arrays para dados individuais e campos fixos para dados compartilhados.

Parâmetros:

• chamadaId (path): ID do grupo de chamadas (int). Todos os registros com este ChamadaId serão atualizados.

Body (JSON):

{
  "usuarioIds": ["user123", "user456", "user789"],
  "presenca": [1, 0, 2],
  "justificativa": [null, null, "Atestado médico"],
  "rascunho": false,
  "ativo": true,
  "dataChamada": "2026-01-06",
  "nivelHierarquico": {
    "horarioId": [1]
  }
}

Estrutura do Request:

• Arrays (dados individuais de cada registro): usuarioIds[], presenca[], justificativa[]
• Campos fixos (aplicados a todos os registros): rascunho, ativo, dataChamada, nivelHierarquico
• Os arrays devem ter o mesmo tamanho e corresponder à quantidade de registros existentes do ChamadaId

Permissões de Edição:

• Professor:
  • Dentro de 14 dias após a data da chamada (calculado como: data atual - dataChamada ≤ 14 dias): Pode editar rascunhos e chamadas concluídas
  • Após 14 dias da data da chamada: Só pode editar rascunhos (Rascunho = true). Chamadas concluídas não podem ser editadas após este prazo
• Admin Instituição (TipoUsuarioId=8):
  • Pode editar sempre (sem restrições de prazo ou status de rascunho)
  • Deve ter permissão no nível hierárquico da chamada (validação usa engenharia reversa da hierarquia)
  • Pode editar chamadas concluídas e rascunhos, independente da data

Validações:

• Os arrays usuarioIds, presenca e justificativa devem ter o mesmo tamanho
• A quantidade de elementos nos arrays deve corresponder à quantidade de registros existentes do ChamadaId
• Limite máximo de 100 itens por lote (prevenção de DoS)
• Quando Presenca[i] = 1, Justificativa[i] é automaticamente definida como null
• Validação individual de cada registro (data, justificativa, duplicidade)
• Processamento parcial: alguns registros podem ser atualizados com sucesso enquanto outros falham

Resposta (400 Bad Request): Retornado quando:

• ChamadaId não encontrado
• Arrays com tamanhos diferentes
• Quantidade de arrays não corresponde à quantidade de registros existentes
• Professor tenta editar chamada concluída após 14 dias: "Professores podem editar chamadas apenas até 14 dias após a data da chamada. Após este prazo, apenas rascunhos podem ser editados. Para edições após este prazo, contate um administrador da instituição."
• Outras validações de negócio (data futura, justificativa obrigatória, duplicidade, etc.)

Resposta (200 OK): Objeto AtualizarChamadasResponse com sucessos e erros

{
  "sucessos": [
    {
      "id": 1,
      "chamadaId": 5,
      "usuarioId": "user123",
      "presenca": 1,
      "justificativa": null,
      "ativo": true,
      "dataChamada": "2026-01-06",
      "rascunho": false,
      "nivelHierarquico": {
        "horarioId": [1]
      },
      "criacao": "2026-01-06T10:00:00",
      "atualizacao": "2026-01-06T14:30:00",
      "usuarioCriacao": "prof123",
      "usuarioAtualizacao": "prof123"
    },
    {
      "id": 2,
      "chamadaId": 5,
      "usuarioId": "user456",
      "presenca": 0,
      "justificativa": null,
      "ativo": true,
      "dataChamada": "2026-01-06",
      "rascunho": false,
      "nivelHierarquico": {
        "horarioId": [1]
      },
      "criacao": "2026-01-06T10:00:00",
      "atualizacao": "2026-01-06T14:30:00",
      "usuarioCriacao": "prof123",
      "usuarioAtualizacao": "prof123"
    }
  ],
  "erros": [
    {
      "indice": 2,
      "usuarioId": "user789",
      "mensagem": "Justificativa obrigatória para Presenca=2"
    }
  ],
  "totalProcessado": 3,
  "totalSucesso": 2,
  "totalErro": 1
}

Notas Importantes:

• O campo chamadaId não pode ser alterado (preservado automaticamente)
• Os campos id, usuarioCriacao e criacao são preservados (não podem ser alterados)
• Os campos usuarioAtualizacao e atualizacao são atualizados automaticamente
• Diferente do POST que é atômico (tudo ou nada), o PUT permite processamento parcial: alguns registros podem ser atualizados com sucesso enquanto outros falham
• Se todos os registros falharem, retorna erro. Se alguns falharem, retorna sucesso parcial com lista de erros

DELETE /api/Chamadas/chamadaId/{chamadaId}

Descrição: Exclui todas as chamadas de um grupo (soft delete via Ativo=false). Inativa todos os registros com o mesmo ChamadaId, ou seja, todos os registros criados juntos no mesmo POST.

Parâmetros:

• chamadaId (path): ID do grupo de chamadas (int). Todos os registros com este ChamadaId serão inativados.

Nota Importante: Quando você exclui uma chamada usando o ChamadaId, todos os registros que foram criados juntos no mesmo POST serão inativados simultaneamente. Isso garante que o grupo de chamadas seja tratado como uma unidade lógica.

Resposta (200 OK):

{
  "message": "Chamada excluída com sucesso",
  "success": true
}

Resposta (200 OK) - Múltiplos registros:

{
  "message": "3 chamadas excluídas com sucesso",
  "success": true
}

Resposta (404 Not Found): "Chamada não encontrada" - Retornado quando não existe nenhum registro com o ChamadaId informado.

📝 Campos e Validações

CriarChamadaRequest

Validações de Arrays:

• Os arrays UsuarioIds, Presenca e Justificativa devem ter obrigatoriamente o mesmo tamanho
• Os arrays não podem estar vazios (mínimo 1 elemento)
• Cada elemento do array UsuarioIds deve ser válido (não nulo/vazio e máximo 450 caracteres)
• Cada elemento do array Presenca deve ser 0, 1 ou 2
• Cada elemento do array Justificativa deve ter no máximo 200 caracteres (se não for null)

CriarChamadasResponse

ChamadaResponse

ChamadaAgrupadaResponse

DTO de resposta para chamadas agrupadas por ChamadaId. Usado no endpoint GET /api/Chamadas.

ChamadaAgrupadaResponse

DTO de resposta para chamadas agrupadas por ChamadaId. Usado no endpoint GET /api/Chamadas.

Observação: Os campos fixos (rascunho, ativo, dataChamada, nivelHierarquico, campos de auditoria) são compartilhados entre todos os registros do mesmo ChamadaId, pois são criados no mesmo POST. Os arrays (id, usuario, presenca, justificativa) contêm os valores individuais de cada registro do grupo.

ErroChamada

Regras de Validação

Justificativa

• Presenca = 2 (Justificado): Justificativa é obrigatória
• Presenca = 1 (Presente): Justificativa é automaticamente definida como null pelo sistema, mesmo que o usuário envie uma justificativa. O sistema ignora qualquer valor informado e define como null.
• Presenca = 0 (Ausente): Justificativa é opcional
• Tamanho máximo: 200 caracteres

Nota Importante: Quando Presenca=1 (Presente), o sistema automaticamente define Justificativa=null antes de processar a requisição. Isso significa que mesmo que você acidentalmente envie uma justificativa junto com Presenca=1, ela será ignorada e definida como null automaticamente. Não é necessário remover o campo do request, mas ele será ignorado.

Data

• Professor: Não pode criar chamadas para datas futuras
• Professor: Não pode criar chamadas para datas anteriores a 14 dias
• Admin Instituição (TipoUsuarioId=8): Pode criar chamadas para qualquer data (passado ou futuro) se tiver permissão no nível hierárquico da chamada
• A validação de permissão usa engenharia reversa: se a chamada tem HorarioId=27 e o Admin tem permissão apenas para InstituicaoId=2, o sistema verifica se o horário pertence à instituição (Horario → Turma → Unidade → Instituição)
• A verificação é feita na tabela usuariopermissao verificando UsuarioId, TipoUsuarioId=8 e acesso ao nível hierárquico

Duplicidade

• Não é permitido criar chamadas concluídas (Rascunho=false) duplicadas
• Duplicidade é verificada por: UsuarioId + DataChamada + horarioId (do NivelHierarquico)
• Rascunhos podem ser duplicados
• Atomicidade: Se qualquer registro falhar na validação de duplicidade, nenhuma chamada será criada. O erro retornado indicará especificamente qual usuário falhou e o motivo.

💼 Casos de Uso

Caso 1: Registrar Presença em Lote

Cenário: Professor registra presença de múltiplos alunos em uma aula

POST /api/Chamadas
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioIds": ["aluno123", "aluno456", "aluno789"],
  "presenca": [1, 1, 0],
  "justificativa": [null, null, null],
  "dataChamada": "2026-01-06",
  "rascunho": false,
  "nivelHierarquico": {
    "horarioId": [1]
  }
}

Resposta (201 Created):

{
  "sucessos": [
    {
      "id": 1,
      "chamadaId": 5,
      "usuarioId": "aluno123",
      "presenca": 1,
      "justificativa": null,
      "dataChamada": "2026-01-06",
      "rascunho": false,
      "ativo": true
    },
    {
      "id": 2,
      "chamadaId": 5,
      "usuarioId": "aluno456",
      "presenca": 1,
      "justificativa": null,
      "dataChamada": "2026-01-06",
      "rascunho": false,
      "ativo": true
    },
    {
      "id": 3,
      "chamadaId": 5,
      "usuarioId": "aluno789",
      "presenca": 0,
      "justificativa": null,
      "dataChamada": "2026-01-06",
      "rascunho": false,
      "ativo": true
    }
  ],
  "erros": [],
  "totalProcessado": 3,
  "totalSucesso": 3,
  "totalErro": 0
}

Caso 1.1: Registrar Presença Individual (Compatibilidade)

Cenário: Registrar presença de um único aluno (usando array com um elemento)

POST /api/Chamadas
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioIds": ["aluno123"],
  "presenca": [1],
  "justificativa": [null],
  "dataChamada": "2026-01-06",
  "rascunho": false,
  "nivelHierarquico": {
    "horarioId": [1]
  }
}

Caso 2: Registrar Ausências Justificadas em Lote

Cenário: Professor registra ausências justificadas de múltiplos alunos com atestados médicos

POST /api/Chamadas
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioIds": ["aluno123", "aluno456"],
  "presenca": [2, 2],
  "justificativa": [
    "Aluno apresentou atestado médico válido até 10/01/2026",
    "Aluno apresentou atestado médico válido até 12/01/2026"
  ],
  "dataChamada": "2026-01-06",
  "rascunho": false,
  "nivelHierarquico": {
    "horarioId": [1]
  }
}

Caso 2.1: Erro na Validação (Atomicidade Total)

Cenário: Um registro falha na validação - todos os registros são rejeitados (atomicidade total)

POST /api/Chamadas
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioIds": ["aluno123", "aluno456", "aluno789"],
  "presenca": [1, 2, 0],
  "justificativa": [null, "Atestado médico", null],
  "dataChamada": "2026-01-20",
  "rascunho": false,
  "nivelHierarquico": {
    "horarioId": [1]
  }
}

Resposta (400 Bad Request) - Erro na validação (nenhuma chamada criada):

{
  "status": false,
  "message": "Erro ao criar chamada para o usuário aluno456: A data da chamada não pode ser futura. Apenas administradores da instituição com permissão no nível hierárquico podem criar chamadas para datas futuras.",
  "data": {
    "sucessos": [],
    "erros": [
      {
        "indice": 1,
        "usuarioId": "aluno456",
        "mensagem": "A data da chamada não pode ser futura. Apenas administradores da instituição com permissão no nível hierárquico podem criar chamadas para datas futuras."
      }
    ],
    "totalProcessado": 3,
    "totalSucesso": 0,
    "totalErro": 1
  }
}

Comportamento: Como o registro do índice 1 (aluno456) falhou na validação de data futura, a operação foi abortada imediatamente. Nenhuma chamada foi criada, nem mesmo a do aluno123 que estava válida. O sistema retorna o erro específico do usuário que falhou (aluno456) e o motivo da falha.

Caso 3: Erro - Arrays com Tamanhos Diferentes

Cenário: Tentativa de criar chamadas com arrays de tamanhos diferentes (deve falhar)

POST /api/Chamadas
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioIds": ["aluno123", "aluno456"],
  "presenca": [1],
  "justificativa": [null, null],
  "dataChamada": "2026-01-06",
  "rascunho": false,
  "nivelHierarquico": {
    "horarioId": [1]
  }
}

Resposta (400 Bad Request):

{
  "usuarioIds": ["Os arrays UsuarioIds, Presenca e Justificativa devem ter o mesmo tamanho."],
  "presenca": ["Os arrays UsuarioIds, Presenca e Justificativa devem ter o mesmo tamanho."],
  "justificativa": ["Os arrays UsuarioIds, Presenca e Justificativa devem ter o mesmo tamanho."]
}

Caso 4: Pesquisar Chamadas do Mês

Cenário: Buscar todas as chamadas de janeiro de 2026

GET /api/Chamadas?MesAno=01/2026&Pagina=1&TamanhoPagina=20
Authorization: Bearer {token}

Caso 4.1: Buscar Chamadas por ChamadaId

Cenário: Buscar todas as chamadas criadas em uma única operação (mesmo POST)

GET /api/Chamadas?ChamadaId=5
Authorization: Bearer {token}

Resposta: Retorna todos os registros com ChamadaId=5, ou seja, todos os alunos que foram chamados juntos na mesma operação.

Uso: Útil para histórico, auditoria e relatórios de presença por grupo de chamadas.

Caso 5: Salvar Rascunho em Lote

Cenário: Professor salva múltiplas chamadas como rascunho para concluir depois

POST /api/Chamadas
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioIds": ["aluno123", "aluno456", "aluno789"],
  "presenca": [0, 1, 0],
  "justificativa": [null, null, null],
  "dataChamada": "2026-01-06",
  "rascunho": true,
  "nivelHierarquico": {
    "horarioId": [1]
  }
}

Caso 6: Atualizar Chamadas por ChamadaId (Processamento em Lote)

Cenário: Professor atualiza todas as chamadas de um mesmo grupo (ChamadaId) de uma vez

PUT /api/Chamadas/chamadaId/5
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioIds": ["aluno123", "aluno456", "aluno789"],
  "presenca": [1, 0, 2],
  "justificativa": [null, null, "Atestado médico atualizado"],
  "rascunho": false,
  "ativo": true,
  "dataChamada": "2026-01-06",
  "nivelHierarquico": {
    "horarioId": [1]
  }
}

Resposta (200 OK):

{
  "sucessos": [
    {
      "id": 1,
      "chamadaId": 5,
      "usuarioId": "aluno123",
      "presenca": 1,
      "justificativa": null,
      "dataChamada": "2026-01-06",
      "rascunho": false,
      "ativo": true
    },
    {
      "id": 2,
      "chamadaId": 5,
      "usuarioId": "aluno456",
      "presenca": 0,
      "justificativa": null,
      "dataChamada": "2026-01-06",
      "rascunho": false,
      "ativo": true
    },
    {
      "id": 3,
      "chamadaId": 5,
      "usuarioId": "aluno789",
      "presenca": 2,
      "justificativa": "Atestado médico atualizado",
      "dataChamada": "2026-01-06",
      "rascunho": false,
      "ativo": true
    }
  ],
  "erros": [],
  "totalProcessado": 3,
  "totalSucesso": 3,
  "totalErro": 0
}

Nota: Este endpoint permite atualizar todos os registros de um mesmo ChamadaId de uma vez. Os campos fixos (rascunho, ativo, dataChamada, nivelHierarquico) são aplicados a todos os registros, enquanto os arrays (usuarioIds, presenca, justificativa) são aplicados individualmente a cada registro. Diferente do POST que é atômico, o PUT permite processamento parcial: alguns registros podem ser atualizados com sucesso enquanto outros falham.

⚙️ Regras de Negócio

Permissões por Perfil

Criação (POST)

Edição (PUT)

Validação de Admin Instituição:

• Verificação na tabela usuariopermissao: UsuarioId, TipoUsuarioId=8 e Status=true
• Além de ser Admin Instituição, o usuário deve ter permissão para o nível hierárquico da chamada
• O método ValidarAcessoNivelHierarquicoAsync faz engenharia reversa automaticamente:
  • Se a chamada tem HorarioId=27 e o Admin tem InstituicaoId=2, verifica se o horário pertence à instituição (Horario → Turma → Unidade → Instituição)
  • Se a chamada tem TurmaId=5 e o Admin tem UnidadeId=3, verifica se a turma pertence à unidade (Turma → Unidade)
  • Se a chamada tem UnidadeId=4 e o Admin tem InstituicaoId=1, verifica se a unidade pertence à instituição (Unidade → Instituição)
• Consulte a documentação do Sistema de Permissionamento Hierárquico para mais detalhes

Status de Presença

Rascunho vs Concluída

• Rascunho (Rascunho=true): Pode ser editado, excluído ou duplicado
• Concluída (Rascunho=false): Não pode ser duplicada para mesmo usuário, data e horarioId

🔧 Detalhes Técnicos

Sistema de ChamadaId e Sequence

Visão Geral: O sistema de ChamadaId foi implementado para agrupar múltiplos registros de chamada criados no mesmo POST, permitindo rastreamento histórico e agrupamento lógico de chamadas relacionadas.

Como Funciona

Quando um professor cria chamadas para múltiplos alunos em um único POST:

• Todos os registros válidos recebem o mesmo ChamadaId (gerado automaticamente)
• Cada registro mantém seu próprio Id único
• O ChamadaId permite buscar todas as chamadas criadas juntas

Exemplo Prático

POST /api/Chamadas com 3 alunos:
- Aluno A → Id=1, ChamadaId=5
- Aluno B → Id=2, ChamadaId=5
- Aluno C → Id=3, ChamadaId=5

Todos têm o mesmo ChamadaId=5, mas Ids diferentes (1, 2, 3)

Geração Thread-Safe

O ChamadaId é gerado usando uma Sequence (tabela auxiliar + stored procedure) que garante:

• Thread-safety: Múltiplas requisições simultâneas não geram valores duplicados
• Atomicidade: Geração e atribuição ocorrem dentro de uma transação única
• Sequencial: Valores incrementais facilitam ordenação e rastreamento

Decisão Arquitetural: Por Que Sequence?

Durante o desenvolvimento, foram consideradas três opções para gerar o ChamadaId. A Sequence foi escolhida após análise detalhada das alternativas:

Opção 1: MAX(ChamadaId) + 1 (Rejeitada)

Problemas identificados:

• ❌ Race conditions: Em alta concorrência, múltiplas requisições podem obter o mesmo valor
• ❌ Deadlocks: Bloqueios de tabela podem ocorrer
• ❌ Performance: Requer lock de tabela inteira
• ❌ Não thread-safe: Valores duplicados podem ser gerados

Opção 2: GUID/UUID (Rejeitada)

Problemas identificados:

• ❌ Não sequencial: Valores aleatórios dificultam ordenação
• ❌ Tamanho: 16 bytes vs 4 bytes (int)
• ❌ Performance: Índices maiores e mais lentos
• ❌ Legibilidade: Valores difíceis de ler e debugar

Opção 3: Sequence do Banco de Dados (Escolhida)

Vantagens que justificam a escolha:

• ✅ Thread-safe: Garantido pelo banco de dados
• ✅ Atomicidade: Operação atômica, sem race conditions
• ✅ Performance: Otimizado pelo banco
• ✅ Sequencial: Valores incrementais facilitam ordenação
• ✅ Padrão Microsoft: Recomendado para geração sequencial

Implementação no MySQL:

Como MySQL não suporta Sequence nativamente (como SQL Server), implementamos uma solução equivalente usando:

• Tabela auxiliar ChamadaIdSequence: Armazena o último valor gerado
• Stored procedure GetNextChamadaId(): Garante thread-safety com transação
• Método ObterProximoChamadaIdAsync(): Interface C# para obter próximo valor

Fluxo de Criação

1. POST /api/Chamadas recebe múltiplos alunos
   ↓
2. Service valida TODOS os registros PRIMEIRO
   ↓
3. Se QUALQUER registro falhar na validação:
   ↓
   → Retorna erro imediatamente (nenhuma chamada criada)
   → Erro indica usuário específico que falhou e motivo
   ↓
4. Se TODOS os registros passarem na validação:
   ↓
5. Inicia transação (atomicidade)
   ↓
6. Obtém próximo ChamadaId (thread-safe)
   ↓
7. Aplica o mesmo ChamadaId a todos os registros
   ↓
8. Adiciona todos ao contexto (AddRange)
   ↓
9. Salva tudo de uma vez (SaveChanges único)
   ↓
10. Commit da transação
   ↓
11. Retorna resposta com todas as chamadas criadas

Casos de Uso

• Histórico de Chamadas: Buscar todas as chamadas criadas em uma única operação usando GET /api/Chamadas?ChamadaId=5
• Auditoria: Identificar quando e como um grupo de chamadas foi criado
• Agrupamento Lógico: Agrupar chamadas relacionadas à mesma aula/evento
• Relatórios: Gerar relatórios de presença por grupo de chamadas

Garantias

• ✅ Atomicidade Total: Se qualquer registro falhar na validação, nenhuma chamada é criada. Se todas passarem na validação, todas são criadas dentro de uma transação única (ou todas são criadas ou nenhuma é criada)
• ✅ Thread-safety: Múltiplas requisições simultâneas não geram valores duplicados
• ✅ Validação prévia: Todos os registros são validados antes de gerar ChamadaId. Se qualquer validação falhar, a operação é abortada imediatamente
• ✅ Erro específico: Quando uma validação falha, o erro retornado indica especificamente qual usuário falhou e o motivo
• ✅ Performance: Índices otimizados para buscas por ChamadaId

Para mais detalhes técnicos, consulte o documento ChamadaId_Sequence_Sistema.md.

Timezone

Todas as operações de data/hora utilizam DateTimeHelper.AgoraBrasil() para garantir consistência com o timezone do Brasil (UTC-3).

Nível Hierárquico

O campo NivelHierarquico é armazenado como JSON no banco de dados. Formato:

{
  "instituicaoId": [1, 2],
  "unidadeId": [3],
  "turmaId": [4],
  "horarioId": [5]
}

Todos os campos são opcionais e podem ser arrays de inteiros.

Soft Delete

A exclusão de chamadas é feita via soft delete, definindo Ativo=false. Os registros permanecem no banco de dados para auditoria.

Auditoria

A entidade Chamada herda de EntityTracking, que fornece automaticamente:

• UsuarioCriacao: ID do usuário que criou
• Criacao: Data/hora de criação
• UsuarioAtualizacao: ID do usuário que atualizou
• Atualizacao: Data/hora da última atualização

📊 Códigos de Resposta HTTP

🧪 Exemplos de Teste

cURL

# Criar chamadas em lote - Múltiplos alunos
curl -X POST "https://localhost:5001/api/Chamadas" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "usuarioIds": ["aluno123", "aluno456", "aluno789"],
    "presenca": [1, 1, 0],
    "justificativa": [null, null, null],
    "dataChamada": "2026-01-06",
    "rascunho": false,
    "nivelHierarquico": {
      "horarioId": [1]
    }
  }'

# Pesquisar chamadas
curl -X GET "https://localhost:5001/api/Chamadas?MesAno=01/2026&Pagina=1&TamanhoPagina=20" \
  -H "Authorization: Bearer {token}"

# Buscar chamadas por ChamadaId (todas as chamadas criadas juntas)
curl -X GET "https://localhost:5001/api/Chamadas?ChamadaId=5" \
  -H "Authorization: Bearer {token}"

# Atualizar chamadas por ChamadaId (processamento em lote)
curl -X PUT "https://localhost:5001/api/Chamadas/chamadaId/5" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "usuarioIds": ["aluno123", "aluno456", "aluno789"],
    "presenca": [1, 0, 2],
    "justificativa": [null, null, "Atestado médico"],
    "rascunho": false,
    "ativo": true,
    "dataChamada": "2026-01-06",
    "nivelHierarquico": {
      "horarioId": [1]
    }
  }'

C# / .NET

using System.Net.Http;
using System.Text;
using System.Text.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = 
    new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token);

// Criar chamadas em lote
var request = new
{
    usuarioIds = new[] { "aluno123", "aluno456", "aluno789" },
    presenca = new[] { 1, 1, 0 },
    justificativa = new string[] { null, null, null },
    dataChamada = new DateTime(2026, 1, 6),
    rascunho = false,
    nivelHierarquico = new
    {
        horarioId = new[] { 1 }
    }
};

var json = JsonSerializer.Serialize(request);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://localhost:5001/api/Chamadas", content);
var result = await response.Content.ReadAsStringAsync();

// Atualizar chamadas por ChamadaId (processamento em lote)
var updateRequest = new
{
    usuarioIds = new[] { "aluno123", "aluno456", "aluno789" },
    presenca = new[] { 1, 0, 2 },
    justificativa = new string[] { null, null, "Atestado médico" },
    rascunho = false,
    ativo = true,
    dataChamada = new DateTime(2026, 1, 6),
    nivelHierarquico = new
    {
        horarioId = new[] { 1 }
    }
};

var updateJson = JsonSerializer.Serialize(updateRequest);
var updateContent = new StringContent(updateJson, Encoding.UTF8, "application/json");
var updateResponse = await client.PutAsync("https://localhost:5001/api/Chamadas/chamadaId/5", updateContent);
var updateResult = await updateResponse.Content.ReadAsStringAsync();

Arquivo HTTP

Consulte o arquivo InMinds.CordenaAi.Api/Tests/teste-chamadas.http para exemplos completos de testes HTTP.

🔒 Segurança

Autenticação

Todos os endpoints requerem autenticação via Bearer Token (JWT). O token deve ser enviado no header Authorization:

Authorization: Bearer {token}

Autorização

O sistema utiliza PermissionamentoHelper e FinanceiroPermissionamentoHelper para verificar permissões do usuário:

• Professor: Restrições de data (não pode criar para futuro ou mais de 14 dias no passado)
• Admin Instituição (TipoUsuarioId=8): Sem restrições de data se tiver permissão no nível hierárquico da chamada. A validação usa engenharia reversa da hierarquia (verifica se HorarioId pertence à InstituicaoId, etc.)

Auditoria

Todas as operações registram automaticamente:

• Usuário que criou/atualizou
• Data/hora de criação/atualização

📚 Glossário

✅ Checklist de Implementação

• ✅ Tabela Chamadas criada no banco de dados
• ✅ Entidade Chamada e enum PresencaStatus criados
• ✅ DTOs (Request/Response) implementados
• ✅ Repository com método PesquisarAsync e filtros dinâmicos
• ✅ Service com validações de data, permissão, duplicidade e justificativa
• ✅ Controller com endpoints CRUD completos
• ✅ AutoMapper Profile configurado
• ✅ Dependências registradas no DI container
• ✅ Arquivo de testes HTTP criado
• ✅ Documentação HTML completa

🔧 Troubleshooting

Problema: Justificativa Obrigatória

Sintoma: Erro ao criar chamada com Presenca=2 sem justificativa

Solução: A justificativa é obrigatória quando Presenca=2 (Justificado). Informe o campo justificativa no request.

Problema: Data Futura

Sintoma: Erro ao criar chamada para data futura (perfil Professor)

Solução: Professores não podem criar chamadas para datas futuras. Use uma data atual ou passada (máximo 14 dias). Admin Instituição (TipoUsuarioId=8) com permissão no nível hierárquico pode criar para qualquer data.

Problema: Chamada Duplicada

Sintoma: Erro ao criar chamada concluída duplicada

Solução: Não é permitido criar chamadas concluídas (Rascunho=false) duplicadas para o mesmo usuário, data e horarioId. Use Rascunho=true ou atualize a chamada existente. Se qualquer registro falhar na validação de duplicidade, nenhuma chamada será criada (atomicidade total).

Problema: Justificativa em Presente

Sintoma: Justificativa informada junto com Presenca=1 (Presente)

Solução: Quando Presenca=1 (Presente), o sistema automaticamente define a justificativa como null, mesmo que você envie uma justificativa no request. Não é necessário remover o campo, pois ele será ignorado automaticamente. A chamada será criada/atualizada normalmente com justificativa = null.

Problema: Arrays com Tamanhos Diferentes

Sintoma: Erro ao criar chamadas com arrays de tamanhos diferentes

Solução: Os arrays usuarioIds, presenca e justificativa devem ter obrigatoriamente o mesmo tamanho. Verifique se todos os arrays têm a mesma quantidade de elementos antes de enviar a requisição.

Problema: Erro na Validação (Atomicidade Total)

Sintoma: Erro ao criar chamadas em lote - nenhuma chamada foi criada mesmo que algumas pareçam válidas

Solução: O sistema processa todas as chamadas de forma totalmente atômica. Se qualquer registro falhar na validação, nenhuma chamada será criada e o erro específico do usuário que falhou será retornado. Verifique a mensagem de erro que indica qual usuário falhou e o motivo. Corrija o problema e tente novamente. Isso garante integridade dos dados e evita estados inconsistentes.

Exemplo: Se você tentar criar chamadas para 3 alunos e o segundo aluno tiver uma data inválida, nenhuma das 3 chamadas será criada. O erro retornado indicará especificamente o segundo aluno e o motivo (ex: "A data da chamada não pode ser futura").

Problema: ChamadaId Duplicado

Sintoma: Preocupação sobre possíveis ChamadaIds duplicados em alta concorrência

Solução: O sistema utiliza Sequence (tabela auxiliar + stored procedure) que garante thread-safety. Múltiplas requisições simultâneas não geram valores duplicados. A geração ocorre dentro de uma transação, garantindo atomicidade.

Problema: Editar Chamada Concluída Após 14 Dias (Professor)

Sintoma: Erro ao tentar editar chamada concluída (Rascunho=false) como professor após 14 dias da data da chamada

Solução: Professores podem editar chamadas concluídas apenas dentro de 14 dias após a data da chamada. Após este prazo, apenas rascunhos podem ser editados por professores. Para editar chamadas concluídas após 14 dias, contate um administrador da instituição com permissão no nível hierárquico da chamada. O cálculo é feito como: (data atual - dataChamada) ≤ 14 dias.

Problema: Editar Rascunho Após 14 Dias (Professor)

Sintoma: Professor consegue editar rascunho após 14 dias, mas não consegue editar chamada concluída

Solução: Isso é comportamento esperado. Após 14 dias da data da chamada, professores podem editar apenas rascunhos (Rascunho=true). Chamadas concluídas não podem ser editadas após este prazo. Dentro dos 14 dias, professores podem editar tanto rascunhos quanto chamadas concluídas.

Problema: Gaps na Sequência de ChamadaId

Sintoma: Sequência de ChamadaId apresenta gaps (ex: 5, 7, 8 - falta o 6)

Solução: Gaps na sequência são comportamento esperado e não indicam problema. Podem ocorrer quando uma transação é revertida (rollback) ou quando um erro ocorre após gerar ChamadaId mas antes de salvar. Isso é normal e não afeta a funcionalidade do sistema.

Problema: Atualizar ChamadaId Inexistente

Sintoma: Erro 404 ao tentar atualizar chamadas por ChamadaId

Solução: Verifique se o ChamadaId existe no banco de dados. Use GET /api/Chamadas?ChamadaId={chamadaId} para verificar se existem registros com esse ChamadaId antes de tentar atualizar.

Problema: Arrays com Tamanho Diferente da Quantidade de Registros

Sintoma: Erro ao atualizar chamadas por ChamadaId - "A quantidade de elementos nos arrays não corresponde à quantidade de registros existentes"

Solução: Os arrays usuarioIds, presenca e justificativa devem ter exatamente a mesma quantidade de elementos que existem registros com o ChamadaId especificado. Use GET /api/Chamadas?ChamadaId={chamadaId} para verificar quantos registros existem antes de atualizar.

Problema: Processamento Parcial no PUT

Sintoma: Alguns registros são atualizados com sucesso enquanto outros falham no PUT

Solução: Isso é comportamento esperado. Diferente do POST que é atômico (tudo ou nada), o PUT permite processamento parcial. A resposta incluirá lista de sucessos e erros. Verifique o campo erros na resposta para identificar quais registros falharam e o motivo.

Problema: Tentar Alterar ChamadaId

Sintoma: ChamadaId não é alterado após atualização

Solução: Isso é comportamento esperado. O campo chamadaId não pode ser alterado após a criação e é preservado automaticamente pelo sistema. O mesmo se aplica aos campos id, usuarioCriacao e criacao.

Versão: 1.0
Última Atualização: Janeiro de 2026
Responsável: Equipe de Desenvolvimento CordenaAi