tep_aula03

Imported from Salatielbg/tep_aula03 (AGENTS.md). Install upstream with npx skills add Salatielbg/tep_aula03. Copyright stays with the author.

AGENTS.md — Diretrizes para Agentes de IA

Auditoria de Smells (Seção 6.2): O arquivo foi auditado contra os 6 defeitos de configuração. Identificou-se e removeu-se ativamente Lint Leakage (regras de estilo/formatação cobertas por linter) e Context Bloat, mantendo apenas comandos essenciais, regras arquiteturais e restrições inegociáveis.

Este documento define as diretrizes, padrões de arquitetura, regras de negócio e procedimentos de teste para qualquer agente de IA que for implementar, refatorar ou estender o Sistema de Gestão Escolar e Avaliação de Desempenho.

1. Visão Geral e Contexto do Projeto

O objetivo do projeto é gerenciar turmas, alunos e notas com pesos e limites de aprovação totalmente dinâmicos (definidos por turma). O sistema calcula médias ponderadas, classifica a situação acadêmica dos alunos, gera estatísticas em tempo real (média, mediana, distribuição e alertas de proximidade da aprovação) e persiste o estado entre execuções.

Documento de Referência Principal: spec.md — Toda implementação deve aderir estritamente às especificações contidas no spec.md.

2. Princípios de Design e Regras Inegociáveis

1. Proibido Hardcoding de Regras Pedagógicas:
   • Pesos de avaliações, nota mínima para aprovação e nota mínima para exame jamais devem ser valores fixos no código. Devem ser sempre obtidos da configuração da turma (Turma.criterios e Turma.configuracao_avaliacoes).
2. Validação Rigorosa e Mensagens Claras:
   • Nenhuma entrada inválida deve ser aceita silenciosamente ou gerar stack traces não tratados para o usuário.
   • Mensagens de erro devem seguir o padrão especificado na Seção 4 do spec.md (identificando o campo, o valor recebido e o critério esperado).
3. Persistência Atômica e Confiável:
   • Todas as alterações (inserção, edição, exclusão) devem refletir imediatamente no arquivo de persistência (data.json ou similar).
   • O carregamento de dados na inicialização deve ser resiliente a arquivos inexistentes (criando um estado inicial vazio válido).
4. Cálculos Matemáticos Precisos:
   • Médias ponderadas: normalizar pela soma dos pesos cadastrados.
   • Mediana: lidar corretamente com número par e ímpar de notas.
   • "Quase Aprovados": considerar o intervalo semiaberto $[\text{nota_aprovacao} - 0.5, \text{nota_aprovacao}[$. Alunos já aprovados ($\ge \text{nota_aprovacao}$) não devem constar nessa lista.

3. Arquitetura Sugerida

A estrutura recomendada segue separação clara de responsabilidades (Clean Architecture / Camadas):

sistema-turmas/
├── spec.md                   # Especificação formal de requisitos
├── AGENTS.md                 # Este documento de diretrizes para agentes
├── data/
│   └── database.json         # Arquivo padrão de persistência
├── src/
│   ├── models/               # Entidades de domínio (Turma, Aluno, Avaliacao, Criterios)
│   │   ├── turma.py
│   │   ├── aluno.py
│   │   └── criterios.py
│   ├── services/             # Lógica de negócio e cálculos estatísticos
│   │   ├── calculadora.py    # Média ponderada e classificação
│   │   ├── estatisticas.py   # Média geral, mediana, distribuição, quase aprovados
│   │   └── gestor_turmas.py  # Operações e validações de turma e alunos
│   ├── storage/              # Camada de persistência
│   │   └── json_repository.py
│   ├── validators/           # Funções de validação e tratamento de erros
│   │   └── validadores.py
│   └── cli/                  # Interface de linha de comando interativa
│       └── menu.py
├── tests/                    # Suíte de testes unitários e de integração
│   ├── test_calculadora.py
│   ├── test_estatisticas.py
│   ├── test_validacoes.py
│   └── test_persistencia.py
└── main.py                   # Ponto de entrada da aplicação

4. Responsabilidades dos Módulos

4.1. models/

• Definir classes/data classes imutáveis ou fortemente tipadas para Turma, Aluno, CriteriosAprovacao e Avaliacao.
• Garantir que objetos não sejam instanciados em estados inválidos.

4.2. services/calculadora.py

• Calcular média ponderada:

  # Fórmula: soma(nota * peso) / soma(pesos)

• Classificar aluno em APROVADO, EXAME ou REPROVADO usando os critérios da turma correspondente.

4.3. services/estatisticas.py

• calcular_estatisticas(turma, alunos) -> EstatisticasTurma:
  • media_geral: Média aritmética simples das médias dos alunos.
  • mediana: Mediana das médias.
  • distribuicao: Dicionário com contagem e percentual por status.
  • quase_aprovados: Lista de objetos/dicionários com {aluno, media, falta_para_aprovacao} para alunos no intervalo $[\text{aprovacao} - 0.5, \text{aprovacao}[$.

4.4. storage/

• Serialização e desserialização robusta (JSON/SQLite).
• Criação de backup temporário ao salvar ou uso de gravação atômica (tempfile + replace).

5. Convenções de Código e Estilo

• Linguagem recomendada: Python 3.10+ (ou TypeScript/Node.js, se solicitado).
• Tipagem: Uso obrigatório de Type Hints em todas as assinaturas de funções e métodos.
• Tratamento de Exceções: Criar exceções de domínio personalizadas (ex: ValidationError, TurmaNotFoundError, DuplicateMatriculaError).
• Funções Puras: Manter as funções de cálculo (calculadora.py, estatisticas.py) como funções puras e determinísticas, facilitando os testes unitários.

6. Roteiro de Testes e Validação Obrigatória

Qualquer alteração ou nova funcionalidade deve ser validada com a seguinte suíte mínima de testes:

Testes Unitários

1. Cálculo de Média Ponderada:
   • Pesos arbitrários (ex: 1, 2, 3) e pesos fracionários (ex: 2.5, 7.5).
   • Notas no limite ($0.0$ e $10.0$).
2. Classificações por Turma:
   • Turma A (Aprovação: 7.0, Exame: 4.0) vs Turma B (Aprovação: 6.0, Exame: 3.0).
   • Nota exatamente no limite de aprovação (ex: 7.0 -> Aprovado).
   • Nota exatamente no limite de exame (ex: 4.0 -> Exame).
   • Nota logo abaixo do limite de exame (ex: 3.99 -> Reprovado).
3. Estatísticas:
   • Mediana com número ímpar e par de alunos.
   • Quase aprovados: aluno com 6.50 (entra no alerta para aprovação 7.0), aluno com 6.49 (não entra), aluno com 7.00 (já aprovado, não entra).
   • Turma vazia (sem alunos) ou sem notas lançadas: não deve gerar divisão por zero.
4. Validações e Erros:
   • Tentativa de lançar nota negativa ou $> 10.0$.
   • Cadastro com peso $\le 0$.
   • Configuração com nota_exame >= nota_aprovacao.
   • Cadastro de matrícula duplicada.
5. Persistência:
   • Salvar estado, reiniciar serviço/repositório e validar se todos os dados retornam idênticos.

7. Instruções para Execução do Projeto

# Executar a aplicação CLI
python main.py

# Executar a suíte de testes automatizados
pytest -v