docs(web-push): guia de configuração do projeto Firebase do web push - #20
docs(web-push): guia de configuração do projeto Firebase do web push#20daniloleonecarneiro wants to merge 5 commits into
Conversation
Documenta como apontar o web push de uma instalação para um projeto Firebase próprio: o que pegar no console, onde guardar a service account, o save na Super Admin UI e como verificar o resultado nos artefatos servidos. Cobre os pontos que não são óbvios pelo código: - os quatro artefatos são renderizados a partir de templates versionados, e a rota servida — não o upload para o S3 — é a fonte da verdade; - a substituição no web-push.js acontece nos literais do bundle porque o initializeApp roda num field initializer, antes do override do snippet; - o firebaseConfig só é trocado com os seis campos obrigatórios presentes, enquanto o VAPID é trocado fora desse portão — salvar a config sem o VAPID deixa a instância num estado quebrado que não emite erro; - testar a conexão só faz JSON.parse, então uma credencial inválida passa. Inclui verificação por curl nas rotas públicas e uma tabela de troubleshooting.
As quebras no meio das frases e as tabelas de coluna larga deixavam o texto picotado e difícil de ler. O prettier do repo usa proseWrap preserve, então as quebras eram deliberadas e sem motivo. Reordena o guia pela tarefa — o que pegar, configurar, verificar — e desce a explicação de como os arquivos são gerados para depois disso. Troca a tabela de troubleshooting por parágrafos curtos e reduz a de artefatos para três colunas.
Configurar o FCM habilita a instalação, mas nada registra até que o shim e o snippet estejam no site. O guia parava na configuração e deixava essa metade implícita, que é justamente a que falha calada: com só um dos dois no ar, o site não capta assinatura nenhuma e nada indica isso. Registra por que o arquivo precisa estar na raiz — escopo de service worker não sobe de diretório — e a conferência do cookieDomain, que sai do domínio padrão da conta e costuma vir com o domínio da própria instalação em vez do domínio do site do cliente.
filipecrosk
left a comment
filipecrosk
left a comment
There was a problem hiding this comment.
Requesting changes before merge.
-
The
default_domainguidance needs to require an absolute URL, e.g.https://www.example.com. A bare domain makes the currentnew URL()path fall back to an empty cookie domain, creating a host-only cookie and breaking cross-subdomain identity. -
The verification command uses GNU-only
sha256sum, but our documented development environment is macOS. Useshasum -a 256, or document both portable variants.
Um domínio configurado sem http(s):// (ex. www.shop.example.com) fazia new URL() lançar, o catch vazio engolia o erro e o snippet saía com cookieDomain vazio — cookie host-only, identidade quebrada entre subdomínios, sem nenhum sinal do que houve. Prefixa http:// quando o valor não tem esquema (mesmo fallback usado em mail.utils.ts) e loga quando o domínio ainda assim não parseia.
Documenta explicitamente que default_domain precisa de esquema (https://www.example.com), e a consequência de um domínio sem esquema — cookie host-only e identidade quebrada entre subdomínios. sha256sum é GNU-only e o ambiente de dev documentado é macOS; passa a mostrar as duas variantes (sha256sum e shasum -a 256) no comando de verificação do service worker.
filipecrosk
left a comment
filipecrosk
left a comment
There was a problem hiding this comment.
The two original requests are implemented, and the focused account-service tests pass. The runbook is now inconsistent with the code and with the related PR set:\n\n1. The new runtime path explicitly normalizes a schemeless by prefixing , but the runbook says a bare domain is parsed as a relative path and produces an empty/host-only cookie domain. Keep the absolute-URL recommendation, but document the actual compatibility behavior instead of a failure that no longer occurs.\n\n2. The “save all three at once” warning says Firebase config and VAPID replacement happen independently and can produce a mixed project/key. PR #21 now intentionally makes those substitutions atomic. Because these PRs are being reviewed and merged as one related set, update this runbook section and troubleshooting text to describe the final behavior after #21 (an incomplete pair leaves the bundle defaults unchanged).\n\nValidation at :\n- : 17 tests passed\n- msgops-api type-check passed\n- No GitHub checks are configured
filipecrosk
left a comment
filipecrosk
left a comment
There was a problem hiding this comment.
The two original requests are implemented, and the focused account-service tests pass. The runbook is now inconsistent with the code and with the related PR set:
-
The new runtime path explicitly normalizes a schemeless
default_domainby prefixinghttp://, but the runbook says a bare domain is parsed as a relative path and produces an empty/host-only cookie domain. Keep the absolute-URL recommendation, but document the actual compatibility behavior instead of a failure that no longer occurs. -
The “save all three at once” warning says Firebase config and VAPID replacement happen independently and can produce a mixed project/key. PR #21 now intentionally makes those substitutions atomic. Because these PRs are being reviewed and merged as one related set, update this runbook section and troubleshooting text to describe the final behavior after #21 (an incomplete pair leaves the bundle defaults unchanged).
Validation at b13a7c07e353fac52b217f4810a7fd6f3c49599a:
accounts.service.spec.ts: 17 tests passed- msgops-api type-check passed
- No GitHub checks are configured
2 participants
Summary
Adiciona um guia operacional para apontar o web push de uma instalação para um projeto Firebase próprio, e o indexa na tabela de Operations do
docs/README.md. O gatilho foi configurar uma instalação do zero: o caminho funciona, mas três comportamentos só ficam evidentes lendo o código e dois deles falham em silêncio.Changes
docs/operations/web-push-fcm.md: o que pegar no Firebase Console, onde guardar a service account, o save na Super Admin UI, a instalação no site do cliente (shim na raiz + snippet), verificação porcurle problemas comuns.docs/README.md: entrada na tabela de Operations.Os pontos que o guia registra e que não são óbvios pelo código:
firebaseConfigexige os seis campos obrigatórios; a davapidKeynão passa por essa checagem. O resultado éfirebaseConfigde um projeto comvapidKeyde outro, e ogetTokencunha contra esse par sem reclamar.POST /admin/integrations/fcm/test-connectionnão valida a credencial: fazJSON.parsee devolve oproject_id. Chave revogada, expirada ou de outro projeto passa verde.BMS_ASSETS_URLnem de bucket público; a falha doregeneratePlatformServiceWorkeré não-fatal e oPUTdevolve 200 assim mesmo.web-push.jsacontece nos literais do bundle porque o construtor dobmsPushchamainitializeApp(this.firebaseConfig)num field initializer, antes da linha que aplica o override vindo do snippet. Config passada pela página chega tarde demais.Type of change
fix:)feat:)refactor:)docs:)chore:)Testing
Só documentação, sem mudança de comportamento — não rodei a suíte. Os comandos do guia foram executados contra uma instalação local configurada com um projeto Firebase novo:
GET /bms/web-push.jseGET /bms/push/:accountHash.jspassam a servir oprojectIdconfigurado, sem resíduo dos literais do bundle, nas duas contas da instalação.O
web-push.jssai com a chave VAPID configurada. O service worker não a contém, o que é esperado: ele recebe apenas a web config e a URL do tracker.A query de
system_confige o cálculo doaccountHashconferem com o que as rotas devolvem.pnpm type-checkpassespnpm lintpassespnpm testpassesManually verified the change end-to-end (descrito acima)
Screenshots
Não se aplica.
Notes for reviewers
O guia está em pt-BR, seguindo
operations/whatsapp-cloud.md. A seção de reset de senha do super-admin cobre dev local e usa placeholders, sem valores reais.Os comportamentos descritos aqui estão apenas documentados, não corrigidos. O PR #21 fixa os dois mais perigosos em teste, também sem alterá-los — se a decisão for exigir o VAPID junto da web config, os testes de lá são o primeiro lugar a mudar.