Documentação Operacional do Site BH Carimbos

2. Aviso de Confidencialidade

Este manual é destinado ao cliente, à equipe autorizada e a profissionais contratados para manutenção do site. Ele orienta operação e manutenção, mas não substitui contrato, parecer jurídico ou guarda formal de credenciais.

O controle de acesso à documentação, ao repositório, à hospedagem, ao domínio, à planilha e ao e-mail deve permanecer sob responsabilidade do cliente/proprietário. Se o site for alterado, esta documentação deve ser atualizada na mesma versão operacional.

3. Resumo Executivo do Projeto

O site BH Carimbos tem objetivo comercial: gerar contatos qualificados para pedidos de carimbos personalizados em Belo Horizonte e região. As conversões principais são WhatsApp, formulário, telefone, e-mail e rota pelo mapa.

O resultado entregue organiza páginas comerciais, páginas locais, páginas institucionais, políticas legais, sitemap, robots, dados estruturados e arquivos de apoio para rastreamento.

4. Escopo Contratado / Entregue

Critérios de aceite: site acessível no domínio final, HTTPS ativo, redirecionamento www/sem www validado conforme padrão oficial, páginas principais carregando, formulário funcionando, lead salvo na planilha, e-mail de aviso recebido, WhatsApp, telefone, e-mail clicável e rota funcionando, sitemap enviado, Search Console configurado, llms.txt validado, mobile e desktop revisados e documentação entregue.

5. Visão Geral Técnica

A arquitetura usa geração estática: código do projeto gera HTML/CSS/JS otimizado, publicado em hospedagem compatível com Vercel. O formulário usa um endpoint serverless em api/contact.ts, que valida, sanitiza e envia o lead para Google Sheets.

código -> build Astro -> hospedagem -> domínio
formulário -> /api/contact -> Google Sheets -> aviso por e-mail
CTAs -> WhatsApp / telefone / mapa / e-mail

Ambientes previstos: local para desenvolvimento, preview para validação técnica e produção em https://bhcarimbos.com.br. Site, domínio, DNS, hospedagem e repositório são ativos diferentes: alterar um deles pode não alterar os demais.

6. Stack Utilizada

7. Contas e Propriedades

8. Domínio e DNS

Domínio oficial do site: https://bhcarimbos.com.br. A gestão do domínio deve ser mantida pelo responsável autorizado pelo cliente. O registrador é Registro.br, com DNS gerenciado no Registro.br e apontamentos para a Vercel. O subdomínio da documentação é https://docs.bhcarimbos.com.br/.

SSL/TLS deve permanecer ativo e HTTPS deve ser forçado. Remover TXT de verificação pode afetar Search Console, hospedagem ou serviços de e-mail.

9. Hospedagem

A plataforma final de hospedagem é Vercel. O projeto de produção é bh-carimbos/agoracarimbo, disponível no painel em https://vercel.com/bh-carimbos/agoracarimbo. A URL técnica temporária da plataforma é usada apenas para validações internas e não é publicada nesta documentação.

Alteração de código exige novo deploy. Alteração de domínio/DNS pode não exigir redeploy. Alteração de variável de ambiente normalmente exige redeploy para garantir leitura correta.

10. Repositório e Versionamento

O projeto está em repositório privado, sob responsabilidade da conta técnica criada para o projeto. A URL do repositório não é publicada nesta documentação. Branch principal e de produção: main. Não há tag/release pública obrigatória; a versão documental inicial é v1.0.

git status
npm install
npm run check
npm run build
git add .
git commit -m "Descrever alteração realizada"
git push

Alterações futuras devem ser registradas por commit técnico no repositório e também no histórico de versões da documentação, com data, responsável, resumo da alteração, impacto e testes realizados.

11. Estrutura de Pastas

12. Explicação dos Arquivos Principais

13. Páginas do Site

As rotas confirmadas estão em src/data/routes.ts e são geradas por src/pages/index.astro, src/pages/[...slug].astro, src/pages/404.astro e src/pages/sitemap.xml.ts.

14. Explicação Página por Página

As páginas de serviço usam intenção comercial local. Alterações devem preservar title, description, H1, CTA, links internos, dados comerciais e ressalvas de prazo.

15. Componentes Visuais

16. Sistema Visual

O sistema visual usa identidade direta, comercial e local, com detalhes em laranja, preto e cinza. A tipografia deve permanecer legível, com boa hierarquia, contraste adequado e botões claros para ações comerciais.

• Logos: usar assets/logo/logo-horizontal.png, logo-principal.png e logo-icon.png sem distorção.
• Ícones: usar arquivos fornecidos em assets/icones.
• Imagens: usar fotos reais de produtos e imagens fornecidas; não substituir por banco externo sem autorização.
• Responsividade: testar menu, formulários, botões, cards e rodapé em celular.

17. Conteúdo Textual

Tom recomendado: claro, objetivo, comercial e responsável. Dados comerciais finais: nome comercial BH Carimbos, empresa Agora Carimbos, WhatsApp +55 31 3274-5665, e-mail agoracarimbos@hotmail.com, endereço Rua Tenente Marino Freire, 679, Bairro Maria Helena, Venda Nova, Belo Horizonte/MG, horário de segunda a sexta, das 07:00 às 18:00, pagamento por Pix ou link de pagamento no cartão, produção média de 24 horas com ressalva de disponibilidade, entrega média de 48 horas conforme endereço e disponibilidade, marcas Trodat, Colop, Nykon ou similares e emissão de nota fiscal.

Antes de editar CTAs, formulários, FAQs ou textos SEO, validar consistência com WhatsApp, rodapé, contato, mapa, schema e páginas legais.

18. Como Alterar Informações Comuns

19. WhatsApp

Número oficial: +55 31 3274-5665. Formato técnico: 553132745665. O WhatsApp é a principal conversão do site.

Mensagem padrão: “Olá! Vim pelo site da BH Carimbos e gostaria de fazer um orçamento.” Existem mensagens contextualizadas por página quando aplicável; quando não houver mensagem específica, o sistema usa a mensagem padrão de orçamento. CTAs prioritários: WhatsApp como ação principal; formulário, telefone, e-mail e mapa/rota como ações secundárias. Mensagens e links devem ser revisados em src/data/whatsapp.ts e src/lib/whatsapp.ts. Testes obrigatórios: clique no desktop, clique no celular, mensagem preenchida, páginas comerciais, Header, Footer e CTA final.

20. Google Maps

Endereço oficial: Rua Tenente Marino Freire, 679, Bairro Maria Helena, Venda Nova, Belo Horizonte/MG. O site usa botão/link de rota para o endereço comercial; o link público implementado fica em src/data/site.ts.

Ao alterar endereço, revisar texto visível, botão de rota, schema LocalBusiness, rodapé, página de contato e páginas locais. Testar abertura do mapa em desktop e celular.

21. Formulário de Contato

O formulário organiza o pedido antes do atendimento. Campos obrigatórios no site: nome, WhatsApp, tipo de carimbo, detalhe do pedido, região e consentimento LGPD. O e-mail é opcional, mas validado se preenchido. Também são registrados página de origem, honeypot e dados de data/hora no fluxo técnico.

Quando não chegar lead: testar formulário, conferir deploy, revisar variáveis de ambiente, permissões da planilha, cabeçalhos A:K, logs da hospedagem e aviso por e-mail.

22. Google Sheets

Planilha operacional: Leads - BH Carimbos. Aba: leads. Acesso restrito ao cliente e equipe autorizada. O link da planilha e o ID não são publicados nesta documentação.

Backup recomendado: mensal e também antes de alterações estruturais, como mudanças de colunas, cabeçalhos, permissões ou automações.

23. Google Apps Script

Existe Apps Script ativo para notificação de leads, vinculado à conta técnica do projeto: bhcarimbos.contato@gmail.com. A finalidade é notificar novos leads por e-mail, destacar dados principais, classificar contexto/prioridade do lead e orientar o atendimento sem alterar o site.

Tipo de gatilho: por tempo, a cada 5 minutos. Logs devem ser consultados no painel do Apps Script, em Execuções/Executions, acessível apenas por conta autorizada. O Apps Script possui lógica para cadastrar/adicionar destinatários autorizados diretamente pela planilha/menu, sem expor código sensível e sem alterar o site.

Testes: criar lead de teste, confirmar linha na planilha, confirmar e-mail recebido, revisar spam, verificar logs e cotas. Riscos: permissão revogada, gatilho removido, cota excedida, cabeçalho alterado, e-mail bloqueado ou script desativado.

24. Notificação por E-mail

E-mail público comercial: agoracarimbos@hotmail.com. Destinatário atual dos avisos de leads: bhcarimbos.contato@gmail.com. O remetente é descrito como conta Google autorizada vinculada ao Apps Script.

Assunto: assunto estratégico de novo lead da BH Carimbos, com identificação do tipo de pedido quando disponível. Dados incluídos: nome, WhatsApp, e-mail se informado, tipo de carimbo, detalhe do pedido, região, página de origem, consentimento/status e link de contato pelo WhatsApp quando possível. Dados omitidos: senhas, tokens, credenciais, URLs privadas de edição, private keys, dados internos de conta Google e informações que não sejam necessárias para atendimento.

O Apps Script permite cadastrar/adicionar destinatários autorizados para receber avisos diretamente pela planilha/menu do sistema, sem alterar o site. Para testar, enviar um lead controlado, confirmar planilha, caixa de entrada, spam e horário do envio.

25. Privacidade e LGPD

Dados coletados: nome, WhatsApp, e-mail opcional, tipo de carimbo, detalhes do pedido, região, consentimento e página de origem. Finalidade: atendimento comercial e orçamento. Não coletar documentos pessoais pelo formulário sem necessidade e sem orientação específica.

Retenção recomendada: 24 meses, salvo política interna diferente do cliente ou solicitação de exclusão. Acesso aos leads: cliente e equipe autorizada de atendimento/gestão.

Solicitação de exclusão: localizar o lead na planilha, excluir ou anonimizar os dados solicitados e registrar internamente que a solicitação foi atendida, se aplicável. Dúvidas jurídicas devem ser validadas com profissional jurídico.

26. SEO Técnico

O site usa URLs amigáveis, canonical por página, title, meta description, headings, sitemap criado em src/pages/sitemap.xml.ts, robots em produção e página 404. Google Search Console configurado como propriedade de domínio, com sitemap enviado.

• Sitemap disponível em /sitemap.xml.
• Arquivo llms.txt mantido como entregue e validado.
• H1, title e canonical devem permanecer coerentes com cada página.
• Links quebrados e redirecionamentos devem ser corrigidos em manutenção.
• Não bloquear páginas comerciais relevantes no robots.

27. SEO Local

NAP oficial: BH Carimbos / Agora Carimbos, Rua Tenente Marino Freire, 679, Maria Helena, Venda Nova, Belo Horizonte/MG, telefone +55 31 3274-5665. Manter consistência no site, em redes, diretórios e materiais públicos que o cliente vier a manter.

Páginas locais confirmadas: Pampulha e Venda Nova. Não criar páginas locais sem conteúdo real e sem capacidade de atendimento descrita corretamente.

28. AEO

A documentação de conteúdo deve favorecer respostas diretas: perguntas frequentes, “como pedir”, “o que enviar”, prazos, retirada, entrega e diferenças entre modelos. Respostas devem ser específicas, curtas quando possível e sem promessa não confirmada.

Risco: respostas vagas aumentam retrabalho no atendimento e reduzem a chance de aparecer em mecanismos de resposta.

29. GEO

O site deve manter conteúdo factual rastreável em HTML, com NAP consistente, páginas específicas, FAQ estruturado, llms.txt entregue e validado, e informações comerciais verificáveis. Permitir rastreamento não significa expor dados internos: credenciais, leads e links privados nunca devem ser públicos.

URLs prioritárias para monitoramento: página inicial, carimbos-bh, carimbo-em-bh, carimbo-personalizado-bh, carimbo-cnpj-bh, carimbo-na-hora-bh, carimbo-automatico-bh, carimbo-medico-bh, carimbo-empresa-bh, nossos-produtos, contato e perguntas-frequentes.

30. Dados Estruturados

O arquivo src/lib/seo.ts confirma schemas: Organization, WebSite, WebPage, LocalBusiness e FAQPage. Os dados estruturados estão aprovados sem reviews, ratings, preços, estoque ou ofertas falsas. BreadcrumbList, Service, ContactPoint detalhado e sameAs devem ser usados apenas quando implementados com dados reais.

Validar no Rich Results Test e em validador de Schema.org após alterações.

31. Open Graph e Compartilhamento

Imagem padrão aprovada: /assets/seo/og-image.png. Manter og:title, og:description, og:url, og:type, og:image e Twitter Card coerentes no componente de SEO.

Previews de WhatsApp, Facebook e LinkedIn podem usar cache. Após alterar imagem ou metadados, aguardar atualização ou usar ferramentas de depuração das plataformas.

32. Analytics e Conversões

GA4, GTM, Google Ads, Meta Pixel e eventos de conversão ativos não fazem parte da entrega atual. Estado atual: não instalado.

Eventos futuros possíveis: clique no WhatsApp, envio de formulário, clique no telefone, clique no mapa e clique em e-mail. Ativar somente mediante aprovação do cliente, revisão de privacidade/cookies e configuração técnica adequada.

33. Segurança do Site

HTTPS está ativo em produção e o site não deve expor segredos no front-end. Headers em vercel.json aprovados como configuração básica final: nosniff, strict-origin-when-cross-origin, restrição de permissões e bloqueio de iframe via X-Frame-Options: DENY.

CSP rígida não foi implementada nesta versão. Pode ser tratada como melhoria futura opcional após testes para evitar quebra de scripts, formulário, assets ou funcionalidades. DevTools deve ser tratado como ambiente público: qualquer dado enviado ao navegador pode ser visto.

34. Segurança do Formulário

Proteções confirmadas: método POST, JSON, validação server-side, sanitização, limite de tamanho, honeypot, origem permitida, erro genérico, rate limit em memória, bloqueio temporário de duplicidade e logs sem conteúdo sensível.

35. Acessibilidade

Manter HTML semântico, labels no formulário, foco visível, contraste adequado, links descritivos, hierarquia de títulos e mensagens de erro com aria-live quando aplicável. Testar navegação por teclado e leitura em mobile.

36. Performance

A geração estática do Astro reduz carga do servidor e favorece Core Web Vitals. Manter JavaScript mínimo, CSS otimizado, imagens dimensionadas, cache da hospedagem e cuidado com mapas incorporados.

Validar em PageSpeed/Lighthouse, principalmente mobile. Riscos comuns: imagens pesadas, scripts externos, excesso de tracking e layout instável.

37. Compatibilidade

• Chrome desktop e Android.
• Edge desktop.
• Safari/iOS.
• Tablet em orientação vertical e horizontal.
• WhatsApp mobile com mensagem preenchida.
• Telefone mobile via tel:.
• E-mail mobile via mailto:.

38. Testes Realizados

39. Publicação

Checklist pós-publicação: domínio, HTTPS, páginas, CTAs, formulário, planilha, e-mail, sitemap, Search Console, mobile e desktop.

40. Pós-Publicação

Rotina sugerida: validar em 3, 7, 14 e 30 dias. Conferir Search Console, sitemap, indexação, formulário, e-mail, WhatsApp, páginas com maior acesso, dúvidas recorrentes e ajustes iniciais de conteúdo.

41. Manutenção

Alterações simples: textos, telefone, e-mail, links, pequenos ajustes de conteúdo e imagens já previstas. Alterações médias: nova seção, ajuste de layout, nova página simples e revisão de SEO em página existente. Alterações complexas: nova integração, automação, mudança estrutural, redesign, painel, login, CRM, Ads/Analytics, migração de hospedagem, DNS ou infraestrutura.

Atualizações de dependências devem ser testadas em preview com npm run check e npm run build. Alterações futuras devem ser registradas por commit técnico e no histórico de versões da documentação.

42. Como Solicitar Alterações Futuras

Alterações futuras devem ser solicitadas ao responsável técnico por canal combinado diretamente com o cliente, preferencialmente por escrito, com descrição clara da alteração desejada. A solicitação deve informar página, texto atual, texto desejado, objetivo, prazo, impacto esperado e anexos aprovados. Mudanças devem ser aprovadas antes da execução, testadas após publicação, registradas no histórico e refletidas nesta documentação quando afetarem operação.

43. Riscos Operacionais

44. Boas Práticas do Cliente

• Não alterar DNS sem orientação técnica.
• Não remover permissões antes de revisar dependências.
• Não apagar colunas da planilha.
• Não compartilhar planilha publicamente.
• Usar 2FA em contas críticas.
• Renovar domínio e revisar cobranças.
• Solicitar alterações com clareza e validar publicação.

45. Itens que Não Devem Ser Alterados Sem Suporte Técnico

46. Checklist para Alterar Textos

• Identificar página e arquivo em src/data.
• Editar conteúdo sem promessa comercial indevida.
• Revisar ortografia, SEO, H1 e CTAs.
• Rodar localmente, gerar build e testar página.
• Publicar, validar mobile/desktop e registrar alteração.

47. Checklist para Alterar Contatos

• Telefone visível e tel:.
• WhatsApp, número técnico e mensagens padrão.
• E-mail visível e mailto:.
• Destinatário de aviso, se aplicável.
• Formulário, planilha e e-mail de aviso.

48. Checklist para Alterar Endereço

• Texto do endereço em todas as páginas.
• Google Maps e botão de rota.
• Schema LocalBusiness.
• Rodapé, contato e SEO local.
• Canais públicos mantidos pelo cliente e teste mobile.

49. Checklist para Criar Nova Página

• Definir objetivo, público e intenção de busca.
• Criar rota, conteúdo único, title, description, H1 e canonical.
• Adicionar links internos e CTA.
• Avaliar schema, sitemap, mobile e build.
• Publicar e validar indexação.

50. Checklist para Remover Página

• Confirmar necessidade e acessos.
• Definir redirecionamento 301/308.
• Remover menu, sitemap e links internos.
• Testar URL antiga e Search Console.
• Registrar alteração.

51. Checklist de Segurança Antes de Publicar Alteração

• Sem .env, token ou private key em arquivo público.
• Sem dados reais de lead no código.
• Sem logs sensíveis.
• Formulário validado e planilha privada.
• Headers revisados e build limpo.

52. Histórico de Versões

53. Melhorias Futuras

Ads, Analytics avançado, CRM, WhatsApp API, e-mail profissional, novas páginas, manutenção recorrente, redesign, automações adicionais, migração de infraestrutura e ferramentas pagas dependem de aprovação e podem exigir novo orçamento ou serviço.

54. Termos Técnicos

55. Dados de Acesso Entregues

Domínio/Registro.br e Google Business Profile não são listados como acessos entregues nesta seção.

56. Como Guardar Senhas e Acessos

• Senhas devem ser guardadas em gerenciador de senhas do cliente.
• Nunca salvar senhas no HTML, na documentação, no repositório, na planilha ou em mensagens públicas.
• Usar 2FA em contas críticas.
• Registrar proprietários de cada conta.
• Evitar dependência de conta pessoal quando houver conta corporativa.
• Trocar senhas após entrega, quando aplicável.
• Revogar acessos antigos e revisar permissões periodicamente.
• Separar documentação de credenciais.

57. Checklist Final de Aceite

• Domínio funcionando com HTTPS.
• Páginas principais, comerciais, locais e legais acessíveis.
• Formulário envia lead para planilha.
• E-mail de aviso recebido.
• WhatsApp, telefone, e-mail e Maps testados.
• Mobile e desktop revisados.
• Sitemap, robots, schema e metadados validados.
• Planilha privada e acessos entregues por canal seguro.
• Documentação entregue e cliente aprovou.

58. Anexos Técnicos

Fim da documentação v1.0.