Refactor-Monolith

🏗️ REFACTOR-MONOLITH - Decomposição Segura de Monolitos

🚨 PRINCÍPIO FUNDAMENTAL

╔══════════════════════════════════════════════════════════════════╗
║  NUNCA REFATORAR SEM ENTENDER 100% DA LÓGICA DE NEGÓCIO         ║
║  NUNCA EXTRAIR SEM MAPEAR 100% DAS DEPENDÊNCIAS                 ║
║  NUNCA QUEBRAR O QUE FUNCIONA                                    ║
╚══════════════════════════════════════════════════════════════════╝

Regra de Ouro: É melhor um monolito funcionando do que módulos quebrados.

---

📋 QUANDO USAR ESTA SKILL

✅ USAR QUANDO:

• Arquivo com +500 linhas
• Arquivo com +10 funções/​métodos
• Arquivo com múltiplas responsabilidades (UI + lógica + dados)
• Arquivo difícil de manter/​entender
• Arquivo com funções que poderiam ser reutilizadas
• Arquivo que múltiplos devs precisam mexer simultaneamente

❌ NÃO USAR QUANDO:

• Arquivo funciona bem e não causa problemas
• Refatoração apenas por "limpeza estética"
• Prazo apertado sem tempo para testes
• Não há entendimento completo do negócio
• Sistema em produção crítica sem ambiente de teste

---

🔬 FASE 0: PRÉ-ANÁLISE (OBRIGATÓRIA)

0.1 Perguntas de Negócio (FAZER ANTES DE TUDO)

ANTES de olhar o código, entender:

1. PROPÓSITO
   - Qual o objetivo principal deste arquivo?
   - Que problema de negócio ele resolve?
   - Quem são os usuários das funcionalidades?

2. CRITICIDADE
   - Este arquivo é crítico para o sistema?
   - Quebrar aqui impacta faturamento/​operação?
   - Há janela segura para mudanças?

3. HISTÓRICO
   - Por que ficou monolítico? (crescimento orgânico? pressa?)
   - Houve tentativas anteriores de refatorar?
   - Quais funcionalidades foram adicionadas recentemente?

4. EXPECTATIVA
   - Qual o resultado esperado da refatoração?
   - Quais módulos idealmente existiriam?
   - Há padrão de modularização já usado no projeto?

0.2 Checklist de Viabilidade

□ Entendi o propósito de negócio do arquivo
□ Sei quem usa cada funcionalidade
□ Tenho acesso ao arquivo completo
□ Posso testar após cada mudança
□ Tenho rollback disponível (git)
□ Não há deploy urgente pendente
□ Stakeholder aprovou a refatoração

Se qualquer item for NÃO → PARAR e resolver antes de continuar.

---

🔍 FASE 1: ANÁLISE ESTRUTURAL PROFUNDA

1.1 Radiografia do Arquivo

# Métricas básicas
wc -l [arquivo]                    # Total de linhas
grep -c "function\|=>" [arquivo]   # Total de funções
grep -c "async" [arquivo]          # Funções assíncronas
grep -c "export\|module.exports" [arquivo]  # Exports

# Complexidade
grep -n "if\|else\|switch\|for\|while" [arquivo] | wc -l  # Branches
grep -n "try\|catch" [arquivo] | wc -l                      # Error handling
grep -n "TODO\|FIXME\|HACK" [arquivo]                       # Débitos técnicos

1.2 Mapa de Funções (DOCUMENTAR TODAS)

## INVENTÁRIO DE FUNÇÕES - [nome-arquivo.js]

| # | Função | Linha | Linhas | Responsabilidade | Dependências Internas | Chamada Por |
|---|--------|-------|--------|------------------|----------------------|-------------|
| 1 | init() | 15 | 45 | Inicialização | config, setupUI | main |
| 2 | fetchData() | 60 | 30 | Busca API | formatResponse | init, refresh |
| 3 | formatResponse() | 90 | 25 | Formata dados | - | fetchData |
| ... | ... | ... | ... | ... | ... | ... |

### Legenda de Responsabilidades:
- CONFIG: Configuração e constantes
- INIT: Inicialização e setup
- UI: Manipulação de DOM/​interface
- DATA: Busca e processamento de dados
- CALC: Cálculos e lógica de negócio
- UTIL: Utilitários genéricos
- EVENT: Handlers de eventos
- EXPORT: Exportação/​download
- CACHE: Gerenciamento de cache
- VALID: Validações

1.3 Análise de Responsabilidades

## MATRIZ DE RESPONSABILIDADES

┌─────────────────────────────────────────────────────────────┐
│ RESPONSABILIDADE      │ FUNÇÕES           │ LINHAS │ %     │
├───────────────────────┼───────────────────┼────────┼───────┤
│ Configuração          │ 2                 │ 50     │ 5%    │
│ Inicialização         │ 3                 │ 120    │ 12%   │
│ Interface (UI)        │ 8                 │ 300    │ 30%   │
│ Lógica de Negócio     │ 5                 │ 250    │ 25%   │
│ Comunicação (API)     │ 4                 │ 150    │ 15%   │
│ Utilitários           │ 6                 │ 80     │ 8%    │
│ Event Handlers        │ 4                 │ 50     │ 5%    │
├───────────────────────┼───────────────────┼────────┼───────┤
│ TOTAL                 │ 32                │ 1000   │ 100%  │
└─────────────────────────────────────────────────────────────┘

DIAGNÓSTICO:
- UI (30%) + Lógica (25%) = 55% → Forte candidato a separação
- Utilitários (8%) → Pode virar módulo compartilhado

---

🕸️ FASE 2: MAPEAMENTO EXAUSTIVO DE DEPENDÊNCIAS

2.1 Dependências Internas (Dentro do Arquivo)

## GRAFO DE DEPENDÊNCIAS INTERNAS

funcaoA()
├── chama: funcaoB(), funcaoC()
├── usa variável: CONFIG, state
└── modifica: elementoDOM

funcaoB()
├── chama: funcaoD()
├── usa variável: CONFIG
└── retorna para: funcaoA(), funcaoE()

funcaoC()
├── chama: nenhuma
├── usa variável: state
└── retorna para: funcaoA()

## VARIÁVEIS DE ESTADO COMPARTILHADAS
| Variável | Tipo | Escrito por | Lido por | Crítica? |
|----------|------|-------------|----------|----------|
| state | object | init, fetchData | render*, calc* | SIM |
| CONFIG | const | - | todos | NÃO |
| currentPage | let | pagination | render | SIM |

2.2 Dependências Externas (Fora do Arquivo)

# Quem importa este arquivo?
grep -r "require.*[nome-arquivo]\|import.*[nome-arquivo]" . --include="*.js"

# Este arquivo importa quem?
grep -n "require\|import" [arquivo]

# Quais IDs/​classes DOM são manipulados?
grep -oE "(getElementById|querySelector)\\(['\"][^'\"]+['\"]\\)" [arquivo]

# Quais rotas/​endpoints são chamados?
grep -oE "fetch\\(['\"][^'\"]+['\"]" [arquivo]
grep -oE "/​api/[^'\" ]+" [arquivo]

2.3 Matriz de Acoplamento

## MATRIZ DE ACOPLAMENTO

                    │ config │ core │ ui │ utils │ EXTERNO
────────────────────┼────────┼──────┼────┼───────┼─────────
config              │   -    │  ←   │ ←  │   ←   │    
core                │   →    │  -   │ ←→ │   ←   │   API
ui                  │   →    │  →←  │ -  │   ←   │   DOM
utils               │   →    │  →   │ →  │   -   │    
────────────────────┼────────┼──────┼────┼───────┼─────────

LEGENDA:
→  = depende de (importa/​usa)
←  = é dependido por (exporta para)
←→ = dependência mútua (ALERTA: difícil separar)

2.4 Identificação de "Costuras Naturais"

## COSTURAS PARA CORTE

Uma "costura" é um ponto onde o código pode ser dividido com MÍNIMO impacto.

### COSTURAS IDENTIFICADAS:

1. ✅ COSTURA LIMPA: Funções utilitárias (linhas 800-900)
   - Não dependem de estado
   - Não acessam DOM
   - Funções puras
   - RISCO: Baixo

2. ⚠️ COSTURA MÉDIA: Configuração (linhas 1-50)
   - Constantes globais
   - Precisam ser importadas por todos módulos
   - RISCO: Médio (ordem de carregamento)

3. 🔴 COSTURA DIFÍCIL: UI + Core (linhas 200-600)
   - Dependência mútua
   - Estado compartilhado
   - RISCO: Alto (requer refatoração de estado primeiro)

### ORDEM RECOMENDADA DE EXTRAÇÃO:
1º → Utilitários (risco baixo, ganho rápido)
2º → Configuração (estabiliza imports)
3º → Separar estado em store
4º → UI (após estado isolado)
5º → Core (após UI isolado)

---

❓ FASE 3: PERGUNTAS DE CLARIFICAÇÃO

3.1 Perguntas Obrigatórias ao Stakeholder

ANTES de propor estrutura de módulos, PERGUNTAR:

## SOBRE FUNCIONALIDADES

1. "A função [X] ainda é usada ou é código legado?"
   → Identificar dead code antes de extrair

2. "O comportamento de [Y] está correto ou há bugs conhecidos?"
   → Não perpetuar bugs em módulos novos

3. "Existe regra de negócio não documentada em [Z]?"
   → Capturar conhecimento tácito

## SOBRE PRIORIDADES

4. "Quais funções são mais críticas para o negócio?"
   → Priorizar estabilidade das críticas

5. "Quais partes mudam com mais frequência?"
   → Isolar partes voláteis

6. "Há planos de novas features que afetam este arquivo?"
   → Considerar evolução futura

## SOBRE RESTRIÇÕES

7. "Há restrições de performance a considerar?"
   → Evitar overhead de modularização excessiva

8. "Outros sistemas/​equipes dependem deste código?"
   → Mapear consumidores externos

9. "Posso renomear funções ou há contratos fixos?"
   → Entender flexibilidade de interface

3.2 Análise Lógica x Código

## CHECKLIST: LÓGICA DE NEGÓCIO

Para CADA função identificada, validar:

□ Entendo O QUE esta função faz (propósito)
□ Entendo POR QUE ela existe (regra de negócio)
□ Entendo QUANDO ela é chamada (fluxo)
□ Entendo QUEM depende do resultado (consumidores)
□ O código reflete corretamente a lógica?
□ Há edge cases tratados que não são óbvios?
□ Há comentários explicando decisões de negócio?

## ALERTAS DE LÓGICA OCULTA

🚨 ATENÇÃO para:
- Números mágicos sem explicação
- Condicionais complexos (if dentro de if)
- Try/​catch que engole erros silenciosamente
- Timeouts/​delays sem justificativa
- Ordenações específicas de operações
- Validações que parecem redundantes (podem não ser)

---

📐 FASE 4: PROPOSTA DE ARQUITETURA MODULAR

4.1 Template de Estrutura

## PROPOSTA DE MODULARIZAÇÃO

### ARQUIVO ORIGINAL:
`[caminho/​arquivo-monolito.js]` (XXX linhas)

### ESTRUTURA PROPOSTA:

[pasta-modulo]/ ├── config.js # Constantes e configuração │ └── [XX linhas] - Funções: A, B │ ├── core.js # Lógica de negócio principal │ └── [XX linhas] - Funções: C, D, E │ ├── ui.js # Manipulação de interface │ └── [XX linhas] - Funções: F, G, H │ ├── api.js # Comunicação com backend │ └── [XX linhas] - Funções: I, J │ ├── utils.js # Utilitários │ └── [XX linhas] - Funções: K, L, M │ ├── events.js # Event handlers │ └── [XX linhas] - Funções: N, O │ └── index.js # Orquestrador (entry point) └── [XX linhas] - init, bindEvents

### DIAGRAMA DE DEPENDÊNCIAS:

                ┌──────────┐
                │  index   │ (entry point)
                └────┬─────┘
                     │
     ┌───────────────┼───────────────┐
     ▼               ▼               ▼
┌────────┐      ┌────────┐      ┌────────┐
│  core  │◄────►│   ui   │      │ events │
└───┬────┘      └───┬────┘      └───┬────┘
    │               │               │
    ▼               ▼               │
┌────────┐      ┌────────┐          │
│  api   │      │ config │◄─────────┘
└───┬────┘      └────────┘
    │
    ▼
┌────────┐
│ utils  │ (sem dependências internas)
└────────┘

### REGRAS DE IMPORTAÇÃO:

1. `utils` → Não importa nenhum módulo interno
2. `config` → Não importa nenhum módulo interno  
3. `api` → Importa apenas `utils`, `config`
4. `core` → Importa `api`, `utils`, `config`
5. `ui` → Importa `core`, `utils`, `config`
6. `events` → Importa `ui`, `core`, `config`
7. `index` → Importa todos, orquestra

4.2 Validação da Proposta

## CHECKLIST DE VALIDAÇÃO DA ARQUITETURA

### Princípios
□ Cada módulo tem UMA responsabilidade clara
□ Dependências fluem em uma direção (sem ciclos)
□ Módulos podem ser testados isoladamente
□ Nenhuma lógica de negócio duplicada
□ Estado centralizado ou claramente distribuído

### Compatibilidade
□ API pública (exports) permanece compatível
□ Ordem de inicialização preservada
□ Event listeners funcionam igual
□ Performance não degradada

### Praticidade
□ Estrutura segue padrão já usado no projeto
□ Nomenclatura consistente
□ Tamanho dos módulos equilibrado (não criar micro-módulos)

---

🔧 FASE 5: EXTRAÇÃO INCREMENTAL SEGURA

5.1 Princípio da Extração Atômica

╔══════════════════════════════════════════════════════════════════╗
║  UMA FUNÇÃO POR VEZ                                              ║
║  UM COMMIT POR EXTRAÇÃO                                          ║
║  UM TESTE APÓS CADA MUDANÇA                                      ║
╚══════════════════════════════════════════════════════════════════╝

5.2 Protocolo de Extração

## SEQUÊNCIA DE EXTRAÇÃO (para cada função)

### PASSO 1: Preparar
```bash
# Criar branch
git checkout -b refactor/​extract-[nome-funcao]

# Backup
cp [arquivo-original].js [arquivo-original].js.backup

PASSO 2: Criar Módulo Destino (se não existir)

// [pasta]/[modulo-destino].js

// Imports necessários (identificados na análise)
// ...

// Função extraída virá aqui

// Export
module.exports = { /​* funções */ };

PASSO 3: Copiar Função (NÃO recortar ainda)

// [pasta]/[modulo-destino].js

function funcaoExtraida() {
  // Código COPIADO do original
  // Ainda não modificou o original
}

module.exports = { funcaoExtraida };

PASSO 4: Testar Módulo Isolado

# Verificar syntax
node --check [modulo-destino].js

# Teste unitário se possível
node -e "const m = require('./[modulo-destino]'); console.log(m.funcaoExtraida);"

PASSO 5: Atualizar Original para Usar Módulo

// [arquivo-original].js

// ADICIONAR import no topo
const { funcaoExtraida } = require('./[pasta]/[modulo-destino]');

// MANTER função original COMENTADA (não deletar ainda)
/​*
function funcaoExtraida() {
  // código antigo
}
*/

// Código que chamava funcaoExtraida() continua funcionando
// porque agora vem do import

PASSO 6: Testar Sistema Completo

# Testar funcionalidade no browser/​app
# Verificar console por erros
# Testar casos de uso principais

PASSO 7: Commit Atômico

git add [modulo-destino].js [arquivo-original].js
git commit -m "refactor: extract funcaoExtraida to [modulo]

- Moved funcaoExtraida from monolith to dedicated module
- Original function kept commented for safety
- All tests passing"

PASSO 8: Só Depois de Validado, Remover Código Comentado

# Após 1-2 dias sem problemas em produção
# Remover função comentada do original
git commit -m "chore: remove commented legacy funcaoExtraida"

### 5.3 Ordem de Extração Recomendada

```markdown
## ORDEM SEGURA DE EXTRAÇÃO

NÍVEL 1 - RISCO ZERO (fazer primeiro)
├── Constantes e configuração
├── Funções utilitárias puras
└── Funções sem dependências internas

NÍVEL 2 - RISCO BAIXO
├── Funções de formatação
├── Funções de validação
└── Helpers de cálculo

NÍVEL 3 - RISCO MÉDIO
├── Funções de API/​fetch
├── Funções de cache
└── Event handlers simples

NÍVEL 4 - RISCO ALTO (fazer por último)
├── Funções de UI que manipulam estado
├── Funções de inicialização
└── Orquestradores/​controllers

NÍVEL 5 - NUNCA EXTRAIR SOZINHO
├── Funções com dependência circular
├── Funções que modificam estado global
└── Funções com efeitos colaterais ocultos
→ Requer refatoração prévia do estado

---

✅ FASE 6: VALIDAÇÃO E TESTES

6.1 Testes de Regressão

## CHECKLIST DE REGRESSÃO (após cada extração)

### Funcional
□ Feature principal funciona
□ Features secundárias funcionam
□ Edge cases funcionam
□ Erros são tratados corretamente

### Performance
□ Tempo de carregamento similar
□ Sem memory leaks novos
□ Sem requests duplicados

### Compatibilidade
□ Funciona no Chrome
□ Funciona no Firefox
□ Funciona no Safari
□ Funciona no mobile

### Multi-tenant (se aplicável)
□ Dados isolados por liga_id
□ Sem vazamento entre tenants

6.2 Smoke Test Rápido

// Script de smoke test
async function smokeTest() {
  const checks = [];
  
  // 1. Módulos carregam sem erro
  try {
    const config = require('./​config');
    const core = require('./​core');
    const ui = require('./​ui');
    checks.push({ name: 'Modules load', status: '✅' });
  } catch (e) {
    checks.push({ name: 'Modules load', status: '❌', error: e.message });
  }
  
  // 2. Funções existem
  const requiredFunctions = ['init', 'render', 'fetchData'];
  requiredFunctions.forEach(fn => {
    const exists = typeof core[fn] === 'function';
    checks.push({ name: `Function ${fn}`, status: exists ? '✅' : '❌' });
  });
  
  // 3. Exports corretos
  // ...
  
  console.table(checks);
  return checks.every(c => c.status === '✅');
}

---

🚨 FASE 7: ROLLBACK E RECUPERAÇÃO

7.1 Plano de Rollback

## ROLLBACK PLAN

### Cenário 1: Bug detectado imediatamente
```bash
# Reverter último commit
git revert HEAD

Cenário 2: Bug detectado após múltiplas extrações

# Voltar para estado antes da refatoração
git log --oneline  # Encontrar commit anterior
git checkout [hash-commit-seguro] -- [arquivo-original].js

Cenário 3: Rollback completo

# Voltar branch inteira
git checkout main
git branch -D refactor/[nome]

# Restaurar backup
cp [arquivo].js.backup [arquivo].js

Cenário 4: Produção quebrou

# Deploy emergencial do backup
# 1. Reverter no git
# 2. Rebuild
# 3. Deploy
# 4. Investigar em ambiente de dev

### 7.2 Pontos de Verificação

```markdown
## CHECKPOINTS DE SEGURANÇA

Criar checkpoint ANTES de:
□ Extrair primeira função
□ Extrair função crítica
□ Modificar estrutura de estado
□ Alterar ordem de inicialização
□ Remover código comentado

Checkpoint = commit + tag
```bash
git commit -m "checkpoint: before extracting [funcao]"
git tag checkpoint-[nome]-[data]

---

## 📋 TEMPLATES E CHECKLISTS

### Template: Documento de Refatoração

```markdown
# REFATORAÇÃO: [Nome do Arquivo]

## Metadata
- **Arquivo:** [caminho/​arquivo.js]
- **Linhas:** [XXX]
- **Data início:** [data]
- **Responsável:** [nome]
- **Status:** [Em análise | Em andamento | Concluído | Pausado]

## Motivação
[Por que refatorar este arquivo?]

## Análise
- Funções identificadas: [X]
- Responsabilidades: [lista]
- Dependências externas: [lista]
- Riscos identificados: [lista]

## Estrutura Proposta
[Diagrama de módulos]

## Plano de Execução
| # | Extração | Risco | Status | Data |
|---|----------|-------|--------|------|
| 1 | utils.js | Baixo | ✅ | [data] |
| 2 | config.js | Baixo | ⏳ | |
| ... | ... | ... | ... | |

## Validações
- [ ] Testes funcionais
- [ ] Testes de regressão
- [ ] Review de código
- [ ] Aprovação stakeholder

## Rollback
[Instruções de rollback]

## Lições Aprendidas
[Preencher ao final]

Checklist Master

## CHECKLIST COMPLETO - REFATORAÇÃO DE MONOLITO

### PRÉ-REFATORAÇÃO
□ Entendi 100% da lógica de negócio
□ Mapeei 100% das dependências
□ Identifiquei costuras naturais
□ Proposta aprovada pelo stakeholder
□ Tenho ambiente de teste
□ Tenho plano de rollback
□ Branch criada
□ Backup feito

### DURANTE REFATORAÇÃO
□ Extraindo uma função por vez
□ Commitando após cada extração
□ Testando após cada commit
□ Mantendo código antigo comentado
□ Documentando decisões

### PÓS-REFATORAÇÃO
□ Todos testes passando
□ Performance validada
□ Multi-tenant validado
□ Code review feito
□ Documentação atualizada
□ Código comentado removido
□ Branch mergeada
□ Tag de versão criada

### MONITORAMENTO (1 semana após)
□ Sem bugs reportados
□ Sem degradação de performance
□ Equipe consegue manter novos módulos
□ Lições aprendidas documentadas

---

🚫 ANTI-PATTERNS (NUNCA FAZER)

❌ Big Bang Refactor

ERRADO: Refatorar tudo de uma vez, commitar no final
CERTO: Uma extração por vez, um commit por extração

❌ Refatorar Sem Entender

ERRADO: "Vou separar em módulos porque está grande"
CERTO: "Entendi que X faz Y por causa de Z, posso extrair"

❌ Deletar Código Imediatamente

ERRADO: Recortar função do original para o módulo
CERTO: Copiar, testar, só depois comentar, só depois deletar

❌ Criar Micro-Módulos

ERRADO: Um arquivo por função (50 arquivos de 20 linhas)
CERTO: Agrupar por responsabilidade (5-8 arquivos coesos)

❌ Ignorar Dependências Circulares

ERRADO: Extrair A que depende de B que depende de A
CERTO: Resolver ciclo primeiro (extrair dependência comum C)

❌ Refatorar e Adicionar Feature

ERRADO: "Já que estou mexendo, vou melhorar X também"
CERTO: Refatoração pura, sem mudança de comportamento

---

🎯 COMANDOS DE ATIVAÇÃO

Iniciar Análise

@Refactor-Monolith analisar [caminho/​arquivo.js]

Continuar de Fase Específica

@Refactor-Monolith fase-2 [caminho/​arquivo.js]  # Mapeamento
@Refactor-Monolith fase-4 [caminho/​arquivo.js]  # Proposta
@Refactor-Monolith fase-5 [caminho/​arquivo.js]  # Extração

Extrair Função Específica

@Refactor-Monolith extrair [funcao] de [origem] para [destino]

---

📚 REFERÊNCIAS

Princípios Aplicados

• S.A.I.S (Solicitar → Analisar → Identificar → Alterar)
• S.D.A (Sistema de Dependências Arquiteturais)
• Antipattern (Preservar intenção original)
• Preservação da Lógica (Nunca quebrar funcionalidade)

Integração com Workflow

/​pesquisa → identifica monolito problemático
/​Refactor-Monolith → planeja decomposição
/​spec → detalha mudanças cirúrgicas
/​code → implementa extrações

---

STATUS: 🏗️ REFACTOR-MONOLITH - SURGICAL DECOMPOSITION PROTOCOL

Versão: 1.0

Última atualização: 2026-01-17