SteelBase/.kiro/specs/sistema-cache-perfis/requirements.md

Requirements Document - Sistema de Cache de Perfis

Introduction

Sistema de cache intermediário para armazenar dados de perfis estruturais carregados de arquivos CSV. O sistema permitirá carregar dados uma vez, armazená-los localmente no navegador (IndexedDB), e fornecer uma interface para atualizar/sincronizar quando os arquivos CSV forem modificados.

Glossary

• IndexedDB: Banco de dados NoSQL do navegador para armazenamento local persistente
• CSV Source: Arquivos CSV originais em BD/perfis/
• Cache Layer: Camada intermediária que armazena dados processados
• Sync Manager: Componente responsável por sincronizar dados entre CSV e cache
• Data Service: API unificada para acesso aos dados de perfis
• Admin Panel: Interface administrativa para gerenciar o cache

Requirements

Requirement 1: Armazenamento Local com IndexedDB

User Story: Como desenvolvedor, quero armazenar dados de perfis localmente no navegador, para que o aplicativo não precise carregar CSVs repetidamente.

Acceptance Criteria

1. WHEN o aplicativo inicializa, THE Sistema SHALL criar um banco IndexedDB chamado "AcoCalcProDB"
2. THE Sistema SHALL criar object stores separadas para cada tipo de perfil (cantoneiras, perfis_w, perfis_i, etc.)
3. THE Sistema SHALL armazenar metadados incluindo timestamp de última atualização e versão dos dados
4. THE Sistema SHALL persistir dados entre sessões do navegador
5. THE Sistema SHALL suportar até 50MB de dados armazenados

Requirement 2: Carregamento Inteligente de Dados

User Story: Como usuário, quero que o aplicativo carregue dados rapidamente, para que eu não precise esperar toda vez que abrir uma seção.

Acceptance Criteria

1. WHEN o usuário acessa uma seção de perfil, THE Sistema SHALL verificar se dados existem no cache local
2. IF dados existem no cache, THEN THE Sistema SHALL carregar do cache em menos de 100ms
3. IF dados não existem no cache, THEN THE Sistema SHALL carregar do CSV e armazenar no cache
4. THE Sistema SHALL exibir indicador de loading durante carregamento inicial
5. THE Sistema SHALL funcionar offline após primeiro carregamento

Requirement 3: Interface de Sincronização

User Story: Como administrador, quero atualizar os dados do cache quando modificar arquivos CSV, para que as alterações sejam refletidas no aplicativo.

Acceptance Criteria

1. THE Sistema SHALL fornecer botão "🔄 Atualizar Dados" no painel administrativo
2. WHEN usuário clica em atualizar, THE Sistema SHALL recarregar todos os CSVs
3. THE Sistema SHALL mostrar progresso da sincronização (0-100%)
4. THE Sistema SHALL exibir timestamp da última sincronização
5. THE Sistema SHALL permitir atualização seletiva por tipo de perfil

Requirement 4: Versionamento e Validação

User Story: Como desenvolvedor, quero detectar quando dados estão desatualizados, para que o sistema possa atualizar automaticamente.

Acceptance Criteria

1. THE Sistema SHALL armazenar hash MD5 de cada arquivo CSV
2. WHEN aplicativo inicializa, THE Sistema SHALL comparar hashes dos arquivos
3. IF hash mudou, THEN THE Sistema SHALL marcar dados como desatualizados
4. THE Sistema SHALL exibir notificação quando dados estiverem desatualizados
5. THE Sistema SHALL permitir configurar atualização automática ou manual

Requirement 5: API Unificada de Acesso

User Story: Como desenvolvedor, quero uma API simples para acessar dados, para que não precise me preocupar se vêm do cache ou CSV.

Acceptance Criteria

1. THE Sistema SHALL fornecer função getPerfis(tipo) que retorna dados do cache ou CSV
2. THE Sistema SHALL fornecer função searchPerfis(tipo, filtros) para busca com filtros
3. THE Sistema SHALL fornecer função getPerfilById(tipo, id) para busca por ID
4. THE Sistema SHALL retornar Promises para todas operações assíncronas
5. THE Sistema SHALL tratar erros gracefully com fallback para CSV

Requirement 6: Gerenciamento de Espaço

User Story: Como usuário, quero gerenciar o espaço usado pelo cache, para que não ocupe muito armazenamento do navegador.

Acceptance Criteria

1. THE Sistema SHALL exibir espaço total usado pelo cache no painel admin
2. THE Sistema SHALL permitir limpar cache de tipos específicos de perfis
3. THE Sistema SHALL permitir limpar todo o cache com um botão
4. THE Sistema SHALL avisar quando espaço disponível for menor que 10MB
5. THE Sistema SHALL funcionar mesmo se IndexedDB não estiver disponível (fallback para CSV)

Requirement 7: Migração e Compatibilidade

User Story: Como desenvolvedor, quero migrar dados existentes para o novo sistema, para que não haja perda de funcionalidade.

Acceptance Criteria

1. THE Sistema SHALL detectar se é primeira execução
2. WHEN primeira execução, THE Sistema SHALL carregar todos os CSVs e popular cache
3. THE Sistema SHALL manter compatibilidade com código existente
4. THE Sistema SHALL permitir desabilitar cache via configuração
5. THE Sistema SHALL migrar automaticamente entre versões do schema

Requirement 8: Monitoramento e Debug

User Story: Como desenvolvedor, quero monitorar operações do cache, para que possa debugar problemas.

Acceptance Criteria

1. THE Sistema SHALL logar todas operações de cache no console (modo debug)
2. THE Sistema SHALL exibir estatísticas de hit/miss do cache
3. THE Sistema SHALL permitir exportar dados do cache para JSON
4. THE Sistema SHALL permitir importar dados de JSON para cache
5. THE Sistema SHALL fornecer ferramenta de diagnóstico no painel admin

Requirement 9: Performance e Otimização

User Story: Como usuário, quero que o aplicativo seja rápido, para que eu possa trabalhar eficientemente.

Acceptance Criteria

1. THE Sistema SHALL carregar dados do cache em menos de 100ms
2. THE Sistema SHALL indexar campos comuns (nome, tipo) para busca rápida
3. THE Sistema SHALL usar Web Workers para parsing de CSV em background
4. THE Sistema SHALL implementar lazy loading para perfis não utilizados
5. THE Sistema SHALL comprimir dados antes de armazenar (se >1MB)

Requirement 10: Configuração Flexível de Fontes

User Story: Como administrador, quero configurar caminhos dos arquivos CSV, para que possa reorganizar estrutura de pastas.

Acceptance Criteria

1. THE Sistema SHALL permitir configurar caminho base dos CSVs no painel admin
2. THE Sistema SHALL permitir configurar nome de arquivo para cada tipo de perfil
3. THE Sistema SHALL validar se arquivos existem antes de tentar carregar
4. THE Sistema SHALL salvar configuração no localStorage
5. THE Sistema SHALL fornecer configuração padrão funcional

Technical Constraints

• Deve funcionar em navegadores modernos (Chrome 60+, Firefox 60+, Safari 12+, Edge 79+)
• Deve usar apenas JavaScript vanilla (sem frameworks)
• Deve ser compatível com código existente
• Deve funcionar offline após primeiro carregamento
• Deve ter fallback para CSV se IndexedDB não disponível

Non-Functional Requirements

• Performance: Carregamento do cache < 100ms
• Reliability: Taxa de sucesso > 99.9%
• Usability: Interface intuitiva no painel admin
• Maintainability: Código modular e bem documentado
• Scalability: Suportar até 10.000 registros por tipo de perfil