Pular para conteúdo

Frontend Entrypoint e Painel

O subsistema de gestão é formado por dois componentes que trabalham juntos: o panel (Single-Page Application em React/Vite servida por Nginx) e o frontend-entrypoint (Backend-for-Frontend / BFF desenvolvido em FastAPI, também referenciado internamente como platform_api).

Ele centraliza a autenticação dos lojistas e administradores, o ciclo de vida e credenciais de cada loja, o gerenciamento de sessões, a administração do número central B2B e serve como fonte única de verdade dos lojistas para os demais microsserviços da plataforma.


Papel na Plataforma

flowchart TD
    user([Lojista / Super Admin]) -->|HTTPS| panel[Panel SPA: Nginx :8000]
    panel -->|HTML / JS / Assets estáticos| user
    panel -->|Proxy /auth, /api, /merchants| bff[Frontend Entrypoint / BFF: :7000]

    bff <-->|Sessões sid: TTL| redis[(Redis)]
    bff <-->|Schema platform: merchants & config| db[(PostgreSQL)]

    bff -->|Embedded Signup & Provisionamento| wpp[WhatsApp Entrypoint]
    bff -->|Healthcheck & OAuth Connect| woo[WooCommerce Wrapper]
    bff -->|Copilot Chat & Métricas| mkt[Marketing Campaigns]

    subgraph InternalConsumers [Consumidores Internos do platform_api]
        wpp_c[WhatsApp Entrypoint]
        woo_c[WooCommerce Wrapper]
        b2c_c[Agente B2C]
        b2b_c[Agente B2B]
    end

    InternalConsumers -->|GET /internal/merchants/*| bff

    style panel fill:#f0f9ff,stroke:#0284c7,stroke-width:1.5px,color:#0369a1
    style bff fill:#f0f9ff,stroke:#0284c7,stroke-width:2px,color:#0369a1
    style redis fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e
    style db fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e
    style wpp fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#6b21a8
    style woo fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#6b21a8
    style mkt fill:#f0fdf4,stroke:#16a34a,stroke-width:1.5px,color:#166534

Limites de Responsabilidade

É responsabilidade do Subsistema NÃO é responsabilidade do Subsistema
Autenticação (Argon2), emissão e controle de sessões HTTP (sid) no Redis. Falar diretamente com a Meta Graph API (delega ao WhatsApp Entrypoint).
CRUD completo de lojistas (platform.merchants) e do número central (platform.platform_config). Executar a lógica de checkout ou calcular fretes (B2C / WooCommerce).
Resolução multi-tenant interna para os outros microsserviços via /internal/merchants/. Processar filas de IA ou embeddings vetoriais (GenAI Wrapper).
Controle de permissões (RBAC) com papéis super_admin, admin e merchant. Conectar-se diretamente ao WordPress do lojista (WooCommerce Wrapper).
Exibir dashboards operacionais, créditos e estimativas de custo, planos, campanhas, Flows e assistente de marketing. Servir como ponto de entrada de webhooks públicos da Meta.

Autenticação e Controle de Acesso (RBAC)

O serviço implementa autenticação baseada em sessão com cookie HttpOnly seguro (sid), cujo estado reside no Redis:

flowchart LR
    req[Requisição com cookie sid] --> verify{Sessão válida no Redis?}
    verify -->|Não| 401[401 Unauthorized]
    verify -->|Sim| rbac{Validação de Papel via authz.py}
    rbac -->|super_admin| all[Acesso irrestrito a todas as lojas e config global]
    rbac -->|admin| staff[Acesso operacional a qualquer lojista sem config global]
    rbac -->|merchant| store[Acesso estritamente restrito ao seu próprio merchant_id]

Matriz de Papéis Operacionais

Operação merchant admin super_admin
Ver métricas da própria loja Sim Sim Sim
Ver métricas de outras lojas Não Sim Sim
Criar novos lojistas Não Sim Sim
Excluir lojistas Não Não Sim
Gerenciar número central da plataforma (WABA B2B) Não Não Sim
Conectar WooCommerce e disparar sincronização Sim Sim Sim

Modelo de Dados: Schema platform

O BFF gerencia diretamente o schema platform no PostgreSQL:

  1. platform.merchants: Guarda os dados de cada lojista cadastrado:
  2. Credenciais do WooCommerce (woocommerce_url, consumer_key, consumer_secret cifrados).
  3. Configurações do WhatsApp (phone_number_id, waba_id, access tokens, status).
  4. IDs de Flows ativos (Flow de endereço B2C, Flow de onboarding).
  5. Identificadores de catálogo do Facebook e status de sincronização.
  6. platform.platform_config: Tabela singleton (sempre exatamente 1 linha) que armazena a configuração operacional do número central da plataforma (usado pelo Agente B2B para falar com os lojistas), os IDs de Flow e os modelos de IA habilitados (ai_models). Permite ajustar essas configurações pelo painel sem depender de arquivos de ambiente por loja.
  7. Planos, créditos e campanhas: o BFF entrega ao painel o catálogo de planos, o histórico de consumo de IA e os endpoints administrativos de campanhas. Ele mantém a autorização no limite público e encaminha ao serviço interno responsável.

Contratos de API do BFF

Autenticação & Sessões (/auth/)

Método Rota Papel Mínimo Descrição
POST /auth/login Público Autentica e-mail/senha com Argon2 e retorna cookie de sessão sid.
POST /auth/logout Autenticado Invalida e remove a sessão correspondente no Redis.
GET /auth/me Autenticado Retorna dados do usuário autenticado, papel e merchant_id associado.

Gestão de Lojistas (/merchants/)

Método Rota Papel Mínimo Descrição
GET /merchants/ admin Lista lojistas com paginação, filtros e status de conexão.
POST /merchants/ admin Cadastra novo lojista na plataforma.
GET /merchants/{id} merchant (próprio) Retorna detalhes operacionais, tokens e flags da loja.
PUT /merchants/{id} merchant (próprio) Atualiza dados cadastrais, chaves de webhook ou credenciais.
DELETE /merchants/{id} super_admin Remove lojista e revoga acessos da plataforma.

Endpoints Internos (/internal/)

Consumidos exclusivamente pelos outros microsserviços na rede Docker via biblioteca merchants_client com validação de X-Internal-Key:

Método Rota Consumidor Finalidade
GET /internal/merchants/ Todos Retorna lista de todos os lojistas ativos para tarefas em lote.
GET /internal/merchants/{id} Todos Retorna credenciais decifradas e dados de conexão da loja.
GET /internal/merchants/by-phone/{phone_number_id} WhatsApp Entrypoint Resolve o merchant_id do webhook a partir do número da Meta.
GET /internal/platform-config Agente B2B Retorna credenciais e Flow ID do número central da plataforma.

Configuração Essencial

Variável Descrição
DATABASE_URL Conexão PostgreSQL (pool assíncrono via asyncpg).
REDIS_URL Conexão Redis para armazenamento de sessões de usuários.
PLATFORM_API_INTERNAL_KEY Chave de autorização das rotas /internal/* de serviço a serviço.
SESSION_SECRET Chave secreta de criptografia e integridade de cookies de sessão.
SESSION_TTL_SECONDS Tempo de expiração da sessão de login no Redis (padrão: 86400 / 24h).
WHATSAPP_URL Endereço do container whatsapp-entrypoint para provisionamento.
WOOCOMMERCE_URL Endereço do container woocommerce-wrapper para healthchecks.

Diagnóstico Rápido

  1. Usuário deslogando frequentemente: Verifique a conectividade com o Redis e o TTL das chaves session:{sid}. Se o Redis reiniciar sem persistência, todas as sessões ativas são invalidadas.
  2. Microsserviços internos não encontram lojista: Verifique se o cabeçalho X-Internal-Key enviado pelo cliente corresponde exatamente à variável PLATFORM_API_INTERNAL_KEY do BFF. Requisições sem chave correta retornam 401 Unauthorized.
  3. Erros no painel após atualizar schema: Execute o container db-migrate. Ele faz o preflight de compatibilidade e roda alembic upgrade heads; o frontend-entrypoint não é o executor de migrations. Consulte Deploy e Migrações.