sar/docs/plano-migracao-modelo-canonico.md

Plano de Migração — Modelo de Dados Canônico SAR

Data: 2026-06-22 Autor: Julian (Product Owner SAR) Status: Proposta para avaliação

---

1. Contexto e Problema

Situação atual

O SAR foi iniciado consultando diretamente as views do ERP JCS (vw_clientes, vw_pedidos_erp, vw_produtos, etc.) que existem dentro do banco de dados do cliente (libreplast@192.168.0.43). Isso funcionou para o cliente piloto, mas cria uma dependência estrutural que inviabiliza a expansão do produto.

Problema identificado

Sintoma	Consequência
SAR acessa views do ERP via SQL raw	Cada novo ERP exige reescrever queries
Schema sar vive dentro do banco ERP	Sem isolamento; SAR depende de acesso ao servidor do cliente
Views são específicas do ERP JCS	ERP diferente = produto diferente
Sem camada de abstração	Impossível oferecer o SAR como SaaS multi-tenant real

Diagnóstico técnico (levantamento 2026-06-22)

Módulos 100% acoplados ao ERP:   auth, catalog, clients
Módulos parcialmente acoplados:  orders (leitura), dashboard
Módulos já independentes:        notifications, workspace
Views ERP consumidas:            11 views + 1 tabela direta
Tabelas próprias SAR existentes: 6 models Prisma

---

2. Solução Proposta

Modelo Canônico + Connectors

┌─────────────────────────────────────────────────────┐
│                    APP SAR                          │
│         (frontend + API NestJS)                     │
│    Lê APENAS tabelas próprias do SAR                │
└──────────────────────┬──────────────────────────────┘
                       │ Prisma ORM
                       ▼
┌─────────────────────────────────────────────────────┐
│              Banco de Dados SAR                     │
│         (PostgreSQL isolado por workspace)          │
│  tabelas canônicas: clientes, produtos, pedidos...  │
└──────────┬──────────────────────┬───────────────────┘
           │                      │
           ▼                      ▼
┌──────────────────┐   ┌──────────────────────────────┐
│  Connector       │   │  Connector                   │
│  ERP JCS         │   │  ERP X (futuro)              │
│  (PostgreSQL)    │   │  (REST API / CSV / outro)    │
└──────────────────┘   └──────────────────────────────┘

Princípio: O ERP é uma fonte de dados, não o sistema de registro do SAR. Cada cliente tem um connector específico para seu ERP. O SAR opera exclusivamente sobre seu próprio modelo de dados.

O que não muda

Os dados transacionais do SAR já estão corretos e permanecem sem alteração:

• pedidos, pedido_itens, historico_pedido
• alcada_desconto, meta_representante
• push_subscription

---

3. Tabelas Canônicas a Criar

3.1 Entidades mestres (sincronizadas do ERP)

Tabela SAR	Substitui	Campos principais
sar.clientes	vw_clientes	codigo, razao_social, nome_fantasia, cnpj, cidade, uf, ativo, representante_codigo
sar.representantes	vw_representantes	codigo, nome, email, senha_hash, tipo (rep/supervisor), ativo
sar.produtos	vw_produtos	codigo, descricao, unidade, ncm, ativo
sar.estoques	vw_estoque	produto_codigo, deposito, saldo (snapshot com timestamp)
sar.pautas	vw_pautas	codigo, descricao, ativa
sar.pauta_produtos	vw_pauta_produtos	pauta_codigo, produto_codigo, preco, desconto_max
sar.formas_pagamento	vw_formas_pagamento	codigo, descricao, parcelas, ativa
sar.municipios	vw_municipios	ibge, nome, uf
sar.empresa	gestao.empresa	cnpj, razao_social, nome_fantasia, endereco, logo_url

3.2 Histórico ERP (read-only, sincronizado)

Tabela SAR	Substitui	Propósito
sar.pedidos_erp	vw_pedidos_erp	Histórico de pedidos anteriores ao SAR
sar.pedido_itens_erp	vw_peditens_erp	Itens dos pedidos ERP

3.3 Controle de sincronização

Tabela SAR	Propósito
sar.sync_log	Registro de cada execução de sync (início, fim, erros, registros processados)
sar.sync_config	Configuração do connector por workspace (tipo ERP, credenciais, frequência)

---

4. Plano de Execução por Fases

Fase 0 — Banco de Dados Isolado [Fundação]

Objetivo: Separar o banco SAR do banco ERP do cliente.

Ações:

• Provisionar banco PostgreSQL exclusivo para o SAR (sar_db)
• Configurar variável DATABASE_URL apontando para o novo banco
• Manter ERP_DB_* apenas no connector (não no app principal)
• Estrutura multi-tenant: um schema por workspace ou banco por workspace (já previsto na stack)

Resultado: SAR pode funcionar mesmo sem acesso ao ERP; connector roda separado.

Estimativa: 2–3 dias

---

Fase 1 — Schema Canônico [Estrutura]

Objetivo: Criar todos os models Prisma das tabelas canônicas.

Ações:

• Adicionar 11 models ao schema.prisma (seção 3.1 e 3.2)
• Adicionar 2 models de controle de sync (seção 3.3)
• Gerar e aplicar migrations
• Nenhuma mudança no código da API ainda

Resultado: Tabelas existem no banco, prontas para receber dados.

Estimativa: 3–4 dias

---

Fase 2 — Sync Service (Connector ERP JCS) [Motor]

Objetivo: Criar a camada que lê o ERP e popula as tabelas canônicas.

Ações:

• Criar módulo SyncModule no NestJS
• Implementar ErpJcsConnector com leitura das 11 views existentes
• Sync completo na inicialização do workspace
• Sync incremental por cron (ex: a cada 5 minutos para estoque, 30 min para cadastros)
• Registrar execuções em sync_log
• Endpoint admin /api/v1/sync/trigger para forçar sync manual

Estratégia de sync:

┌────────────────────────────────────────────────────┐
│  Frequências recomendadas                          │
│                                                    │
│  A cada 5 min:   estoques (alta volatilidade)      │
│  A cada 30 min:  produtos, pautas, preços          │
│  A cada 60 min:  clientes, representantes          │
│  A cada 6h:      pedidos_erp (histórico)           │
│  1x por dia:     municipios, empresa, formas_pgto  │
└────────────────────────────────────────────────────┘

Resultado: Tabelas SAR ficam populadas e atualizadas automaticamente.

Estimativa: 5–8 dias

---

Fase 3 — Migração dos Módulos [Execução]

Objetivo: Substituir todos os $queryRaw por queries Prisma nas tabelas canônicas.

Prioridade e ordem:

Ordem	Módulo	Complexidade	Motivo da prioridade
1	catalog	Baixa	Somente leitura, sem lógica de negócio complexa
2	clients	Média	Base do dashboard e pedidos
3	auth	Baixa	Bem delimitado; lê apenas representantes
4	dashboard	Média	Depende de clients migrado
5	orders (leitura)	Média	Parte escrita já usa Prisma corretamente

Processo por módulo:

1. Com o sync rodando, os dados já estão nas tabelas canônicas
2. Substituir $queryRaw por prisma.cliente.findMany(...) etc.
3. Manter o contrato de resposta da API (frontend não muda)
4. Teste comparativo: mesmo resultado via ERP vs. via tabela SAR
5. Remover a query antiga após validação

Resultado: Zero dependência de views ERP no código da API.

Estimativa: 5–8 dias

---

Fase 4 — Segundo Connector (Validação da Abstração) [Prova]

Objetivo: Onboarding de um cliente com ERP diferente do JCS.

Ações:

• Identificar segundo ERP (ex: TOTVS, Sankhya, outro)
• Criar ErpXConnector implementando a mesma interface do ErpJcsConnector
• Mapear campos do ERP X para o schema canônico SAR
• Sem nenhuma mudança no app SAR

Resultado: Prova de conceito real de que a arquitetura é ERP-agnóstica.

Estimativa: 4–6 dias (variável conforme ERP)

---

5. Cronograma Estimado

Semana 1:  Fase 0 (banco isolado) + Fase 1 (schema Prisma)
Semana 2:  Fase 2 (Sync Service — maior esforço)
Semana 3:  Fase 3 (migração dos módulos)
Semana 4:  Fase 4 (segundo connector) + testes + documentação

Total estimado: 4 semanas (19–25 dias úteis)

---

6. Riscos e Mitigações

Risco	Probabilidade	Impacto	Mitigação
Divergência de dados entre ERP e tabela SAR durante sync	Médio	Alto	Sync comparativo com log de diferenças; alertas
Latência do sync afeta experiência do rep	Baixo	Médio	Sync de estoque a cada 5 min é suficiente para força de vendas
ERP do cliente sem conectividade temporária	Médio	Baixo	SAR continua funcionando com dados do último sync
Campos do segundo ERP sem equivalência no schema canônico	Médio	Médio	Schema canônico flexível com campo metadata jsonb por entidade
Custo de manutenção de dois bancos	Baixo	Baixo	Banco SAR é pequeno; ERP continua como está

---

7. Benefícios Esperados

Benefício	Impacto
Multi-ERP real	Onboarding de qualquer cliente independente do ERP
Isolamento de falhas	Queda do ERP não derruba o SAR
Performance	Queries no banco SAR são mais rápidas (schema otimizado)
Funciona offline	Rep consulta dados mesmo sem VPN/internet no cliente
Multi-tenant limpo	Banco SAR separado por workspace desde o início
Evolução independente	SAR pode adicionar campos sem depender do ERP

---

8. Decisão

O projeto SAR não precisa ser refeito do zero. A infraestrutura (NestJS, autenticação, frontend React, ciclo de pedidos, alçadas, metas, push notifications) está correta e é reaproveitada integralmente.

A mudança é cirúrgica e incremental:

• Adicionar banco e tabelas canônicas (Fases 0 e 1)
• Construir o motor de sync (Fase 2)
• Substituir queries raw módulo a módulo (Fase 3)

O risco de não fazer essa migração agora é maior: quanto mais o produto crescer sobre as views do ERP JCS, mais caro fica refatorar depois.

---

Documento gerado em 2026-06-22. Para dúvidas: jcsinfo@gmail.com