Avalia.EDUACESSO

1. Resumo executivo

O Avalia.EDUACESSO será a camada de avaliação acadêmica do ecossistema EDUACESSO, permitindo que instituições de ensino criem, apliquem, corrijam, auditem e analisem avaliações de forma integrada, segura e escalável.

1.1 Visão do produto

Centralizar o ciclo avaliativo em uma plataforma única: banco de questões, elaboração de avaliações, geração de prova e folha de respostas, correção objetiva, lançamento de notas discursivas, relatórios e exportações acadêmicas.

1.2 Declaração do produto

Para instituições de ensino que precisam aplicar avaliações com segurança, padronização e agilidade, o Avalia.EDUACESSO oferece um módulo completo de gestão de avaliações, com correção automática, controle de gabaritos, rastreabilidade e relatórios acadêmicos.

2. Contexto e problema

A gestão de avaliações em instituições de ensino costuma envolver várias etapas manuais: criação de questões, montagem de provas, impressão, preenchimento de gabaritos, correção manual, conferência de notas, lançamento em planilhas ou sistemas acadêmicos e emissão de relatórios. Esse fluxo gera retrabalho, risco de erro, ausência de rastreabilidade e dificuldade de análise pedagógica.

2.1 Problemas identificados

• Tempo elevado para correção de provas objetivas.
• Dificuldade de controlar versões diferentes de uma mesma avaliação.
• Uso disperso de documentos, planilhas, formulários e arquivos PDF.
• Falta de histórico estruturado de questões e avaliações aplicadas.
• Risco de inconsistência no lançamento de notas.
• Ausência de relatórios automáticos por turma, curso, disciplina e instituição.
• Dificuldade de auditar correções, alterações de gabarito e exportações.
• Baixa padronização visual e documental das provas institucionais.

2.2 Oportunidade

Criar uma solução própria integrada ao EDUACESSO, com capacidade de atender múltiplas instituições e crescer para novos módulos, como simulados, avaliações diagnósticas, CPA, avaliações institucionais, ENADE interno e relatórios de desempenho por competência.

3. Objetivos e resultados esperados

3.1 Objetivo geral

Desenvolver um módulo web e API de avaliações acadêmicas que permita criar provas, gerenciar banco de questões, gerar gabaritos, corrigir automaticamente cartões-resposta, lançar notas e emitir relatórios acadêmicos.

3.2 Objetivos específicos

• Disponibilizar banco de questões próprio por instituição, curso, disciplina, assunto e docente.
• Permitir montagem de provas objetivas, discursivas ou mistas.
• Gerar provas com versões diferentes por aluno, turma ou quantidade definida.
• Gerar folha de respostas com QR Code ou código identificador.
• Realizar correção automática de questões objetivas por leitura de imagem.
• Permitir revisão manual de correções com baixa confiança.
• Permitir lançamento de notas discursivas e feedback por questão.
• Emitir relatórios de desempenho por aluno, turma, curso, disciplina e instituição.
• Exportar resultados em formatos compatíveis com sistemas acadêmicos.
• Garantir segurança, privacidade, auditoria e isolamento por instituição.

3.3 Resultados esperados

4. Escopo do produto

4.1 Em escopo

• Dashboard administrativo.
• Cadastro de instituições, cursos, turmas, disciplinas, docentes e estudantes.
• Banco de questões com categorização e níveis de dificuldade.
• Criação de avaliações objetivas, discursivas e mistas.
• Geração de provas em PDF com cabeçalho institucional.
• Geração de folha de respostas com QR Code.
• Correção automática de cartão-resposta via upload/câmera.
• Revisão manual de leituras com baixa confiança.
• Lançamento de notas discursivas.
• Publicação controlada de gabaritos.
• Relatórios acadêmicos e exportação de notas.
• API REST para integração com outros módulos do EDUACESSO.
• Registro de logs e auditoria.

4.2 Fora do escopo inicial

• Aplicação de prova online com ambiente anticolagem completo.
• Proctoring por câmera, áudio ou reconhecimento facial.
• Correção automática de redações por IA.
• Integração nativa com todos os sistemas acadêmicos do mercado no MVP.
• Marketplace público de questões de terceiros.
• Aplicativo mobile nativo na primeira versão, salvo se definido como prioridade estratégica.

4.3 Premissas

• O sistema será multi-instituição, com separação lógica por institution_id.
• O Avalia.EDUACESSO poderá operar como módulo independente ou integrado ao EDUACESSO principal.
• A primeira versão deve funcionar em navegador desktop e mobile responsivo.
• A leitura de cartão-resposta poderá iniciar com upload de imagem e evoluir para câmera integrada.
• O sistema deve permitir correção manual/revisão quando a imagem não for lida com segurança.

5. Usuários, papéis e permissões

6. Personas e jornadas

6.1 Jornada do professor

1. Acessa o Avalia.EDUACESSO.
2. Seleciona instituição, curso, turma e disciplina.
3. Cadastra ou seleciona questões do banco.
4. Monta a avaliação com pontuação e instruções.
5. Gera versões diferentes e folhas de respostas.
6. Imprime ou distribui a prova.
7. Captura as folhas respondidas pela câmera ou upload.
8. Revisa eventuais leituras duvidosas.
9. Lança notas discursivas, se houver.
10. Fecha correção e exporta os resultados.

7. Módulos funcionais

7.1 Painel inicial

• Resumo de avaliações recentes.
• Provas em rascunho.
• Provas aguardando correção.
• Correções pendentes de revisão.
• Indicadores de média por turma.
• Atalhos para criar prova, banco de questões e relatórios.

7.2 Banco de questões

• Cadastro manual de questões.
• Questões objetivas com alternativas.
• Questões discursivas.
• Classificação por disciplina, assunto, competência, dificuldade e professor.
• Visibilidade: privada, institucional e pública.
• Histórico de edição e uso da questão.
• Busca textual e filtros.
• Importação futura via planilha.

7.3 Montagem de avaliações

• Criar avaliação por turma, curso e disciplina.
• Selecionar questões manualmente.
• Montar avaliação por critérios: assunto, dificuldade e quantidade.
• Definir pontuação por questão.
• Configurar instruções, tempo, cabeçalho e observações.
• Definir se haverá gabarito público após a aplicação.

7.4 Geração de provas

• Gerar uma versão única.
• Gerar versões por aluno.
• Gerar número determinado de versões.
• Embaralhar questões.
• Embaralhar alternativas.
• Gerar PDF institucional.
• Gerar caderno de prova e folha de respostas.

7.5 Folha de respostas

• Identificação da instituição.
• Identificação da avaliação.
• Identificação do estudante, quando aplicável.
• QR Code assinado.
• Campos de marcação por questão.
• Área para assinatura do estudante.
• Orientações de preenchimento.

7.6 Correção automática

• Upload de imagem ou captura por câmera.
• Leitura do QR Code.
• Identificação de versão da prova.
• Leitura das marcações.
• Cálculo automático de nota objetiva.
• Sinalização de rasuras, marcações múltiplas ou campos em branco.
• Fila de revisão manual para leituras inseguras.

7.7 Notas e resultados

• Nota objetiva.
• Nota discursiva.
• Nota final.
• Feedback por questão discursiva.
• Situação: pendente, corrigido, revisado, publicado.
• Exportação e integração com sistemas acadêmicos.

7.8 Relatórios

• Resultado por estudante.
• Resultado por turma.
• Resultado por curso.
• Resultado por disciplina.
• Acertos por questão.
• Desempenho por assunto ou competência.
• Questões com maior índice de erro.
• Média, mediana, maior nota, menor nota e desvio padrão.

7.9 Gabarito público

• Publicação manual ou agendada.
• Link público por token.
• Controle de visualização.
• Registro de quem publicou e quando publicou.

7.10 Agentes de IA

• Agente elaborador de provas.
• Agente revisor pedagógico.
• Agente corretor assistido.
• Agente de feedback ao aluno.
• Agente de relatórios acadêmicos.
• Gateway de provedores: OpenAI, Anthropic, Hermes Agent e provedores futuros.

7.11 Portais personalizados

• Portal do aluno com notas, gabaritos, feedbacks e histórico.
• Portal do professor com banco de questões, provas, IA, correções e relatórios.
• Identidade visual por instituição.
• Widgets configuráveis por perfil.
• Feature flags por instituição.
• Templates de prova, folha de resposta e comunicação.

8. Requisitos funcionais

8.1 Priorização MoSCoW

A priorização dos requisitos segue o modelo MoSCoW: MUST obrigatório, SHOULD importante, COULD desejável, WON'T fora do escopo inicial.

9. Regras de negócio

9.1 Instituição e isolamento

• Toda entidade operacional deve possuir institution_id.
• Usuários só acessam dados de instituições às quais estão vinculados.
• O administrador global pode visualizar todas as instituições, conforme política interna.

9.2 Banco de questões

• Questões privadas são visíveis apenas ao autor e perfis autorizados.
• Questões institucionais são visíveis aos docentes/coordenadores da mesma instituição.
• Questões públicas podem ser usadas como biblioteca compartilhada, caso habilitado.
• Questões já usadas em avaliações não devem ser apagadas fisicamente; devem ser arquivadas.
• Alterações em questões já aplicadas devem criar nova versão lógica da questão.

9.3 Avaliação

• A avaliação em rascunho pode ser editada livremente.
• Após gerar versões/PDF, alterações críticas devem gerar nova versão da avaliação.
• A soma dos pontos das questões deve bater com a pontuação total ou exigir confirmação.
• A avaliação encerrada não pode receber novas correções sem reabertura autorizada.

9.4 Gabarito

• O gabarito interno é obrigatório para correção automática.
• O gabarito público só deve ser exibido após publicação manual ou agendada.
• A publicação de gabarito deve registrar usuário, data, hora e IP.

9.5 Correção

• Folha sem QR Code legível deve permitir identificação manual por avaliação/versão/aluno.
• Questão com múltiplas marcações pode ser considerada nula, conforme configuração da avaliação.
• Questão em branco deve receber zero, salvo regra específica.
• Correção com baixa confiança deve ir para revisão manual.
• Toda revisão manual deve registrar o usuário responsável.

9.6 Notas

• Nota final = nota objetiva + nota discursiva + ajustes autorizados.
• Notas não podem ultrapassar a pontuação máxima definida.
• Alterações de nota após fechamento devem exigir justificativa.

10. Fluxos operacionais

10.1 Fluxo de criação de prova

1. Professor acessa o painel.
2. Clica em “Nova avaliação”.
3. Seleciona instituição, curso, turma e disciplina.
4. Informa título, data, instruções e pontuação total.
5. Seleciona questões existentes ou cadastra novas.
6. Define pontuação por questão.
7. Salva avaliação como rascunho.
8. Confere pré-visualização.
9. Gera versões e PDF.

10.2 Fluxo de aplicação impressa

1. Professor gera PDF da prova e folhas de respostas.
2. Sistema cria QR Code para cada versão/aluno.
3. Professor imprime e aplica a prova.
4. Aluno preenche o cartão-resposta.
5. Professor recolhe as folhas.

10.3 Fluxo de correção automática

1. Professor acessa a avaliação.
2. Clica em “Corrigir folhas”.
3. Envia imagem ou usa câmera do dispositivo.
4. Sistema identifica QR Code e versão da prova.
5. Sistema lê as marcações.
6. Sistema calcula nota objetiva.
7. Se houver baixa confiança, envia para revisão.
8. Professor revisa, se necessário.
9. Sistema consolida resultado.

10.4 Fluxo de fechamento de notas

1. Professor verifica lista de correções.
2. Lança notas discursivas, quando houver.
3. Confere nota final.
4. Fecha a avaliação.
5. Exporta notas.
6. Publica gabarito, se autorizado.

11. API e integrações

11.1 Base técnica sugerida

11.2 Endpoints principais

POST   /auth/login
GET    /auth/me

GET    /institutions
POST   /institutions

GET    /courses
POST   /courses

GET    /classes
POST   /classes

GET    /students
POST   /students

GET    /questions
POST   /questions
GET    /questions/{question_id}
PATCH  /questions/{question_id}

GET    /exams
POST   /exams
GET    /exams/{exam_id}
POST   /exams/{exam_id}/items
POST   /exams/{exam_id}/generate-versions
POST   /exams/{exam_id}/pdf

POST   /corrections/scan
GET    /corrections/{correction_id}
POST   /corrections/{correction_id}/essay-scores

GET    /results
POST   /exports/results

POST   /exams/{exam_id}/publish-answer-key
GET    /public/exams/{public_token}/answer-key

11.3 Integrações previstas

11.4 Exemplo de payload para criar questão

{
  "institution_id": "uuid-da-instituicao",
  "type": "objective",
  "statement": "Qual é a principal função do sistema respiratório?",
  "subject": "Anatomia",
  "topic": "Sistema respiratório",
  "difficulty": "medium",
  "visibility": "institutional",
  "options": [
    { "text": "Realizar trocas gasosas" },
    { "text": "Produzir hormônios" },
    { "text": "Controlar a digestão" },
    { "text": "Filtrar o sangue" }
  ],
  "correct_option_index": 0,
  "max_score": 1.0
}

11A. Agentes de IA para elaboração e correção de provas

O Avalia.EDUACESSO deverá possuir uma camada de Agentes de IA para apoiar professores, coordenações e instituições na elaboração de provas, revisão pedagógica, criação de gabaritos, correção assistida, feedback acadêmico e geração de relatórios. A IA não substitui a decisão docente: todo resultado sensível deve passar por validação humana.

11A.1 Visão geral do Motor de IA

O Motor de IA será uma camada intermediária entre o Avalia.EDUACESSO e provedores externos ou internos de inteligência artificial. Esse motor deverá receber solicitações estruturadas, escolher o provedor/modelo adequado, aplicar políticas de segurança, mascarar dados sensíveis, registrar logs, validar o resultado e devolver uma resposta revisável.

Componentes principais

11A.2 Agente Elaborador de Provas

O Agente Elaborador de Provas auxiliará o professor na criação de avaliações a partir de parâmetros acadêmicos. Ele poderá sugerir questões, montar matrizes avaliativas, gerar versões de prova, propor alternativas, criar gabaritos comentados e indicar o nível de dificuldade de cada item.

Entradas do agente

• Instituição, curso, turma, disciplina e período letivo.
• PPC do curso, ementa, plano de ensino e objetivos de aprendizagem.
• Conteúdos programáticos e competências esperadas.
• Banco de questões interno do professor ou da instituição.
• Nível de dificuldade desejado: fácil, médio, difícil ou misto.
• Tipo de prova: objetiva, discursiva, mista, simulado, diagnóstica ou recuperação.
• Quantidade de questões e pontuação total.
• Distribuição por assunto, unidade ou competência.
• Parâmetros pedagógicos, como taxonomia de Bloom, competências ENADE ou matriz própria.

Saídas do agente

• Prova preliminar editável.
• Questões objetivas com alternativas e gabarito.
• Questões discursivas com rubrica de correção.
• Gabarito comentado.
• Matriz de habilidades/conteúdos por questão.
• Classificação de dificuldade por questão.
• Alertas de duplicidade, ambiguidade ou baixa qualidade.
• Sugestão de tempo de prova.
• Versões alternativas para impressão.

Regras específicas

• O agente não pode inserir questão diretamente em prova oficial sem revisão do professor.
• O agente deve informar a base usada para gerar ou revisar as questões.
• O agente deve apontar quando não houver contexto suficiente para gerar questão confiável.
• Questões geradas por IA devem ser marcadas com metadado de origem.
• Questões aprovadas pelo professor podem entrar no banco institucional.
• A edição humana deve ser preservada como versão final aprovada.

11A.3 Agente Revisor Pedagógico

O Agente Revisor Pedagógico analisará provas e questões antes da aplicação, verificando coerência, clareza, alinhamento com a ementa, nível de dificuldade, possíveis ambiguidades e consistência do gabarito.

11A.4 Agente Corretor de Provas

O Agente Corretor de Provas atuará em duas frentes: correção objetiva automatizada por leitura de cartão-resposta e correção assistida de questões discursivas com base em rubricas definidas pelo professor.

Correção objetiva

• Recebe imagem da folha de resposta.
• Lê QR Code, avaliação, versão e estudante.
• Identifica marcações.
• Compara respostas com gabarito da versão correta.
• Calcula nota objetiva.
• Indica confiança da leitura.
• Envia para revisão quando houver rasura, marcação múltipla ou baixa qualidade de imagem.

Correção discursiva assistida

• Usa rubrica criada pelo professor ou pela coordenação.
• Gera sugestão de nota, não nota definitiva.
• Aponta evidências textuais que justificam a sugestão.
• Gera feedback pedagógico para o aluno.
• Permite ao professor aceitar, ajustar ou rejeitar a sugestão.
• Registra diferença entre sugestão da IA e nota final humana.

11A.5 Agente de Feedback ao Aluno

O Agente de Feedback ao Aluno deverá gerar devolutivas individualizadas e pedagógicas com base no desempenho do estudante. O feedback deve indicar pontos fortes, conteúdos a revisar e recomendações de estudo, sem linguagem punitiva ou exposição indevida de dados pessoais.

Tipos de feedback

• Feedback por questão.
• Feedback por assunto.
• Feedback por competência.
• Plano de estudo pós-avaliação.
• Resumo de erros recorrentes.
• Mensagem de orientação para recuperação.

11A.6 Agente de Relatórios Acadêmicos

O Agente de Relatórios Acadêmicos deverá transformar dados de avaliação em análises gerenciais para professor, coordenação, secretaria e gestão institucional.

Relatórios gerados com apoio de IA

• Análise da turma por desempenho geral.
• Questões com maior índice de erro.
• Conteúdos com maior dificuldade de aprendizagem.
• Comparação entre turmas.
• Sugestões de intervenção pedagógica.
• Resumo executivo para coordenação.
• Relatório institucional de avaliações por curso.

11A.7 Requisitos funcionais dos Agentes de IA

11A.8 Endpoints sugeridos para IA

POST   /ai/exams/generate
POST   /ai/questions/generate
POST   /ai/questions/review
POST   /ai/rubrics/generate
POST   /ai/corrections/essay-suggest
POST   /ai/feedback/student
POST   /ai/reports/class-summary
POST   /ai/reports/course-summary
GET    /ai/providers
POST   /ai/providers
PATCH  /ai/providers/{provider_id}
GET    /ai/audit-logs

11A.9 Modelo de aprovação humana

11B. Integrações: Google Workspace, OpenAI, Anthropic, Hostinger e Hermes Agent

O Avalia.EDUACESSO deverá possuir um barramento de integrações para conectar serviços institucionais, modelos de IA, hospedagem, armazenamento, automação e agentes externos. A arquitetura deve ser modular para evitar dependência rígida de um único provedor.

11B.1 Arquitetura de integração

Usuário
  ↓
Portal Avalia.EDUACESSO
  ↓
API Avalia.EDUACESSO
  ↓
AI Gateway / Integration Gateway
  ├── Google Workspace Connector
  ├── OpenAI Connector
  ├── Anthropic Connector
  ├── Hostinger Connector
  ├── Hermes Agent Connector
  └── Storage / Logs / Auditoria

11B.2 Google Workspace Connector

O conector Google Workspace deverá permitir que o Avalia.EDUACESSO leia, organize e gere documentos acadêmicos institucionais, respeitando permissões da conta e escopos autorizados.

Uso previsto

• Buscar PPC, ementas, planos de ensino e matrizes no Google Drive.
• Gerar provas e relatórios em Google Docs.
• Exportar resultados para Google Sheets.
• Enviar notificações por Gmail institucional, se autorizado.
• Organizar pastas por instituição, curso, turma, disciplina e avaliação.
• Guardar PDFs de provas, folhas de respostas e relatórios.

Requisitos

• OAuth 2.0 ou conta de serviço, conforme política da instituição.
• Escopos mínimos necessários.
• Controle por instituição.
• Logs de leitura, criação, edição e exportação.
• Não usar documentos do Drive sem autorização do usuário/instituição.

11B.3 OpenAI Connector

O conector OpenAI deverá permitir uso de modelos de linguagem para geração de questões, revisão pedagógica, feedback, rubricas, relatórios e automações textuais. As chaves devem ficar no servidor, nunca no frontend.

Uso previsto

• Geração de questões e alternativas.
• Revisão de enunciados e gabaritos.
• Criação de rubricas.
• Feedback individualizado.
• Relatórios interpretativos.
• Classificação de dificuldade e assunto.

Requisitos

• Chave por ambiente ou por instituição, conforme plano comercial.
• Controle de custo, limite de uso e auditoria.
• Registro de modelo usado, prompt, resposta e usuário solicitante.
• Mascaramento de dados pessoais antes do envio.

11B.4 Anthropic Connector

O conector Anthropic deverá permitir uso de modelos Claude para tarefas de análise, revisão, geração textual, avaliação por rubrica e raciocínio pedagógico. A integração deve seguir o mesmo padrão de segurança do AI Gateway.

Uso previsto

• Análise de provas longas e documentos acadêmicos.
• Revisão de coerência pedagógica.
• Criação de feedback estruturado.
• Geração de relatórios de turma e curso.
• Apoio à elaboração de matrizes avaliativas.

11B.5 Hostinger Connector

O conector Hostinger deverá apoiar a operação de infraestrutura do Avalia.EDUACESSO, especialmente em VPS, deploy, monitoramento, métricas, alertas e rotinas administrativas. Essa integração não deve acessar dados acadêmicos salvo necessidade técnica e autorização expressa.

Uso previsto

• Monitorar uso de CPU, memória, disco e tráfego do servidor.
• Gerar alertas de indisponibilidade ou alto consumo.
• Apoiar rotinas de deploy e manutenção.
• Registrar status da infraestrutura no painel técnico.
• Automatizar verificações de ambiente de homologação e produção.

11B.6 Hermes Agent Connector

O Hermes Agent deverá ser tratado como conector de agente externo ou auto-hospedado, usado para orquestrar tarefas de apoio técnico e operacional, como análise de arquivos, automação de rotinas, execução de fluxos, integração com terminal/servidor e acionamento de ferramentas. Como há variações de projetos e documentações com o nome Hermes, sua adoção deverá depender de validação técnica prévia da equipe.

Uso previsto

• Executar rotinas administrativas em ambiente controlado.
• Apoiar análise de documentos e arquivos acadêmicos.
• Orquestrar fluxos com múltiplos provedores de IA.
• Gerar relatórios técnicos de execução.
• Atuar como agente local quando a instituição optar por execução auto-hospedada.

Restrições obrigatórias

• Não deve executar comandos destrutivos sem autorização explícita.
• Não deve ter acesso irrestrito ao banco de produção.
• Deve operar com permissões mínimas.
• Deve registrar todas as ações executadas.
• Deve ter ambiente isolado para testes.

11B.7 Tabela de conectores

11B.8 Modelo de configuração de provedores

{
  "institution_id": "uuid",
  "provider": "openai",
  "enabled": true,
  "usage_policy": {
    "monthly_token_limit": 1000000,
    "allowed_tasks": [
      "generate_questions",
      "review_questions",
      "generate_feedback",
      "essay_correction_suggestion"
    ],
    "requires_human_approval": true,
    "mask_personal_data": true
  },
  "secrets_ref": "vault://institutions/{id}/openai",
  "default_model": "configured-by-admin"
}

11B.9 Segurança das integrações

• As chaves de API devem ser armazenadas em cofre de segredos ou variável de ambiente segura.
• O frontend nunca deve receber chaves de provedores.
• Toda chamada para IA deve passar pelo backend.
• O sistema deve registrar custo estimado, tokens/uso, provedor, modelo e finalidade.
• Dados pessoais devem ser mascarados sempre que não forem indispensáveis.
• Integrações devem ser desativáveis por instituição.
• Deve haver fallback quando um provedor estiver indisponível.

11C. Modo de personalização dos portais: aluno e professor

O Avalia.EDUACESSO deverá possuir um modo de personalização para adaptar a experiência dos portais por instituição, perfil de usuário, curso, turma e finalidade acadêmica. O objetivo é permitir identidade visual própria, menus, widgets, permissões, mensagens e fluxos específicos para alunos e professores.

11C.1 Objetivos do modo de personalização

• Permitir que cada instituição utilize sua marca, logotipo, cores e domínio/subdomínio.
• Adaptar o portal do aluno para consulta de avaliações, notas, gabaritos, feedbacks e planos de estudo.
• Adaptar o portal do professor para criação de provas, banco de questões, correções e relatórios.
• Permitir ativar ou desativar módulos por instituição.
• Permitir configurar mensagens, banners, avisos e atalhos por perfil.
• Permitir layout white label para instituições parceiras.

11C.2 Portal do Aluno

O Portal do Aluno deve ser simples, responsivo e focado em transparência acadêmica. O aluno deve visualizar apenas informações liberadas pela instituição/professor.

Funcionalidades do Portal do Aluno

• Visualizar avaliações vinculadas à turma.
• Consultar nota quando publicada.
• Consultar gabarito quando liberado.
• Receber feedback por questão, assunto ou competência.
• Visualizar plano de estudo sugerido.
• Consultar histórico de avaliações.
• Baixar comprovante ou relatório individual, se permitido.
• Receber avisos institucionais e acadêmicos.
• Acessar documentos de apoio vinculados à avaliação.

Widgets configuráveis do aluno

11C.3 Portal do Professor

O Portal do Professor deve priorizar produtividade: criar prova, gerenciar banco de questões, usar agente de IA, gerar PDF, corrigir folhas, revisar respostas e emitir relatórios.

Funcionalidades do Portal do Professor

• Dashboard de avaliações em rascunho, geradas, em correção e fechadas.
• Banco de questões com filtros e revisão por IA.
• Assistente de IA para elaborar provas.
• Assistente de IA para revisar questões.
• Gerador de versões e PDF.
• Leitor/corretor de folha de respostas.
• Fila de revisão manual.
• Lançamento de notas discursivas.
• Relatórios de turma e disciplina.
• Exportação de resultados.
• Publicação ou bloqueio de gabarito.

Widgets configuráveis do professor

11C.4 Personalização visual

• Logotipo da instituição.
• Favicon.
• Cores primária, secundária e de destaque.
• Imagem de capa/login.
• Nome exibido do portal.
• Subdomínio: ies.avalia.eduacesso.com ou avalia.eduacesso.com/ies.
• Rodapé institucional.
• Termos de uso e política de privacidade por instituição.
• Templates de e-mail e notificações.
• Modelos de prova e folha de respostas por instituição.

11C.5 Personalização funcional

11C.6 Modelo de dados para personalização

11C.7 Endpoints sugeridos para personalização

GET    /portal/config
PUT    /portal/config

GET    /portal/theme
PUT    /portal/theme

GET    /portal/widgets
POST   /portal/widgets
PATCH  /portal/widgets/{widget_id}

GET    /portal/role-layouts/{role}
PUT    /portal/role-layouts/{role}

GET    /portal/feature-flags
PATCH  /portal/feature-flags/{feature_key}

GET    /portal/notification-templates
PUT    /portal/notification-templates/{event_key}

GET    /student-portal/dashboard
GET    /teacher-portal/dashboard

11C.8 Requisitos funcionais dos portais personalizados

12. Modelo de dados

12.1 Entidades principais

12.2 Convenções

• Chaves primárias em UUID.
• Datas em UTC no banco.
• Campos sensíveis com mascaramento em respostas públicas.
• Soft delete para entidades acadêmicas relevantes.
• Versionamento lógico de questões já utilizadas em avaliações.

13. Segurança, LGPD e auditoria

13.1 Segurança

• Autenticação por token seguro.
• Hash de senhas com algoritmo robusto.
• Controle de acesso por papel e instituição.
• Tokens de QR Code assinados com HMAC.
• Validação de upload de imagens.
• Limite de tamanho de arquivo.
• Proteção contra acesso cruzado entre instituições.
• Rate limit em endpoints sensíveis.

13.2 LGPD

• Coletar apenas dados necessários para finalidade acadêmica.
• Exibir CPF apenas quando indispensável e para perfis autorizados.
• Registrar finalidade do tratamento de dados acadêmicos.
• Permitir política de retenção para imagens de cartão-resposta.
• Permitir anonimização em relatórios estatísticos, quando aplicável.
• Controlar acesso aos resultados por perfil.

13.3 Auditoria obrigatória

14. Experiência do usuário

14.1 Princípios de interface

• Fluxos simples, com poucos passos para criar e corrigir provas.
• Linguagem acadêmica clara e objetiva.
• Botões de ação evidentes: criar, gerar, corrigir, revisar, exportar.
• Estados visuais para rascunho, gerada, em correção, pendente, fechada e publicada.
• Design responsivo para uso em desktop, tablet e celular.
• Pré-visualização antes da geração final do PDF.

14.2 Telas previstas

14.3 Acessibilidade

• Contraste adequado entre texto e fundo.
• Campos com labels visíveis.
• Navegação por teclado nas telas principais.
• Mensagens de erro claras.
• Compatibilidade com leitores de tela nas funções essenciais.

15. Requisitos não funcionais

15.1 Stack recomendada

• Backend: FastAPI, NestJS ou Laravel API.
• Banco: PostgreSQL.
• Fila/cache: Redis.
• Storage: S3 compatível, MinIO ou storage em nuvem.
• PDF: Playwright, Puppeteer, WeasyPrint ou serviço equivalente.
• Leitura OMR/OCR: OpenCV/serviço dedicado.
• Frontend: React, Vue, Next.js ou interface integrada ao EDUACESSO.

16. MVP

16.1 Objetivo do MVP

Entregar a primeira versão funcional capaz de criar avaliações, gerar PDF, gerar folha de respostas, receber imagem de cartão-resposta, corrigir questões objetivas, permitir revisão manual e exportar notas.

16.2 Funcionalidades obrigatórias do MVP

1. Login e controle de perfil básico.
2. Cadastro de instituição, curso, turma, estudante e professor.
3. Cadastro de questões objetivas e discursivas.
4. Banco de questões com filtros básicos.
5. Criação de avaliação por turma.
6. Associação de questões e pontuação.
7. Geração de versões da prova.
8. Geração de PDF da prova.
9. Geração de folha de respostas com QR Code.
10. Upload de imagem da folha.
11. Correção objetiva automática inicial.
12. Revisão manual.
13. Lançamento de nota discursiva.
14. Lista de resultados.
15. Exportação CSV/XLSX.
16. Logs de auditoria.
17. Agente de IA para geração preliminar de questões/provas com aprovação humana.
18. Agente de IA para revisão pedagógica de questões.
19. Configuração inicial do portal do aluno.
20. Configuração inicial do portal do professor.
21. Feature flag para ativar/desativar IA por instituição.

16.3 Entregáveis do MVP

17. Roadmap

18. Métricas de sucesso

19. Riscos e dependências

19.1 Riscos

19.2 Dependências

• Definição da stack final do EDUACESSO.
• Acesso ao ambiente de desenvolvimento/homologação.
• Mapeamento da autenticação atual.
• Modelo de dados de instituições, cursos, turmas e usuários.
• Definição do storage para PDFs e imagens.
• Padronização da folha de respostas.
• Definição do fluxo de integração com sistema acadêmico.

20. Critérios de aceite

20.1 Critérios gerais

• O sistema deve permitir login com perfil autorizado.
• O usuário deve acessar apenas dados da sua instituição.
• O professor deve conseguir criar uma avaliação completa.
• O professor deve conseguir cadastrar questões objetivas e discursivas.
• O sistema deve gerar PDF da prova e folha de respostas.
• O sistema deve gerar QR Code válido por avaliação/versão/aluno.
• O sistema deve receber imagem de folha de resposta.
• O sistema deve calcular nota objetiva.
• O sistema deve permitir revisão manual.
• O sistema deve permitir lançamento de nota discursiva.
• O sistema deve consolidar nota final.
• O sistema deve exportar resultados em CSV/XLSX.
• O sistema deve registrar logs de ações sensíveis.

20.2 Casos de teste mínimos

21. Plano de implantação

21.1 Implantação técnica

1. Criar ambiente de homologação em subdomínio separado.
2. Configurar banco PostgreSQL e storage de arquivos.
3. Implementar autenticação e permissões.
4. Implementar cadastro de base acadêmica.
5. Implementar banco de questões e avaliações.
6. Implementar geração de PDF e folha de respostas.
7. Implementar correção inicial e revisão manual.
8. Implementar relatórios e exportações.
9. Executar testes de segurança e isolamento por instituição.
10. Realizar piloto com uma turma real.

21.2 Piloto recomendado

• Selecionar 1 curso e 1 turma.
• Criar banco inicial de 30 a 50 questões.
• Aplicar uma avaliação objetiva com 10 a 20 questões.
• Corrigir as folhas pelo sistema.
• Comparar resultado automático com conferência manual.
• Ajustar folha de respostas e parâmetros de leitura.
• Expandir para demais cursos e turmas.

22. Anexos técnicos

22.1 Status de avaliação

draft            = rascunho
generated        = versões/PDF gerados
correction_open  = correção aberta
closed           = avaliação fechada
archived         = avaliação arquivada

22.2 Status de correção

queued          = aguardando processamento
processing      = em processamento
pending_review  = pendente de revisão
completed       = concluída
failed          = falhou

22.3 Estrutura sugerida de repositório

eduacesso-avalia/
  backend/
    app/
    migrations/
    tests/
    openapi.yaml
  frontend/
    src/
    components/
    pages/
  docs/
    PRD_Avalia_EDUACESSO.html
    manual-operacional.md
  docker-compose.yml
  README.md

22.4 Prompt técnico para início no Codex

Analise completamente o projeto EDUACESSO antes de modificar qualquer arquivo.
Mapeie stack, rotas, banco, autenticação, módulos funcionais, dependências e deploy.
Depois proponha um plano incremental para implantar o módulo Avalia.EDUACESSO
em pasta, branch ou módulo isolado, sem quebrar a estrutura existente.

Objetivo: implementar o módulo de avaliações com banco de questões, criação de provas,
geração de versões, PDF, folha de respostas com QR Code, correção automática,
revisão manual, lançamento de notas, relatórios, exportações e logs de auditoria.