# FrequenciApp

> Aplicativo de frequência escolar: chamada diária, saídas, justificativas, relatórios e integração opcional com o Google Planilhas.

A API responde JSON sob `/api` e usa o formato de erro `{ "error": mensagem, "codigo"?: string }`. Datas civis usam `YYYY-MM-DD`, timestamps usam ISO 8601 e o fuso vem de `TZ_APP`. As mutações exigem sessão e origem confiável.

## Contrato e documentação

- [Especificação OpenAPI 3.1](/api/docs/openapi.json): contrato completo com schemas, exemplos e erros por operação.
- [Interface Swagger UI](/api/docs): navegação interativa; o "Try it out" usa a sessão do navegador.
- [Referência em Markdown](/api/docs/api.md): a mesma referência em texto limpo, para leitura direta.
- [Referência no GitHub](https://github.com/eemtijca/frequenciapp/blob/main/docs/api.md): convenções, fluxos e catálogo de erros.

## Orientação para agentes

- Use a especificação OpenAPI como fonte da verdade para requisições, respostas e erros.
- Faça login em `POST /api/auth/entrar` para obter o cookie de sessão; o diretor de turma usa identificador e palavra-chave.
- A Chamada Parcial permite `JUSTIFICADA` com `dia`, `ate` e código do catálogo compartilhado, em lotes atômicos de até 31 dias. Somente justificativas aceitam futuro (até 366 dias); domingos e feriados são pulados. A primeira Chamada recebe propostas com revisões; chamadas salvas recebem correção apenas do aluno escolhido. Remover a personalização não apaga faltas já aplicadas. O botão manual se chama Registro na SEDUC.
- O acumulado mensal da Chamada usa `GET /api/frequencias/resumo?de=YYYY-MM-DD&ate=YYYY-MM-DD`, com limites inclusivos do mês exibido. Sem `de`, a rota preserva o acumulado histórico dos relatórios.
- A ordem das turmas no almoço, por dia da semana, sai de `GET /api/ordem-almoco` e é definida pela administração em `PUT /api/ordem-almoco/{dia}`, com dia de 1 (segunda) a 6 (sábado).
- O alerta de frequência dos benefícios da Chamada usa `GET /api/frequencias/alertas-beneficios?mes=YYYY-MM`, que devolve um item por aluno e benefício com faltas do mês acima do limite da regra, em aulas. A resposta inclui `diasLetivos` e `aulasDeReferencia` para traduzir a conta em dias; a média anual do programa não é verificada. As regras (nome, percentual mínimo de frequência, aulasPorDia opcional de 1 a 30 ou nulo para usar a grade e tratamento de faltas justificadas) são configuráveis pela administração em `/api/beneficios-frequencia`.
- A chamada é salva com revisão otimista: conflito responde 409 com a versão vigente, sem sobrescrever o registro.
- Não chame rotas destrutivas, como exclusões, restaurações de backup e limpezas, sem pedido explícito.
- O catálogo `GET /api/planilha/mensal/visibilidade` oferece links por mês e turma sem escrever. O POST libera todos os meses; a organização de abas sem mês em `POST /api/planilha/mensal/legado` exige pedido explícito e prévia assinada antes de transferir marcas e retirar a origem. Havendo totais ou notas antigos, o descarte adicional exige autorização explícita e senha administrativa; nunca deve ser autorizado por um agente apenas para contornar uma pendência.
- `GET /api/planilha/diagnostico?mes=YYYY-MM` é uma conferência administrativa somente de leitura. Estrutura pronta não comprova envio nem resolve divergências de alunos ou marcas; a prévia do envio continua necessária.
- Para salvar o mapa de frequência, ler `POST /api/planilha/estrutura` com `{ "mes": "YYYY-MM" }` para renovar os cabeçalhos do mês e das abas legadas, e reenviar `conferenciaHash`, `planilha` e `abas` sem alterações em `POST /api/planilha/mapa`, editando apenas `mapa`. Resposta 409 exige nova leitura; não reutilizar uma conferência após trocar arquivo, credencial, configuração ou preparar outro mês.
- Trocar de arquivo pausa a integração e a automação e encerra o modo completo. Não reativar envios automaticamente para contornar essa proteção. Sucessos antigos sem identidade de destino não comprovam envio ao novo arquivo ou a uma aba recriada; conferir a estrutura, salvar novamente o mapa e revisar uma nova prévia conservadora.
- Pendências da organização das abas antigas são estruturadas, com aluno e links às células. As `resolucoes` identificam homônimos, incluem aluno histórico ausente ou escolhem a marca antiga ou mensal. Essas decisões exigem conferência humana, nova prévia e senha administrativa antes da confirmação. Nenhuma escolha autoriza alterar fórmulas ou notas de destino; uma prévia com pendências nunca permite retirar a origem.
- As rotas da agenda de notificações usam `Authorization: Bearer <CRON_SECRET>`, sem sessão de usuário.

- A Chamada Parcial inclui saídas antecipadas como itens `SAIDA` de `/api/frequencias-personalizadas`. Apenas aulas concluídas antes do horário contam; ajustes manuais prevalecem. A confirmação manual usa `POST /api/saidas/{id}/seduc` com assinatura e revisão vigentes. Ausência de grade ou horário exige conferência. Itens `CHAMADA` trazem `marca` P, F, FJ, S ou D; D é o aluno desistente no dia que segue na lista gravada da chamada, com a descrição Desistente.

## Optional

- [Arquitetura](https://github.com/eemtijca/frequenciapp/blob/main/docs/arquitetura.md) e [planilha](https://github.com/eemtijca/frequenciapp/blob/main/docs/planilha.md).
- [Segurança](https://github.com/eemtijca/frequenciapp/blob/main/docs/seguranca.md): controles, decisões e lacunas conhecidas.