Projeto-Portaria/docs/07-REQUISITOS-DE-CAMPO.md

07 — Requisitos de campo

Este documento não é backlog de software. É pré-requisito contratual de instalação. Um condomínio que não atenda a estes itens não pode ser ativado — o produto vai falhar em campo por motivos que nenhuma linha de código resolve.

1. Por que este documento existe

O produto inteiro pressupõe que o visitante consegue abrir uma página web na calçada. Essa premissa quebra com frequência:

• Hall de entrada blindado não pega 4G. Concreto armado, vidro laminado e subsolo derrubam o sinal. O visitante escaneia o QR e nada acontece.
• Celular sem bateria no fim do dia de um entregador.
• Visitante sem smartphone — idoso entregando documento, prestador com aparelho antigo.
• Sol direto tornando o QR ilegível e a tela invisível.

Nenhum desses é resolvível em software. São requisitos físicos, e precisam estar no contrato de instalação junto com o preço.

2. Checklist de ativação

Um condomínio só entra em produção com todos os itens verificados em campo, não no papel.

2.1 Conectividade — obrigatório

• Wi-Fi aberto de visitante com cobertura medida em cada portaria
• SSID óbvio: Portaria-<NomeDoCondominio>
• Captive portal que abre direto a página do visitante
• Portal instrui a abrir no navegador padrão — o mini-navegador do captive portal (CNA do iOS, e vários Androids) bloqueia câmera e geolocalização, as duas permissões de que o fluxo depende. O portal exibe botão/instrução "abrir no Safari/Chrome", e o teste de ativação percorre o fluxo completo a partir do portal, não de um navegador já aberto
• Rede isolada da rede administrativa (VLAN separada, sem acesso à LAN interna)
• Banda mínima 5 Mbps simétricos reservados para o visitante
• Teste de sinal ≥ -70 dBm no ponto exato onde o visitante fica

A rede de visitante isolada não é detalhe: uma rede aberta com acesso à LAN do condomínio é porta de entrada para ataque. Ela serve apenas para chegar à internet.

2.2 QR — obrigatório

• Impresso em material fosco (brilhante reflete sol e não é lido)
• Mínimo 15×15 cm, correção de erro nível H
• Altura de 1,20 a 1,50 m do chão
• Protegido de sol direto (marquise, ângulo, ou toldo)
• URL curta legível abaixo do código, para digitação manual
• Instrução em português e inglês
• Suporte com placa reserva, para reimpressão em caso de vandalismo

2.3 Fallback físico — obrigatório

• Botão físico de chamada na portaria, ligado ao mesmo fluxo
• Botão à altura acessível (≤ 1,20 m) e identificado com pictograma
• Aciona chamada para a portaria/operador sem depender de celular
• Alimentação com no-break de no mínimo 4 horas

O botão físico é o que atende quem não tem celular, está sem bateria ou não consegue usar o QR. Sem ele, o produto exclui uma parcela real de visitantes — e cria a situação em que alguém legítimo simplesmente não consegue entrar.

Na v1, o botão é deliberadamente um interfone direto (GSM/4G ou SIP) para o responsável/central — fora da plataforma. É proposital: ele precisa continuar funcionando exatamente quando a plataforma cai, então não pode depender dela. Integrá-lo como dispositivo da plataforma (disparando o fluxo de visita com operador) é v2, atrás de AccessControlDevice.

2.4 Aviso legal — obrigatório

• Placa física com o aviso de tratamento de dados, visível antes da coleta
• Nome e contato do encarregado (DPO) do condomínio
• Texto idêntico ao exibido na tela, com a mesma versão
• LIA preenchida e arquivada (06-LGPD-E-SEGURANCA.md)

2.5 Energia e contingência — obrigatório

• No-break para roteador, botão de chamada e equipamento de rede (≥ 4h)
• Telefone de contingência do responsável pela abertura, afixado na portaria
• Procedimento escrito para queda total, conhecido pelo zelador
• Contato do síndico e da empresa de segurança visíveis

2.6 Cadastro — obrigatório

• Base de unidades importada e conferida contra a lista da administradora
• Ao menos um morador com app instalado por unidade (meta: 80% das unidades)
• ring_order definido nas unidades com múltiplos moradores
• delivery_rule definida por unidade (default DEIXAR_PORTARIA)
• Responsáveis pela abertura cadastrados com prioridade
• quiet_hours acordada com o síndico
• geofence_meters calibrado no local (default 80 m; ajustar em condomínio grande)

Unidade sem nenhum morador com app é unidade que nunca atende. Abaixo de 60% de cobertura, o condomínio não deve ser ativado no plano Autônomo — só no Assistido.

3. Calibragem do geofence

O raio padrão de 80 m funciona na maioria dos casos, mas precisa ser medido:

1. Ficar no ponto do visitante e registrar a coordenada em gates.location
2. Medir a precisão real do GPS no local (prédio alto e marquise degradam muito)
3. Ajustar geofence_meters para cobrir a imprecisão sem abrir demais
4. Testar com dois aparelhos diferentes, Android e iPhone

Raio apertado demais rejeita visitante legítimo — falha muito pior que aceitar alguém a 100 m. Na dúvida, use raio maior e confie no selo de distância que aparece para o morador durante a chamada.

4. Onboarding do condomínio

1. Visita técnica       sinal, energia, posição do QR, ponto do botão   1 dia
2. Contrato             plano, operador, LIA, contrato de operador      —
3. Infraestrutura       Wi-Fi, captive portal, botão, no-break, placas  2–5 dias
4. Cadastro             import CSV, conferência, responsáveis           1 dia
5. Adesão dos moradores convites, assembleia, suporte na instalação     2–4 semanas
6. Piloto assistido     operador ligado, monitoramento diário           2 semanas
7. Ativação             plano definitivo conforme taxa de atendimento   —

A etapa 5 é a mais longa e a mais subestimada. Adesão dos moradores é trabalho de campo, não de software: assembleia, cartaz no elevador, plantão de instalação no hall. Um condomínio com 30% de adesão não tem produto funcionando, por melhor que o código esteja.

A etapa 6 não é opcional. Duas semanas com operador ligado revelam a taxa real de atendimento daquele condomínio. É esse número — não a expectativa comercial — que define se ele fica no plano Autônomo ou no Assistido.

5. Reconciliação contínua

A base de moradores desatualiza sozinha: gente muda de apartamento, vende, aluga, troca de celular. Base desatualizada quebra o produto silenciosamente — a chamada simplesmente não é atendida e ninguém sabe por quê.

Mensal, o relatório GET /admin/reconciliation lista:

• Moradores com valid_until vencido
• Unidades sem nenhum dispositivo ativo
• Dispositivos com push falhando há mais de 7 dias (token morto = desinstalou)
• Unidades com taxa de atendimento abaixo de 30% no mês
• Moradores convidados que nunca aceitaram

O síndico ou a administradora confirma as mudanças. Isso é rotina de operação, não incidente — e é o que mantém o produto vivo depois do primeiro mês.

6. Procedimento de contingência

Afixado fisicamente na portaria:

SE O SISTEMA NÃO RESPONDER

1. Use o botão de chamada da portaria
2. Se não funcionar, ligue para o responsável:
      <NOME>  <TELEFONE>
3. Fora do horário, segurança 24h:
      <TELEFONE>
4. Registre a entrada no livro físico

O livro físico permanece na portaria e é preenchido
sempre que o sistema estiver indisponível.

O livro físico não é retrocesso — é a contingência que torna o produto vendável. Enquanto a abertura depender de humano e existir queda de energia, o condomínio precisa de um caminho que funcione sem eletricidade e sem internet. Vender autonomia total seria desonesto, e a primeira queda destruiria a confiança no produto.

7. Materiais de campo

Entregues na ativação:

Material	Onde
Placa do QR (fosca, 15×15)	Cada portaria
Placa do aviso LGPD + DPO	Ao lado do QR
Adesivo do botão de chamada	Junto ao botão
Cartaz de contingência	Interior da portaria
Cartaz de adesão para moradores	Elevadores e hall
Guia rápido do morador (1 página)	Digital + impresso
Guia do responsável pela abertura	Impresso na portaria
Guia do síndico (admin)	Digital