prompt inicial do projeto

docs/07-REQUISITOS-DE-CAMPO.md

@@ -0,0 +1,150 @@
+# 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
+- [ ] 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.
+
+### 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 |