Pular para conteúdo

ADR-005 — Núcleo Curricular Canônico

Status: Aprovado — implementação concluída até Cobertura Curricular v2
Data: 2026-09-07

Contexto

O SIGESC possui uma base curricular v2 com BNCC, adaptações municipais, SkillPicker e Cobertura Curricular, porém a modelagem atual mistura referência curricular, organização local, objeto de conhecimento e registro docente. Além disso, o fluxo canônico de conteúdo (content_entries) não persiste hoje as relações selecionadas no SkillPicker, enquanto a Cobertura Curricular ainda calcula o realizado a partir de learning_objects.adaptation_ids, uma fonte legada.

A evolução aprovada exige suportar fontes curriculares oficiais por mantenedora, Plano de Ensino Bimestral versionado, registro docente estruturado e, no futuro, avaliação ligada a habilidades e evidências individuais de aprendizagem.

Decisão

1. Cadeia canônica

O SIGESC adota a seguinte cadeia conceitual:

Fontes Curriculares Oficiais → Versão Curricular → Plano de Ensino Bimestral → Registro Docente → Cobertura Curricular → Avaliação → Evidência de Aprendizagem → Intervenção.

As camadas planejado, trabalhado, avaliado e aprendido/evidenciado são distintas e não podem ser inferidas umas das outras sem evidência explícita.

2. Fontes curriculares

O sistema deve representar documentos oficiais por curriculum_sources, incluindo, conforme aplicabilidade ao componente:

  • BNCC;
  • Complemento/BNCC da Computação federal;
  • Documento Curricular Municipal (DCM);
  • Referenciais curriculares municipais específicos, como Computação e Educação Digital.

A identidade e o texto de origem devem ser preservados. Normalização técnica não altera silenciosamente a fonte documental.

3. Versionamento

Cada mantenedora pode publicar versões curriculares com vigência temporal. Uma consulta histórica de 2026 deve continuar usando a versão que valia em 2026, mesmo após alterações de 2027.

4. Plano de Ensino Bimestral

O plano é versionado por, no mínimo:

  • mantenedora_id;
  • academic_year;
  • etapa/ano ou faixa aplicável;
  • component_id;
  • bimestre/período.

O plano contém itens que relacionam habilidades, objetos de conhecimento, objetivos/orientações e práticas/sugestões metodológicas. Habilidades de faixa (EF15COxx, EF69COxx) devem ser representáveis sem forçar um único ano.

5. Registro docente

content_entries continua sendo a SSoT de novas escritas do que foi efetivamente ministrado.

O contrato evolui de forma aditiva para guardar, quando aplicável:

  • referências de habilidades selecionadas;
  • referências de objetos de conhecimento selecionados;
  • objetos de conhecimento livres criados via NOVO;
  • referências de práticas pedagógicas selecionadas;
  • práticas livres via NOVO/Outra prática;
  • referência/snapshot da revisão do Plano de Ensino que orientou o lançamento.

Uma aula pode possuir múltiplas habilidades, objetos e práticas.

6. Migração sem inferência

O campo histórico content, atualmente rotulado na UI como Conteúdo/Objeto de Conhecimento, passa a significar somente Conteúdo.

Todo valor já gravado é preservado integralmente em content. Não haverá separação automática de texto, NLP, IA, regex ou heurística para inventar Objetos de Conhecimento ou habilidades históricas.

methodology histórico permanece preservado como descrição textual de Práticas Pedagógicas.

7. Governança de NOVO

  • Habilidade: não pode ser criada livremente pelo professor. Habilidade local nova exige fluxo curricular autorizado da mantenedora.
  • Objeto de Conhecimento: professor pode registrar NOVO no contexto da aula; isso não altera o plano oficial.
  • Prática Pedagógica: professor pode selecionar sugestões ou registrar livremente uma prática diferente; não exige alteração curricular.

8. Cobertura Curricular v2

O denominador deixa de ser a lista genérica de adaptações ativas e passa a ser o conjunto de itens do Plano de Ensino publicado para o escopo consultado.

O numerador passa a ser derivado exclusivamente de relações estruturadas em content_entries, nunca de novas escritas em learning_objects.

A cobertura deve distinguir:

  • previsto e trabalhado;
  • previsto e pendente;
  • trabalhado fora do plano;
  • histórico não estruturado;
  • período futuro;
  • plano inexistente.

Sem plano publicado, o sistema não deve fabricar percentual de cobertura.

9. Permissões

São capacidades distintas:

  • leitura/consulta curricular;
  • gestão curricular;
  • publicação de versão/plano.

A política deve ser aplicada no backend e refletida no frontend. O tenant é sempre derivado do contexto autenticado/selecionado; um mantenedora_id arbitrário enviado pelo cliente não pode ampliar escopo.

10. Preparação para aprendizagem

O modelo futuro deve suportar a cadeia:

Avaliação → Questão/Item → Habilidade(s) → Resposta do estudante → Resultado da questão → Evidência → Situação de domínio.

Acerto de questão não equivale automaticamente a habilidade consolidada. A geração de avaliação e correção automática/assistida permanecem sob supervisão humana.

Estado de implementação — 2026-09-07

A implementação aprovada neste ciclo alcançou, em produção, a cadeia até Cobertura Curricular v2:

  • F2/F3 — Fontes, versões e Plano de Ensino Bimestral: integrada no PR #523, merge 17d53cf2281eb2f92463e229442a3ff2db200314, promovida pelo release protegido #524 (run 34167106353).
  • F4 — Registro docente canônico: integrada no PR #525, merge 157cee1f61294645c986702893093617b280f001, promovida pelo release protegido #526 (run 34168513959). Novas escritas docentes do fluxo migrado usam content_entries; learning_objects permanece somente como fallback histórico/compatibilidade.
  • F5 — Cobertura Curricular v2: integrada no PR #527, merge 2c203568d9575b47bd66345695692a88de3a7743, promovida pelo release protegido #528 (run 34170558542). O release concluiu com SHA público/health, proveniência do runtime e continuidade do volume Mongo verificados; rollback compensatório não foi acionado.

A Cobertura v2 usa o Plano de Ensino publicado como denominador e relações estruturadas de content_entries como numerador. A cobertura legada continua disponível durante o rollout para compatibilidade histórica, sem ser a fonte das novas escritas.

Evolução operacional derivada da Cobertura — 2026-09-08

A S5.5 — Intervenções Curriculares implementou alertas operacionais preventivos derivados exclusivamente da Cobertura F5 e do calendário letivo institucional. A etapa foi integrada pelo PR #549, merge c9c9f2bdf508e91ec5ddda508e0856777d92a8b2, e certificada em produção pelo release protegido #550, workflow SIGESC Production Release run 34185424070 (número 174). O release verificou SHA público/health, proveniência do runtime e continuidade do volume Mongo; rollback compensatório não foi acionado.

Essa S5.5 não representa a implementação do elo arquitetural final de Intervenção baseado em evidência individual de aprendizagem. Trata-se de intervenção operacional sobre atraso de cobertura curricular — isto é, sobre a relação entre planejado e trabalhado — sem inferir avaliação, domínio de habilidade ou aprendizagem do estudante.

Assim, os elos canônicos seguintes — Avaliação → Evidência de Aprendizagem → Intervenção baseada em evidência — permanecem como direção arquitetural aprovada, mas não fazem parte do escopo implementado neste ciclo. Qualquer implementação desses elos exige especificação funcional/técnica própria antes de código, para preservar a separação entre planejado, trabalhado, avaliado e aprendido/evidenciado.

Consequências

Positivas

  • elimina a ambiguidade entre conteúdo e objeto de conhecimento;
  • reconecta o diário canônico à cobertura;
  • preserva histórico sem inferência destrutiva;
  • torna o currículo auditável por fonte e vigência;
  • prepara o sistema para avaliações alinhadas ao que foi planejado e efetivamente ensinado;
  • permite futura análise de aprendizagem por habilidade e estudante.

Custos

  • exige novas coleções/contratos e índices;
  • exige atualização coordenada de backend e frontend;
  • cobertura legada deve conviver temporariamente com Cobertura v2 durante o rollout;
  • planos antigos sem estrutura curricular permanecem classificados como histórico não estruturado, em vez de receber dados inventados.

Restrições de implantação

  1. mudanças devem ser aditivas antes de qualquer remoção;
  2. nenhuma escrita nova em learning_objects;
  3. nenhum backfill automático de habilidade/objeto a partir de texto livre;
  4. todos os novos documentos tenant-scoped devem conter mantenedora_id e ser consultados fail-closed;
  5. índices devem ser criados de forma idempotente;
  6. rollout deve possuir testes de isolamento, compatibilidade histórica e cobertura v2;
  7. deploy só ocorre com CI verde e promoção protegida conforme o runbook de produção.