# FASE 7 — Escalonamento, fila de operador e recado

## Objetivo

Completar a retaguarda: escalonamento entre moradores, fila de operador humano com contexto, app do operador, e recado em vídeo. É o que transforma "chamada não atendida" em "visita resolvida".

## Pré-requisitos

FASES 0–6 concluídas. Ler `docs/03-FLUXOS-E-CONTRATOS.md` §4 e `docs/00-VISAO-E-PRODUTO.md` §1.

## Por que esta fase existe

A tese do produto é que o morador atende. A realidade é que ele nem sempre atende — gente em reunião, dirigindo, dormindo. É por isso que o mercado consolidado usa operador humano 24h.

Esta fase é o que torna a aposta vendável: quando o morador não atende, o visitante **não fica sem saída**. E é o que sustenta comercialmente o plano Assistido.

## Tarefas

### 1. Escalonamento entre moradores

`VISIT_RING_TIMEOUT` (20s) → `ESCALONADA`. Toca para os demais `unit_members` da unidade, **em paralelo**, respeitando `ring_order` para ordenar a exibição e `receives_calls`.

O primeiro que atender vence; os demais recebem cancelamento da notificação — deixar notificação órfã tocando depois de resolvido é ruído que faz o morador desativar o app.

### 2. Fila de operador

Ativa apenas com `tenant_features.operator_queue` habilitado. Sem o módulo, `ESCALONADA` vai direto para `RECADO_EM_VIDEO`.

Fila ordenada por tempo de espera, com prioridade para `VISITA` sobre `ENTREGA`. `POST /operator/queue/claim` usa `FOR UPDATE SKIP LOCKED` — dois operadores nunca pegam a mesma visita.

Posição na fila enviada ao visitante por `QUEUE_POSITION` no WebSocket. Esperar é tolerável; esperar sem saber quanto falta, não.

`VISIT_QUEUE_TIMEOUT` (120s) → `RECADO_EM_VIDEO`.

### 3. App do operador

Mesmo binário Compose Multiplatform, perfil decidido por `GET /me`. Layout mais denso que o do morador.

**Fila** à esquerda: foto, tipo, unidade, tempo de espera e **por que escalonou** (ninguém atendeu / quiet hours / unidade inexistente).

**Contexto** à direita, antes de assumir: histórico da unidade, visitas recentes, regra de entrega, nomes dos moradores, telefone. **O operador nunca atende sem contexto** — atender às cegas é o que faz a portaria remota parecer pior que a física.

Presença: `DISPONIVEL` / `EM_ATENDIMENTO` / `OFFLINE`, com heartbeat. Operador que perde conexão volta para `OFFLINE` automaticamente e suas visitas retornam à fila.

Ao resolver, o operador registra `resolution_reason` — obrigatório, e é o que alimenta a análise de por que o modelo autônomo falhou naquele caso.

### 4. Recado em vídeo

`RECADO_EM_VIDEO`: o visitante grava até 30s. Salvo em `media_assets` com `kind = RECADO_VIDEO` e retenção de 30 dias.

Notificação ao morador **sem urgência** — não é CallKit, não é full-screen intent. É pendência, não chamada.

Aparece no topo da home do app até ser resolvida. O morador pode autorizar retroativamente (gerando `access_grant` com validade estendida), negar, ou apenas marcar como visto.

### 5. Quiet hours

Dentro de `condominiums.quiet_hours`, visitas não pré-autorizadas **pulam o toque ao morador**: vão direto para `FILA_OPERADOR` (se o módulo estiver ativo) ou `RECADO_EM_VIDEO`.

É a defesa contra tocar em todos os apartamentos de madrugada, e precisa ser óbvia para o visitante: "Fora do horário. Transferindo para a portaria."

### 6. Cancelamento de notificações

Ao resolver a visita, cancele as notificações pendentes em todos os dispositivos que foram acionados. Android usa `notificationId` estável por visita; iOS usa `CXProvider.reportCall(with:endedAt:reason:)`.

Uma chamada CallKit que continua tocando depois de resolvida é bug grave de percepção — o morador acha que o app está quebrado.

### 7. Métricas de escalonamento

`portaria.escalation.ratio` (quantas visitas escalaram) · `portaria.queue.wait_time` · `portaria.queue.abandoned` · `portaria.message.recorded` · `portaria.message.unresolved_24h`.

`escalation.ratio` é a métrica que decide se um condomínio fica no plano Autônomo ou precisa migrar para o Assistido.

## Critérios de aceite

- [ ] Escalonamento toca para os demais moradores após 20s
- [ ] Primeiro a atender vence; notificações dos outros são canceladas
- [ ] Sem `operator_queue`, escalonada vai direto para recado
- [ ] Dois operadores não pegam a mesma visita (teste concorrente)
- [ ] Posição na fila chega ao visitante em tempo real
- [ ] Operador que perde conexão devolve a visita à fila
- [ ] Recado gravado, armazenado e notificado sem urgência
- [ ] Recado aparece como pendência na home até resolver
- [ ] Quiet hours desvia sem tocar em ninguém, com aviso ao visitante
- [ ] CallKit não continua tocando após resolução
- [ ] Fluxo completo sem morador algum: QR → escalonamento → fila → operador → autorizado

## Não faça nesta fase

- Pré-autorização e recorrentes (v2)
- WhatsApp (FASE 8)
- Escalação para telefone/PSTN