Validador CSV OneRoster: Integridade de Dados 1EdTech Rigorosa e Linter de Pré-Verificação

Realize validação rigorosa de pré-verificação em pacotes de listas CSV OneRoster v1.1 e v1.2 antes da ingestão SIS/Clever/ClassLink: audite a integridade referencial de chaves estrangeiras, elimine matrículas órfãs, aplique particionamento bulk vs delta e sanitize armadilhas de codificação.

Quando Usar Esta Habilidade

Ative esta habilidade quando:

• Validar ou depurar pacotes de exportação de listas de sistemas de informação de alunos (SIS) (arquivos .zip ou diretórios CSV) para conformidade com OneRoster v1.1 ou v1.2.
• O usuário perguntar: "Por que o Clever está rejeitando nosso arquivo zip OneRoster?", "Verificar usuários órfãos userSourcedIds em enrollments.csv", "Validar modo bulk vs delta em CSVs OneRoster" ou "Sanitizar caracteres UTF-8 BOM de listas escolares".
• Auditar a integridade relacional entre manifest.csv, orgs.csv, users.csv, courses.csv, classes.csv, enrollments.csv e academicSessions.csv.
• Preparar pipelines automatizados de CI/CD de pré-verificação para capturar registros de alunos ou professores corrompidos antes das execuções de sincronização noturna do SIS.

NÃO use esta habilidade quando:

• Integrar endpoints de API OneRoster REST / OAuth 2.0 (esta habilidade foca estritamente em associações de tabelas CSV).
• Gerar PII de alunos sintética ou fabricada sem autorização.
• Trabalhar em planilhas CSV genéricas não padronizadas que não seguem as especificações 1EdTech.

Modelos Mentais Principais e Regras Inegociáveis

1. A Lei da Autoridade Raiz do Manifest:

   • manifest.csv DEVE residir estritamente no nível raiz do arquivo ZIP (nunca aninhado dentro de uma subpasta).
   • DEVE declarar a versão exata da especificação: oneroster.version,1.1 ou oneroster.version,1.2.
   • DEVE listar todos os arquivos presentes na troca. Se um arquivo CSV estiver presente no arquivo, mas omitido de manifest.csv, ou listado em manifest.csv, mas ausente do zip, o pacote é rejeitado.

2. A Partição Estrita Bulk vs Delta:

   • Um pacote de troca = estritamente UM modo operacional.
   • Modo de Troca Bulk: Representa um snapshot mestre completo. No OneRoster 1.1, as linhas NÃO DEVEM conter colunas dateLastModified ou status. No 1.2, todos os campos de status DEVEM ser active.
   • Modo de Troca Delta: Representa mudanças incrementais. Cada linha DEVE conter um timestamp UTC ISO 8601 válido (YYYY-MM-DDTHH:MM:SS.sssZ) em dateLastModified e um status válido (active ou tobedeleted).
   • Misturar formatos bulk e delta dentro do mesmo arquivo é uma falha fatal de validação.

3. A Hierarquia de Integridade Referencial de Chaves Estrangeiras:

   • Cadeia de dependência relacional: $$\mathbf{orgs.csv} \longleftarrow \mathbf{courses.csv} \longleftarrow \mathbf{classes.csv} \longleftarrow \mathbf{enrollments.csv} \longrightarrow \mathbf{users.csv}$$
   • Cada schoolSourcedId em users.csv e classes.csv DEVE resolver para um sourcedId existente em orgs.csv.
   • Cada courseSourcedId em classes.csv DEVE resolver para courses.csv.
   • Cada userSourcedId e classSourcedId em enrollments.csv DEVE resolver para chaves primárias ativas em users.csv e classes.csv.
   • Tolerância Zero a Órfãos: Um único link órfão (por exemplo, matricular um ID de aluno excluído) invalida o lote.

4. Axiomas de Restrição Estrita de Enumeração de Papéis:

   • Em users.csv: role DEVE corresponder estritamente ao enum OneRoster:
     • v1.1: administrator, proctor, student, teacher.
     • v1.2: adiciona aide, guardian, parent, staff.
   • Em enrollments.csv: role é estritamente restrito a administrator, proctor, student, teacher. Papéis de fornecedor personalizados (substitute, dean) devem ser mapeados para enums de especificação válidos.
   • Valores primários de sourcedId DEVEM ser strings únicas sensíveis a maiúsculas e minúsculas (formato UUID RFC 4122 fortemente recomendado).

5. Sanitização RFC 4180 CSV & UTF-8 BOM:

   • Arquivos DEVEM ser codificados em UTF-8 sem Byte Order Mark (BOM).
   • O Microsoft Excel frequentemente adiciona \xEF\xBB\xBF antes das exportações CSV, corrompendo o nome da primeira coluna (sourcedId $\neq$ sourcedId).
   • Campos contendo vírgulas, aspas duplas ou novas linhas DEVEM ser colocados entre aspas duplas ("). Aspas literais dentro de campos devem ser escapadas como "".

Pecados Nomeados e Anti-Padrões (Что категорически ЗАПРЕЩЕНО)

…