Visão Geral do Web Host

O Wippy Web Host é uma single-page application em Vue 3 construída com a metodologia Feature-Sliced Design e entregue por um CDN em https://web-host.wippy.ai. Ele hospeda todas as páginas e componentes de UI voltados ao usuário de uma aplicação Wippy. Você não o compila nem o publica — você o configura através do módulo de backend wippy/facade e ele carrega automaticamente.

Arquitetura FE do Wippy

Modelo de Três Camadas

Uma aplicação Wippy em execução é composta por três camadas aninhadas:

Camada 1 — Página servida pelo wippy/facade. Esta é a sua página HTML renderizada pelo backend. O módulo wippy/facade registra um servidor de arquivos estáticos e um endpoint /facade/config no seu gateway Wippy. Quando um usuário navega até sua aplicação, o wippy/facade serve uma página HTML enxuta que carrega a entrada de módulo JS do Web Host a partir do CDN (module.js para compat, managed-layout.js para managed) e a inicializa com a configuração de /facade/config. A página em si não carrega Vue nem React — ela é intencionalmente enxuta.

Camada 2 — Web Host. O bundle do Web Host carrega como um módulo JS que assume a página inteira e seu histórico de navegador. Ele é dono do chrome do Wippy: a sidebar de navegação, o painel de chat, o gerenciamento de sessões e a surface de renderização de páginas. Ele recebe sua configuração completa da chamada de init da página e nunca contém URLs ou tokens específicos de deploy dentro do próprio bundle. É isso que torna o bundle hospedado em CDN portável entre deploys. (Para embutições manuais sem facade, o mesmo host pode em vez disso rodar dentro de um iframe via a entrada iframe.html — veja a tabela de pontos de entrada abaixo.)

Camada 3 — Micro-frontends filhos. O Web Host, por sua vez, embute views definidas pelo usuário como iframes aninhados (módulos view.page) ou como web components (módulos view.component). Cada filho roda isolado. O Web Host injeta um script de proxy que dá aos filhos acesso à API do Wippy, ao contexto de autenticação, ao CSS do tema e aos canais de comunicação — tudo sem que o filho precise saber onde está publicado.

Página (HTML do wippy/facade — carrega module.js / managed-layout.js)
  └─ Web Host (assume a página + o histórico do navegador)
       ├─ UI de chat, navegação, sidebar
       └─ Micro-frontends filhos
            ├─ view.page  → iframe srcdoc + proxy.js
            └─ view.component → custom element + ESM @wippy-fe/proxy

Pontos de Entrada

O CDN do Web Host serve vários pontos de entrada a partir do mesmo diretório versionado. O correto depende de como você está integrando:

Cada entrada é servida pelo CDN em <release-tag>/<entry> (por exemplo, /<release-tag>/module.js).

Entrada Caso de uso
module.js App completo no modo compat — o shell padrão com sidebar de navegação + área de página + painel direito de chat. Montado diretamente na página via window.initWippyApp(); assume a página inteira e seu histórico de navegador. É a entrada que o wippy/facade atual serve por padrão.
managed-layout.js App completo no modo managed — o layout multi-painel declarativo. Servido pela facade quando fe_mode = managed. Acesso antecipado (veja Layout Multi-Painel).
iframe.html App completo rodando dentro de um iframe, para isolamento ou embutição parcial em página. Use-o para embutições manuais sem facade, em que você fornece a configuração via um handshake de PostMessage SetConfig. A própria facade carrega as entradas de módulo JS acima, não esta.
chat-iframe.html Interface de chat mínima, sem sidebar nem páginas. Útil para embutir um widget de chat focado.
chat.js Módulo ESM headless expondo as stores de chat e o cliente WebSocket. Use para construir UIs completamente customizadas.
ws.js Serviço WebSocket autônomo, sem dependência de Vue ou Pinia. Use para integrações de tempo real de baixo nível.

A versão publicada 1.0.64 inclui o import map completo do Host em iframe.html e chat-iframe.html antes da execução dos módulos. A entrada autônoma chat-iframe.html inicia o app ao carregar; não chame initChatApp depois.

Para deploys padrão baseados em wippy/facade, você nunca referencia esses caminhos diretamente. A facade lê fe_facade_url de sua configuração, seleciona a entrada de módulo JS que corresponde a fe_mode (module.js para compat, managed-layout.js para managed) e constrói a URL correta automaticamente.

Versionamento no CDN

O Web Host é versionado por tag do git. O padrão canônico de URL de produção é:

https://web-host.wippy.ai/<release-tag>/

Onde <release-tag> é a tag de release do git do Web Host — seja uma release estável ou um deploy de preview de branch de feature. O CDN de staging fica em https://web-host.staging.wippy.ai/<release-tag>/.

Normalmente você não define a versão. O módulo wippy/facade vem com um fe_facade_url padrão apontando para um build do Web Host correspondente, então a versão do Web Host acompanha o módulo da facade — atualizar o wippy/facade é como você migra para um Web Host mais novo. Apps filhos que compartilham bibliotecas de vendor via o import map recebem exatamente as versões que aquele build fornece.

Para fixar uma versão específica do Web Host — para permanecer em um build comprovadamente bom, ou para optar por uma tag de branch de feature / acesso antecipado — sobrescreva o parâmetro fe_facade_url:

- name: fe_facade_url
  value: https://web-host.wippy.ai/<release-tag>

Isso fixa o deploy inteiro nesse build. Veja Overrides de CLI para a sintaxe -o / --override que permite defini-lo em tempo de execução.

Stack Técnica

O Web Host é construído com Vue 3 (Composition API), PrimeVue + Tailwind CSS 3 para componentes de UI, Pinia para gerenciamento de estado, Vue Router para navegação e Axios para HTTP. Durante o desenvolvimento, busque <fe_facade_url>/import-map.json e coloque todas as chaves do objeto imports dele nos externals do Rollup, mesmo que o artefato atual não importe aquela chave. Empacote uma dependência importada apenas quando o especificador exato dela estiver ausente. Busque novamente quando a tag do Web Host mudar ou uma nova dependência for adicionada.

Veja Também