@maestro-ai/mcp-server 1.2.0 → 2.1.0

package/dist/content/guides/Guia de Estrat/303/251gias de Cache.md"

@@ -1,352 +0,0 @@
-# Guia de Estratégias de Cache
-
-> **Prioridade**: 🟡 MÉDIA  
-> **Aplicável a**: Projetos Nível 2 (Médio) e Nível 3 (Complexo)
-
----
-
-## Por que Cache?
-
-- **Latência**: Acesso a memória ~100ns vs disco ~10ms vs rede ~100ms
-- **Throughput**: Reduz carga no banco de dados
-- **Custo**: Menos recursos computacionais
-- **Disponibilidade**: Continua servindo se origem falhar (stale data)
-
----
-
-## Padrões de Cache
-
-### 1. Cache-Aside (Lazy Loading)
-
-O mais comum. Aplicação gerencia o cache.
-
-```mermaid
-sequenceDiagram
-    participant App
-    participant Cache
-    participant DB
-    
-    App->>Cache: GET user:123
-    Cache-->>App: null (miss)
-    App->>DB: SELECT * FROM users WHERE id=123
-    DB-->>App: user data
-    App->>Cache: SET user:123 = data
-    App-->>Client: user data
-```
-
-```typescript
-async function getUser(id: string): Promise<User> {
-  const cacheKey = `user:${id}`;
-  
-  // 1. Tentar cache
-  const cached = await redis.get(cacheKey);
-  if (cached) {
-    return JSON.parse(cached);
-  }
-  
-  // 2. Buscar no banco
-  const user = await db.users.findById(id);
-  
-  // 3. Popular cache
-  if (user) {
-    await redis.setex(cacheKey, 3600, JSON.stringify(user));
-  }
-  
-  return user;
-}
-```
-
-**Prós**: Simples, só cacheia o que é acessado  
-**Contras**: Cache miss inicial, dados podem ficar stale
-
----
-
-### 2. Write-Through
-
-Escreve no cache E no banco simultaneamente.
-
-```typescript
-async function updateUser(id: string, data: Partial<User>): Promise<User> {
-  // 1. Atualizar banco
-  const user = await db.users.update(id, data);
-  
-  // 2. Atualizar cache imediatamente
-  await redis.setex(`user:${id}`, 3600, JSON.stringify(user));
-  
-  return user;
-}
-```
-
-**Prós**: Cache sempre atualizado  
-**Contras**: Latência de escrita dobra, escreve dados que talvez não sejam lidos
-
----
-
-### 3. Write-Behind (Write-Back)
-
-Escreve no cache, async para banco.
-
-```typescript
-async function updateUser(id: string, data: Partial<User>): Promise<User> {
-  // 1. Atualizar só no cache
-  const user = { ...await getCachedUser(id), ...data };
-  await redis.setex(`user:${id}`, 3600, JSON.stringify(user));
-  
-  // 2. Enfileirar escrita no banco
-  await queue.add('sync-user-to-db', { id, data });
-  
-  return user;
-}
-```
-
-**Prós**: Escrita super rápida, batch possível  
-**Contras**: Risco de perda de dados, complexidade
-
----
-
-### 4. Read-Through
-
-Cache é um proxy transparente.
-
-```typescript
-// O cache gerencia a busca automaticamente
-const user = await cache.get('user:123', {
-  fallback: () => db.users.findById('123'),
-  ttl: 3600
-});
-```
-
-**Prós**: Código limpo, abstração total  
-**Contras**: Menos controle, dependência do cache library
-
----
-
-## Estratégias de Invalidação
-
-> "There are only two hard things in Computer Science: cache invalidation and naming things."
-
-### 1. TTL (Time-To-Live)
-
-```typescript
-// Cache expira automaticamente
-await redis.setex('user:123', 3600, data); // 1 hora
-```
-
-**Usar quando**: Dados mudam pouco, stale data aceitável
-
-### 2. Invalidação Explícita
-
-```typescript
-async function updateUser(id: string, data: any) {
-  await db.users.update(id, data);
-  await redis.del(`user:${id}`);
-}
-```
-
-**Usar quando**: Consistência importante
-
-### 3. Event-Driven Invalidation
-
-```typescript
-// Producer
-eventBus.emit('user.updated', { userId: '123' });
-
-// Consumer
-eventBus.on('user.updated', async ({ userId }) => {
-  await redis.del(`user:${userId}`);
-  await redis.del(`user-profile:${userId}`);
-});
-```
-
-**Usar quando**: Múltiplos caches afetados, microserviços
-
-### 4. Cache Tags
-
-```typescript
-// Cachear com tags
-await cache.set('product:123', data, { 
-  tags: ['products', 'category:electronics'] 
-});
-
-// Invalidar por tag
-await cache.invalidateTag('category:electronics');
-```
-
-**Usar quando**: Muitos itens relacionados precisam invalidar juntos
-
----
-
-## Padrões Avançados
-
-### Stale-While-Revalidate
-
-Retorna stale imediatamente, atualiza em background.
-
-```typescript
-async function getWithSWR(key: string, fetcher: () => Promise<any>) {
-  const cached = await redis.get(key);
-  
-  if (cached) {
-    const data = JSON.parse(cached);
-    
-    // Se próximo de expirar, revalidar em background
-    if (data._expiresAt < Date.now() + 60000) {
-      refreshInBackground(key, fetcher);
-    }
-    
-    return data.value;
-  }
-  
-  return fetchAndCache(key, fetcher);
-}
-```
-
-### Cache Stampede Prevention
-
-Evita que muitas requisições simultâneas busquem a mesma coisa.
-
-```typescript
-const locks = new Map<string, Promise<any>>();
-
-async function getWithLock(key: string, fetcher: () => Promise<any>) {
-  const cached = await redis.get(key);
-  if (cached) return JSON.parse(cached);
-  
-  // Se já tem requisição em andamento, esperar ela
-  if (locks.has(key)) {
-    return locks.get(key);
-  }
-  
-  // Criar lock
-  const promise = fetcher().then(async (data) => {
-    await redis.setex(key, 3600, JSON.stringify(data));
-    locks.delete(key);
-    return data;
-  });
-  
-  locks.set(key, promise);
-  return promise;
-}
-```
-
-### Multi-Layer Cache
-
-```
-Browser Cache → CDN → Application Cache → Database
-```
-
-```typescript
-async function getProduct(id: string) {
-  // L1: In-memory (LRU)
-  if (memoryCache.has(id)) {
-    return memoryCache.get(id);
-  }
-  
-  // L2: Redis
-  const cached = await redis.get(`product:${id}`);
-  if (cached) {
-    const data = JSON.parse(cached);
-    memoryCache.set(id, data);
-    return data;
-  }
-  
-  // L3: Database
-  const product = await db.products.findById(id);
-  
-  // Populate caches
-  await redis.setex(`product:${id}`, 3600, JSON.stringify(product));
-  memoryCache.set(id, product);
-  
-  return product;
-}
-```
-
----
-
-## Cache para diferentes tipos de dados
-
-| Tipo de Dado | TTL Sugerido | Estratégia |
-|--------------|--------------|------------|
-| Dados de usuário | 5-15 min | Cache-aside + invalidação no update |
-| Configurações | 1-24 horas | Read-through + event invalidation |
-| Catálogo/produtos | 15-60 min | Cache-aside + SWR |
-| Sessions | Até expirar | Write-through |
-| Rate limit counters | 1-60 seg | Write-through |
-| Agregações/reports | 5-60 min | Pre-computed, refresh periódico |
-
----
-
-## Redis Patterns
-
-### Hash para objetos
-
-```typescript
-// Mais eficiente que JSON serializado
-await redis.hset('user:123', {
-  name: 'John',
-  email: 'john@example.com',
-  role: 'admin'
-});
-
-// Buscar campo específico
-const email = await redis.hget('user:123', 'email');
-
-// Buscar tudo
-const user = await redis.hgetall('user:123');
-```
-
-### Sorted Set para rankings/feeds
-
-```typescript
-// Adicionar item com score (timestamp)
-await redis.zadd('user:123:feed', Date.now(), postId);
-
-// Buscar últimos 20
-const recent = await redis.zrevrange('user:123:feed', 0, 19);
-
-// Remover antigos
-await redis.zremrangebyrank('user:123:feed', 0, -101); // Manter só 100
-```
-
-### Set para tags/relacionamentos
-
-```typescript
-// Adicionar tags
-await redis.sadd('product:123:tags', 'electronics', 'sale', 'featured');
-
-// Buscar produtos com múltiplas tags
-const products = await redis.sinter('tag:electronics', 'tag:sale');
-```
-
----
-
-## Checklist de Implementação
-
-- [ ] Padrão de cache definido por tipo de dado
-- [ ] TTLs configurados apropriadamente
-- [ ] Estratégia de invalidação documentada
-- [ ] Proteção contra cache stampede
-- [ ] Monitoramento de hit/miss ratio
-- [ ] Alertas para Redis indisponível
-- [ ] Fallback gracioso se cache falhar
-- [ ] Testes com cache habilitado E desabilitado
-
----
-
-## Métricas para Monitorar
-
-| Métrica | Alerta se... |
-|---------|--------------|
-| Hit Rate | < 80% (depende do caso) |
-| Latência p99 | > 10ms |
-| Memória usada | > 80% do disponível |
-| Evictions | Taxa alta inesperada |
-| Conexões | Próximo do max |
-
----
-
-## Referências
-
-- [Redis Best Practices](https://redis.io/docs/manual/patterns/)
-- [Caching Strategies](https://codeahoy.com/2017/08/11/caching-strategies-and-how-to-choose-the-right-one/)
-- [Facebook TAO](https://www.usenix.org/system/files/conference/atc13/atc13-bronson.pdf)

package/dist/content/guides/Guia de Migrations Zero-Downtime.md

@@ -1,311 +0,0 @@
-# Guia de Migrations Zero-Downtime
-
-> **Prioridade**: 🟠 ALTA  
-> **Aplicável a**: Projetos Nível 2 (Médio) e Nível 3 (Complexo)
-
----
-
-## O Problema
-
-Migrations tradicionais podem causar:
-- **Downtime** durante alterações de schema
-- **Erros** em deploys blue-green (versão antiga vs nova)
-- **Locks** em tabelas grandes (minutos a horas)
-- **Rollback impossível** após aplicar destructive changes
-
----
-
-## Princípios Fundamentais
-
-### 1. Backward Compatibility
-
-Toda migration deve ser compatível com a versão **anterior** do código por pelo menos um ciclo de deploy.
-
-```
-Deploy N:   Código v1 + Schema v1
-Deploy N+1: Código v2 + Schema v2 (compatível com v1)
-Deploy N+2: Código v2 + Schema v3 (pode remover compatibilidade)
-```
-
-### 2. Expand-Contract Pattern
-
-Nunca faça alterações destrutivas diretamente.
-
-```mermaid
-graph LR
-    A[Estado Inicial] -->|1. Expand| B[Adiciona novo]
-    B -->|2. Migrate| C[Transfere dados]
-    C -->|3. Contract| D[Remove antigo]
-```
-
-### 3. Small, Incremental Changes
-
-- Uma alteração por migration
-- Migrations devem ser rápidas (< 1 segundo em tabelas grandes)
-- Rollback sempre possível
-
----
-
-## Padrões de Migration
-
-### Adicionar Coluna (Seguro ✅)
-
-```sql
--- Step 1: Adicionar coluna nullable ou com default
-ALTER TABLE users ADD COLUMN phone VARCHAR(20);
-
--- Step 2: (Código) Deploy versão que escreve na nova coluna
--- Step 3: (Job) Preencher dados antigos se necessário
--- Step 4: (Código) Deploy versão que lê da nova coluna
--- Step 5: (Se necessário) Tornar NOT NULL
-ALTER TABLE users ALTER COLUMN phone SET NOT NULL;
-```
-
-### Renomear Coluna (⚠️ Requer Cuidado)
-
-**❌ NUNCA FAÇA:**
-```sql
-ALTER TABLE users RENAME COLUMN name TO full_name;
-```
-
-**✅ FAÇA EM 3 DEPLOYS:**
-
-```sql
--- Deploy 1: Adicionar nova coluna
-ALTER TABLE users ADD COLUMN full_name VARCHAR(255);
-
--- Deploy 1: Trigger para sincronizar (opcional, ou fazer no código)
-CREATE TRIGGER sync_name_columns
-BEFORE INSERT OR UPDATE ON users
-FOR EACH ROW
-EXECUTE FUNCTION sync_name_to_full_name();
-```
-
-```python
-# Deploy 2: Código escreve em ambas, lê da nova
-def update_user(user_id, name):
-    db.execute("""
-        UPDATE users 
-        SET name = %s, full_name = %s 
-        WHERE id = %s
-    """, name, name, user_id)
-    
-def get_user(user_id):
-    # Lê da nova coluna
-    return db.query("SELECT full_name FROM users WHERE id = %s", user_id)
-```
-
-```sql
--- Deploy 3: Remover coluna antiga
-ALTER TABLE users DROP COLUMN name;
-```
-
-### Remover Coluna (⚠️ 2 Deploys)
-
-```python
-# Deploy 1: Código para de usar a coluna
-# (mas schema ainda tem a coluna)
-```
-
-```sql
--- Deploy 2: Remover coluna (depois que código antigo não está mais ativo)
-ALTER TABLE users DROP COLUMN legacy_field;
-```
-
-### Adicionar Índice (⚠️ Pode Bloquear)
-
-**❌ Bloqueia tabela:**
-```sql
-CREATE INDEX idx_users_email ON users(email);
-```
-
-**✅ Não bloqueia (PostgreSQL):**
-```sql
-CREATE INDEX CONCURRENTLY idx_users_email ON users(email);
-```
-
-**✅ Não bloqueia (MySQL 8+):**
-```sql
-ALTER TABLE users ADD INDEX idx_email (email), ALGORITHM=INPLACE, LOCK=NONE;
-```
-
-### Alterar Tipo de Coluna (⚠️ Complexo)
-
-Use o Expand-Contract:
-
-```sql
--- Step 1: Adiciona nova coluna
-ALTER TABLE orders ADD COLUMN amount_cents BIGINT;
-
--- Step 2: Trigger ou código para sincronizar
--- Step 3: Backfill job
-UPDATE orders SET amount_cents = amount * 100 WHERE amount_cents IS NULL;
-
--- Step 4: Código usa nova coluna
--- Step 5: Remove coluna antiga
-ALTER TABLE orders DROP COLUMN amount;
-```
-
----
-
-## Migrations em Tabelas Grandes
-
-Para tabelas com milhões de registros:
-
-### Técnica 1: Batch Processing
-
-```python
-def backfill_in_batches(batch_size=1000):
-    while True:
-        affected = db.execute("""
-            UPDATE users 
-            SET new_column = compute_value(old_column)
-            WHERE new_column IS NULL
-            LIMIT %s
-        """, batch_size)
-        
-        if affected == 0:
-            break
-            
-        time.sleep(0.1)  # Evita sobrecarga
-```
-
-### Técnica 2: pt-online-schema-change (MySQL)
-
-```bash
-pt-online-schema-change --execute \
-    --alter "ADD COLUMN phone VARCHAR(20)" \
-    D=mydb,t=users
-```
-
-### Técnica 3: gh-ost (MySQL)
-
-```bash
-gh-ost \
-    --database=mydb \
-    --table=users \
-    --alter="ADD COLUMN phone VARCHAR(20)" \
-    --execute
-```
-
-### Técnica 4: pgroll (PostgreSQL)
-
-```yaml
-# migration.yaml
-operations:
-  - add_column:
-      table: users
-      column:
-        name: phone
-        type: varchar(20)
-        nullable: true
-```
-
----
-
-## Feature Flags para Schema
-
-Controle quais versões do código usam qual schema:
-
-```python
-# config/feature_flags.py
-SCHEMA_V2_ENABLED = os.getenv('SCHEMA_V2_ENABLED', 'false') == 'true'
-
-# models/user.py
-class User:
-    def get_display_name(self):
-        if SCHEMA_V2_ENABLED:
-            return self.full_name
-        return self.name
-```
-
----
-
-## Rollback Strategies
-
-### Migrations Reversíveis
-
-```python
-# Django
-class Migration(migrations.Migration):
-    operations = [
-        migrations.AddField(
-            model_name='user',
-            name='phone',
-            field=models.CharField(max_length=20, null=True),
-        ),
-    ]
-    
-    def reverse(self):
-        # Explícito: remover o campo
-        pass
-```
-
-### Sempre Tenha Backup
-
-```bash
-# Antes de migrations em produção
-pg_dump -Fc mydb > backup_before_migration_$(date +%Y%m%d).dump
-
-# Verificar que backup é restaurável
-pg_restore --list backup.dump
-```
-
----
-
-## Checklist de Migration
-
-### Antes da Migration
-
-- [ ] Migration testada em ambiente de staging
-- [ ] Tempo de execução medido em dataset similar ao prod
-- [ ] Plano de rollback documentado
-- [ ] Backup recente verificado
-- [ ] Horário de baixo tráfego escolhido (se necessário)
-
-### Durante a Migration
-
-- [ ] Monitorar locks e tempo de execução
-- [ ] Monitorar CPU/memória do banco
-- [ ] Logs de aplicação para erros
-- [ ] Comunicação com time se demorar
-
-### Após a Migration
-
-- [ ] Verificar integridade dos dados
-- [ ] Remover código/colunas legadas no próximo deploy
-- [ ] Atualizar documentação de schema
-
----
-
-## Ferramentas por Stack
-
-| Stack | Ferramenta | Recursos |
-|-------|-----------|----------|
-| **PostgreSQL** | pgroll, Flyway | Online DDL, versioning |
-| **MySQL** | gh-ost, pt-osc | Zero-downtime ALTERs |
-| **Rails** | strong_migrations | Bloqueia migrations perigosas |
-| **Django** | django-pg-zero-downtime-migrations | Checks automáticos |
-| **Node.js** | TypeORM, Prisma | Migrations declarativas |
-| **Java** | Flyway, Liquibase | Enterprise-ready |
-
----
-
-## Anti-Patterns
-
-| ❌ Não Faça | ✅ Faça Assim |
-|-------------|---------------|
-| Renomear coluna diretamente | Expand-Contract em 3 deploys |
-| Alterar tipo diretamente | Nova coluna + migrar dados |
-| DROP COLUMN com código usando | Remover uso no código primeiro |
-| CREATE INDEX sem CONCURRENTLY | Usar CONCURRENTLY ou online DDL |
-| Múltiplas alterações em uma migration | Uma alteração por migration |
-
----
-
-## Referências
-
-- [Stripe - Online Migrations at Scale](https://stripe.com/blog/online-migrations)
-- [GitHub - gh-ost](https://github.com/github/gh-ost)
-- [PostgreSQL - ALTER TABLE](https://www.postgresql.org/docs/current/sql-altertable.html)
-- [Strong Migrations (Rails)](https://github.com/ankane/strong_migrations)