# ESTRATÉGIA DE SINCRONIZAÇÃO ERP - HELM

## 📋 Visão Geral da Arquitetura

```
ERP (Desbravador)
    ↓
[Integração de Dados]
    ├─ Buscar dados via SQL (origem)
    ├─ Validar integridade
    ├─ Detectar mudanças (hash)
    ├─ Fila de processamento
    ↓
Banco HELM
    ├─ Log de sincronização
    ├─ Rastreamento de registros
    ├─ Auditoria completa
```

---

## 🔄 FLUXO DE SINCRONIZAÇÃO

### Fase 1: INICIALIZAÇÃO
```
1. Verificar última sincronização bem-sucedida
2. Buscar origem de dados e conexão
3. Estabelecer conexão com ERP
4. Criar registro em integracao_log (status='processando')
```

### Fase 2: BUSCA DE DADOS (Incremental)
```
IF primeira_sincronizacao:
    SELECT * FROM origem_sql
ELSE:
    -- Sincronização incremental
    SELECT * FROM origem_sql 
    WHERE data_modificacao > ultima_sinc_sucesso
    OR data_criacao > ultima_sinc_sucesso
```

**Importante**: A origem de dados (SQL) deve ter campos de data:
- `data_criacao` - Quando o registro foi criado
- `data_modificacao` - Quando foi modificado
- `data_delecao` - Quando foi deletado (soft delete no ERP)

### Fase 3: PROCESSAMENTO EM LOTES
```
Para cada registro (lote de 1000):
    1. Calcular hash SHA256 do registro
    2. Consultar integracao_rastreamento por chave_origem
    
    IF registro_nao_existe_no_rastreamento:
        → INSERT: Adicionar fila com operação 'INSERT'
        
    ELIF hash_mudou:
        → UPDATE: Adicionar fila com operação 'UPDATE'
        
    ELIF deletado_no_erp AND fl_sincronizar_delecoes:
        → DELETE: Adicionar fila com operação 'DELETE'
        
    ELSE:
        → SKIP: Nenhuma mudança detectada
```

### Fase 4: PROCESSAMENTO ASSÍNCRONO (Fila)
```
Worker assíncrono processa back.integracao_fila:
    
Para cada registro pendente (ordenado por prioridade):
    1. BEGIN TRANSACTION
    2. Executar operação (INSERT/UPDATE/DELETE)
    3. Atualizar status em integracao_rastreamento
    4. Registrar validações em integracao_validacao
    5. IF sucesso:
        - COMMIT
        - Atualizar flstatus='concluido'
       ELSE:
        - ROLLBACK
        - qttenativas += 1
        - IF qttenativas >= 5:
            - flstatus='erro', notificar administrador
        ELSE:
            - Reagendar para reprocessamento
```

### Fase 5: SINCRONIZAÇÃO DE DELETIONS
```
Para cada registro marcado como deletado no ERP:
    1. Verificar integracao_rastreamento (flstatus='deletado')
    2. Recuperar cdregistro_destino
    3. Executar DELETE (ou soft delete) na tabela destino
    4. Atualizar rastreamento com dthdelecao
```

### Fase 6: FINALIZAÇÃO
```
1. Registrar em integracao_log:
   - dthfim = NOW()
   - qtregistros_processados
   - qtregistros_erro
   - flstatus = 'sucesso' ou 'erro'
2. Atualizar integracao_config_sinc.ultima_sinc_sucesso
3. Agendar próxima sincronização
```

---

## 🛡️ VALIDAÇÕES DE SEGURANÇA

### 1. Validação de Duplicação
```sql
-- Antes de INSERT
SELECT COUNT(*) FROM realizado 
WHERE campo_unico = novo_valor 
AND cdempresa = empresa_destino
```

### 2. Validação de Integridade Referencial
```sql
-- Se inserindo em realizado:
- Validar se cdempresa existe
- Validar se cdconta existe
- Validar se cdcentrocusto existe
- etc
```

### 3. Hash para Detectar Mudanças
```php
$hash_novo = sha256(json_encode($registro));
$hash_anterior = SELECT hash_dados FROM integracao_rastreamento WHERE chave_origem = X;

if ($hash_novo !== $hash_anterior) {
    // Houve mudança, adicionar UPDATE à fila
}
```

### 4. Soft Delete
```sql
-- No ERP (Desbravador):
UPDATE lancamento SET data_delecao = NOW(), flativo = false WHERE id = X;

-- Não deletar, apenas marcar como deletado
-- Isso permite recuperação e sincronização correta
```

---

## ⚡ OTIMIZAÇÕES PARA ALTO VOLUME

### 1. Processamento em Lotes
```php
// Processar 1000 registros por vez
foreach (array_chunk($registros, 1000) as $lote) {
    // Processar lote
}
// Libera memória entre lotes
```

### 2. Índices Estratégicos
```sql
-- Já criados nas tabelas:
- idx_rast_origem (cdintegracao, chave_origem)
- idx_fila_prioridade (flprioridade, dthcriacao)
- idx_rast_status (flstatus)
```

### 3. Query com COPY (Para insert em massa)
```sql
-- Ao invés de N INSERT individuais:
COPY tabela_destino (col1, col2, col3) FROM STDIN;
-- 10x mais rápido que INSERT individual
```

### 4. Processamento Assíncrono
```
- Fila permite processamento paralelo
- Worker pode executar múltiplos registros em paralelo
- Não bloqueia interface do usuário
```

### 5. Particionamento (Futuro)
```sql
-- Se tabelas crescerem além de 100M registros:
CREATE TABLE realizado_2024_01 PARTITION OF realizado
    FOR VALUES FROM ('2024-01-01') TO ('2024-02-01');
```

---

## 🔐 TRATAMENTO DE ERROS E RESILIÊNCIA

### Cenário 1: Falha de Conexão
```
1. Catch exception ao conectar ao ERP
2. Registrar em integracao_log (flstatus='erro')
3. Agendar retry automático (exponential backoff)
4. Notificar administrador após 3 tentativas
```

### Cenário 2: Registro Já Existe
```
1. Detectar violação de UNIQUE constraint
2. Registrar em integracao_validacao (resultado='aviso')
3. Incrementar qttenativas
4. Marcar para revisão manual se qttenativas > 3
```

### Cenário 3: Integridade Referencial Violada
```
1. Tentar INSERT/UPDATE
2. Catch FK violation
3. Registrar erro em integracao_rastreamento
4. Alertar que registro no ERP referencia dados que não existem
5. Disponibilizar interface para correção manual
```

### Cenário 4: Sincronização Parcial
```
Se do.com falha no meio (ex: erro no 500º registro de 1000):
1. Já processou 499 registros (já commitados)
2. Falha no 500º (rollback desse lote)
3. Próxima sincronização continua de onde parou
   (verifica última data de sincronização bem-sucedida)
```

---

## 📊 MONITORAMENTO E AUDITORIA

### Dashboard de Sincronização
```
- Última sincronização: 2024-01-10 15:32:00
- Status: ✅ Sucesso
- Registros processados: 45,230
- Registros com erro: 3
- Tempo decorrido: 5m 32s
- Próxima sincronização: 2024-01-10 16:32:00
```

### Alertas
```
1. Se sincronização falha 3 vezes consecutivas
2. Se fila tem > 10,000 itens pendentes
3. Se taxa de erro > 5%
4. Se sincronização leva > 30 minutos
```

### Auditoria
```
Cada sincronização gera registro completo:
- Quem solicitou
- De qual integração
- Quantos registros afetados
- Quais validações executadas
- Qualquer erro ou aviso
```

---

## 🚀 ARQUITETURA ESCALÁVEL

### Hoje (Volume: 1M registros/mês)
```
- Processamento sequencial em lotes de 1000
- Sincronização agendada a cada 1 hora
- Tempo de sincronização: ~5-10 minutos
```

### Quando escalar (Futuro: 10M+ registros/mês)
```
1. Implementar workers paralelos
2. Processamento em múltiplas threads/processes
3. Usar message queue (RabbitMQ, Redis)
4. Particionamento de tabelas por data
5. Read-only replicas para queries pesadas
```

---

## 📋 QUERY SQL ÚTEIS

### Ver status da sincronização atual
```sql
SELECT * FROM back.integracao_log 
ORDER BY dthcriacao DESC LIMIT 10;
```

### Ver registros com erro
```sql
SELECT * FROM back.integracao_rastreamento
WHERE flstatus = 'erro'
LIMIT 100;
```

### Ver fila de processamento
```sql
SELECT cdintegracao, tipo_operacao, flstatus, COUNT(*)
FROM back.integracao_fila
GROUP BY cdintegracao, tipo_operacao, flstatus;
```

### Reprocessar registros com erro (com cautela!)
```sql
UPDATE back.integracao_fila
SET flstatus = 'pendente', qttenativas = 0
WHERE flstatus = 'erro'
AND dthcriacao > NOW() - INTERVAL '24 hours';
```

---

## 🎯 PRÓXIMOS PASSOS

1. Criar arquivo `erp_sincronizacao.php` com lógica principal
2. Criar `erp_worker.php` para processar fila assincronamente
3. Criar `erp_validacoes.php` com regras de validação
4. Criar interface de monitoramento em `dashboard_integracao.php`
5. Implementar cron job para sincronizações agendadas
6. Testes de carga com 1M registros
