Import/Export

Guia do administrador para importação e exportação de dados de alunos, turmas e núcleos.

Visão Geral

A página Importar/Exportar permite:

• Exportar alunos, turmas e núcleos em CSV ou JSON para backup ou análise
• Importar alunos via arquivo CSV ou JSON, com validação linha-a-linha
• Baixar modelos vazios para preenchimento manual e importação em lote

Acesso restrito a Administradores (role ADMIN).

---

Exportar

1. Vá para Importar/Exportar → aba Exportar
2. Selecione a entidade: Estudantes, Turmas ou Núcleos
3. Selecione o formato: CSV ou JSON
4. Clique em Baixar

O arquivo gerado inclui todos os campos do schema atual, incluindo studentId, status e timestamps. Alunos com status: DELETED não são incluídos.

Formato CSV

Colunas planas (flat). Telefones expandidos em 6 colunas (phone1Number, phone1Qualifier, …). Endereço em 7 colunas (addressStreet, addressNumber, …). Booleanos como Sim/Não.

Coluna	Tipo	Descrição
studentId	UUID	Identificador único (apenas exportação)
Nome completo	string	displayName
Data de nascimento	YYYY-MM-DD	birthDate
Responsável	string	guardianName
Turma	string	Nome da turma (resolvido automaticamente)
Região	string	nucleusRegion (7 cores)
Participa do Núcleo	Sim/Não	nucleusParticipates
phone1Number	dígitos	Telefone principal
phone1Qualifier	string	Qualificador (Mãe, Pai, etc.)
addressStreet	string	Logradouro
…		(demais campos de endereço, alergias, necessidades especiais)

Formato JSON

Estrutura aninhada natural, idêntica ao tipo Student:

[
  {
    "studentId": "uuid",
    "displayName": "João Silva",
    "guardianName": "Maria Silva",
    "birthDate": "2020-01-15",
    "phones": [{ "number": "11999999999", "qualifier": "Mãe" }],
    "address": {
      "street": "Rua Principal",
      "number": "123",
      "complement": "",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zip": "01001000"
    },
    "classId": "uuid-da-turma",
    "nucleusParticipates": true,
    "nucleusRegion": "Azul",
    "nucleusName": "Azul Centro",
    "allergies": null,
    "specialNeeds": null,
    "status": "ACTIVE",
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z"
  }
]

---

Importar

Fluxo

1. Vá para Importar/Exportar → aba Importar
2. Arraste um arquivo .csv ou .json na zona de upload, ou clique para selecionar
3. O formato é detectado automaticamente
4. Selecione Pré-visualizar (dry-run) para ver o que será importado sem salvar
5. Revise as 3 seções:
   • ✅ Linhas prontas — serão importadas
   • ⚠️ Possíveis duplicatas — marque/desmarque quais importar
   • ❌ Linhas com erro — sempre ignoradas
6. Clique em Importar

Pré-visualização (dry-run)

Antes de importar, ative "Pré-visualizar" para ver exatamente o que acontecerá. Nenhum dado é salvo no modo dry-run.

A pré-visualização mostra:

• Número de linhas válidas (✅)
• Possíveis duplicatas com checkbox por linha (⚠️)
• Erros de validação com nome da criança + mensagem em português (❌)
• Resumo: "Importar X estudantes (Y duplicatas selecionadas, Z ignoradas por erro)"

Regras de validação

Regra	Erro
displayName obrigatório	"Nome completo é obrigatório"
guardianName obrigatório	"Responsável é obrigatório"
birthDate formato YYYY-MM-DD	"Data de nascimento inválida. Use o formato AAAA-MM-DD"
Turma deve existir	"Turma 'X' não encontrada. Turmas disponíveis: Berçário, Infantil, …"
Região inválida	"Região inválida. Use: Azul Celeste, Azul, Amarela, …"
Telefone inválido	"Telefone X: número inválido"
Max 3 telefones	"Máximo de 3 telefones por aluno"

Detecção de duplicatas

O sistema verifica se já existe um aluno com nome similar (distância de edição ≤ 2) E mesma data de nascimento ou mesmo responsável. Duplicatas são mostradas como ⚠️ aviso — você decide se importa ou pula cada uma.

Formatos aceitos

CSV: delimitador auto-detectado (, ; ou tab). Encoding UTF-8 (BOM tratado automaticamente). Datas no formato Excel (número serial) são convertidas automaticamente.

JSON: formato aninhado (com phones como array e address como objeto) ou formato plano (com phone1Number, addressStreet, etc.). Ambos são normalizados automaticamente.

Após a importação

• Alunos são criados localmente (IndexedDB) e enfileirados para sincronização
• O StatusIndicator mostrará a quantidade de itens pendentes de sync
• Se houver erros, você pode baixar o CSV apenas com as linhas com erro + coluna _erro

Limites

• Tamanho máximo do arquivo: 10 MB
• Máximo de linhas por importação: 1000

---

Modelos

1. Vá para Importar/Exportar → aba Modelos
2. Selecione a entidade: Estudantes, Turmas ou Núcleos
3. Selecione o formato: CSV ou JSON
4. Clique em Baixar modelo

O modelo CSV inclui:

• Cabeçalho com todos os campos
• Uma linha de exemplo com valores formatados ((11) 98765-4321, Sim, Berçário)
• Nome do arquivo: neemias-template-estudantes-v1.1.0.csv

O modelo JSON é um array vazio [].

---

Troubleshooting

Problema	Solução
"Formato não reconhecido"	Verifique se o arquivo é .csv ou .json válido. Formatos detectados automaticamente.
"Turma 'X' não encontrada"	O nome da turma no CSV deve corresponder exatamente a uma turma existente. Cadastre a turma em Turmas primeiro.
Datas aparecem como números	Excel pode salvar datas como números seriais. O importador converte automaticamente. Se falhar, salve o CSV como "CSV UTF-8" no Excel.
Caracteres acentuados quebrados	Salve o arquivo como UTF-8. No Excel: "Salvar como" → "CSV UTF-8 (delimitado por vírgulas)".
Telefones não reconhecidos	O parser aceita qualquer formato: (11) 98765-4321, 11987654321, 11 98765-4321. Dígitos são extraídos automaticamente.

---

Referência de Campos

A lista completa de campos é derivada do schema atual. Consulte app/src/modules/importExport/fieldManifest.ts para a definição canônica. Para adicionar um campo novo ao sistema, siga o guia Extending Student Fields.