Topologia Canônica de Roteamento por Unidade (/location/:locationSlug/…​)

1. Princípio Arquitetural

No ecossistema multi-tenant da plataforma Yzex, todas as rotas operacionais que dependem do contexto de uma filial/unidade específica adotam a topologia canônica em inglês baseada em caminho (Path-based Routing):

https://[host]/location/:locationSlug/[módulo]/[subitem]

Exemplo canônico para configurações de integrações:

https://[host]/location/sobateriassp/settings/integrations/whatsapp

2. Segregação de Escopos: Operacional vs. Gestão Estrutural

  • Rotas Operacionais (unit): Exigem e refletem o slug da unidade ativa diretamente no caminho (/location/:locationSlug/…​). Exemplos: Home operacional (/location/:locationSlug/home), Integrações WhatsApp (/location/:locationSlug/settings/integrations/whatsapp).

  • Rotas de Gestão Estrutural (management): Constituem exceções legítimas de transbordo de contexto que operam no nível global da organização. Permanecem sem o prefixo de unidade. Exemplos: /settings/organizations, /settings/locations, /settings/groups, /settings/tags, /settings/users, /settings/invites, /settings/roles.

3. Camadas de Imposição e Defesa em Profundidade

  1. Middleware Global (context.global.ts):

    • Extrai deterministicamente o locationSlug do caminho da URL (/location/:slug).

    • Invoca selectUnitBySlug(slug) no useAppContext para carregar o contexto da unidade ativa.

    • Redireciona requisições legadas diretas (ex.: /settings/integrations/whatsapp) para a rota canônica /location/:targetSlug/settings/integrations/whatsapp com preservação de query parameters (?domain=…​).

  2. Isolamento de Estado e API BFF:

    • O composable useWhatsappInstances injeta o currentUnit.value.id nas chamadas de listagem e criação.

    • O endpoint BFF GET /api/integrations/whatsapp/instances valida o vínculo multi-tenant e filtra rigorosamente via .eq('location_id', locationId).

    • A view WhatsappIntegrationContent.vue aplica filtro reativo computado scopedInstances garantindo tolerância zero a vazamentos de contexto (Context Bleed).