Publisher CLI - Guia Completo para Administradores

🚀 Visão Geral

O Publisher CLI é uma ferramenta de linha de comando para gerenciar o sistema Publisher de imóveis multi-tenant. Este guia documenta funcionalidades avançadas para usuários administradores.

📋 Hierarquia de Usuários

• Admin (Sistema): Único usuário que pode gerenciar TODOS os tenants
• Master (Tenant): Dono de um tenant específico, acessa apenas seus dados
• User (Tenant): Usuário regular dentro de um tenant

🔐 Autenticação e Gerenciamento de Sessão

Login Básico

# Login como admin (especificando tenant)
pnpm dev auth login --email <admin-email> --password <admin-password> --tenant <tenant-id>

# Login como usuário master de um tenant
pnpm dev auth login --email <user-email> --password <user-password>

Verificar Status da Autenticação

# Mostra informações do usuário atual
pnpm dev auth status

# Saída esperada para Admin:
✅ Autenticado
────────────────────────────────────────
Email: <email-do-usuario>
API URL: https://publisher-api.vercel.app/api/v1
Tenant ativo: <tenant-id>

👤 Usuário:
  Nome: <nome-do-usuario>
  Email: <email-do-usuario>
  Tenant: <tenant-id>
  Admin: Sim/Não
  Master: Sim/Não

Informações Detalhadas do Token JWT

# Mostra payload completo do token, validade, etc
pnpm dev auth info

# Informações mostradas:
- Header (algoritmo, tipo)
- Payload (usuário, tenant, permissões)
- Validade (emissão, expiração, dias restantes)
- Token parcial
- Configuração local vs token

🏢 Gerenciamento de Tenants (Admin Only)

Listar Todos os Tenants

# Lista com tabela formatada
pnpm dev tenant list

# Lista em JSON (útil para scripts)
pnpm dev tenant list --json

# Com limite de resultados
pnpm dev tenant list --limit 10

Buscar Tenant Específico

# Buscar por nome (case insensitive)
pnpm dev tenant list --json | grep -i "XYZ" -B 1 -A 3

# Exemplo de saída:
"key": "XYZ-1234",
"name": "Imobiliária XYZ",
"email": "[email protected]"

Trocar de Tenant (Admin Only)

# IMPORTANTE: Este comando usa PUT /auth/tenant e recebe NOVO TOKEN
pnpm dev auth tenant MLC-8217

# O que acontece:
1. Faz PUT /auth/tenant com o novo tenant
2. Recebe novo token JWT com tenant codificado
3. Salva automaticamente o novo token
4. Agora todas as operações são no contexto desse tenant

💾 Backup de Dados

Backup do Tenant Atual

# Backup padrão (cria pasta com timestamp)
pnpm dev backup

# Backup com diretório específico
pnpm dev backup -o meu-backup

# Formato YAML (padrão é JSON)
pnpm dev backup -f yaml

Backup de Qualquer Tenant (Admin Only)

# 1. Primeiro trocar para o tenant desejado
pnpm dev auth tenant XYZ-1234

# 2. Fazer backup
pnpm dev backup -o casa-top-backup

# Resultado: Baixa TODOS os dados do tenant

O que é Incluído no Backup

• ✅ Properties (imóveis)
• ✅ Users (usuários)
• ✅ Tenant (informações do tenant)
• ✅ Roles (papéis/permissões)
• ✅ Cities (cidades)
• ✅ Districts (bairros)
• ✅ Integrations (integrações)
• ❌ Events (excluído propositalmente)
• ❌ Items (endpoint não disponível)

Estrutura do Backup

backup-directory/
├── properties.json    # Todos os imóveis
├── users.json        # Usuários do tenant
├── tenant.json       # Dados do tenant
├── roles.json        # Papéis/permissões
├── cities.json       # Cidades cadastradas
├── districts.json    # Bairros
├── integrations.json # Integrações
└── metadata.json     # Informações do backup

🔄 Paginação e Performance

Como Funciona a Paginação

• API usa DynamoDB com paginação por startKey
• Backup baixa automaticamente 100 items por vez
• Continua até não haver mais startKey na resposta

Exemplo de Resposta com Paginação

{
  "properties": [...],  // ou "data": [...]
  "startKey": "xyz123" // Se presente, há mais páginas
}

🎯 Casos de Uso Práticos

1. Admin Fazendo Backup de Vários Tenants

# Fazer login como admin
pnpm dev auth login --email <admin-email> --password <admin-password> --tenant <tenant-id>

# Backup do Marcio
pnpm dev auth tenant MLC-8217
pnpm dev backup -o backups/marcio-$(date +%Y%m%d)

# Backup da Casa Top
pnpm dev auth tenant XYZ-1234
pnpm dev backup -o backups/casa-top-$(date +%Y%m%d)

# Voltar ao tenant original
pnpm dev auth tenant DEV-001

2. Verificar Quantos Dados um Tenant Tem

# Trocar para o tenant
pnpm dev auth tenant BTS-6104

# Fazer backup e ver o total
pnpm dev backup -o temp-backup

# Output mostrará: "✓ Backed up X items to temp-backup"

3. Script para Backup de Múltiplos Tenants

#!/bin/bash
# backup-tenants.sh

TENANTS=("XYZ-1234" "ABC-1234" "DEF-6104")
ADMIN_EMAIL="<seu-email-admin>"
ADMIN_PASSWORD="<sua-senha-admin>"
ADMIN_TENANT="<seu-tenant-admin>"

# Login como admin
pnpm dev auth login --email $ADMIN_EMAIL --password $ADMIN_PASSWORD --tenant $ADMIN_TENANT

for TENANT in "${TENANTS[@]}"; do
  echo "Backing up $TENANT..."
  pnpm dev auth tenant $TENANT
  pnpm dev backup -o "backups/$TENANT-$(date +%Y%m%d-%H%M%S)"
done

⚠️ Limitações e Observações

Tokens e Sessões

• Token JWT contém o tenant codificado
• Mudar apenas config local NÃO muda o token
• Sempre use auth tenant para trocar corretamente
• Tokens expiram em 31 dias por padrão

Endpoints Importantes

• GET /auth - Verifica autenticação
• PUT /auth/tenant - Troca tenant (admin only)
• GET /tenants - Lista tenants (admin only)
• GET /properties?startKey=X&limit=100 - Lista com paginação

🛠️ Troubleshooting

"Tenant must be provided on request"

• Certifique-se de incluir --tenant no login
• Para admin: use qualquer tenant válido (ex: DEV-001)

Backup retorna poucos dados

• Verifique com auth info se o token tem o tenant correto
• Use auth tenant <id> em vez de apenas mudar a config

Estrutura de Tenant

{
  "id": "ten_Fze9UXfl8au84VH0NdYH8ix3MzFd",
  "key": "XYZ-1234",
  "name": "Imobiliária XYZ",
  "email": "[email protected]",
  "created_at": "2023-12-18T..."
}

🚦 Fluxo Completo de Trabalho

1. Login como Admin

   pnpm dev auth login --email <admin-email> --password <admin-password> --tenant <tenant-id>

2. Verificar Status

   pnpm dev auth status
   pnpm dev auth info

3. Listar Tenants Disponíveis

   pnpm dev tenant list

4. Trocar para Tenant Desejado

   pnpm dev auth tenant XYZ-1234

5. Fazer Backup

   pnpm dev backup -o backup-XYZ-1234

6. Verificar Resultado

   ls -la backup-XYZ-1234/

Nota: Este guia foi criado com base na implementação atual do Publisher CLI. Sempre verifique a versão e atualizações do sistema.