SteelBase/.kiro/specs/importador-inteligente-csv/requirements.md

Requirements Document

Introduction

Sistema inteligente de importação de CSV que permite ao usuário mapear colunas de forma visual e memoriza as configurações para futuras importações automáticas.

Glossary

• CSV: Arquivo de valores separados por vírgula contendo dados tabulares
• Mapeamento de Colunas: Correlação entre colunas do CSV e campos do sistema
• Perfil de Importação: Configuração salva de mapeamento para um tipo específico de material
• Campo Obrigatório: Campo que deve ser preenchido para importação válida
• Campo Opcional: Campo que pode ficar vazio sem impedir a importação
• Sistema: Aplicação AÇO CALC PRO
• Usuário: Engenheiro ou técnico que importa dados de materiais

Requirements

Requirement 1

User Story: Como usuário, quero importar um CSV com qualquer estrutura de colunas, para que eu possa usar dados de diferentes fornecedores sem precisar reformatar os arquivos.

Acceptance Criteria

1. WHEN o usuário seleciona um arquivo CSV, THE Sistema SHALL detectar automaticamente todas as colunas presentes
2. WHEN o Sistema detecta as colunas, THE Sistema SHALL exibir uma interface de mapeamento visual
3. WHEN o usuário visualiza o mapeamento, THE Sistema SHALL mostrar preview dos dados de cada coluna
4. WHERE existe um perfil de importação salvo, THE Sistema SHALL aplicar o mapeamento automaticamente
5. IF o CSV tem colunas não mapeadas, THEN THE Sistema SHALL permitir que o usuário as ignore ou mapeie

Requirement 2

User Story: Como usuário, quero mapear visualmente as colunas do CSV para os campos do sistema, para que eu possa garantir que os dados sejam importados corretamente.

Acceptance Criteria

1. THE Sistema SHALL exibir lado a lado as colunas do CSV e os campos esperados
2. WHEN o usuário arrasta uma coluna CSV, THE Sistema SHALL permitir soltar sobre um campo do sistema
3. WHEN o usuário mapeia uma coluna, THE Sistema SHALL mostrar preview dos valores que serão importados
4. THE Sistema SHALL destacar campos obrigatórios que ainda não foram mapeados
5. WHEN todos os campos obrigatórios estão mapeados, THE Sistema SHALL habilitar o botão de importação

Requirement 3

User Story: Como usuário, quero que o sistema sugira automaticamente o mapeamento de colunas, para que eu economize tempo em importações repetitivas.

Acceptance Criteria

1. WHEN o Sistema detecta colunas do CSV, THE Sistema SHALL comparar nomes com campos conhecidos
2. WHEN existe similaridade entre nomes, THE Sistema SHALL sugerir mapeamento automático
3. THE Sistema SHALL usar algoritmo de similaridade de strings (Levenshtein ou similar)
4. WHEN o Sistema sugere mapeamento, THE Sistema SHALL permitir que o usuário aceite ou modifique
5. THE Sistema SHALL considerar sinônimos comuns (ex: "diametro" = "diameter" = "diam")

Requirement 4

User Story: Como usuário, quero que o sistema memorize meus mapeamentos de colunas, para que importações futuras do mesmo tipo sejam automáticas.

Acceptance Criteria

1. WHEN o usuário completa um mapeamento, THE Sistema SHALL salvar o perfil no localStorage
2. THE Sistema SHALL associar o perfil ao tipo de material (cantoneiras, tubos, etc)
3. WHEN o usuário importa novamente o mesmo tipo, THE Sistema SHALL aplicar o perfil automaticamente
4. THE Sistema SHALL permitir que o usuário edite ou delete perfis salvos
5. THE Sistema SHALL exportar/importar perfis de mapeamento em JSON

Requirement 5

User Story: Como usuário, quero validar os dados antes da importação, para que eu possa corrigir erros antes de salvar no banco de dados.

Acceptance Criteria

1. WHEN o usuário mapeia as colunas, THE Sistema SHALL validar tipos de dados (números, texto)
2. WHEN existe erro de tipo, THE Sistema SHALL destacar a linha com erro
3. THE Sistema SHALL mostrar estatísticas de validação (X linhas válidas, Y com erro)
4. WHEN o usuário confirma importação, THE Sistema SHALL importar apenas linhas válidas
5. THE Sistema SHALL gerar relatório de erros com linhas que falharam

Requirement 6

User Story: Como usuário, quero converter unidades automaticamente durante a importação, para que eu possa usar CSVs com diferentes sistemas de medida.

Acceptance Criteria

1. WHEN o Sistema detecta coluna numérica, THE Sistema SHALL permitir especificar unidade
2. THE Sistema SHALL suportar conversões: mm↔pol, kg↔lb, MPa↔ksi
3. WHEN o usuário seleciona conversão, THE Sistema SHALL aplicar fator de conversão automaticamente
4. THE Sistema SHALL mostrar preview dos valores convertidos
5. THE Sistema SHALL salvar preferência de conversão no perfil de importação

Requirement 7

User Story: Como usuário, quero criar campos calculados durante a importação, para que eu possa derivar dados que não estão no CSV.

Acceptance Criteria

1. THE Sistema SHALL permitir criar campos calculados usando fórmulas
2. WHEN o usuário cria fórmula, THE Sistema SHALL validar sintaxe
3. THE Sistema SHALL suportar operações: +, -, *, /, potência, raiz
4. WHEN a fórmula é válida, THE Sistema SHALL calcular valores automaticamente
5. THE Sistema SHALL mostrar preview dos valores calculados

Requirement 8

User Story: Como usuário, quero categorizar automaticamente os itens durante a importação, para que eu não precise adicionar manualmente a categoria de cada item.

Acceptance Criteria

1. THE Sistema SHALL permitir definir regras de categorização
2. WHEN o usuário define regra, THE Sistema SHALL usar condições (SE...ENTÃO)
3. THE Sistema SHALL suportar condições baseadas em valores numéricos e texto
4. WHEN a regra é aplicada, THE Sistema SHALL atribuir categoria automaticamente
5. THE Sistema SHALL mostrar preview das categorias atribuídas

Requirement 9

User Story: Como usuário, quero importar múltiplos CSVs de uma vez, para que eu possa atualizar todo o banco de dados rapidamente.

Acceptance Criteria

1. THE Sistema SHALL permitir selecionar múltiplos arquivos CSV
2. WHEN múltiplos arquivos são selecionados, THE Sistema SHALL processar em lote
3. THE Sistema SHALL aplicar perfil de importação correspondente a cada arquivo
4. THE Sistema SHALL mostrar progresso de importação em tempo real
5. WHEN a importação em lote termina, THE Sistema SHALL gerar relatório consolidado

Requirement 10

User Story: Como usuário, quero exportar o banco de dados atual para CSV, para que eu possa fazer backup ou compartilhar dados.

Acceptance Criteria

1. THE Sistema SHALL permitir exportar cada tipo de material para CSV
2. WHEN o usuário exporta, THE Sistema SHALL incluir todas as colunas do banco
3. THE Sistema SHALL usar formato compatível com reimportação
4. THE Sistema SHALL permitir exportar todos os tipos de uma vez (ZIP)
5. THE Sistema SHALL incluir metadata (data de exportação, versão)