@maestro-ai/cli 1.0.0

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

@@ -0,0 +1,311 @@
+# 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)

package/content/guides/Guia de Multi-tenancy.md

@@ -0,0 +1,368 @@
+# Guia de Multi-tenancy
+
+> **Prioridade**: 🟡 MÉDIA  
+> **Aplicável a**: SaaS, plataformas com múltiplos clientes/organizações
+
+---
+
+## O que é Multi-tenancy?
+
+Multi-tenancy é uma arquitetura onde uma única instância de software serve múltiplos clientes (tenants) com isolamento de dados.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Aplicação SaaS                       │
+├─────────────────────────────────────────────────────────┤
+│  Tenant A  │  Tenant B  │  Tenant C  │  Tenant D        │
+│  (Empresa X)│ (Empresa Y) │ (Startup Z)│ (Corp W)       │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Modelos de Isolamento
+
+### 1. Database per Tenant
+
+Cada tenant tem seu próprio banco de dados.
+
+```mermaid
+graph TD
+    App[Aplicação] --> DB1[(Tenant A DB)]
+    App --> DB2[(Tenant B DB)]
+    App --> DB3[(Tenant C DB)]
+```
+
+| Prós | Contras |
+|------|---------|
+| Isolamento máximo | Maior custo de infra |
+| Fácil backups por tenant | Complexidade operacional |
+| Boa para compliance | Migrations em muitos DBs |
+| Customização por tenant | Não escala para muitos tenants |
+
+**Usar quando**: Enterprise customers, compliance rígido (HIPAA, PCI), <100 tenants
+
+### 2. Schema per Tenant
+
+Um banco, mas schemas separados por tenant.
+
+```mermaid
+graph TD
+    App[Aplicação] --> DB[(Database)]
+    DB --> S1[schema_tenant_a]
+    DB --> S2[schema_tenant_b]
+    DB --> S3[schema_tenant_c]
+```
+
+| Prós | Contras |
+|------|---------|
+| Bom isolamento | Migrations por schema |
+| Mais barato que DB separado | Limite de schemas |
+| Fácil backup por tenant | Consultas cross-tenant complexas |
+
+**Usar quando**: Poucas centenas de tenants, isolamento importante
+
+### 3. Row-Level Security (Shared Database)
+
+Todos os tenants na mesma tabela, filtrados por tenant_id.
+
+```sql
+-- Todas as tabelas têm tenant_id
+CREATE TABLE orders (
+    id UUID PRIMARY KEY,
+    tenant_id UUID NOT NULL,
+    customer_name VARCHAR(255),
+    ...
+);
+
+CREATE INDEX idx_orders_tenant ON orders(tenant_id);
+```
+
+| Prós | Contras |
+|------|---------|
+| Escala para milhares de tenants | Risco de vazamento de dados |
+| Operação simples | Queries precisam sempre filtrar |
+| Migrations únicas | Backup por tenant é complexo |
+| Menor custo | Menos isolamento de performance |
+
+**Usar quando**: Muitos tenants pequenos (1000+), dados similares, startups
+
+### 4. Híbrido
+
+Tenants pequenos compartilham, grandes têm DB próprio.
+
+```mermaid
+graph TD
+    App[Aplicação] --> DB1[(Shared DB)]
+    App --> DB2[(Enterprise A DB)]
+    App --> DB3[(Enterprise B DB)]
+    DB1 --> T1[tenant_1..99]
+```
+
+**Usar quando**: Freemium + Enterprise, mix de necessidades
+
+---
+
+## Implementação: Row-Level Security
+
+### PostgreSQL RLS
+
+```sql
+-- Habilitar RLS
+ALTER TABLE orders ENABLE ROW LEVEL SECURITY;
+
+-- Policy: usuários só veem dados do seu tenant
+CREATE POLICY tenant_isolation ON orders
+    FOR ALL
+    USING (tenant_id = current_setting('app.current_tenant')::uuid);
+
+-- No código, antes de cada requisição:
+-- SET app.current_tenant = 'tenant-uuid';
+```
+
+### Middleware de Tenant (Node.js)
+
+```typescript
+// middleware/tenantContext.ts
+import { AsyncLocalStorage } from 'async_hooks';
+
+interface TenantContext {
+  tenantId: string;
+  tenantConfig?: TenantConfig;
+}
+
+export const tenantStorage = new AsyncLocalStorage<TenantContext>();
+
+export function tenantMiddleware(req, res, next) {
+  // Extrair tenant de: subdomain, header, JWT, etc.
+  const tenantId = extractTenantId(req);
+  
+  if (!tenantId) {
+    return res.status(400).json({ error: 'Tenant not identified' });
+  }
+
+  tenantStorage.run({ tenantId }, () => {
+    // Setar no Prisma/TypeORM para RLS
+    db.$executeRaw`SET app.current_tenant = ${tenantId}`;
+    next();
+  });
+}
+
+function extractTenantId(req): string | null {
+  // Opção 1: Subdomain (tenant1.app.com)
+  const subdomain = req.hostname.split('.')[0];
+  if (subdomain !== 'www' && subdomain !== 'app') {
+    return getTenantIdBySubdomain(subdomain);
+  }
+  
+  // Opção 2: Header
+  if (req.headers['x-tenant-id']) {
+    return req.headers['x-tenant-id'];
+  }
+  
+  // Opção 3: JWT claim
+  if (req.user?.tenantId) {
+    return req.user.tenantId;
+  }
+  
+  return null;
+}
+
+// Helper para acessar tenant em qualquer lugar
+export function getCurrentTenant(): TenantContext {
+  const context = tenantStorage.getStore();
+  if (!context) throw new Error('No tenant context');
+  return context;
+}
+```
+
+### Repository Pattern com Tenant Scope
+
+```typescript
+// repositories/BaseRepository.ts
+import { getCurrentTenant } from '../middleware/tenantContext';
+
+export abstract class BaseRepository<T> {
+  protected abstract tableName: string;
+
+  async findAll(): Promise<T[]> {
+    const { tenantId } = getCurrentTenant();
+    return db.query(
+      `SELECT * FROM ${this.tableName} WHERE tenant_id = $1`,
+      [tenantId]
+    );
+  }
+
+  async findById(id: string): Promise<T | null> {
+    const { tenantId } = getCurrentTenant();
+    return db.queryOne(
+      `SELECT * FROM ${this.tableName} WHERE id = $1 AND tenant_id = $2`,
+      [id, tenantId]
+    );
+  }
+
+  async create(data: Omit<T, 'id' | 'tenant_id'>): Promise<T> {
+    const { tenantId } = getCurrentTenant();
+    return db.insert(this.tableName, { ...data, tenant_id: tenantId });
+  }
+}
+
+// Uso
+class OrderRepository extends BaseRepository<Order> {
+  tableName = 'orders';
+  
+  async findByStatus(status: string): Promise<Order[]> {
+    const { tenantId } = getCurrentTenant();
+    return db.query(
+      `SELECT * FROM orders WHERE status = $1 AND tenant_id = $2`,
+      [status, tenantId]
+    );
+  }
+}
+```
+
+---
+
+## Identificação de Tenant
+
+| Método | Exemplo | Prós | Contras |
+|--------|---------|------|---------|
+| **Subdomain** | `acme.app.com` | Óbvio para usuário | DNS/SSL por tenant |
+| **Path** | `app.com/acme/...` | Simples | Polui URLs |
+| **Header** | `X-Tenant-ID` | Limpo | Só para APIs |
+| **JWT Claim** | `{ tenantId: '...' }` | Seguro, autenticado | Precisa de auth |
+| **Query Param** | `?tenant=acme` | Fácil testar | Fácil vazar |
+
+**Recomendação**: Subdomain para apps, Header/JWT para APIs.
+
+---
+
+## Customização por Tenant
+
+### Configurações
+
+```typescript
+interface TenantConfig {
+  id: string;
+  name: string;
+  subdomain: string;
+  plan: 'free' | 'pro' | 'enterprise';
+  features: {
+    maxUsers: number;
+    customBranding: boolean;
+    ssoEnabled: boolean;
+    apiAccess: boolean;
+  };
+  branding?: {
+    logo: string;
+    primaryColor: string;
+  };
+}
+
+// Cache de config por tenant
+const tenantConfigCache = new Map<string, TenantConfig>();
+
+async function getTenantConfig(tenantId: string): Promise<TenantConfig> {
+  if (tenantConfigCache.has(tenantId)) {
+    return tenantConfigCache.get(tenantId)!;
+  }
+  
+  const config = await db.tenants.findById(tenantId);
+  tenantConfigCache.set(tenantId, config);
+  return config;
+}
+```
+
+### Feature Flags por Tenant
+
+```typescript
+async function hasFeature(feature: string): Promise<boolean> {
+  const { tenantId } = getCurrentTenant();
+  const config = await getTenantConfig(tenantId);
+  return config.features[feature] === true;
+}
+
+// Uso
+if (await hasFeature('ssoEnabled')) {
+  // Mostrar opções de SSO
+}
+```
+
+---
+
+## Segurança
+
+### Checklist de Isolamento
+
+- [ ] Todas as queries filtram por tenant_id
+- [ ] Índices incluem tenant_id
+- [ ] Uploads/Storage segregados por tenant
+- [ ] Logs incluem tenant para auditoria
+- [ ] Rate limiting por tenant
+- [ ] Testes verificam isolamento
+
+### Testes de Isolamento
+
+```typescript
+describe('Tenant Isolation', () => {
+  it('should not access data from other tenants', async () => {
+    // Setup: criar dados em dois tenants
+    await asTenant('tenant-a', async () => {
+      await orderRepo.create({ product: 'A' });
+    });
+    
+    await asTenant('tenant-b', async () => {
+      await orderRepo.create({ product: 'B' });
+    });
+
+    // Verificar isolamento
+    await asTenant('tenant-a', async () => {
+      const orders = await orderRepo.findAll();
+      expect(orders.every(o => o.tenant_id === 'tenant-a')).toBe(true);
+      expect(orders.find(o => o.product === 'B')).toBeUndefined();
+    });
+  });
+});
+```
+
+---
+
+## Migrations Multi-tenant
+
+### Para Shared Database
+
+```sql
+-- Migration normal - aplica para todos
+ALTER TABLE orders ADD COLUMN priority INT DEFAULT 0;
+```
+
+### Para Schema per Tenant
+
+```bash
+# Script para aplicar migration em todos os schemas
+for schema in $(psql -t -c "SELECT schema_name FROM information_schema.schemata WHERE schema_name LIKE 'tenant_%'"); do
+  psql -c "SET search_path TO $schema; -- migration SQL here;"
+done
+```
+
+---
+
+## Checklist de Implementação
+
+- [ ] Modelo de isolamento escolhido e documentado
+- [ ] Middleware de identificação de tenant
+- [ ] Todas as queries incluem tenant_id
+- [ ] Testes de isolamento automatizados
+- [ ] Config/features por tenant
+- [ ] Rate limiting por tenant
+- [ ] Logs e métricas por tenant
+- [ ] Backup/restore por tenant (se necessário)
+- [ ] Provisioning de novo tenant automatizado
+
+---
+
+## Referências
+
+- [Multi-tenancy Patterns (Microsoft)](https://docs.microsoft.com/en-us/azure/architecture/guide/multitenant/overview)
+- [PostgreSQL Row-Level Security](https://www.postgresql.org/docs/current/ddl-rowsecurity.html)
+- [Multi-tenant SaaS Patterns (AWS)](https://aws.amazon.com/solutions/implementations/saas-tenant-isolation/)