# 🗄️ Sistema de Persistência de Dados - Aço Calc Pro

## 📋 Visão Geral

Este documento técnico descreve a arquitetura completa do sistema de persistência de dados do Aço Calc Pro, garantindo que todas as personalizações e configurações do painel administrativo permaneçam inalteradas durante o uso e recarregamento do aplicativo.

## 🏗️ Arquitetura Atual de Persistência

### 1. **Camadas de Armazenamento**

```mermaid
graph TD
    A[Aplicação] --> B[State Manager]
    B --> C[Storage Layer]
    C --> D[localStorage]
    C --> E[IndexedDB]
    C --> F[Cache Manager]
    
    subgraph "Persistência Local"
        D
        E
        F
    end
    
    G[Admin Panel] --> H[Data Manager]
    H --> C
    I[User Preferences] --> C
```

### 2. **Componentes Principais**

#### **Data Manager** (`js/database/data-manager.js`)
- **Função**: Gerenciamento central de dados e cache inteligente
- **Armazenamento**: localStorage com prefixo `acoCalcPro_cache_`
- **TTL**: 24 horas para atualização automática
- **Versionamento**: Detecta mudanças e atualiza automaticamente

```javascript
// Estrutura de cache
localStorage.setItem('acoCalcPro_cache_cantoneiras', JSON.stringify(dados));
localStorage.setItem('acoCalcPro_metadata', JSON.stringify(metadata));
```

#### **Storage Manager** (`js/core/storage.js`)
- **Função**: Gerenciamento de preferências do usuário
- **Armazenamento**: localStorage com chave `acoCalcPreferences`
- **Dados**: tema, esquema de cores, tamanho de fonte, família de fonte

```javascript
// Estrutura de preferências
const userPreferences = {
    theme: 'dark',
    colorScheme: 'default',
    fontSize: 'medium',
    fontFamily: 'default'
};
```

#### **Cache Manager** (`js/core/cache-manager.js`)
- **Função**: Gerenciamento avançado com IndexedDB
- **Armazenamento**: IndexedDB para grandes volumes de dados
- **Fallback**: CSV embutido quando IndexedDB não disponível
- **Stores**: cantoneiras, barras, tubos, perfis, etc.

#### **State Manager** (`js/core/state.js`)
- **Função**: Estado global da aplicação
- **Dados**: histórico, favoritos, orçamento, seção atual
- **Persistência**: Integrado com Storage Manager

#### **Admin Panel** (`js/database/admin-panel.js`)
- **Função**: Interface de administração e configurações
- **Estado**: Não persiste configurações atualmente
- **Ações**: Atualizar dados, limpar cache, exportar/importar

## 🔍 Análise de Persistência Atual

### **Pontos Fortes**
1. ✅ **Cache Inteligente**: Dados carregados uma vez, reusados múltiplas vezes
2. ✅ **Versionamento Automático**: Detecta e aplica atualizações
3. ✅ **Multipla Camadas**: localStorage, IndexedDB e CSV como fallback
4. ✅ **Performance Otimizada**: Carregamento rápido após primeiro acesso

### **Pontos de Fragilidade**
1. ❌ **Admin Panel Sem Persistência**: Configurações administrativas não são salvas
2. ❌ **Dependência de localStorage**: Limitado a ~5-10MB
3. ❌ **Sem Sincronização**: Sem backup em nuvem ou sincronização entre dispositivos
4. ❌ **Falta de Migração**: Sem sistema de migração de dados entre versões

## 🎯 Proposta de Arquitetura Robustas

### 1. **Sistema de Configurações Persistentes**

```javascript
// Novo sistema de configurações administrativas
class AdminConfigManager {
    constructor() {
        this.configKey = 'acoCalcPro_admin_config';
        this.version = '1.0.0';
        this.defaultConfig = {
            appName: 'AÇO CALC PRO',
            appSubtitle: 'Plataforma Técnica com Base de Dados de Materiais Brasileiros',
            footerText: '© 2025 AÇO CALC PRO v7.5 PROFESSIONAL EDITION',
            themeDefault: 'escuro',
            modeDefault: 'simples',
            toolsVisibility: {
                'cev': true,
                'seletor': true,
                'equivalencias': false,
                'comparativo': false,
                'parafusos': true,
                'layout': true,
                // ... todas as ferramentas
            },
            dataRefreshInterval: 24, // horas
            autoBackup: true,
            backupInterval: 7, // dias
            lastBackup: null,
            version: this.version
        };
    }
    
    saveConfig(config) {
        const configToSave = { ...this.getConfig(), ...config, version: this.version };
        localStorage.setItem(this.configKey, JSON.stringify(configToSave));
        return configToSave;
    }
    
    getConfig() {
        try {
            const saved = localStorage.getItem(this.configKey);
            return saved ? JSON.parse(saved) : this.defaultConfig;
        } catch {
            return this.defaultConfig;
        }
    }
    
    resetConfig() {
        localStorage.setItem(this.configKey, JSON.stringify(this.defaultConfig));
        return this.defaultConfig;
    }
}
```

### 2. **Sistema de Backup e Restauração**

```javascript
class BackupManager {
    constructor() {
        this.backupKey = 'acoCalcPro_backup';
        this.maxBackups = 5;
    }
    
    async createBackup() {
        const backup = {
            timestamp: Date.now(),
            version: '1.0.0',
            data: {
                preferences: this.getPreferences(),
                adminConfig: this.getAdminConfig(),
                cacheStats: window.dataManager.getCacheStats(),
                appState: this.getAppState()
            }
        };
        
        // Salvar em localStorage
        const backups = this.getBackups();
        backups.unshift(backup);
        
        // Limitar número de backups
        if (backups.length > this.maxBackups) {
            backups.splice(this.maxBackups);
        }
        
        localStorage.setItem(this.backupKey, JSON.stringify(backups));
        return backup;
    }
    
    getBackups() {
        try {
            const saved = localStorage.getItem(this.backupKey);
            return saved ? JSON.parse(saved) : [];
        } catch {
            return [];
        }
    }
    
    restoreBackup(backup) {
        // Restaurar preferências
        if (backup.data.preferences) {
            localStorage.setItem('acoCalcPreferences', JSON.stringify(backup.data.preferences));
        }
        
        // Restaurar configurações admin
        if (backup.data.adminConfig) {
            localStorage.setItem('acoCalcPro_admin_config', JSON.stringify(backup.data.adminConfig));
        }
        
        // Aplicar mudanças
        this.applyRestoredSettings();
        return true;
    }
}
```

### 3. **Sistema de Migração de Dados**

```javascript
class MigrationManager {
    constructor() {
        this.migrationKey = 'acoCalcPro_migration_version';
        this.currentVersion = '1.0.0';
    }
    
    checkAndRunMigrations() {
        const savedVersion = localStorage.getItem(this.migrationKey) || '0.0.0';
        
        if (savedVersion < this.currentVersion) {
            console.log(`🔄 Executando migração de ${savedVersion} para ${this.currentVersion}`);
            this.runMigrations(savedVersion);
            localStorage.setItem(this.migrationKey, this.currentVersion);
        }
    }
    
    runMigrations(fromVersion) {
        // Migrar de versões antigas
        if (fromVersion < '1.0.0') {
            this.migrateToV1();
        }
    }
    
    migrateToV1() {
        // Converter configurações antigas
        const oldConfig = localStorage.getItem('acoCalcPro_config');
        if (oldConfig) {
            try {
                const parsed = JSON.parse(oldConfig);
                // Converter para novo formato
                const newConfig = this.convertToNewFormat(parsed);
                localStorage.setItem('acoCalcPro_admin_config', JSON.stringify(newConfig));
                localStorage.removeItem('acoCalcPro_config');
            } catch (e) {
                console.warn('⚠️ Falha ao migrar configurações antigas');
            }
        }
    }
}
```

### 4. **Integração com Admin Panel**

```javascript
// Atualizar admin-panel.js para persistir configurações
function abrirPainelDados() {
    const adminConfig = window.adminConfigManager.getConfig();
    const stats = window.dataManager.getCacheStats();
    
    // Adicionar seções de configuração no modal
    const configSection = `
        <div class="card" style="background: var(--color-bg-1); margin-bottom: 20px;">
            <h3 style="color: var(--color-primary); margin: 0 0 16px 0;">⚙️ Configurações do Sistema</h3>
            <div style="display: grid; gap: 12px;">
                <div>
                    <label>Nome do Aplicativo:</label>
                    <input type="text" id="admin-app-name" value="${adminConfig.appName}" 
                           onchange="salvarConfigAdmin('appName', this.value)">
                </div>
                <div>
                    <label>Tema Padrão:</label>
                    <select id="admin-theme-default" onchange="salvarConfigAdmin('themeDefault', this.value)">
                        <option value="escuro" ${adminConfig.themeDefault === 'escuro' ? 'selected' : ''}>Escuro</option>
                        <option value="claro" ${adminConfig.themeDefault === 'claro' ? 'selected' : ''}>Claro</option>
                    </select>
                </div>
                <div>
                    <label>Intervalo de Atualização (horas):</label>
                    <input type="number" id="admin-refresh-interval" value="${adminConfig.dataRefreshInterval}" 
                           onchange="salvarConfigAdmin('dataRefreshInterval', parseInt(this.value))">
                </div>
                <div>
                    <label>
                        <input type="checkbox" ${adminConfig.autoBackup ? 'checked' : ''} 
                               onchange="salvarConfigAdmin('autoBackup', this.checked)">
                        Auto Backup
                    </label>
                </div>
            </div>
        </div>
        
        <div class="card" style="background: var(--color-bg-1); margin-bottom: 20px;">
            <h3 style="color: var(--color-primary); margin: 0 0 16px 0;">🛠️ Visibilidade de Ferramentas</h3>
            <div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); gap: 8px;">
                ${Object.entries(adminConfig.toolsVisibility).map(([tool, visible]) => `
                    <label style="display: flex; align-items: center; gap: 8px;">
                        <input type="checkbox" ${visible ? 'checked' : ''} 
                               onchange="salvarConfigAdminTool('${tool}', this.checked)">
                        ${tool}
                    </label>
                `).join('')}
            </div>
        </div>
        
        <div class="card" style="background: var(--color-bg-1); margin-bottom: 20px;">
            <h3 style="color: var(--color-primary); margin: 0 0 16px 0;">💾 Backup e Restauração</h3>
            <div style="display: flex; gap: 12px; flex-wrap: wrap;">
                <button class="btn btn-success" onclick="criarBackup()">
                    📥 Criar Backup
                </button>
                <button class="btn btn-warning" onclick="restaurarUltimoBackup()">
                    📤 Restaurar Último Backup
                </button>
                <button class="btn btn-info" onclick="exportarConfig()">
                    📋 Exportar Configurações
                </button>
                <button class="btn btn-primary" onclick="importarConfig()">
                    📋 Importar Configurações
                </button>
            </div>
        </div>
    `;
    
    // Incluir configSection no modalHTML...
}

// Funções para salvar configurações
function salvarConfigAdmin(chave, valor) {
    const config = window.adminConfigManager.getConfig();
    config[chave] = valor;
    window.adminConfigManager.saveConfig(config);
    console.log(`✅ Config ${chave} salva:`, valor);
}

function salvarConfigAdminTool(tool, visible) {
    const config = window.adminConfigManager.getConfig();
    config.toolsVisibility[tool] = visible;
    window.adminConfigManager.saveConfig(config);
    console.log(`✅ Tool ${tool} visibilidade:`, visible);
    
    // Aplicar mudança imediatamente na UI
    aplicarVisibilidadeFerramentas();
}
```

## 🔄 Fluxo Completo de Persistência

```mermaid
sequenceDiagram
    participant User
    participant AdminPanel
    participant AdminConfig
    participant Storage
    participant Backup
    participant App
    
    User->>AdminPanel: Abre configurações
    AdminPanel->>AdminConfig: Carrega config atual
    AdminConfig->>Storage: Lê localStorage
    Storage-->>AdminConfig: Config salva
    AdminConfig-->>AdminPanel: Config atual
    AdminPanel-->>User: Mostra interface
    
    User->>AdminPanel: Altera config
    AdminPanel->>AdminConfig: Salva nova config
    AdminConfig->>Storage: Atualiza localStorage
    AdminConfig-->>AdminPanel: Confirmação
    AdminPanel-->>App: Aplica mudanças
    App-->>User: Interface atualizada
    
    AdminConfig->>Backup: Cria backup automático
    Backup->>Storage: Salva histórico
    
    Note over User,Storage: Em caso de reload...
    App->>AdminConfig: Carrega config salva
    AdminConfig->>Storage: Lê persistência
    Storage-->>AdminConfig: Config intacta
    AdminConfig-->>App: Aplica config
    App-->>User: Estado restaurado
```

## 📊 Monitoramento e Debugging

### **Sistema de Logs Persistente**

```javascript
class PersistentLogger {
    constructor() {
        this.logKey = 'acoCalcPro_logs';
        this.maxLogs = 100;
    }
    
    log(level, message, data = null) {
        const logs = this.getLogs();
        const entry = {
            timestamp: Date.now(),
            level,
            message,
            data,
            userAgent: navigator.userAgent
        };
        
        logs.unshift(entry);
        if (logs.length > this.maxLogs) {
            logs.splice(this.maxLogs);
        }
        
        localStorage.setItem(this.logKey, JSON.stringify(logs));
        
        // Também log no console
        console[level] || console.log(`[${level.toUpperCase()}] ${message}`, data);
    }
    
    getLogs() {
        try {
            const saved = localStorage.getItem(this.logKey);
            return saved ? JSON.parse(saved) : [];
        } catch {
            return [];
        }
    }
    
    exportLogs() {
        const logs = this.getLogs();
        const blob = new Blob([JSON.stringify(logs, null, 2)], { type: 'application/json' });
        const url = URL.createObjectURL(blob);
        const a = document.createElement('a');
        a.href = url;
        a.download = `aco-calc-pro-logs-${Date.now()}.json`;
        a.click();
        URL.revokeObjectURL(url);
    }
}
```

## 🛡️ Estratégias de Resiliência

### 1. **Graceful Degradation**
- Sistema funciona mesmo sem localStorage (modo básico)
- Fallback para CSV quando IndexedDB falhar
- Mensagens claras para usuário quando recursos não disponíveis

### 2. **Validação e Sanitização**
- Validação de dados antes de salvar
- Sanitização de inputs do admin
- Verificação de integridade ao carregar

### 3. **Limite de Armazenamento**
- Monitoramento de uso de localStorage
- Limpeza automática de dados antigos
- Compressão de dados grandes

### 4. **Recuperação de Erros**
- Try-catch em todas as operações de I/O
- Logs detalhados de erros
- Sistema de recuperação automática

## 📈 Métricas e Monitoramento

### **Dashboard de Saúde do Sistema**

```javascript
function getSystemHealth() {
    const health = {
        storage: {
            localStorageAvailable: isStorageAvailable(),
            usage: getStorageUsage(),
            quota: getStorageQuota()
        },
        cache: {
            dataManager: window.dataManager.getCacheStats(),
            indexedDB: window.cacheManager ? window.cacheManager.checkHealth() : null
        },
        config: {
            adminConfig: window.adminConfigManager.getConfig(),
            userPreferences: userPreferences
        },
        timestamp: Date.now()
    };
    
    return health;
}
```

## 🚀 Implementação Passo a Passo

### **Fase 1: Sistema de Configurações (Prioridade Alta)**
1. Criar `AdminConfigManager` class
2. Integrar com `admin-panel.js`
3. Adicionar UI de configurações no painel
4. Implementar funções de salvamento/restauração

### **Fase 2: Sistema de Backup (Prioridade Média)**
1. Criar `BackupManager` class
2. Implementar criação automática de backups
3. Adicionar UI de backup/restauração
4. Criar sistema de exportação/importação

### **Fase 3: Sistema de Migração (Prioridade Média)**
1. Criar `MigrationManager` class
2. Implementar detecção de versão
3. Criar scripts de migração
4. Adicionar rollback em caso de falha

### **Fase 4: Monitoramento (Prioridade Baixa)**
1. Implementar `PersistentLogger`
2. Criar dashboard de saúde
3. Adicionar alertas de problema
4. Implementar telemetria anônima

## 📋 Checklist de Validação

- ✅ Configurações do admin persistem após reload
- ✅ Backup automático funciona corretamente
- ✅ Restauração mantém integridade dos dados
- ✅ Sistema de migração trata versões antigas
- ✅ Logs persistentes ajudam no debugging
- ✅ Dashboard mostra saúde do sistema
- ✅ Fallbacks funcionam quando storage falha
- ✅ UI reflete mudanças imediatamente
- ✅ Performance não é degradada
- ✅ Usuário recebe feedback de ações

## 🔧 Manutenção e Troubleshooting

### **Comandos de Diagnóstico**
```javascript
// Verificar integridade do sistema
console.log('Health Check:', getSystemHealth());

// Verificar configurações atuais
console.log('Admin Config:', window.adminConfigManager.getConfig());

// Verificar backups disponíveis
console.log('Backups:', window.backupManager.getBackups());

// Exportar logs para análise
window.persistentLogger.exportLogs();
```

### **Procedimentos de Recuperação**
1. **Configurações corrompidas**: Usar `resetConfig()`
2. **Cache corrompido**: Limpar e recarregar dados
3. **Storage cheio**: Limpar logs antigos e backups
4. **Erros críticos**: Restaurar último backup válido

---

**Status**: Documentação Técnica Completa  
**Versão**: 1.0.0  
**Data**: 2025-01-01  
**Responsável**: Sistema de Documentação Aço Calc Pro