300 lines
9.8 KiB
Markdown
300 lines
9.8 KiB
Markdown
# 📋 Requisitos Técnicos - Sistema de Persistência Robustas
|
|
|
|
## 🎯 Objetivo
|
|
|
|
Implementar um sistema de persistência robusto que garanta que todas as personalizações e configurações do painel administrativo do Aço Calc Pro permaneçam inalteradas durante o uso e recarregamento do aplicativo.
|
|
|
|
## 📊 Situação Atual
|
|
|
|
### **Sistema Existente**
|
|
- ✅ Data Manager com cache localStorage (24h TTL)
|
|
- ✅ Storage Manager para preferências básicas
|
|
- ✅ Cache Manager com IndexedDB
|
|
- ❌ **Admin Panel sem persistência de configurações**
|
|
|
|
### **Problemas Identificados**
|
|
1. Configurações do admin panel não são salvas
|
|
2. Sem sistema de backup/restauração
|
|
3. Sem migração de dados entre versões
|
|
4. Sem monitoramento de integridade
|
|
5. Falta feedback visual de persistência
|
|
|
|
## 🏗️ Requisitos Funcionais
|
|
|
|
### **RF01 - Sistema de Configurações Administrativas**
|
|
- [ ] Criar sistema centralizado de configurações admin
|
|
- [ ] Persistir nome do aplicativo
|
|
- [ ] Persistir subtítulo do aplicativo
|
|
- [ ] Persistir texto do rodapé
|
|
- [ ] Persistir tema padrão (escuro/claro)
|
|
- [ ] Persistir modo padrão (simples/experto)
|
|
- [ ] Persistir visibilidade de cada ferramenta (20+ ferramentas)
|
|
- [ ] Persistir intervalo de atualização de dados
|
|
- [ ] Persistir configurações de backup automático
|
|
|
|
### **RF02 - Interface de Configuração**
|
|
- [ ] Adicionar seção de configurações no painel admin
|
|
- [ ] Criar formulários para cada tipo de configuração
|
|
- [ ] Implementar salvamento automático (onchange)
|
|
- [ ] Adicionar botão de reset para configurações padrão
|
|
- [ ] Mostrar preview das mudanças em tempo real
|
|
- [ ] Adicionar validação de inputs
|
|
|
|
### **RF03 - Sistema de Backup/Restauração**
|
|
- [ ] Criar backup automático antes de mudanças significativas
|
|
- [ ] Implementar backup manual via botão
|
|
- [ ] Criar lista de backups disponíveis
|
|
- [ ] Implementar restauração seletiva por backup
|
|
- [ ] Adicionar confirmação antes de restaurar
|
|
- [ ] Limitar número de backups (máx 5)
|
|
- [ ] Exportar backup como arquivo JSON
|
|
|
|
### **RF04 - Persistência de Estado da UI**
|
|
- [ ] Salvar última aba ativa do sidebar
|
|
- [ ] Salvar estado de colapsos/expansões
|
|
- [ ] Salvar filtros aplicados em cada seção
|
|
- [ ] Salvar ordenação de tabelas
|
|
- [ ] Salvar tamanho de colunas redimensionadas
|
|
- [ ] Salvar posição de scroll quando relevante
|
|
|
|
### **RF05 - Sistema de Migração**
|
|
- [ ] Detectar versão atual vs salva
|
|
- [ ] Executar migrações automáticas quando necessário
|
|
- [ ] Criar logs de migração
|
|
- [ ] Implementar rollback em caso de falha
|
|
- [ ] Notificar usuário sobre migrações realizadas
|
|
|
|
### **RF06 - Monitoramento e Debugging**
|
|
- [ ] Criar dashboard de saúde do sistema
|
|
- [ ] Mostrar uso de storage (localStorage/IndexedDB)
|
|
- [ ] Exibir últimas operações realizadas
|
|
- [ ] Adicionar sistema de logs persistentes
|
|
- [ ] Exportar logs para troubleshooting
|
|
- [ ] Mostrar erros de forma amigável
|
|
|
|
### **RF07 - Feedback Visual**
|
|
- [ ] Adicionar toast notifications para ações
|
|
- [ ] Mostrar indicador de salvamento
|
|
- [ ] Adicionar animações de sucesso
|
|
- [ ] Mostrar progresso de operações longas
|
|
- [ ] Adicionar indicadores de erro
|
|
|
|
## 🔧 Requisitos Técnicos
|
|
|
|
### **RT01 - Armazenamento**
|
|
- **localStorage**: Para configurações pequenas (< 5MB)
|
|
- **IndexedDB**: Para dados grandes e backups
|
|
- **Fallback**: Funcionar sem storage (modo básico)
|
|
- **Quota**: Monitorar e respeitar limites do navegador
|
|
- **Validação**: Validar dados antes de salvar
|
|
|
|
### **RT02 - Performance**
|
|
- **Salvamento**: < 100ms para configurações simples
|
|
- **Carregamento**: < 200ms para restaurar estado completo
|
|
- **Backup**: < 1s para criar backup completo
|
|
- **Memória**: < 10MB adicionais em memória
|
|
- **CPU**: Operações assíncronas, não bloquear UI
|
|
|
|
### **RT03 - Segurança**
|
|
- **Sanitização**: Sanitizar todos os inputs
|
|
- **Validação**: Validar tipos e ranges de dados
|
|
- **Escopo**: Isolar dados por aplicação
|
|
- **Limpeza**: Remover dados sensíveis de logs
|
|
|
|
### **RT04 - Compatibilidade**
|
|
- **Browsers**: Chrome 60+, Firefox 55+, Safari 11+, Edge 79+
|
|
- **Mobile**: Suporte para navegadores mobile modernos
|
|
- **Storage**: Detectar e lidar com storage indisponível
|
|
- **Fallback**: Funcionalidade básica sem storage
|
|
|
|
### **RT05 - Manutenibilidade**
|
|
- **Modular**: Cada sistema em classe separada
|
|
- **Documentado**: JSDoc completo para todas funções
|
|
- **Testável**: Funções puras quando possível
|
|
- **Logs**: Logging adequado para debugging
|
|
|
|
## 📐 Arquitetura Proposta
|
|
|
|
### **Estrutura de Classes**
|
|
|
|
```javascript
|
|
// Gerenciadores principais
|
|
class AdminConfigManager // Configurações administrativas
|
|
class BackupManager // Backup e restauração
|
|
class MigrationManager // Migração entre versões
|
|
class PersistentLogger // Logs persistentes
|
|
class SystemHealthMonitor // Monitoramento de saúde
|
|
|
|
// Integração com existente
|
|
class EnhancedDataManager extends DataManager
|
|
class EnhancedStorage extends Storage
|
|
```
|
|
|
|
### **Estrutura de Dados**
|
|
|
|
```javascript
|
|
// Config admin persistida
|
|
interface AdminConfig {
|
|
version: string;
|
|
appName: string;
|
|
appSubtitle: string;
|
|
footerText: string;
|
|
themeDefault: 'escuro' | 'claro';
|
|
modeDefault: 'simples' | 'experto';
|
|
toolsVisibility: Record<string, boolean>;
|
|
dataRefreshInterval: number; // horas
|
|
autoBackup: boolean;
|
|
backupInterval: number; // dias
|
|
lastBackup: number | null;
|
|
uiState: {
|
|
activeSidebarTab: number;
|
|
collapsedSections: string[];
|
|
appliedFilters: Record<string, any>;
|
|
tableSort: Record<string, { column: string; direction: 'asc' | 'desc' }>;
|
|
columnWidths: Record<string, number>;
|
|
scrollPositions: Record<string, number>;
|
|
};
|
|
}
|
|
|
|
// Backup completo
|
|
interface BackupData {
|
|
timestamp: number;
|
|
version: string;
|
|
config: AdminConfig;
|
|
preferences: UserPreferences;
|
|
cacheStats: CacheStats;
|
|
logs: LogEntry[];
|
|
}
|
|
```
|
|
|
|
## 🎨 Interface de Usuário
|
|
|
|
### **Novos Elementos no Admin Panel**
|
|
|
|
1. **Aba "Configurações"**
|
|
- Formulário de config gerais
|
|
- Toggle switches para ferramentas
|
|
- Inputs para textos customizados
|
|
- Selects para temas e modos
|
|
|
|
2. **Aba "Backup & Restore"**
|
|
- Botão "Criar Backup Agora"
|
|
- Lista de backups existentes
|
|
- Botões "Restaurar" para cada backup
|
|
- Botão "Exportar Config"
|
|
- Botão "Importar Config"
|
|
|
|
3. **Aba "System Health"**
|
|
- Uso de storage (gráfico/barra)
|
|
- Status de cada componente
|
|
- Últimas operações
|
|
- Botão "Exportar Logs"
|
|
- Botão "Limpar Tudo"
|
|
|
|
### **Toast Notifications**
|
|
```javascript
|
|
// Novo sistema de notificações
|
|
class ToastManager {
|
|
show(message, type = 'info', duration = 3000) {
|
|
// Criar e exibir toast
|
|
}
|
|
|
|
success(message) { this.show(message, 'success'); }
|
|
error(message) { this.show(message, 'error', 5000); }
|
|
warning(message) { this.show(message, 'warning', 4000); }
|
|
info(message) { this.show(message, 'info'); }
|
|
}
|
|
```
|
|
|
|
## 🧪 Testes Requeridos
|
|
|
|
### **Testes Unitários**
|
|
- [ ] AdminConfigManager.saveConfig() persiste corretamente
|
|
- [ ] AdminConfigManager.getConfig() retorna valores salvos
|
|
- [ ] BackupManager.createBackup() cria backup válido
|
|
- [ ] BackupManager.restoreBackup() restaura corretamente
|
|
- [ ] MigrationManager detecta e executa migrações
|
|
|
|
### **Testes de Integração**
|
|
- [ ] Configurações sobrevivem a reload da página
|
|
- [ ] Backup é criado antes de mudanças críticas
|
|
- [ ] Restauração funciona de backups antigos
|
|
- [ ] UI reflete mudanças de configuração
|
|
- [ ] Performance dentro dos limites especificados
|
|
|
|
### **Testes de Aceitação**
|
|
- [ ] Usuário consegue alterar nome do app
|
|
- [ ] Usuário consegue mostrar/ocultar ferramentas
|
|
- [ ] Usuário consegue criar e restaurar backup
|
|
- [ ] Usuário recebe feedback de ações
|
|
- [ ] Sistema funciona após reload do navegador
|
|
|
|
## 📋 Checklist de Implementação
|
|
|
|
### **Fase 1 - Core (Semana 1)**
|
|
- [ ] Criar AdminConfigManager
|
|
- [ ] Adicionar seção de config no admin panel
|
|
- [ ] Implementar salvamento de config básicas
|
|
- [ ] Adicionar feedback visual básico
|
|
|
|
### **Fase 2 - Backup (Semana 2)**
|
|
- [ ] Criar BackupManager
|
|
- [ ] Adicionar UI de backup/restauração
|
|
- [ ] Implementar backup automático
|
|
- [ ] Adicionar exportação/importação
|
|
|
|
### **Fase 3 - Estado UI (Semana 3)**
|
|
- [ ] Implementar persistência de estado da UI
|
|
- [ ] Adicionar sistema de logs
|
|
- [ ] Criar dashboard de saúde
|
|
- [ ] Adicionar monitoramento
|
|
|
|
### **Fase 4 - Polish (Semana 4)**
|
|
- [ ] Adicionar sistema de migração
|
|
- [ ] Implementar toast notifications completas
|
|
- [ ] Adicionar animações e transições
|
|
- [ ] Escrever testes e documentação
|
|
|
|
## 🚨 Riscos e Mitigação
|
|
|
|
### **Risco: Storage Insuficiente**
|
|
- **Mitigação**: Monitorar uso, limpar dados antigos, usar IndexedDB
|
|
- **Fallback**: Funcionalidade básica sem persistência
|
|
|
|
### **Risco: Performance Degradada**
|
|
- **Mitigação**: Operações assíncronas, lazy loading, cache
|
|
- **Monitoramento**: Métricas de performance em tempo real
|
|
|
|
### **Risco: Dados Corrompidos**
|
|
- **Mitigação**: Validação rigorosa, backups frequentes, rollback
|
|
- **Recuperação**: Sistema de migração e restauração
|
|
|
|
### **Risco: Complexidade Excessiva**
|
|
- **Mitigação**: Implementação incremental, código modular
|
|
- **Documentação**: Documentação clara e exemplos
|
|
|
|
## 📊 Métricas de Sucesso
|
|
|
|
### **Funcionais**
|
|
- 100% das configurações persistem após reload
|
|
- 0% perda de dados durante operações normais
|
|
- < 1 segundo para criar backup completo
|
|
- < 200ms para aplicar configurações
|
|
|
|
### **Qualidade**
|
|
- 0 erros críticos em produção
|
|
- > 90% cobertura de testes para core
|
|
- Código com complexidade ciclomática < 10
|
|
- Documentação 100% atualizada
|
|
|
|
### **Usabilidade**
|
|
- Usuário consegue completar tarefas sem documentação
|
|
- Feedback visual em < 100ms
|
|
- Interface intuitiva e consistente
|
|
- Erros claros e acionáveis
|
|
|
|
---
|
|
|
|
**Documento de Requisitos** - Versão 1.0
|
|
**Data**: Janeiro 2025
|
|
**Status**: Aprovado para Implementação |