1.0.4 • Published 1 month ago
@techbins/publisher-cli v1.0.4
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": "contato@imobiliariaxyz.com.br"
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çãoPUT /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": "contato@imobiliariaxyz.com.br",
"created_at": "2023-12-18T..."
}
🚦 Fluxo Completo de Trabalho
Login como Admin
pnpm dev auth login --email <admin-email> --password <admin-password> --tenant <tenant-id>
Verificar Status
pnpm dev auth status pnpm dev auth info
Listar Tenants Disponíveis
pnpm dev tenant list
Trocar para Tenant Desejado
pnpm dev auth tenant XYZ-1234
Fazer Backup
pnpm dev backup -o backup-XYZ-1234
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.