# 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 |