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.
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 |
O BFF gerencia diretamente o schema platform no PostgreSQL:
platform.merchants: Guarda os dados de cada lojista cadastrado:
- Credenciais do WooCommerce (
woocommerce_url, consumer_key, consumer_secret cifrados).
- Configurações do WhatsApp (
phone_number_id, waba_id, access tokens, status).
- IDs de Flows ativos (Flow de endereço B2C, Flow de onboarding).
- Identificadores de catálogo do Facebook e status de sincronização.
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.
- 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
- 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.
- 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.
- 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.