# clinic-queue-panel — Fundações de UX/UI

> **Nomenclatura.** "Painel de TV Inteligente" é o nome comercial do projeto, usado na Proposta Técnica e Comercial (05/08/2026) e no Contrato (Cláusula 1) — é o nome que a Qualimplan reconhece e o que aparece em qualquer material voltado à clínica (wireframe, mockup, apresentações). **"clinic-queue-panel" é o codinome interno de engenharia**, usado neste documento e no repositório — mantido deliberadamente genérico porque a Cláusula 7 do contrato dá à Coldwing licença de retorno para reaproveitar o núcleo técnico em outras clínicas (ver seção 8, reusabilidade multi-tenant). Não é inconsistência: são dois nomes para dois públicos.
>
> **Nota de razão social.** A CONTRATANTE no contrato é juridicamente "Milagres & Milagres Clínica Odontológica Ltda." (CNPJ 12.384.106/0001-15) — "Qualimplan" é o nome fantasia/marca. Para design e produto, "Qualimplan" é sempre o nome correto (é a marca exibida). A razão social só importa em documentos formais/jurídicos.

> **Propósito deste documento.** Registrar as decisões de design (visual, interação, acessibilidade e som) que dão vida às duas interfaces do sistema — o **Painel de TV** e o **Painel de Gestão** — a partir da identidade visual da Qualimplan. Não é um design system genérico: é o conjunto de fundações de design **específico deste sistema**, ancorado nas regras de negócio e nos limites já definidos no *Guia do Projeto*. Onde uma decisão deriva de uma cláusula ou seção, a origem é citada.
>
> **Escopo.** Cobre arquitetura de informação (inventário de telas), tokens visuais, tipografia, iconografia, estados de tela, acessibilidade e diretriz sonora. **Não** cobre arquitetura de software, contratos de API nem regras de negócio — essas vivem no *Guia do Projeto*, que continua sendo a fonte de verdade funcional.
>
> **Status.** Esboço para a reunião de terça (18/08/2026). Seções marcadas com 🟡 dependem de decisão ou de terceiro; ver a seção 10.

---

## 0. Como este documento se relaciona com o Guia do Projeto

O *Guia do Projeto* é o **PRD/spec funcional**: escopo, regras de negócio, endpoints, arquitetura. Este documento é a camada de **design** que se apoia nele. Regra prática: se a pergunta é *"o que o sistema faz e por quê"*, a resposta está no Guia; se é *"como isso se parece e se comporta na tela"*, está aqui.

Princípio herdado que molda tudo abaixo: **reusabilidade multi-tenant** (Guia, seção 8). Toda cor, texto, limiar e ativo visual aqui definido é **valor de configuração da aplicação Qualimplan**, nunca constante fixa no núcleo. Este documento descreve a instância Qualimplan; o núcleo deve poder receber outra identidade sem reescrita.

---

## 1. Princípios de design

Quatro princípios que resolvem empates de decisão ao longo do projeto:

1. **Resiliência acima de completude.** Dado faltando nunca quebra a tela nem esconde o paciente da fila. Herdado da decisão de 16/08 (Guia, seção 4.2): dentista sem sala vinculada exibe só o nome do dentista. Este princípio se estende a todos os estados de erro.
2. **Um público, um objetivo por tela.** O Painel de TV serve a quem espera, ansioso, olhando de longe por segundos — hierarquia mínima. O Painel de Gestão serve a quem opera, de perto, com atenção — densidade de dados é aceitável. Não misturar as duas linguagens.
3. **Calor, não frieza clínica.** A marca já é acolhedora (dente laranja, curva orgânica do "Q"). O design segue esse tom: humano, tranquilizador — evita a estética hospitalar fria (cruz vermelha, alarme).
4. **A marca é configuração.** Ver seção 0. Nada de "Qualimplan" hardcoded no núcleo.

---

## 2. Tokens visuais

### 2.1 Cores institucionais

Fonte: manual de marca Qualimplan (identidade visual, rev. 001, jun/2011) e Guia, seção 10. As aproximações hex são adequadas para tela (Pantone é tinta física; não exige validação de gráfica).

| Papel no sistema | Nome / Pantone | Hex | Uso |
|---|---|---|---|
| Primária / destaque | Pantone 151 C (laranja) | `#FF8200` | Chamada em destaque, CTA, elemento de foco |
| Secundária / marca | Pantone 321 C (teal) | `#00778B` | Cabeçalhos, ícones, molduras, identidade |
| Neutro / texto secundário | Pantone Cool Gray 9 C | `#75787B` | Texto de apoio, metadados, rótulos |
| Detalhe / acabamento | Pantone 877 C (prata metálico) | `#8A8D8F` | Bordas, divisórias, detalhes sutis |

> **Nota sobre o metálico.** Pantone 877 C é uma tinta metálica — em tela vira um cinza claro comum (`#8A8D8F`). Usar só como detalhe/acabamento; não esperar efeito metálico em display.

🟡 **Cores semânticas de alerta (semáforo).** O sistema precisa de verde / amarelo / vermelho para o semáforo de espera (Médio / Crítico), que **não** existem no manual de marca. Proposta a validar (ver 2.2 e seção 7 para a regra de acessibilidade que as acompanha):

| Estado | Hex proposto | Observação |
|---|---|---|
| Normal / OK | `#2E7D32` (verde) | A confirmar contraste final |
| Médio / atenção | `#F9A825` (âmbar) | Distinto do laranja da marca `#FF8200` para não confundir alerta com CTA |
| Crítico | `#C62828` (vermelho) | — |

> **Ponto de atenção herdado do manual:** o laranja da marca (`#FF8200`) é quente e próximo do âmbar de alerta. Para evitar ambiguidade "isto é destaque ou é alerta?", o âmbar do semáforo deve ser visivelmente mais amarelo, e o alerta nunca deve depender só da cor (seção 7).

### 2.2 Contraste — verificação obrigatória

Toda combinação texto/fundo precisa passar em WCAG. Alvo: **AA (4.5:1)** para texto de gestão; para o Painel de TV, mirar **7:1 (AAA)** dado que é leitura à distância e em condições de luz não controladas. 🟡 Verificar especificamente:

- Teal `#00778B` sobre branco e branco sobre teal (cabeçalhos).
- Laranja `#FF8200` — tende a falhar contraste como **texto** sobre branco; provável uso só como **fundo de bloco** com texto branco/escuro por cima, ou como elemento gráfico, não como texto pequeno.
- Cinza `#75787B` sobre branco em tamanhos pequenos.

### 2.3 Tipografia

> **Contexto herdado da análise da identidade.** O *wordmark* "Qualimplan" é um logotipo **desenhado à mão** (ag alex guerra, 2011) — não existe fonte por trás dele para uso em UI, e isso é normal. O PDF é imagem rasterizada, sem fonte embutida ou metadado, então não foi possível extrair um nome de fonte oficial dos arquivos. Em vez de adivinhar, **caracterizamos o DNA tipográfico do wordmark** e pesquisamos fontes de mercado que o carregam.

**DNA tipográfico da marca** (observado ampliando o wordmark): sans **geométrica**, **monolinear** (traço de espessura constante), **"a" de andar único** (single-story — o traço definidor), **terminações arredondadas e suaves**, contraformas largas e abertas, pingo do "i" redondo e alto, pé do "l" levemente curvado. Em uma frase: *sans geométrica arredondada, monolinear, de andar único.*

**Método.** Renderizamos as candidatas escrevendo "Qualimplan" e o conteúdo real do painel (nome longo em pt-BR + sala + número de espera) lado a lado com o wordmark. Descartadas: **Nunito** (tem "a" de **dois andares** — quebra o DNA, apesar do visual amigável), **Rubik** (menos geométrica/redonda), **Baloo 2** (pesada demais, só display).

**Decisão — par tipográfico** (mantém consistência: ambas são sans geométricas de andar único, mesmo DNA; a diferença é papel, não família):

| Papel | Fonte | Onde | Por quê |
|---|---|---|---|
| **Display / marca** | **Quicksand** | Painel de TV: nome do paciente, cabeçalhos, momentos de identidade | Match mais fiel ao wordmark — geométrica, monolinear, andar único, terminações arredondadas. Carrega o calor da marca. |
| **Workhorse / texto** | **Poppins** | Painel de Gestão, textos pequenos, botões, rótulos e **todos os números** (tempo de espera) | Mesmo DNA geométrico de andar único, mas melhor legibilidade de números e desempenho impecável em qualquer tamanho e densidade. |

> **Racional da divisão.** As duas superfícies têm necessidades opostas: a TV é emocional e vista de longe (o calor arredondado da Quicksand importa); o dashboard é denso e visto de perto, com números críticos (a legibilidade da Poppins importa). É o padrão clássico de design liderado por marca: uma *display* para a identidade, uma *text* para a função. Ambas gratuitas (Google Fonts / OFL), com bom suporte a português.
>
> **Cuidados de uso.** (1) Na TV, usar Quicksand em pesos fortes (SemiBold/Bold) — seus pesos leves afinam e perdem legibilidade à distância (ver 4.2). (2) Números de tempo de espera sempre em Poppins, mesmo quando cercados de texto em Quicksand — precisão de leitura acima de pureza estética. (3) Como toda a identidade, as duas fontes entram como **configuração da aplicação Qualimplan**, não constante do núcleo (seção 0/9).

**Escala tipográfica** — diretrizes fixadas (valores finais a confirmar no mockup):
- **Painel de TV:** dois níveis dominantes — nome do paciente (maior elemento da tela) e sala/dentista (secundário). Tamanho **calculado por distância de leitura**, não por preferência (ver seção 4.2).
- **Painel de Gestão:** escala convencional de dashboard (título, seção, corpo, rótulo, dado numérico), otimizada para densidade e leitura de perto.
- **Regra de i18n (Guia, seção 7):** strings de UI em português, isoladas em arquivo de config — nunca hardcoded. A tipografia serve texto em pt-BR (acentuação, "ç", palavras longas como "Odontológicos").

### 2.4 Espaçamento, raio e elevação

Base sugerida a confirmar no mockup:
- **Grid de espaçamento:** múltiplos de 8px (escala 4 / 8 / 16 / 24 / 32 / 48 / 64).
- **Raio de borda:** arredondado, ecoando a curva do "Q" — sugestão de raio médio-generoso (ex. 12–16px em cards). Reforça o princípio 3 (calor, não frieza).
- **Elevação/sombra:** sutil no Painel de Gestão; no Painel de TV, evitar sombras finas que somem à distância — preferir separação por cor de bloco e espaçamento.

### 2.5 Som (token de marca)

Ver seção 8 para a diretriz completa. Registrado aqui porque, no contrato, o som é **configurável por cliente** ("textos do alerta sonoro" — Guia, seção 8) — portanto é um token da aplicação, não do núcleo.

### 2.6 Breakpoints — responsividade desktop

Escopo desta rodada: **só desktop** (decisão registrada em 3.4) — mobile/tablet ficam anotados, não desenhados. Baseado em padrões de mercado 2026 para breakpoints de desktop:

| Breakpoint | Faixa | Comportamento |
|---|---|---|
| Desktop padrão | 1280–1439px | Layout de referência do wireframe (seção 3.4) — grid completo, sidebar fixa, densidade normal |
| Desktop grande | 1440–1919px | Mesma estrutura, mais respiro/whitespace; colunas não esticam além do max-width de conteúdo |
| Desktop wide / ultrawide | ≥1920px | Conteúdo centralizado com max-width; nunca esticar tabelas/formulários pra ocupar a tela toda — vira ilegível |

**Regra prática:** max-width de conteúdo (~1200–1280px), centralizado a partir de 1440px — evita linhas de texto/tabela absurdamente longas em monitor grande. Abaixo de 1280px (ainda dentro do escopo desktop, ex. laptop pequeno), a sidebar do Painel de Gestão pode colapsar para ícones — mas isso ainda não é mobile.

Aplica-se ao **Painel de Gestão** (seção 5.1: "responsividade real é requisito"). O **Painel de TV não usa breakpoints** — é sempre relativo ao viewport único da TV (seção 4.2), não a uma faixa de larguras.

---

## 3. Arquitetura de informação — inventário de telas

> Elo que faltava entre os tokens (seção 2) e as fundações de cada painel (seções 4 e 5). Antes de desenhar *como* uma tela se comporta, é preciso fechar *quantas* telas existem e o que cada uma faz. Dois conceitos que valem manter separados daqui pra frente:
> - **Tela** = uma rota/página navegável, com destino próprio.
> - **Estado** = uma variação de conteúdo dentro da mesma tela (vazio, erro, carregando…) — catalogado nas seções 4.6 e 5.4.
>
> Este inventário é dedução direta do escopo já contratado (Guia, seção 2) — não depende de pesquisa de mercado, só de organizar o que já foi vendido.

### 3.1 Painel de TV — 1 tela

Sem navegação: é um destino fixo, a URL que fica aberta na TV da recepção. Tudo que muda nele é conteúdo/estado (seção 4.6), nunca rota. Essa natureza de "tela única" deriva do princípio de resiliência (seção 1) e da restrição de hardware não controlado (Guia, seção 3) — uma tela sem navegação é uma tela que não pode "travar no lugar errado".

### 3.2 Painel de Gestão — inventário de telas

Derivado do escopo funcional (Guia, seção 2.3). Quatro telas navegáveis:

| # | Tela | Rota sugerida | Propósito | Origem funcional |
|---|---|---|---|---|
| G1 | **Login** | `/login` | Autenticação do usuário do Painel de Gestão | Guia 2.3, 6 |
| G2 | **Monitor de Fila** (home) | `/` ou `/fila` | Visão em tempo real da fila, com alertas de cor; tela padrão após login | Guia 2.3 |
| G3 | **Configurações de Alerta** | `/configuracoes` | Liga/desliga semáforo; ajusta os minutos de Médio/Crítico | Guia 2.3 |
| G4 | **Salas & Vínculos** | `/salas` (aba Vínculos: `/salas/vinculos`) | Duas abas: **Salas** (CRUD de `Sala { id, nome }`) e **Vínculos** (edição de `SalaDoMedico` + sincronização manual) | Guia 4.2, 4.3 |

**Ações que não são telas próprias** — vivem dentro de uma das quatro acima, como modal ou controle inline, e não precisam de rota dedicada:
- **Remoção manual de paciente** — modal/ação dentro do Monitor de Fila (G2). Contingência prevista (Guia 2.3), não precisa de fluxo de confirmação pesado.
- **Sincronização manual de profissionais** — botão com feedback de loading/lock dentro da aba Vínculos (G4).

✅ **Resolvido em 16/08 (era pendência 🟡):** G4 e G5 fundidas em uma tela com duas abas — "Salas" e "Vínculos". Critério de mercado pra tabs (não páginas separadas): mesmo nível hierárquico, conteúdo relacionado, uso mutuamente exclusivo, 2–7 seções — os dois batem em todos os pontos. G3 (Configurações de Alerta) **ficou de fora** da fusão de propósito: não é a mesma tarefa (ajustar limiar de alerta é uma decisão de configuração pontual; gerenciar salas/vínculos é operação recorrente do dia a dia) — fundir os três só porque "todos são admin" seria agrupar por categoria abstrata, não por tarefa real, e criaria uma aba "solitária" ao lado de duas relacionadas.

### 3.3 Mapa de navegação

```
Painel de TV — tela única, sem login
   └── estados internos (seção 4.6)

Painel de Gestão
Login (G1)
   └── Monitor de Fila (G2) — home após autenticar
         ├── Configurações de Alerta (G3)
         └── Salas & Vínculos (G4)
               ├── aba Salas
               └── aba Vínculos
```

### 3.4 Convenções do wireframe

Padrões de mercado consolidados para wireframe profissional (fidelidade média, anotado, com pontos de decisão) e como se aplicam aqui:

- **Fidelidade:** média — estrutura, hierarquia e fluxo bem definidos, neutro/cinza, sem cor de marca. Conteúdo **realista, não lorem ipsum** (ex.: "Maria Aparecida Gonçalves", "Sala 3") — ajuda a clínica a visualizar o produto de verdade em vez de decodificar texto de preenchimento.
- **Tamanho de tela de referência:**
  - **Painel de TV:** 1920×1080 (16:9, resolução padrão de Smart TV) como viewport de referência, com tamanhos relativos à altura do viewport (seção 4.2) — nunca pixel fixo, porque o hardware real é desconhecido (Guia, seção 3).
  - **Painel de Gestão:** desktop, 1440px de largura, como referência para a reunião de terça. 🟡 **Mobile/tablet fica anotado como comportamento responsivo esperado, não desenhado nesta rodada** — decisão de escopo para não travar a entrega de terça; entra numa próxima rodada de wireframe antes do desenvolvimento.
- **Placeholder de ícone/imagem:** caixa neutra com "×" central, usada enquanto a biblioteca de ícones (seção 6) não está fechada — evita comprometer visualmente com um ícone que ainda pode mudar.
- **Anotações:** marcadores numerados ao lado de elementos que precisam de explicação de comportamento (ex.: "① dispara `/appointment/change_status`", "② debounce de 3s contra cliques repetidos"), com legenda listada abaixo de cada tela.
- **Componentes reutilizáveis identificados** (nomear evita redesenhar o mesmo bloco em telas diferentes): Card de chamada, Linha de fila, Badge de status (semáforo), Botão de ação (sincronizar / remover), Campo de formulário (admin), Modal de confirmação, Cabeçalho de navegação (Gestão).
- **Fluxo com pontos de decisão** (extensão do mapa acima):
  - Login (G1) com credencial inválida → permanece em G1, exibe erro — nunca avança sem sessão válida.
  - Troca de aba em G4 (Salas ↔ Vínculos) → conteúdo muda, mesma tela macro, sem navegação de página.
  - Sincronização manual na aba Vínculos (G4) → estado "sincronizando" (loading/lock) → sucesso volta ao normal, falha exibe erro inline sem travar a tela.
  - Remoção manual de paciente em G2 → modal de confirmação → escreve no Clinicorp (mesma operação da baixa automática, Guia 4.1) → sucesso remove da fila; falha mantém o paciente e mostra erro, sem fingir que deu certo.

### 3.5 Reuso de componentes — SOLID sem virar design system

Não construímos um design system, mas isso não significa reinventar cada tela do zero. A literatura confirma que atomic design (o método mais comum pra organizar reuso de UI) é, na prática, aplicação de modularidade e SOLID a componentes — validando que dá pra ter essa disciplina numa escala pequena, sem virar um sistema formal.

| Princípio SOLID | Tradução para componente de UI | Aplicação aqui |
|---|---|---|
| **S — Responsabilidade única** | Um componente faz uma coisa | O Card de chamada só renderiza o que recebe — não decide se o paciente já foi chamado |
| **O — Aberto/fechado** | Estende via props/variantes, não editando o componente em si | Badge de status aceita uma variante (normal/médio/crítico) — não vira 3 componentes diferentes |
| **L — Substituição** | Qualquer variante do componente troca por outra sem quebrar quem usa | Botão de ação (sincronizar, remover) mantém a mesma API não importa a ação |
| **I — Segregação de interface** | Props mínimas e específicas — não empilhar "só por garantia" | Linha de fila não recebe props de admin de sala; são componentes diferentes |
| **D — Inversão de dependência** | Componente depende de token/config, nunca de valor fixo | Ecoa o princípio 4 (marca é configuração) — cor, texto e ícone vêm de token, nunca hardcoded |

**Os 7 componentes já identificados na seção 3.4** ganham essa disciplina: cada um usado em mais de uma tela precisa funcionar sem saber onde está sendo usado. Ex.: o Badge de status aparece no Monitor de Fila (G2) e no semáforo da TV — não pode carregar suposição de que está "dentro do G2".

**Onde isso para:** sem biblioteca versionada, sem Storybook, sem governança formal — é aplicar a mesma disciplina de modularidade numa escala compatível com um projeto de cliente único, seguindo YAGNI (Guia, seção 7): reuso onde ele já é necessário (esses 7 componentes se repetem de fato), não especulativamente.

---

## 4. Painel de TV — fundações

### 4.1 Objetivo e restrições

Tela pública de sala de espera. Vista **de longe, por segundos, por pessoas ansiosas**. O gênero de referência é **sinalização de chamada** (painéis de senha de clínica, quadros de embarque), não dashboard. Restrição herdada (Guia, seção 3): roda sobre **hardware que não controlamos** (TV, computador e rede da clínica) — o design não pode assumir resolução, tamanho de tela ou qualidade de alto-falante específicos.

### 4.2 Legibilidade à distância — regra dimensionável

Padrão de mercado consolidado em sinalização: **≈ 1 polegada (2,5 cm) de altura de letra para cada 3 metros (10 pés) de distância de leitura** como mínimo legível; para conforto, multiplicar por 1,5. Aplicação prática:

- Como não controlamos o hardware, **não fixar tamanhos em pixel** — definir tamanhos **relativos à altura da tela** (ex.: nome do paciente ocupa X% da altura do viewport), de modo que o painel se redimensione em qualquer TV.
- **Regra 3×5** de sinalização: no máximo ~3 linhas, poucas palavras por linha. A chamada tem exatamente 3 blocos de informação (paciente / sala / dentista) — respeita a regra naturalmente.
- **Alto contraste obrigatório** (ver 2.2, alvo 7:1). Texto escuro sobre fundo claro é o mais legível à distância.
- **Fonte sem serifa, peso médio-alto.** Evitar pesos finos e fontes condensadas — somem à distância.

### 4.3 Conteúdo da chamada (Guia, seção 2.2)

Cada chamada exibe, nesta hierarquia:
1. **Identificação do paciente** — elemento dominante. ~~Decisão original: nome completo (Cláusula 2.2)~~ **Substituída em 25/08** pela hierarquia de privacidade já pesquisada e fechada: **apelido** (campo confirmado no Clinicorp) → **primeiro + segundo nome** se não houver apelido → **nunca o nome completo**. Pesquisa de mercado específica de sinalização de sala de espera em saúde já validou essa direção (seção 5.7, doc anterior): "chamar por nome completo em sala de espera pública já é visto como problema de privacidade" — a mudança resolve a ressalva de LGPD que ficou em aberto na decisão original, em vez de só registrar a ressalva e seguir em frente.
2. **Sala / Destino** — resolvida via tabela local DE/PARA (Guia, seção 4.2).
3. **Nome do Profissional.**
4. **Foto do paciente** — ver seção 4.3.2, adicionada em 25/08.

#### 4.3.1 Painel lateral — "Aguardando", não "últimas chamadas"

Decidido em 16/08, a partir de pesquisa de mercado em sistemas de fila (hospitais, bancos, clínicas). O painel lateral da TV originalmente mostrava um histórico de chamadas já feitas, com um rótulo agregado ("Fila normal") no cabeçalho — dois problemas achados na prática:

- **O rótulo agregado era ambíguo.** "Fila normal" não mapeava pra nenhuma regra de negócio real — não é status de um paciente, nem da fila inteira, nem de nada específico. Gerava a pergunta certa: "isso é status de quê?"
- **Histórico é menos útil que "quem vem a seguir".** Pesquisa de mercado confirma o padrão quase universal em sistemas de fila: **"now serving" + "next in line"** — o paciente já viu quem foi chamado antes dele; o que ele quer saber é sua própria posição e status.

**Decisão:** o painel lateral virou **"Aguardando"** — lista dos próximos pacientes (ainda não chamados), cada um com:
- Nome + sala/profissional. 🟡 **Pendência aberta em 25/08:** essa lista ainda mostra o nome como estava antes da mudança da seção 4.3 (não passou pela hierarquia apelido → primeiro+segundo nome). Ficou assim de propósito nesta rodada — o pedido do cliente foi específico pra "no momento da chamada" — mas é uma inconsistência real que vale perguntar: faz sentido a mesma privacidade valer pra quem ainda não foi chamado?
- **Status individual** — reusa o mesmo componente Badge do Painel de Gestão (seção 5, forma+rótulo, nunca só cor): Normal / Atenção / Crítico. Resolve a ambiguidade do rótulo antigo ao mover o status pro nível certo (por paciente, não agregado) e reforça consistência entre TV e Gestão (mesmo dado, mesmo componente, dois lugares — SOLID, seção 3.5).
- **Ordenado por urgência** — crítico primeiro, não por ordem de chegada. Prioriza visualmente quem está esperando mais.
- Também aparece aqui o caso "sem sala vinculada" (seção 4.2) — reforça a resiliência em mais um lugar da tela, não só na chamada em destaque.

#### 4.3.2 Foto do paciente na chamada (25/08) — pedido do cliente, acessibilidade

**Contexto:** pedido explícito da clínica — idosos e pessoas não alfabetizadas reconhecem o próprio rosto numa tela a alguns metros de distância mais rápido do que leem o próprio nome. Dado já confirmado como disponível (cadastro do Clinicorp, seção 10.3 anterior) e a clínica já está ciente da implicação de LGPD (explicado a eles previamente, registrado).

**O que a pesquisa encontrou — e o que não encontrou.** Não existe um precedente de mercado específico de "foto em painel de chamada de fila" documentado o bastante pra citar como padrão — sendo direto sobre essa lacuna em vez de inventar uma fonte. O que a pesquisa de acessibilidade em saúde traz, de forma consistente entre várias fontes independentes, é o princípio mais geral que sustenta a decisão: **conteúdo baseado em imagem funciona melhor que texto pra quem tem baixa alfabetização** (confirmado inclusive em estudo clínico sobre material educativo pra pacientes de baixa alfabetização — abordagem multimídia/baseada em imagem supera texto). Outra fonte, sobre sinalização digital em sala de espera, testa o limiar prático certo: **"se o conteúdo se entende em 5 segundos a 3 metros de distância, está na zona segura"** — o mesmo teste de leitura à distância que o projeto já usa desde a seção 4.2, agora aplicado à foto.

**Desenho:**
- Foto circular, grande (~110–190px, escala com a tela), ao lado do bloco de nome — não substitui o nome, soma a ele. Círculo (não quadrado) por familiaridade — é a forma que avatar/foto de perfil já assume em quase todo produto digital, reconhecimento não exige aprender um padrão novo.
- **Escopo deliberadamente restrito: só na chamada em destaque.** Não aparece na lista "Aguardando" nem em nenhuma outra tela — pedido explícito do cliente ("apenas no momento da chamada"), e reduz a superfície de exposição do dado mais sensível (foto) ao mínimo necessário, mesmo raciocínio de minimização já seguido pro resto do sistema (Guia, seção 6).
- **Resiliência — mesma régua de "dado faltando nunca quebra a tela"** (seção 4.2, já estabelecida pra sala ausente): se o Clinicorp não tem foto cadastrada pra um paciente (comum em cadastros antigos), a tela cai pras **iniciais** — reusa o mesmo componente de avatar já usado na sidebar do Painel de Gestão (seção 5.7.9), não inventa um padrão novo só pra TV. Demonstrado na variante "Dentista sem sala", que agora prova três resiliências ao mesmo tempo (sala ausente, foto ausente, apelido ausente) — economiza uma tela nova pra cada caso.
- **No wireframe, a foto é um placeholder cinza** (silhueta genérica) — mesma regra já aplicada ao logo (seção 4.6.1... conferir): cor e imagem real entram só no mockup, depois que o Clinicorp confirmar o endpoint exato (pergunta já registrada, `perguntas-clinicorp.md`).

🟡 **Pendência de produto, não de design:** se o cliente eventualmente atender outras clínicas fora da odontologia (Guia, seção 8 — reusabilidade multi-tenant), foto de paciente pode não ser uma decisão universal — outras clínicas podem preferir não exibir. Recomendação: quando a implementação real acontecer, isso devia ser um toggle de configuração por clínica (mesmo padrão dos limiares de alerta, seção G3), não um comportamento fixo no core.

### 4.4 A "chamada" como evento visual — padrão ouro (visual + sonoro juntos)

Requisito herdado (Guia, seção 2.2): destaque visual + sinal sonoro, **sem piscar a tela nem recarregar visivelmente**. Implementado em 18/08 a partir de pesquisa de mercado — três fontes convergindo no mesmo formato:

- **Broadcast / lower-third de TV** (o gênero mais próximo do nosso caso — é literalmente uma tela de televisão): uma barra sólida que **cresce** (não pisca) ancora o momento de "algo novo aconteceu", padrão consolidado em telejornalismo pra anunciar informação nova sem sobressaltar.
- **"Radiating halo"** (Nielsen Norman Group): anéis que emanam de um ponto de atenção reforçam um sinal sem distrair — é o mesmo mecanismo técnico já validado e construído pra tela institucional de falha prolongada (seção 4.6.1), reaproveitado aqui (SOLID, seção 3.5).
- **Motion design geral** (Material Design / NN Group): entradas devem ser rápidas (300–500ms), com easing natural (nunca linear/robótico), e toda animação precisa justificar seu propósito — "se eu não consigo explicar a razão, provavelmente não preciso dela".

**A combinação implementada:**
1. **Barra de destaque** cresce da esquerda pra direita (~450ms) — ocupa o papel do laranja de marca (`#FF8200`, Guia 2.2); em cinza no wireframe, cor real no mockup.
2. **Nome, sala e profissional entram em sequência** (fade + leve escala, ~500ms, com atraso escalonado entre eles) — nunca tudo de uma vez, olho acompanha a ordem de importância.
3. **Anéis emanando do bloco inteiro**, tocando **só 2 vezes** — nunca em loop. É a diferença crítica que respeita "sem piscar a tela": um evento de entrada tem início, meio e fim; piscar não tem fim.
4. **Ícone de som pulsando em sincronia** — reforça pro time que o áudio dispara no mesmo instante do visual (arquivo de som em si ainda pendente, seção 8.2).

Depois da entrada, a tela **assenta** — sem nenhuma animação contínua na chamada em si (a próxima chamada é que dispara tudo de novo). No wireframe, a animação toca automaticamente sempre que a tela "Chamada em destaque" é aberta, e um link "repetir a animação da chamada" permite disparar de novo pra demonstração.

- Atualização contínua e reativa: a lista muda sem "flash" de recarregamento.

#### 4.4.1 🟡 Ideia registrada — movimento ambiente também fora da falha

Parcialmente resolvido em 18/08: o movimento no **momento da chamada** está desenhado (seção 4.4 acima). O que segue em aberto é o movimento **ambiente**, fora de qualquer evento — uma textura ou faixa sutil e contínua nos estados normais da TV, pra reforçar "sistema vivo" o tempo todo, não só quando algo acontece.

- **Por que não decidir agora:** depende de cor de marca final e de tokens que só fecham no mockup (seção 2.1/2.4) — desenhar isso em cinza arriscaria não representar a intenção real. Também precisa validar que não compete com a leitura à distância (seção 4.2) nem com o destaque da chamada (4.4).
- **Quando retomar:** na primeira rodada de mockup de alta fidelidade do Painel de TV, depois da paleta e tipografia estarem aplicadas de verdade.

### 4.5 Semáforo de tempo de espera

Exibição **opcional e configurável** (Guia, seção 2.2 e 2.3). Quando ligado, segue as cores semânticas (2.1) **e** a regra de redundância de acessibilidade (seção 7): cor nunca sozinha.

### 4.6 Catálogo de estados de tela (Painel de TV)

Todo estado abaixo precisa ser desenhado — nenhum pode "quebrar a tela" (princípio 1):

| Estado | Descrição | Origem |
|---|---|---|
| **Fila com chamadas** | Estado normal: lista/último chamado visível | Guia 2.2 |
| **Chamada em destaque** | Momento em que um paciente é chamado (visual + som) | Guia 2.2 |
| **Dentista sem sala vinculada** | Exibe só o nome do dentista, sem sala — nunca omite o paciente | Guia 4.2 (decidido 16/08) |
| **Fila vazia** | Nenhuma chamada ativa — estado de espera acolhedor, com a marca | Novo (a desenhar) |
| **Falha curta** (dentro do ciclo normal) | **Invisível.** A tela de chamada não muda — só continua parada na última informação sincronizada. Nenhum indicador, nenhum aviso. | Pesquisa de mercado (16/08, ver 4.6.1) |
| **Falha prolongada** (além de um limite) | Tela institucional: só a marca (logo + nome), sem qualquer palavra sobre erro/conexão. Brilho sutil + batimento técnico quase imperceptível provam que o sistema está vivo, sem alarmar. | Pesquisa de mercado (16/08, ver 4.6.1) |
| **Modo demo** | Dados fictícios para portfólio/marketing | Guia, seção 11 (Cláusula 15) |

#### 4.6.1 Modelo de resiliência de duas camadas — por que não existe "tela de erro" na TV

Decidido em 16/08, a partir de pesquisa de mercado em digital signage. Ponto de partida: uma tela de "sem conexão" numa TV de sala de espera lotada assusta paciente e passa amadorismo — o padrão de mercado resolve isso de um jeito específico, e não é só estético.

- **"Fail static" / graceful degradation** — o padrão consolidado de digital signage: o player cacheia o conteúdo localmente e, se a sincronização falhar, **continua mostrando o último estado bom conhecido**. Nunca uma tela de erro. Onde a falha se estende além de um limite aceitável, o material de mercado recomenda cair numa "mensagem neutra e segura, como a marca da instituição" — não um aviso técnico.
- **Duas camadas, não uma:**
  - **Curta** (dentro do ciclo normal de sincronização): tratamento *invisível* — a tela de chamada simplesmente não atualiza por alguns segundos. É o "fail static" puro; não existe design para esse caso porque ele é idêntico ao estado normal.
  - **Prolongada** (além de um limite 🟡 a definir com base no ciclo de sincronização — seção 4.2/12.1): a tela troca para o modo institucional. Congelar a última chamada por tempo longo demais viraria informação **enganosa** (o paciente acha que ainda é a vez de quem foi chamado há 10 minutos) — daí a necessidade da segunda camada.
- **"Design otimista" não é o termo certo aqui** — Optimistic UI é um padrão para ações que o *usuário* dispara (curtir, salvar), assumindo sucesso antes da confirmação do servidor. A TV é uma tela ambiente, sem usuário disparando nada; o padrão certo é graceful degradation / fail static.
- **Movimento na periferia, não no centro.** Princípio de mercado em design de kiosk/signage: "motion on the periphery is more subtle than motion in the middle of the line of sight — the most important features should be static." Aplicado aqui como um brilho lento e sutil atrás do logo (não no logo em si) — prova que o sistema está rodando sem competir com a informação.
- **Batimento técnico quase imperceptível.** Um ponto pequeno, de baixíssimo contraste, pulsando bem devagar num canto — não é para o paciente notar a distância normal de sala de espera; é uma pista técnica de "isto está vivo", útil só para quem se aproximar da tela.
- **Relógio sempre real**, mesmo na tela institucional — não depende do Clinicorp, mantém a tela útil e reforça (sem palavras) que nada travou.
- **Freshness indicator fica só no Painel de Gestão.** O padrão de mercado "Data Freshness Indicator" (rótulo de frescor de dado + timestamp + botão de atualizar manual) faz sentido pra quem pode *agir* sobre o atraso — a recepção, não o paciente. Por isso o "Atualizado há Xs" + botão de sync manual (seção 5.4) existe no Gestão e nunca na TV.

---

## 5. Painel de Gestão — fundações

### 5.1 Objetivo e restrições

Interface administrativa interna. Acesso **autenticado, de qualquer dispositivo, dentro ou fora da clínica** (Guia, seção 2.3) → **responsividade real é requisito**, não enfeite. Linguagem de **dashboard operacional em tempo real**: densidade aceitável, leitura de perto.

### 5.2 Áreas funcionais → telas (ver inventário completo em 3.2)

- **Monitoramento da fila em tempo real** (G2), com alertas de cor Médio / Crítico.
- **Controle do semáforo** (G3): liga/desliga exibição e ajusta os minutos que definem cada alerta.
- **Admin de salas** (G4, aba Salas): cadastro de `Sala { id, nome }` (entidade local). CRUD completo — criar, editar e **excluir com confirmação** (toda remoção pede confirmação, seção 3.5/7).
- **Vínculo profissional ↔ sala** (G4, aba Vínculos): edição da tabela `SalaDoMedico`. Exibe só nome do profissional — **CPF não aparece**, nem mascarado: não tem função na tela, é dado sensível exposto à toa.
- **Sincronização manual de profissionais** (dentro de G4, aba Vínculos): botão que força dados frescos, com *debounce/lock* — comunica "sincronizando…" e impede cliques repetidos (Guia, seção 4.3).
- **Contingência manual** (dentro de G2): botão "Finalizar atendimento" — **operação prevista, não erro** (Guia, seção 2.3), e **escreve de volta no Clinicorp** pela mesma operação da baixa automática (`/appointment/change_status`, Guia 4.1) — não é uma máscara local que a próxima sincronização desfaz. Se a escrita falhar, o paciente permanece na fila e o erro é mostrado — nunca finge sucesso. Detalhe completo, incluindo por que é botão e não select, na seção 5.2.1.

#### 5.2.1 "Finalizar atendimento" é integração, não capa visual — e é botão, não select

Registrado em 16/08 — três clarificações importantes sobre essa ação: o que ela faz de fato, por que não virou um seletor de status, e quando ela aparece.

**Esclarecimento de fluxo que muda o modelo mental do sistema todo:** o paciente só **entra** nesta fila depois que a recepção muda o status dele pra "aguardando" **dentro do próprio Clinicorp** — fisicamente, após ele chegar à clínica e passar os dados na recepção. Esse check-in acontece na interface do Clinicorp, não na nossa (consistente com a proposta: "a equipe de recepção continuará operando exclusivamente dentro do Clinicorp"). Isso significa que **o Painel de Gestão nunca precisa de tela de check-in** — é sempre a leitura de quem já está com status "aguardando" no `/appointment/list` (Guia, seção 4.1) que popula a fila. A seção 4.3.1 (painel "Aguardando" da TV) já batia com isso por instinto de design; agora está confirmado por regra de negócio real, não só por boa prática de UX.

**Consequência direta — por que "não compareceu" não existe aqui:** um paciente que nunca chega nunca tem o status mudado pra "aguardando" no Clinicorp, logo **nunca entra na nossa fila**. Não existe cenário de "marcar como não compareceu" no nosso sistema — essa lógica é inteiramente resolvida do lado do Clinicorp/recepção, antes de nos alcançar. Cogitamos inicialmente um select com múltiplas opções de status (inspirado em padrões de mercado como Epic/PCC EHR, que usam "No Show" / "Left without seen" como correções manuais de fim de dia); descartamos porque, no nosso caso, resta **uma única transição manual real**: finalizar o atendimento.

**O botão só aparece pra quem está "em atendimento" — não pra quem está "aguardando".** Não dá pra finalizar algo que ainda não começou. A tabela do Monitor de Fila (G2) agora distingue as duas situações na própria coluna de status: badge **preenchido** ("Em atendimento") para quem já foi chamado — só essas linhas têm o botão "Finalizar" na última coluna; badge de **contorno** (Normal/Atenção/Crítico, a severidade de espera) para quem está "aguardando" — essas linhas mostram só o rótulo "aguardando", sem ação nenhuma. O preenchido vs. contorno já é, sozinho, uma segunda camada de redundância visual (forma do badge inteiro, não só do glifo) — consistente com a regra de acessibilidade da seção 7 (cor nunca sozinha), aplicada aqui a um nível acima do que já tínhamos.

**Decisão de componente:** com uma ação só, vira **botão nomeado** ("Finalizar atendimento"), não select — um select de opção única não é select, é botão fantasiado. Pesquisa de mercado confirma esse padrão: nenhum sistema de fila/ticket (Jira, Zendesk, Dentrix Ascend, Epic, PCC EHR) expõe a lista crua de status como campo livre — todos usam transições nomeadas e curadas (verbos de ação: "Start Progress", "Resolve", "Here", "Ready", "Checkout"), nunca um dropdown de "qualquer status". Um select livre no nosso caso teria dois problemas: (1) exporia o vocabulário de status do Clinicorp por inteiro, que provavelmente inclui estados clínicos/financeiros fora do nosso escopo (Guia, seção 3 — a escrita no Clinicorp é restrita a uma única operação, exclusivamente para baixa); (2) ainda não sabemos os `status_id` completos do Clinicorp (só serão mapeados na segunda-feira, Guia seção 5.6) — um select livre precisaria enumerar algo que não temos ainda.

🟡 **Reabrir só se necessário:** se depois de mapear os status do Clinicorp na segunda aparecer uma segunda transição manual real e dentro do escopo contratado, o componente já foi construído pra crescer de botão pra select sem redesenhar do zero (mesmo modal, mesmo fluxo de confirmação/carregamento/erro — só troca o gatilho de um botão pra uma escolha).

**Dois canais de status, uma coluna — não confundir a origem do dado:**
- **Severidade de espera** (Normal/Atenção/Crítico, badge de contorno) — **calculada por nós**, a partir do tempo de espera. Não existe no Clinicorp, é derivada, e não é editável manualmente — a recepção não deveria poder "mentir" pra um indicador que existe justamente pra transparência/acessibilidade. Só aparece em quem está "aguardando" (tempo de espera só faz sentido pra quem ainda não foi chamado).
- **Situação do agendamento no Clinicorp** (aguardando / em atendimento / finalizado) — dado real, é isso que o botão "Finalizar atendimento" afeta. "Em atendimento" vira o badge preenchido; "aguardando" é o texto simples na última coluna, sem badge de severidade competindo por atenção.

Os dois cabem na mesma coluna "Status" porque, na prática, cada paciente só tem um deles relevante por vez — quem está esperando não tem "situação de atendimento" pra mostrar, e quem está em atendimento não tem mais um tempo de espera correndo.

**Três estados na interface, não um clique-e-pronto:**
1. **Confirmação** — nome do paciente explícito no modal, texto explica que a ação atualiza os dois lados (fila local + Clinicorp).
2. **Em andamento** — feedback de carregamento ("Atualizando o Clinicorp…") enquanto a escrita acontece; botão travado contra clique duplo (mesmo princípio de debounce já usado no sync de profissionais).
3. **Falha** — se a escrita não confirmar, a interface **não finge sucesso**: o paciente continua na lista, um aviso explica o que houve, e a recepção pode tentar de novo. Alinhado à Cláusula 2.2 da proposta ("sujeito a validação técnica") e ao princípio de resiliência já estabelecido (seção 1) — só que aqui aplicado a uma ação de escrita do usuário, não a uma tela passiva.

Isso é consistente com a régua da seção 4.1 do Guia sobre a baixa automática: se a escrita via API não se comportar de forma confiável, existe fallback manual — "Finalizar atendimento" **é** esse fallback, e agora está desenhado para o cenário em que até ele pode falhar.

### 5.3 Alertas de cor no Gestão

Mesmas cores semânticas (2.1) e mesma regra de redundância (seção 7). Num dashboard denso, o rótulo textual do estado é ainda mais importante — nunca um "ponto colorido" sozinho.

### 5.4 Catálogo de estados de tela (Painel de Gestão)

Estados dentro de cada tela do inventário (3.2) — não confundir com a lista de telas em si:

| Estado | Tela | Descrição |
|---|---|---|
| **Login — padrão / erro de credenciais** | G1 | Acesso autenticado (Guia 2.3, 6) |
| **Fila em tempo real — normal** | G2 | Operação padrão |
| **Fila com alertas** | G2 | Um ou mais pacientes em Médio / Crítico |
| **Remoção manual de paciente** | G2 | Confirmação leve, sem tom de culpa |
| **Admin salas — vazio / preenchido / editando** | G4 · aba Salas | CRUD de salas |
| **Vínculo profissional↔sala — sem vínculo / vinculado** | G4 · aba Vínculos | Estado "sem sala" é válido (espelha o fallback do Guia, seção 4.2, já visto na TV — seção 4.6) |
| **Sincronizando profissionais** | G4 · aba Vínculos | Feedback do botão manual (loading/lock) |
| **Erro de sincronização / API** | G4 · aba Vínculos | Falha na chamada ao Clinicorp — mensagem clara, sem travar |

### 5.5 Chamar paciente pelo Monitor de Fila (📝 fora do texto do contrato)

Adicionado em 16/08, revisado em 17/08 depois de duas correções de entendimento importantes — registradas aqui porque mudaram o desenho de raiz.

#### 5.5.1 Duas correções de entendimento

**Primeira correção — onde isso vive.** A primeira versão desta seção desenhava uma tela separada, "Painel do Profissional", com login próprio por dentista. Errado: a clínica **não tem um computador por dentista** — é um único computador interno, compartilhado, que qualquer profissional usa. Não existe "sessão do dentista X" nem necessidade de login separado. A ação de chamar pertence à tela que já existe — o **Monitor de Fila (G2)** — não a uma tela nova.

**Segunda correção — de quem é a chamada.** A chamada é do **paciente**, não de quem está operando o computador no momento. A TV deve mostrar os dados já cadastrados do paciente (nome, sala, profissional — os mesmos que a tabela já resolve via Clinicorp + DE/PARA local), nunca "paciente X chamado por Y". Isso na prática **elimina qualquer necessidade de atribuir a ação a um usuário** — o botão "Chamar" é uma ação genérica da linha, disponível pra quem estiver na tela, sem login separado nenhum.

**O que não muda:** ainda é uma funcionalidade fora do texto assinado do contrato — só um lapso na elaboração, não pedido novo da clínica (contexto completo no histórico desta seção). A recomendação prática continua a mesma: um e-mail curto ou aditivo simples, não uma negociação de valor — protege os dois lados, sem abrir precedente de "qualquer coisa que a clínica sempre esperou entra de graça".

#### 5.5.2 O desenho: dois momentos, não um

O ponto central da solução: **"chamar" e "confirmar que o paciente chegou" são dois momentos diferentes, e só o segundo escreve no Clinicorp.**

Se "chamar" já escrevesse "em atendimento" na hora, e o paciente não aparecesse, "cancelar" precisaria **desfazer** essa escrita — um terceiro tipo de operação (reverter), além de "finalizar" e "confirmar chegada". Separando os dois momentos, "chamar" e "chamar de novo" viram só um gatilho local (toca a TV, dispara som) sem tocar no Clinicorp; só "confirmar chegada" escreve. Isso mantém o sistema em exatamente **duas operações de escrita reais** (finalizar atendimento, confirmar chegada), a mesma disciplina já estabelecida na seção 5.2.1.

**Máquina de estados da linha "aguardando":**

```
Aguardando ──[Chamar]──► Chamando ──[Confirmar chegada]──► Em atendimento
                            │                                (escreve no Clinicorp)
                            ├──[Chamar de novo]──► (continua Chamando, sem escrita)
                            └──[Cancelar]────────► volta pra Aguardando (sem escrita)
```

- **Aguardando:** botão "Chamar" (ícone de megafone) na última coluna, no lugar de onde antes só havia o texto "aguardando".
- **Chamando:** o badge vira preenchido "Chamando…" (mesmo tratamento visual de "Em atendimento", mas com um pulso sutil — reaproveitando a linguagem de movimento discreto já validada na tela institucional de falha prolongada, seção 4.6.1) **com um cronômetro correndo ao lado** (seção 5.5.3). A última coluna ganha dois controles: um botão **"Confirmar" visível e em destaque**, e um menu compacto (⋯) só com as duas exceções.
- **Confirmar chegada:** a única opção que escreve no Clinicorp — a linha passa a ser exatamente o que a seção 5.2.1 já descreve (badge "Em atendimento" + botão "Finalizar").
- **Chamar de novo / Cancelar:** nenhuma escrita, porque nada tinha sido escrito ainda. Ficam agrupadas no menu (⋯), por serem exceções, não o caminho esperado.

#### 5.5.3 Ajuste de 17/08: dar incentivo e clareza pra confirmar

Primeira versão escondia as 3 opções (inclusive "Confirmar chegada") atrás de um "⋯" genérico. Na prática, isso deixava a ação mais importante — e mais esperada — sem nenhum apelo visual: um ícone neutro não convida ninguém a agir. Dois ajustes, com base em pesquisa de UX de filas/tickets:

- **Ação primária visível, só as exceções no menu.** "Confirmar chegada" virou um botão próprio, com destaque visual (preenchido, como os botões primários já usados em "Salvar"/"Entrar"). O menu (⋯) ficou só com "Chamar de novo" e "Cancelar chamada" — as duas exceções, não o caminho esperado. Mesma lógica já confirmada pela pesquisa de tabelas B2B (seção 5.5.5): ação mais comum sempre à vista, secundárias agrupadas.
- **Cronômetro visível no estado "Chamando".** Pesquisa de UX de fila/ticket é direta sobre isso: "os cronômetros só devem pausar quando você está esperando por um retorno externo — tudo o mais continua contando" — a lição sendo que tempo visível e crescente é o que cria a pressão certa pra alguém agir, sem precisar de alarme ou cor de urgência. O cronômetro ao lado do badge "Chamando…" cumpre esse papel: quanto mais tempo passa, mais visível fica que aquilo precisa de resposta.

#### 5.5.4 Ajuste de 17/08: confirmar que "chamar de novo" realmente aconteceu

Problema relatado: ao clicar em "Chamar de novo", nada de perceptível mudava na tela — o badge já estava pulsando desde a primeira chamada, e reiniciar a animação de um elemento que já está em loop contínuo é imperceptível. Resultado: o dentista clica, mas não tem como ter certeza de que uma nova chamada saiu.

Pesquisa de UX confirma o padrão certo pra esse caso — **toast**, não modal nem snackbar com ação: "toasts são ideais pra confirmar ações concluídas, já que são breves e dão feedback instantâneo" e, principalmente, o critério de quando usar cada um: *"se o sistema só precisa de confirmação de status, o toast é a escolha certa pra manter o fluxo"* — exatamente o caso aqui (nenhuma ação de correção é necessária, só a certeza de que funcionou). Um modal ou uma confirmação com botão de "desfazer" seria fricção desproporcional pra uma ação já de baixo risco.

Três reforços combinados, não um só (pesquisa recomenda combinar sinal local + mais visível):

1. **Toast** — "Chamada repetida — [nome do paciente]", canto inferior direito da tela (posição recomendada pela pesquisa pra desktop), some sozinho em ~2,5s (dentro da faixa de mercado de 2–3s pra confirmações rápidas — mensagens de sucesso não devem "ficar por aí" tempo demais).
2. **Cronômetro reinicia do 0:00.** Não é só decorativo: é a prova concreta, sempre visível, de que um novo ciclo de chamada realmente começou — reaproveita o cronômetro que já existia (seção 5.5.3), sem precisar de elemento novo.
3. **Flash único no badge**, distinto do pulso ambiente contínuo — reforço no exato ponto onde o dentista está olhando no instante do clique.

O mesmo toast aparece também no primeiro "Chamar" (não só no "de novo") — pela mesma razão: qualquer disparo de chamada pra TV merece a mesma certeza, não só a repetição.

#### 5.5.5 Por que menu compacto (⋯) pras exceções, não botões extras lado a lado

Pedido explícito: o computador interno da clínica tem tela pequena, e a tabela não pode espremer botões nem competir informação. Pesquisa de mercado (design de tabelas B2B/enterprise) confirma o caminho: agrupar ações de linha pouco frequentes num menu kebab único, em vez de expor múltiplos ícones lado a lado — "se cada linha é um painel de ícones pequenos, o usuário não sabe pra onde olhar". O estado "aguardando" (mais comum) fica com um único botão visível e claro; no estado "chamando", a ação mais provável (confirmar) também fica visível — só as duas exceções vão pro menu. Reduz ruído visual no caso comum, sem esconder a ação certa no caso frequente-mas-transitório.

#### 5.5.6 Ajuste de 17/08 (2ª rodada): bug do pulso, cronômetro "puxadinho", e reordenação por prioridade

Três correções de qualidade, relatadas depois de testar o resultado da seção 5.5.4.

**1. Bug: o flash matava o pulso contínuo.** A implementação do flash (5.5.4) usava `animation: badgeflash .5s` na classe adicionada por clique — mas `animation` é uma propriedade só, não soma valores. Aplicar o flash **substituía inteiro** o pulso contínuo do badge "Chamando" (`animation: badgepulse 1.8s infinite`), e como a classe do flash nunca era removida, o pulso morria de vez no primeiro clique. Correção: (a) um seletor combinado (`.badge--calling.badge--flash`) que declara as duas animações juntas, rodando ao mesmo tempo; (b) a classe do flash agora se remove sozinha ~500ms depois — é um efeito de um tiro só, nunca um estado permanente. Lição: ao empilhar variantes de animação numa mesma propriedade CSS, ou combina os valores explicitamente, ou usa propriedades diferentes — nunca assume que "mais uma classe" soma por conta própria.

**2. Cronômetro parecia "puxadinho".** Antes, o cronômetro era um `<span>` solto do lado de fora do badge, com sua própria tipografia — lia como dois elementos desencontrados, não um. Correção: o cronômetro passou a viver **dentro da própria pílula do badge** ("Chamando… 0:12", tudo no mesmo fundo escuro, mesmo pulso), herdando a cor e participando da mesma animação — agora é uma unidade visual só, não um acréscimo.

**3. A linha precisa ir pro topo ao ser chamada — status manda, espera desempata.** Antes, a tabela só respeitava a ordenação inicial (por tempo de espera) e nunca se atualizava — um paciente recém-chamado podia ficar perdido no meio da lista, arriscando o dentista esquecer de confirmar a chegada dele. Correção: a tabela reordena sozinha a cada mudança de estado, com dois critérios em cascata:
- **1º critério — status, "mais importantes acima":** Chamando (precisa de confirmação agora) → Crítico → Atenção → Normal → Em atendimento (já resolvido, fica embaixo).
- **2º critério, dentro de cada grupo — tempo de espera**, decrescente (mesma lógica de severidade já usada na seção 4.3.1).

A reordenação usa uma animação de deslocamento (técnica FLIP: mede a posição antes, reordena o DOM, anima a diferença) em vez de simplesmente "teletransportar" a linha — mais fácil pro dentista acompanhar visualmente pra onde o paciente foi. Um realce breve na linha reforça ainda mais.

#### 5.5.7 Perguntas técnicas em aberto (independentes da questão contratual)

- A chamada pela nossa tela **substitui** a chamada pelo Clinicorp, ou as duas convivem? Se convivem, o Motor de Integração precisa tratar chamadas vindas de dois lugares sem duplicar nem conflitar.
- Isso entra no MVP de 6 semanas, ou fica documentado como próxima fase logo em seguida? Tecnicamente cabe (é a mesma disciplina de duas escritas já estabelecida) — a decisão é mais sobre cronograma do que sobre viabilidade.
- 📋 **Checklist formal enviado ao Clinicorp em 24/08** (documento separado, `perguntas-clinicorp.md`) — cobre token, rate limit, `status_id` de "em atendimento", e se `/appointment/change_status` aceita a transição "aguardando → em atendimento" vinda de fora do Clinicorp (pergunta #5 da lista, a mais crítica tecnicamente pra essa funcionalidade).

#### 5.5.8 🟡 Confirmado, ainda não construído no wireframe — alerta de novo paciente + protocolo de tempo de espera

Dois itens que a clínica confirmou na reunião de 18/08, mas que ainda não entraram no wireframe (só na pesquisa/recomendação) — registrados aqui pra não se perderem antes da próxima rodada de construção.

**Alerta pro dentista — novo paciente na fila.** Confirmado: "pode seguir com a recomendação". Desenho:
- Badge numerado no item "Monitor de fila" da barra lateral — conta pacientes que entraram em "aguardando" desde a última vez que a tela foi vista, zera ao abrir (evita "cegueira de badge" — pesquisa é enfática que um contador que nunca zera vira ruído).
- Toast reusando o componente já existente ("Novo paciente na fila — [Nome]").
- Som distinto do som da TV — mais discreto, só pro computador interno, nunca broadcast na sala de espera.

**Protocolo de tempo de espera do dentista pelo paciente.** Confirmado, com recomendação seguida: um campo configurável (ex.: 1 min, editável) entra em **Configurações de Alerta (G3)**, mesmo padrão dos campos de minutos que já existem ali pro semáforo. Passado esse tempo sem "Confirmar chegada", a linha ganha a tag **"2ª chamada"** (neutra — não "ausência", que soa como julgamento) e dispara o mesmo alerta acima. **Importante:** o timeout só alerta, nunca dispara uma nova chamada sozinho — quem decide clicar "Chamar de novo" continua sendo humano. É esse timeout que abre o fluxo completo descrito na seção 5.5.9, abaixo.

O Fernando confirmou por telefone uma regra que muda a leitura de "cancelar chamada": **o dentista nunca pode cancelar — só administrativo/recepção.** Isso não é uma restrição de permissão que precisamos construir; é o reconhecimento de que **o cancelamento de verdade (paciente sumiu) nunca deveria estar no nosso software** — quem tira alguém da fila por ausência é sempre a recepção, mudando o status no Clinicorp diretamente, e isso já reflete aqui sozinho (mecanismo que já existe).

**Fluxo completo confirmado:**
1. Chama o paciente → espera o protocolo (seção 5.5.8) → nada → chama de novo → espera de novo → nada.
2. Nesse ponto, quem está na tela liga pra recepção por telefone (fora do nosso sistema) e pede pra tentarem identificar o paciente.
3. Se o paciente realmente foi embora, a recepção muda o status no Clinicorp — o paciente some da nossa fila sozinho, sem nenhum botão nosso envolvido.
4. Se o paciente aparecer depois, a recepção precisa **reinseri-lo com prioridade** — daí a tag de prioridade (seção 5.6).

**Então por que "Cancelar chamada" voltou pra interface?** Motivo diferente do original: é pra **desfazer um clique errado** — o dentista chamou o paciente errado por engano, o atendimento ainda nem começou, nada foi escrito no Clinicorp. Isso é de baixo risco e reversível na hora, então aceitamos manter disponível pra qualquer um usando a tela compartilhada (não construímos um sistema de permissão pra isso — seria complexidade desproporcional ao risco, e o computador é compartilhado mesmo). A distinção importa mais na *documentação* e no *texto da interface* do que na trava técnica: o rótulo e o tooltip deixam claro que essa ação é sobre desfazer, não sobre declarar ausência.

### 5.6 Tag de prioridade

Nasceu do fluxo acima (item 4: paciente reaparece, precisa ser reinserido com prioridade), mas cobre também prioridade prevista em lei.

**Base legal confirmada:** Lei 10.048/2000, com a redação atualizada pela Lei 14.626/2023, define **9 categorias fixas** de atendimento prioritário: pessoa com deficiência, pessoa com TEA (autismo), idoso (60+), gestante, lactante, pessoa com criança de colo, obesidade, mobilidade reduzida, doador de sangue.

**Por que não é campo de texto livre:** pedido explícito da clínica — um campo de justificativa "ia ficar deselegante e desfuncional". A lista legal já é oficial e fechada, então um select curado resolve sem perder nada. Pra prioridade fora da lei (o caso do paciente que reaparece), criamos uma segunda categoria — **"operacional"** — hoje com uma única opção ("Retornou à fila"), mas o componente já está pronto pra crescer se surgir outro motivo operacional legítimo.

**Desenho:**
- Tag compacta na própria célula do paciente (não na coluna de status — prioridade e severidade de espera são conceitos diferentes, seção 5.2.1 já separa isso).
- Clique em "+ prioridade" abre um menu de duas seções (legal / operacional), reusando o componente de select já usado em Salas & Vínculos (SOLID, seção 3.5).
- **Muda a ordenação:** entra acima de Crítico, logo depois de "Chamando" — quem tem prioridade nunca fica perdido no meio da lista (seção 5.5.9).
- **Fica só local — nunca escreve no Clinicorp.** Mantém a régua de duas operações de escrita (finalizar + confirmar chegada) intacta; a prioridade é raciocínio nosso, não do Clinicorp.

### 5.7 Painel Administrativo — Relatórios + Usuários (📝 fora do texto do contrato, novo papel de acesso)

Nasceu de dois pedidos da mesma conversa: tirar as métricas da tela do dentista ("não precisam de métricas… deixa 100% funcional") e ter um lugar só pra dados analíticos, sem virar "Google Analytics". Ganhou um terceiro membro depois: gestão de usuários e permissões (seção 5.7.2).

**A pesquisa trouxe a distinção que resolve isso:** existe "dashboard operacional" (tempo real, pra quem age agora) e "dashboard analítico" (histórico, pra quem decide depois) — são propósitos diferentes, e misturar os dois na mesma tela é exatamente o problema que a clínica pediu pra corrigir.

**Decisão — duas telas separadas, um papel novo:**
- **Monitor de Fila (G2)** perde a faixa de KPIs inteira (Na fila / Em atendimento / Espera média / Em alerta). Sobra só a fila e os controles de ação — puramente operacional, como pedido.
- **"Administrador"** vira uma seção própria na navegação (não mais "Relatórios" sozinho) — primeiro uso de verdade do "controle de acesso por papel" que o Guia já exigia como segurança mínima (seção 6). Dentro dela, dois subitens: **Relatórios** e **Usuários**.

#### 5.7.1 Relatórios

**Desenho — deliberadamente mínimo (pedido explícito: "diminuir o máximo o número de telas e tabelas"):**
- Um filtro de período (Hoje / 7 dias / 30 dias) controla tudo abaixo — não existem duas visões (uma "por dia" e outra "detalhada"); o filtro já resolve as duas necessidades com a mesma tabela.
- Faixa de KPIs (reusa o componente removido do Monitor de Fila): total de atendimentos, espera média, duração média, e um novo — **taxa de "2ª chamada"** — o indicador mais acionável da tela, porque aponta um problema operacional de verdade (comunicação, sala errada, horário), não vaidade de dashboard.
- Uma tabela só, em ordem cronológica: data, paciente, profissional, sala, chegada, chamado, finalizado, espera, duração, nº de chamadas.
- Nenhum gráfico — pesquisa de dashboards operacionais pra pequenas equipes é enfática nisso: gráfico decorativo que "precisa de mouse pra entender" já falhou no propósito.

**Ajuste de 24/08 — profundidade real, não só a pílula mudando de cor.** Na primeira versão, trocar de período só mudava o estado visual do filtro; os números continuavam os mesmos. Corrigido: cada período (Hoje / 7 dias / 30 dias) tem seu próprio conjunto de dados — KPIs, título do painel e linhas da tabela mudam de verdade ao trocar de aba. Pra "7 dias" e "30 dias", a tabela mostra os registros mais recentes com uma nota explícita ("mostrando os 14 mais recentes de 134") em vez de fingir ser uma lista exaustiva — mais honesto do que preencher a tela toda com dado inventado, e mais realista do que um sistema de verdade se comportaria (nenhum relatório de produção renderiza 500 linhas de uma vez sem paginação/scroll).

**Ajuste de 25/08 — faltava a âncora da espera, e a data ficava ambígua.** Duas correções, a partir de pesquisa de UX de tabelas de relatório:

- **Coluna "Chegada" adicionada.** A tabela já mostrava "Espera" (quanto tempo o paciente esperou) sem nunca mostrar *desde quando* — um número solto, sem o ponto de partida que o justifica. "Chegada" é o horário em que o paciente virou "aguardando" no Clinicorp (o mesmo evento que já documentamos como gatilho de entrada na fila, seção 4.3.1) — com ela, dá pra conferir a conta (Chegada + Espera = Chamado) em vez de confiar cegamente no número.
- **Colunas reordenadas pra ordem cronológica.** Data → Paciente/Profissional/Sala (identificação) → Chegada → Chamado → Finalizado (a linha do tempo do atendimento, na ordem em que acontece) → Espera/Duração (métricas derivadas) → Chamadas. Pesquisa de UX de tabelas é direta sobre isso: organizar colunas na lógica do usuário — aqui, a lógica é temporal — reduz carga cognitiva de leitura, em vez de forçar quem lê a montar a linha do tempo de cabeça.
- **Data ganhou mês por extenso e ano** ("24 ago 2026" em vez de "24/08"). Pesquisa de UX/UI sobre formatos de data é enfática: abreviações numéricas com barra (DD/MM) são ambíguas entre culturas e ficam piores ainda em relatórios de período longo — "30 dias" já cruza de agosto pra julho, e sem o ano, arquivos antigos do mesmo relatório ficariam impossíveis de datar com certeza.
- **A tabela ganhou rolagem horizontal, além da vertical já existente** (seção 5.7.4) — com 10 colunas, ela passou a ser mais larga que o espaço disponível na tela; sem isso, a última coluna (Chamadas) ficava cortada e invisível. Mesmo princípio de "não esconder dado, deixar acessível" já seguido em outras partes do sistema.

🟡 **Pendência de retenção (LGPD):** o Guia (seção 6) já previa uma "rotina de expurgo" de dados, mas nunca fixamos prazo. Um histórico por período pede isso agora — sugestão de partida: 90 dias, a confirmar com a clínica.

#### 5.7.2 Usuários — gestão de acesso

Pesquisa de mercado (SaaS B2B, ferramentas de administração) confirma um padrão consistente pra equipes pequenas: **papéis nomeados e simples, nunca uma matriz de permissão granular por funcionalidade** — matriz de checkbox é overhead que só faz sentido quando há dezenas de permissões distintas e times grandes, não é o nosso caso.

**Desenho:**
- Tabela: nome, e-mail, papel (badge), ações (alterar papel / remover acesso).
- **Só dois papéis** — Recepção e Administrador — mapeando exatamente as duas necessidades reais do sistema (operar a fila vs. administrar). Nenhuma checkbox de permissão por tela.
- **"Convidar usuário"**: e-mail + escolha de papel, com a **descrição de cada papel em português claro bem ao lado da opção** — não só "Administrador", mas "Administrador: tudo isso, mais Relatórios e Usuários". Pesquisa é direta sobre isso: descrever o papel em linguagem simples no momento de atribuir evita tanto o admin que super-concede acesso por não entender quanto o usuário travado sem saber por quê.
- **A conta "Recepção" compartilhada continua existindo como uma linha normal da tabela** — é o mesmo login usado no computador compartilhado (seção 5.5.1), não uma exceção; só ganhou uma etiqueta "conta compartilhada" pra deixar isso explícito pra quem olhar a lista depois.
- 🟡 **Regra a reforçar na implementação real** (não simulada no wireframe): nunca permitir remover o último Administrador restante — mercado recomenda travar essa ação especificamente pra evitar uma conta órfã de acesso administrativo.

📝 **Mesma régua de escopo já usada pro "Chamar" (seção 5.5.1):** provavelmente fora do texto assinado do contrato, mesmo tratamento — registro por e-mail/aditivo, não é cobrança automática de valor extra.

#### 5.7.3 Bug corrigido: dropdown fechava ao tentar rolar dentro dele

O menu de prioridade (seção 5.6) tem uma lista rolável (9 categorias legais + operacional). O listener que fecha popovers ao rolar a página usava fase de captura sem checar a origem do evento — rolar *dentro* do próprio menu também contava como "a página rolou" e fechava tudo. Corrigido checando se o evento se originou dentro de um elemento `.select-menu`; se sim, o popover continua aberto. Vale como lição geral: qualquer componente com rolagem interna própria precisa dessa exceção explícita nos listeners globais de scroll.

#### 5.7.4 Monitor de Fila: rolagem interna com cabeçalho fixo

Fila expandida de 5 para 12 pacientes de exemplo, especificamente pra testar o comportamento com volume real — a tela virou "puramente ação médica" (sem KPIs, seção 5.7) e precisa aguentar uma fila cheia sem quebrar o layout. A tabela agora tem altura máxima com rolagem própria (`overflow-y`) e cabeçalho fixo (`position: sticky`) — quem rola pra baixo nunca perde de vista qual coluna é qual. Mesmo padrão vale, em tese, pra qualquer tabela do sistema que possa crescer (Relatórios já usa o mesmo componente, seção 5.7.1).

#### 5.7.5 Terceiro papel: Profissional — e uma tela sem sidebar

Ajuste de 24/08. Até aqui só existiam dois papéis (Administrador, Recepção). A clínica confirmou um terceiro: **Profissional**, o mais restrito dos três — só acessa a fila, e nem tudo dentro dela: não pode usar "Cancelar chamada" (regra já registrada na seção 5.5.9, agora com um papel de verdade pra aplicá-la).

**Consequência de design que não estava óbvia até desenhar:** se o profissional só acessa UM destino (a fila), uma barra lateral de navegação não serve pra nada — não há entre o quê navegar. Em vez de mostrar uma sidebar com um item só (o que teria sido o caminho mais fácil, mas deixaria espaço vertical desperdiçado e um elemento de UI sem função real), a tela do profissional **não tem sidebar nenhuma**. Logo e menu de usuário — que moravam na barra lateral — migraram pro topo:

```
[logo]  Fila                          Atualizado há 4s  [Dr. Carlos Menezes ⌄]
```

**O que muda tecnicamente, não só visualmente:** o menu "⋯" de cada chamada agora verifica em qual tela está (`#screen-g-queue-profissional` ou não) antes de decidir se mostra "Cancelar chamada" — a mesma função que já existia, só com uma condição a mais. Continua sendo a mesma tabela, a mesma lógica de prioridade, a mesma reordenação por status — o profissional não usa uma cópia simplificada da funcionalidade, usa exatamente a mesma, só com uma opção a menos no menu e sem elementos de navegação que não servem pro papel dele.

🟡 Nota técnica: pra essa segunda tabela funcionar de verdade sem duplicar toda a lógica JS, generalizamos a função de reordenação (antes presa a um único `id` fixo) pra funcionar com qualquer tabela de fila que exista na tela ativa. Detalhe de implementação, mas registrado porque é o tipo de decisão que vale a pena replicar se mais telas de fila aparecerem depois (ex.: um segundo monitor em outra sala).

#### 5.7.6 Configurações de Alerta e Salas & Vínculos viram admin-only

Ajuste de 24/08. Até aqui, "Configurações de Alerta" (G3) e "Salas & Vínculos" (G4) apareciam soltas na barra lateral, junto de "Monitor de Fila" — qualquer papel logado via essa tela via as três. A clínica decidiu: só Administrador deveria poder mexer nisso (limiares de alerta e o de-para sala↔profissional são configuração estrutural, não operação do dia a dia).

**Mudança:** as duas entraram pro grupo "Administrador" da barra lateral, junto de Relatórios e Usuários — que já eram admin-only desde a seção 5.7. A barra lateral de quem só tem papel Recepção ou Profissional agora mostra, na prática, só "Monitor de Fila" (Profissional, além disso, nem tem barra lateral — seção 5.7.5).

⚠️ Isso foi uma migração mecânica em 10 telas diferentes (toda tela com barra lateral duplica esse bloco de navegação, decisão de arquitetura antiga, seção 3). Vale registrar o que deu errado no processo, porque é um risco real de qualquer refatoração assim: três telas (`g-queue-empty`, `g-queue-loading`, `g-rooms-empty`) ficaram temporariamente **sem nenhum item marcado como ativo** na barra lateral — a lógica automática de detecção de item ativo não reconheceu que essas variantes deveriam herdar o estado do item "macro" (Monitor de Fila / Salas) do qual são apenas um sub-estado. Corrigido manualmente depois de validar todas as 17 telas uma por uma — checagem que devia ser rotina sempre que a navegação for tocada, não só desta vez.

#### 5.7.7 Filtro por dentista nos Relatórios

Ajuste de 24/08. Pesquisa de mercado confirma o padrão pra esse caso específico: **dropdown**, não abas nem checkboxes — a regra geral é dropdown pra listas curtas e fixas de categorias (aqui, só 3 profissionais), reservando abas/checkboxes pra quando há necessidade de comparar múltiplos valores ao mesmo tempo, que não é o nosso caso.

**Combina com o filtro de período já existente (seção 5.7.1), não substitui.** Os dois filtram juntos — período define a janela de tempo, dentista define de quem. Implementação:
- **"Todos os dentistas"** (padrão): usa os números oficiais do período inteiro, os mesmos hardcoded já documentados na seção 5.7.1.
- **Um dentista específico**: os KPIs são recalculados **a partir da amostra já carregada na tela**, nunca inventando um número que não temos. Pra "Hoje" isso é exato (mostra os 9 registros reais do dia). Pra "7 dias"/"30 dias", como só uma amostra é carregada (seção 5.7.1), o texto abaixo do título deixa isso explícito: *"Dr. Carlos Menezes — 7 registros (da amostra carregada, não do período inteiro)"* — mais honesto do que fingir precisão que a tela não tem.

#### 5.7.8 Ajuste de nomenclatura (25/08): "Médico" nunca devia estar na interface

Correção da clínica: o termo certo pra pessoa é **"Dentista"**, não "Médico" — a clínica é odontológica, e "médico" é uma categoria profissional diferente no Brasil (CRM vs. CRO). Junto disso, o **papel de acesso** (seção 5.7.5) foi renomeado de "Médico" pra **"Profissional"** — deliberadamente mais genérico, pra caber tanto uma conta individual (um dentista específico) quanto uma conta compartilhada, sem prender o nome do papel a uma categoria profissional que pode nem sempre corresponder a quem está logado.

**Duas palavras, dois papéis semânticos diferentes, nunca confundir:**
- **"Dentista"** — usado sempre que o texto se refere à pessoa real ou ao conceito genérico do profissional que atende (nome exibido na TV, coluna "Profissional" das tabelas, filtro de Relatórios, texto explicando o que alguém faz na tela).
- **"Profissional"** — usado exclusivamente como nome do **papel de acesso** (badge em Usuários, opção no formulário de convite, nome da tela sem sidebar) — é sobre permissão, não sobre identidade profissional.

🟡 **Não renomeado de propósito:** o campo técnico `SalaDoMedico` (tabela de vínculo sala↔profissional, seções 3.2 e 5.5) é um nome de schema definido no Guia do Projeto original — renomear aqui, sem atualizar a fonte, criaria descompasso entre os dois documentos. Fica registrado como pendência pra próxima revisão do Guia, não como inconsistência nossa.

#### 5.7.9 Sidebar componentizada (25/08): uma fonte só, nunca remontada por tela

**O problema relatado:** a barra lateral tinha usuários diferentes dependendo da tela — "Recepção" nas telas operacionais, "Alessandro Milagres" nas telas de admin — porque o HTML de cada uma das 10 telas com sidebar era escrito (e mantido) separadamente. Sintoma concreto do problema: um bug real de CSS, achado ao investigar — o avatar circular (`.avatar`) não tinha proteção contra compressão em contexto flex, e no rodapé estreito da sidebar (212px) ficava achatado (17×28px medido, devia ser 28×28). Um nome mais longo do que "Recepção" deixaria isso ainda mais visível — exatamente o sintoma relatado.

**Correção — duas partes:**
1. **CSS:** `.avatar` ganhou `flex: 0 0 28px`, travando o tamanho não importa o contexto flex ao redor. Corrige o achatamento em qualquer lugar que o componente apareça, não só na sidebar.
2. **Componentização de verdade:** em vez de 10 blocos de HTML mantidos manualmente (a causa raiz da divergência), a navegação e o rodapé de usuário passaram a ser gerados por **uma função JavaScript só**, a partir de **uma única fonte de dados** (`SIDEBAR_USER`, `SIDEBAR_NAV`). Na carga da página, essa função varre todas as telas com sidebar padrão e sobrescreve o conteúdo de cada uma — garantindo que usuário, papel, avatar e item ativo sejam sempre gerados do mesmo lugar, nunca redigitados tela por tela. Se algo precisar mudar (o usuário exibido, um item de menu), muda em um ponto só e se propaga sozinho pras 10 telas.

**Usuário padrão do wireframe: Richard Moraes.** Mesmo estilo visual que já existia pro Alessandro Milagres (avatar com iniciais + nome + papel abaixo) — só a pessoa mudou. Como consequência de manter a "Usuários" (seção 5.7.2) coerente com quem está logado, Alessandro Milagres — contato real da clínica — continua na lista como administrador normal (com botão de remover, já que não é mais "quem está logado"), e Richard Moraes assumiu a primeira linha (sem botão de remover, mesma regra da seção 5.7.2) com e-mail de domínio da agência (`@coldwing.com.br`, não `@qualimplan.com.br`) — reflete que é acesso administrativo externo, não conta de funcionário da clínica.

**Um detalhe que só apareceu ao testar:** o popover do menu de usuário (que abre ao clicar no rodapé) é um elemento só, reaproveitado em todo lugar que tem gatilho `data-usermenu` — inclusive a tela do papel Profissional (seção 5.7.5), que mostra "Dr. Carlos Menezes" no topo, não "Richard Moraes". Se o popover sempre mostrasse o usuário fixo da sidebar, ficaria incoerente nessa tela. Corrigido: o popover lê o nome e papel **do próprio gatilho clicado** (não de um valor fixo), então em cada contexto ele mostra exatamente quem está exibido ali — sidebar padrão mostra Richard Moraes, tela sem sidebar mostra o profissional daquela sessão.

## 5.8 Alerta ao dentista + protocolo de tempo de espera (26/08) — finalmente construído

Duas funcionalidades que já estavam confirmadas pela clínica desde a seção 5.5.8, mas nunca tinham virado tela de verdade. Pesquisa desta rodada trouxe dois princípios que definiram o desenho:

- **Badge que não zera sozinho vira ruído.** Confirmado em múltiplas fontes de UX de notificação — um contador que o usuário aprende a ignorar é pior que não ter contador nenhum. Por isso o badge da barra lateral **precisa zerar ao abrir a tela que ele aponta**, não só com o tempo ou manualmente.
- **Alerta baseado em tempo só funciona se disparar sozinho e apontar pro dono certo.** Confirmado em pesquisa de escalonamento de SLA (tickets de suporte): regras de tempo que dependem de alguém ficar olhando o relógio falham silenciosamente. A automação precisa notificar o responsável certo, não uma caixa de entrada genérica.

**Desenho, reaproveitando componentes que já existiam:**
- **Badge numerado no item "Monitor de fila" da barra lateral** — soma toda vez que (a) um paciente novo simula entrar na fila ou (b) uma chamada passa do tempo configurado sem confirmação. Zera sozinho ao abrir o Monitor de Fila, nunca por um botão de "marcar como lido" separado.
- **Toast** (mesmo componente já usado pra "Chamada disparada", seção 5.5.4) — reforça o badge com uma mensagem específica: "Novo paciente na fila — [nome]" ou "Sem resposta — [nome]".
- **Tag "2ª chamada sugerida"** — aparece sozinha na linha da tabela quando o cronômetro (o mesmo já usado desde a seção 5.5.3) passa do limite configurado. Tom deliberadamente neutro ("sugerida", não "atrasada" ou "sem resposta" na própria tag) — mesma régua de linguagem não-acusatória já estabelecida pra "2ª chamada" desde a primeira vez que o conceito apareceu.
- **Campo de configuração novo em Configurações de Alerta (G3)** — "Sugerir nova chamada depois de [1] minuto sem confirmar chegada", mesmo padrão visual dos campos de minuto que já existem ali pro semáforo (Atenção/Crítico). Painel próprio ("Alertas ao dentista"), separado do painel do semáforo — são conceitos diferentes (um é sobre o que a TV mostra, o outro é sobre avisar a equipe).
- 🟡 **No wireframe, o limite real está acelerado** (8 segundos, não 1 minuto) — decisão deliberada pra caber numa demonstração ao vivo sem exigir esperar um minuto inteiro parado. O valor mostrado no campo de configuração (1 minuto) é o que o produto real usaria; só o comportamento de demonstração está com o relógio adiantado, anotado explicitamente na tela pra não confundir quem estiver revisando.
- **O timeout nunca dispara uma chamada sozinho** — só alerta. Quem decide clicar "Chamar de novo" continua sendo humano, mesmo princípio já registrado quando essa funcionalidade foi só recomendação (seção 5.5.8).

---

## 5.9 Fechamento do pacote (26/08) — auditoria final antes do design visual

Última rodada antes de passar pro design de alta fidelidade. Três frentes: dois ajustes de conteúdo, uma auditoria de variantes faltando, e uma reorganização de navegação.

### 5.9.1 Apelido de exemplo — duas rodadas até acertar

**1ª rodada:** "Dona Maria" corrigida pra "Cida" — trocamos uma forma de tratamento (que ninguém cadastraria como apelido) por um apelido carinhoso de verdade, derivado de "Aparecida" (nome do meio de Maria Aparecida Gonçalves).

**2ª rodada, ainda no mesmo dia:** "Cida" também não ficou bom — pra alguém ver a tela sem contexto, não é óbvio que "Cida" vem de "Aparecida" sem explicar a origem, o que atrapalha numa apresentação ao vivo. **Decisão final: apelido no formato primeiro + último nome**, não apelido carinhoso/diminutivo. "Maria Gonçalves" em vez de "Cida" — a ligação com o nome completo é imediata, sem precisar de contexto cultural extra, e ainda assim mais curto que "Maria Aparecida Gonçalves".

**Isso criou uma segunda régua que convive com a primeira, e vale documentar a diferença:**
- **Apelido** (quando existe no Clinicorp) → primeiro + **último** nome. Ex.: Maria Aparecida Gonçalves → "Maria Gonçalves"; Beatriz Santos Lima → "Beatriz Lima".
- **Fallback** (quando não existe apelido) → primeiro + **segundo** nome, nunca o sobrenome. Ex.: Ricardo Almeida Souza → "Ricardo Almeida"; João Pedro Alves → "João Pedro".

São visualmente parecidos mas tecnicamente diferentes — vale a pena ter isso claro numa eventual reunião, porque alguém vai notar a diferença entre "Maria Gonçalves" (sobrenome aparece) e "Ricardo Almeida" (sobrenome não aparece) e vai perguntar por quê. A resposta é essa: um é dado real cadastrado (apelido), o outro é uma regra nossa de fallback pensada especificamente pra nunca expor o sobrenome quando não há escolha melhor.

A lista "Aguardando" da TV segue os mesmos exemplos, mantendo consistência entre as duas telas — Beatriz Lima, João Pedro, Luiza Nogueira, Ricardo Almeida, Maria Gonçalves aparecem igual nos dois lugares em que cada paciente é citado. Único caso especial: **Luiza Nogueira** só tem dois nomes cadastrados (sem nome do meio) — primeiro+último já é o nome completo dela, não há como reduzir mais. Isso é esperado, não um bug.

Importante, sem mudança desde a rodada anterior: **só a TV segue essa régua** — a tabela interna do Monitor de Fila continua com nome completo, porque quem opera precisa de identificação real pra confirmar o paciente certo.

### 5.9.2 Gap real encontrado: "Erro de sincronização" nunca foi construído

Auditoria contra a tabela de estados planejados desde o início do projeto (seção 5.4 mais acima neste doc) achou uma promessa nunca cumprida: **"Erro de sincronização / API"**, registrada por escrito desde a primeira sessão como estado necessário em G4 (Vínculos), nunca virou tela. Corrigido — e estendido também pro G2 (Monitor de Fila), que depende do mesmo tipo de sincronização e corria o mesmo risco:

- **G2 · Erro de sincronização**: mensagem específica (hora da última tentativa confirmada + número de tentativas), nunca um "algo deu errado" genérico. A fila continua na tela com a última versão conhecida — mesma régua de resiliência já estabelecida pra TV (seção 4.6.1): informação nunca some por causa de falha técnica. A tabela continua interativa (chamar, finalizar), porque escrita no Clinicorp é independente da leitura que falhou.
- **G4 · Vínculos · erro de sincronização**: mesma lógica, com uma nuance própria — a falha é só na *leitura* de profissionais novos vindos do Clinicorp; o vínculo sala↔profissional em si (`SalaDoMedico`) é dado nosso, local, já salvo, e continua editável. A tela deixa essa distinção explícita, porque são duas fontes de dado diferentes falhando (ou não) de forma independente.

Essas duas telas fecham exatamente o que a seção 5.4 já previa desde o dia 1 e nunca tinha sido cumprido — não é funcionalidade nova, é dívida de escopo original sendo paga.

### 5.9.3 Reorganização: "Painel de Gestão" era três painéis, virou um

**O problema:** nossa própria ferramenta de navegação (não o produto) tinha três grupos de topo — "Painel de Gestão", "Administrador", "Papel Profissional" — como se fossem três superfícies diferentes. Não são: são a mesma URL (`gestao.qualimplan.app`), o mesmo login, a mesma sidebar componentizada (seção 5.7.9) — só muda o que cada papel vê dentro dela. Ter três grupos de navegação sugeria uma arquitetura de produto que não existe.

**Correção:** um grupo só, "Painel de Gestão · 6 telas", com G1 a G6 em sequência:
- G1 Login, G2 Monitor de Fila, G3 Configurações de Alerta, G4 Salas & Vínculos — o núcleo contratado.
- G5 Relatórios, G6 Usuários — mesma numeração sequencial, na mesma hierarquia visual das demais (sem separador, sem tratamento diferente — ver seção 5.9.4).

**A tela "Papel Profissional" também mudou de lugar** — não é mais um grupo à parte, virou a 5ª variante de G2 (Monitor de Fila), ao lado de Padrão/Vazia/Carregando/Erro. Faz mais sentido conceitualmente: é a mesma tela, o mesmo dado, só com uma chrome diferente pra um papel diferente — exatamente a definição de "variante", não de tela nova.

### 5.9.4 Marcações de "fora do contrato" removidas do wireframe (26/08, 3ª rodada)

O wireframe estava marcado em vários pontos com avisos tipo "📝 fora do texto do contrato — formalizar por aditivo/e-mail" — legítimos durante a construção (ajudavam a não perder de vista o que precisava de confirmação formal com a clínica), mas na entrega final não fazem sentido: **tudo que está no wireframe vai ser entregue**, então marcar parte dele como "talvez não contratado" dentro do próprio artefato de entrega é confuso pra quem for receber.

**Removido do wireframe:**
- O separador visual + aviso na navegação, entre G4 e G5.
- O comentário/nota na tela de Relatórios sobre formalizar por aditivo.
- A menção "Fora do texto do contrato" na descrição da tela de Relatórios (breadcrumb superior).
- O sufixo "· Admin" no crumb de G5/G6 — não tinha função além de sinalizar a mesma distinção contratual; sem ela, G5 e G6 usam exatamente o mesmo formato de crumb que G1–G4 (`Painel de Gestão · G5`, não `Painel de Gestão · G5 · Admin`).

**Mantido neste documento** (fundações), que é registro interno de processo, não entregável de design: o histórico de que G5/G6/Chamar/Prioridade nasceram fora do texto assinado do contrato continua nas seções 5.5–5.7 e na lista de pendências (seção 10.1) — essa informação ainda importa pra conversa comercial com a clínica, só não pertence mais ao artefato visual que vai ser repassado pro design.

### 5.9.5 Bug real: tela de Login (padrão) estava quebrada

Achado ao revisar antes de fechar o pacote — a variante "Padrão" do Login (G1) tinha perdido os campos de e-mail/senha e o botão "Entrar" em algum ponto anterior do processo (provavelmente uma edição de texto que consumiu conteúdo além do pretendido — risco conhecido de fazer muitas substituições de texto em sequência num arquivo grande). A variante "Erro de credenciais", ao lado, estava íntegra e serviu de referência pra reconstruir a padrão corretamente. Testado depois: o botão "Entrar" navega de verdade pro Monitor de Fila.

**Lição registrada:** vale a pena rodar a validação estrutural (balanceamento de tags, pins ⇄ legenda) depois de qualquer edição de texto em lote, não só depois de mudanças de HTML/JS — foi exatamente esse tipo de edição que causou o problema, e só a validação pegou.

### 5.9.6 Convite sem SMTP — link pra copiar, não e-mail automático

**Decisão do cliente:** não vamos configurar um servidor de e-mail (SMTP) só pra enviar convites — foge do escopo do projeto pra uma clínica pequena. Em vez disso, o fluxo de "Convidar usuário" (G6) muda de "enviar e-mail" pra "gerar link pra copiar":

1. Admin preenche e-mail + papel, clica em "Gerar link de convite" (era "Enviar convite" — o rótulo mudou pra não prometer um envio que não existe).
2. O sistema gera um link único (`/convite/{token}`) e mostra dentro do próprio modal, com um botão "Copiar" — feedback visual rápido ("Copiado", com ícone de check) confirma a ação, sem precisar sair da tela.
3. Admin manda esse link por conta própria — WhatsApp, e-mail pessoal, o que for mais rápido. O texto do modal é direto sobre isso: não finge que um e-mail foi enviado quando não foi.
4. A pessoa convidada entra na lista de Usuários imediatamente, mas com um badge novo — **"Convite pendente"** — em vez do papel real. Só quando ela mesma completa o cadastro (nova tela, seção seguinte) é que o papel vira efetivo.

**Nova tela: "Cadastro por convite"** (G1, 3ª variante) — a página que abre quando alguém clica no link copiado. Decisões de desenho:
- **Contexto de quem convidou + pra qual papel, logo no topo** ("Richard Moraes te convidou pra acessar como Recepção") — evita o link parecer phishing pra quem abre sem esperar.
- **E-mail travado, não editável** — foi definido por quem convidou; permitir editar aqui criaria uma conta com e-mail diferente do vínculo original do convite. Se estiver errado, o caminho correto é cancelar o convite e gerar outro, não editar na hora.
- Campos de cadastro mínimos: nome completo, senha, confirmar senha — sem inventar campos que a clínica não pediu.
- Agrupada dentro de G1 (Login) na navegação, não como grupo próprio — é conceitualmente a mesma família de telas "entrada sem sessão", só que pra quem nunca teve conta em vez de quem já tem.

🟡 **Pendência de produto pra próxima etapa** (não é decisão de design, é comportamento de backend): prazo de validade do link (mostramos "7 dias" como texto, mas a regra de expiração de verdade — o que acontece se alguém abrir um link vencido — ainda não foi desenhada). Registrar como próxima pergunta, não como lacuna do wireframe.

---

## 6. Iconografia

**Decisão: Lucide Icons** (MIT, `lucide-react` no ecossistema React/Next.js).

**Método.** Os dois candidatos de mercado mais fortes — Lucide e Tabler — compartilham a mesma geometria técnica (grid 24×24, traço 2px, `stroke-linecap: round`, `stroke-linejoin: round`), confirmada direto no SVG bruto de ambos. Isso significa que o desempate não estava na régua técnica, e sim na curadoria: renderizamos os dois lado a lado para os ícones do nosso set mínimo.

**Por quê Lucide:**
- **Mais quente, mais reconhecível para o nosso caso.** O ícone de "profissional" da Lucide é um estetoscópio; o da Tabler é uma cruz médica — mais frio, mais "hospital". O de "sala" da Lucide já vem com a porta aberta; o da Tabler é uma porta fechada genérica. Bate direto com o princípio 3 do doc (calor, não frieza clínica).
- **Fit de ecossistema.** É o padrão de fato do shadcn/ui e do ecossistema Next.js/React em 2026 (Guia, seção 7 — stack Next.js), o que reduz fricção quando o desenvolvimento começar.
- **Cobertura suficiente sem excesso.** As ~1.500 famílias da Lucide cobrem folgadamente o nosso set mínimo de 10 conceitos — o tamanho menor da biblioteca (vs. ~5.900 da Tabler) não é limitação aqui, é foco: menos ícones "quase iguais" pra escolher errado.

🟡 **Ícone customizado necessário:** "semáforo on/off" não existe como ícone padrão em nenhuma biblioteca — não é um conceito comum de UI. Desenhar como extensão simples seguindo a mesma grade da Lucide (24×24, traço 2px, cantos arredondados): três círculos empilhados é suficiente e mantém consistência.

- **Cor:** teal (`#00778B`) como cor padrão de ícone; laranja reservado a destaque/chamada.
- **Tamanho:** escala padrão da Lucide (16/20/24px), alinhada à escala tipográfica (seção 2.3).
- **Set mínimo mapeado:** sala/porta → `door-open`, profissional → `stethoscope`, tempo/espera → `clock`, alerta → `bell`, sincronizar → `refresh-cw`, remover/contingência → `trash-2`, som → `volume-2`/`volume-x`, semáforo → customizado (acima).
- **Tom:** humano, não hospitalar (princípio 3) — já verificado na curadoria acima.

---

## 7. Acessibilidade

### 7.1 Regra de ouro do semáforo — cor nunca sozinha

Requisito WCAG 1.4.1 (Uso da Cor): informação não pode ser transmitida **só** por cor. Todo estado de alerta (Médio / Crítico) e o semáforo de espera **devem** ter um segundo canal redundante, independente de cor. Escolher pelo menos um:

- **Forma distinta por estado** (padrão consagrado): círculo = normal, quadrado/triângulo = atenção/crítico.
- **Ícone** reforçando o significado (✓ / ⚠ / ✕).
- **Rótulo textual** ("Normal" / "Atenção" / "Crítico") — no Painel de Gestão, praticamente obrigatório.

Isso não é só conformidade: um daltônico (ou qualquer pessoa vendo a TV sob reflexo de sol) precisa entender o estado sem depender do matiz.

### 7.2 Contraste

Ver 2.2. AA (4.5:1) no Gestão; mirar AAA (7:1) na TV. Verificar especialmente o laranja e o teal.

### 7.3 Legibilidade à distância

Ver 4.2 — é acessibilidade de fato: idosos e pessoas com baixa acuidade visual são público real de sala de espera de clínica.

### 7.4 Redundância visual + sonora

A chamada combina **destaque visual e som** (Guia 2.2). Isso já é bom para acessibilidade: quem não ouve vê, quem não olha na hora ouve. Preservar essa redundância — não deixar a chamada depender só do som.

---

## 8. Diretriz sonora

Base: boas práticas de UX sound design (pesquisa de mercado). O som aqui tem **uma função única**: anunciar uma nova chamada. Não é uma biblioteca de feedback de clique/erro.

### 8.1 Princípios aplicados

- **Estratégia antes do som.** Objetivo declarado: *chamar atenção para uma nova chamada, sem gerar ansiedade*. Cada som serve a uma função com significado — nada de som decorativo.
- **Curto e discreto.** Referência de UX: um som não deve durar muito além da animação que acompanha (~0,3s de folga). Nada de toque longo ou repetitivo — a sala de espera já é um ambiente de repetição (várias chamadas/hora); som longo vira fadiga e ansiedade.
- **Perceptível, não alarmante.** Deve cortar o ruído da recepção sem soar como alarme. Tom acolhedor coerente com a marca (princípio 3).
- **Testar no hardware real.** Vai tocar em alto-falante de TV comum, que corta graves e reforça médios/agudos. Testar no dispositivo real da clínica, não em fone. Crítico porque não controlamos o hardware (Guia, seção 3).
- **Consistência de timbre.** Se um dia houver som distinto para alerta crítico vs. chamada normal, devem compartilhar timbre/instrumentação, variando só o suficiente para diferenciar a função.
- **Configurável.** Contrato prevê "textos do alerta sonoro" por cliente (Guia, seção 8) → o som é token da aplicação. Prever, no Painel de Gestão, controle de som on/off e possivelmente escolha/volume.

### 8.2 Especificação inicial do som de chamada

🟡 Arquivo final a escolher/produzir. Requisitos: 1–2 notas, duração curta (~0,5–1s), timbre suave (sino/marimba/chime, não buzzer), acompanha a transição visual da chamada (seção 4.4), volume ajustável no Gestão.

---

## 9. Entregáveis para a reunião de terça (18/08)

Prioridade imediata (Guia, checklist item 14): **wireframe/mockup do Painel de TV com a paleta institucional.** Este documento é a fundação que sustenta esse mockup. Para a reunião, o mockup deve mostrar, no mínimo:

- Estado "chamada em destaque" com nome completo do paciente, sala e dentista, na paleta Qualimplan e em **Quicksand** (nome/cabeçalho) + **Poppins** (números de espera).
- Estado "dentista sem sala vinculada" (prova o princípio de resiliência).
- Semáforo de espera **com** redundância de acessibilidade (prova que pensamos além da cor).
- Uso correto de laranja (destaque) e teal (estrutura).

E levar, explicitamente, as **perguntas em aberto** da seção 10 — a reunião é a oportunidade de fechar as que dependem da clínica.

---

## 10. Decisões pendentes e perguntas para a clínica

### 10.1 Depende da clínica/agência

- 📝 **Chamar paciente, Prioridade, Relatórios e Usuários ficaram fora do texto do contrato** (5.5, 5.6, 5.7) — mesma régua: já eram esperados como parte do produto (não pedido novo da clínica), ação é um e-mail curto/aditivo confirmando o entendimento, não negociação de valor.
- ~~Exibição do nome completo do paciente na TV~~ **Resolvida em 25/08** — a hierarquia apelido → primeiro+segundo nome → nunca nome completo (seção 4.3) substitui a exibição de nome completo, então a ressalva de LGPD original não se aplica mais como estava registrada.
- **Lista "Aguardando" ainda mostra nome sem passar pela hierarquia de privacidade** (4.3.1) — pergunta em aberto pra próxima conversa com a clínica: o mesmo cuidado de privacidade que vale na chamada deveria valer também pra quem ainda não foi chamado?
- ~~Retenção de dados do Relatórios~~ **Confirmada em 26/08 — 90 dias.** Fecha a "rotina de expurgo" que o Guia já previa (seção 6) sem prazo definido.
- **Preferência de identidade** — validar se as aproximações hex das cores estão adequadas aos olhos da clínica.
- **Tipografia — apresentar, não perguntar** (2.3) — o par Quicksand + Poppins está decidido e fundamentado; levar à reunião como proposta pronta. Só reabrir se a clínica insistir numa fonte proprietária específica do manual completo.

### 10.2 Decisão interna de design (podemos fechar nós)

- **Cores semânticas do semáforo** (2.1) — aprovar a paleta verde/âmbar/vermelho proposta e o contraste final.
- **Escala tipográfica final** (2.3) — valores exatos de tamanho/peso a confirmar no mockup (a família já está decidida: Quicksand + Poppins).
- **Espaçamento/raio/elevação finais** (2.4) — confirmar no mockup.
- **Som de chamada** (8.2) — escolher/produzir o arquivo e testar no hardware.
- **Wireframe mobile/tablet do Painel de Gestão** (3.4) — próxima rodada, fora do escopo de terça.
- **Limite exato para "falha prolongada"** (4.6.1) — 🟡 depende do valor final do ciclo de sincronização (Guia, seção 4.3), que por sua vez depende do rate limit do Clinicorp.
- **Faixas/movimento ambiente nos estados normais da TV** (4.4.1) — ideia registrada, não desenhada; retomar no mockup de alta fidelidade.
- **Foto do paciente na TV** — resolvida em 25/08 (seção 4.3.2). Endpoint exato ainda depende do Clinicorp (seção 10.3).
- ~~Alerta de novo paciente na fila + protocolo de tempo de espera do dentista~~ **Resolvida em 26/08** (seção 5.8) — badge + toast + tag "2ª chamada sugerida", disparo automático sem exigir vigilância humana.
- **Trava de "não remover o último Administrador"** (5.7.2) — regra de produto registrada, precisa entrar na implementação real (o wireframe não simula essa validação).
- ~~Cada dentista usa dispositivo próprio, ou o mesmo computador da recepção?~~ **Confirmado em 26/08 — os dois convivem.** Dentista pode logar com conta individual (papel Profissional, já existe em Usuários) *e* existe um computador comum com login colaborativo (mesmo conceito da conta "Recepção" compartilhada, seção 5.7.2 — usada por qualquer um da equipe, não só recepcionistas). Nenhuma mudança estrutural necessária — a arquitetura já suportava os dois casos, só faltava confirmar.
- ❌ **Gestão de conteúdo/mídia pras telas de erro e fila vazia** — decisão da clínica em 26/08: fica de fora do sistema (não é "depois aprimoramos", é definitivamente fora do escopo). Removido da lista de próximas rodadas.
- ❌ **Modo demo** — decisão da clínica em 26/08: não será necessário. Note-se que isso diverge do que o Guia (Cláusula 15) previa originalmente; vale um registro formal (e-mail) confirmando que a clínica está ciente de que prints de portfólio vão precisar de outro cuidado pra não expor dado real, já que o mecanismo que resolveria isso automaticamente não vai existir.

> ✅ **Resolvidas nesta rodada (26/08, 11ª sessão):** tela de Login corrigida — variante padrão estava com campos e botão faltando, reconstruída (5.9.5); fluxo de convite reescrito de "enviar e-mail" pra "gerar link pra copiar", sem SMTP (5.9.6); badge "Convite pendente" novo, estado real até a pessoa completar o próprio cadastro; nova tela "Cadastro por convite" (G1, 3ª variante).

> ✅ **Resolvidas nesta rodada (26/08, 10ª sessão):** marcações de "fora do texto do contrato" removidas do wireframe entregável — mantidas só neste doc interno (5.9.4); apelidos de exemplo trocados de diminutivos (Cida, Bia, Lu) pra primeiro+último nome, mais legível numa apresentação sem precisar de contexto cultural extra (5.9.1, revisão); G5/G6 com crumb padronizado, mesmo formato de G1–G4.

> ✅ **Resolvidas nesta rodada (26/08, 9ª sessão — fechamento do pacote):** apelido de exemplo trocado de "Dona Maria" pra "Cida", realista de verdade (5.9.1); lista "Aguardando" da TV passou a seguir a hierarquia apelido → primeiro+segundo nome, pendência que estava aberta desde 25/08 (5.9.1); gap real encontrado e corrigido — "Erro de sincronização" nunca tinha sido construído em G2 nem G4, apesar de planejado desde a primeira sessão (5.9.2); navegação da ferramenta reorganizada — "Painel de Gestão", "Administrador" e "Papel Profissional" eram três grupos, viraram um só, refletindo que é uma superfície de produto só (5.9.3); "Papel Profissional" deixou de ser tela isolada e virou a 5ª variante de G2, onde conceitualmente pertence.

> ✅ **Resolvidas nesta rodada (26/08, 8ª sessão):** alerta ao dentista (badge + toast) e protocolo de tempo de espera com tag "2ª chamada sugerida" automática, construídos de verdade (5.8); retenção do Relatórios fechada em 90 dias; modelo de login confirmado (individual + colaborativo, sem mudança estrutural); gestão de conteúdo/mídia removida do escopo; modo demo descartado.

> ✅ **Resolvidas nesta rodada (25/08, 7ª sessão):** foto do paciente na chamada em destaque, só no momento da chamada, com fallback pra iniciais quando o Clinicorp não tem foto (4.3.2); hierarquia apelido → primeiro+segundo nome → nunca nome completo, finalmente implementada na TV (4.3, estava só decidida em teoria desde sessão anterior); anotação desatualizada corrigida (a antiga dizia "nome completo, ressalva a validar" — não refletia mais a decisão real).

> ✅ **Resolvidas nesta rodada (25/08, 6ª sessão):** sidebar componentizada — uma função/fonte de dados só, gerando a navegação e o rodapé de usuário nas 10 telas que têm sidebar (5.7.9); bug de CSS do avatar achatado corrigido (`.avatar` agora protegido contra compressão flex, em qualquer contexto); usuário padrão do wireframe unificado como Richard Moraes, coerente entre sidebar, popover e tela de Usuários; nomenclatura "Médico" → "Dentista" (pessoa) / "Profissional" (papel de acesso) em todo o sistema (5.7.8).

> ✅ **Resolvidas em rodada anterior (24/08, 5ª sessão):** papel "Profissional" adicionado — terceiro papel, o mais restrito (5.7.5); tela de fila sem barra lateral pra esse papel, com "Cancelar chamada" omitido do menu (5.7.5); Configurações de Alerta e Salas & Vínculos migradas pra dentro do grupo Administrador (5.7.6); filtro por dentista nos Relatórios, combinável com o filtro de período (5.7.7); bug de botões de ação empilhados verticalmente corrigido, com regra estrutural pra nunca mais acontecer em nenhuma tabela do sistema.

> ✅ **Resolvidas em rodada anterior (24/08, 4ª sessão):** seção "Administrador" reestruturada com subitens Relatórios + Usuários (5.7), tela de gestão de usuários com papéis nomeados (5.7.2), Relatórios com dados reais por período em vez de só visual (5.7.1), bug do dropdown que fechava ao rolar corrigido (5.7.3), Monitor de Fila com rolagem interna testada com fila cheia (5.7.4).

> ✅ **Resolvidas em rodada anterior (18/08, 3ª sessão):** tag de prioridade curada com base na Lei 10.048/2000 (5.6), semântica de "cancelar" esclarecida — desfazer, não ausência (5.5.9), remoção das métricas do Monitor de Fila (5.7).

> ✅ **Resolvidas em rodadas anteriores:** fusão de Salas & Vínculos em abas, remoção do CPF, painel "Aguardando" na TV, integração real de remoção de paciente, biblioteca de ícones, breakpoints de desktop, modelo de reuso de componentes, resiliência de duas camadas na TV.

### 10.3 Depende de terceiro (Clinicorp)

📋 **Checklist formal enviado em 24/08** — ver `perguntas-clinicorp.md` (documento separado). Resumo dos itens que mais afetam design:
- Token de API + limites de rate/quota (trava o ciclo de sincronização, seção 2.6.1/4.6.1).
- `status_id` de "em atendimento" + se `/appointment/change_status` aceita essa transição vinda de fora do Clinicorp (crítico pra seção 5.5 funcionar de verdade).
- Endpoint/campo da **foto do paciente** (seção 10.2) e do **apelido** (já confirmado que existe, falta o endpoint exato) e se o nome vem estruturado (primeiro/último) ou como string única.
- O **modo demo** (4.6) continua prioritário independente dessas respostas — não podemos usar dado real em portfólio (Cláusula 15), e credenciais podem atrasar.

---

## 11. Registro de fontes

- **Identidade visual:** manual de marca Qualimplan (rev. 001, jun/2011) — arquivos `Qualimplan_Logotipo_Pantone.pdf` e `..._Uniforme_Curvas.pdf`.
- **Regras de negócio e limites:** *clinic-queue-panel — Guia do Projeto* (fonte funcional).
- **Legibilidade à distância:** padrões de sinalização digital (regra polegada/distância, regra 3×5, contraste alto).
- **Acessibilidade de cor:** WCAG 2.1 — critérios 1.4.1 (Uso da Cor), 1.4.3 / 1.4.6 (Contraste), 1.4.11 (Contraste de não-texto).
- **UX sound design:** boas práticas de duração, timbre, estratégia e teste em hardware real.
- **Tipografia:** análise do DNA do wordmark + benchmark de sans geométricas arredondadas de andar único; comparação visual das candidatas (Quicksand, Comfortaa, Poppins, Nunito, Rubik, Baloo 2) contra o wordmark real e contra o conteúdo do painel. Fontes: Google Fonts (OFL).
- **Contexto de mercado (painéis de senha BR) e LGPD em saúde:** benchmark de sistemas de fila de clínica e análises de exposição de dados em sala de espera.
- **Convenções de wireframe:** boas práticas de fidelidade média, anotação, conteúdo realista, tamanho de tela de referência e componentes reutilizáveis (mercado 2026).
- **Resiliência de falha de sincronização (TV):** padrões de mercado em digital signage/kiosk — "fail static" / graceful degradation, mensagem neutra de fallback, movimento na periferia vs. centro, e "Data Freshness Indicator" como padrão específico de dashboards operacionais (não de telas ambiente).
- **Iconografia:** comparação técnica e visual entre Lucide e Tabler Icons (SVGs reais renderizados lado a lado); fit de ecossistema com Next.js/React 2026.
- **Breakpoints de desktop:** padrões de mercado 2026 para faixas 1280/1440/1920px e regra de max-width de conteúdo.
- **Fila de espera / "now serving":** padrões de mercado em sistemas de fila de saúde (hospitais, clínicas) — exibição "now serving" + "next in line", priorização visual por urgência.
- **Fusão de telas administrativas:** critérios de mercado pra tabs vs. páginas separadas (mesmo nível hierárquico, conteúdo relacionado, uso mutuamente exclusivo, 2–7 seções) — aplicado à fusão de Salas & Vínculos.
- **Reuso de componentes:** literatura de atomic design como aplicação prática de SOLID e modularidade a UI, sem exigir design system formal.
- **Transições de status — botão vs. select:** padrões de sistemas de fila/ticket (Jira, Zendesk) e, principalmente, de software odontológico/EHR real (Dentrix Ascend, Epic, PCC EHR) — transições nomeadas e curadas ("Here"/"Ready"/"Checkout", "No Show", "Left without seen"), nunca um seletor aberto de status crus.
- **Chamar paciente — dois momentos, menu compacto:** padrões de máquina de estados (chamar ≠ confirmar chegada, só a segunda escreve) desenhados a partir da correção de contexto da clínica (computador único, chamada é do paciente); pesquisa de design de tabelas B2B/enterprise para ações de linha em tela pequena — agrupar em menu kebab em vez de múltiplos ícones lado a lado.
- **Incentivo pra confirmar chegada:** pesquisa de UX de fila/ticket sobre cronômetros visíveis em itens pendentes ("tudo continua contando, exceto quando espera retorno externo") como forma de criar pressão suave sem alarme; padrão de ação primária visível + secundárias agrupadas em menu, já confirmado na pesquisa de tabelas B2B, reaplicado ao estado "chamando".
- **Confirmação de "chamar de novo":** pesquisa de UX sobre toast vs. snackbar vs. modal — critério de quando usar cada um (toast quando só se precisa de confirmação de status, sem ação corretiva); posicionamento recomendado (canto inferior/superior direito em desktop) e janela de exibição (2–3s pra confirmações rápidas).
- **Reordenação animada da fila:** técnica FLIP (First-Last-Invert-Play) — mede a posição antes e depois de reordenar o DOM, anima só a diferença — padrão de mercado pra tornar mudanças de ordem em lista/tabela acompanháveis visualmente, em vez de "teletransportar" itens.
- **Padrão ouro de chamada (visual + sonoro):** convergência de três fontes — broadcast/lower-third de TV (barra que cresce, nunca pisca), Nielsen Norman Group sobre "radiating halo" como reforço de atenção sem distração, e princípios gerais de motion design (Material Design / NN Group) sobre duração de entrada (300–500ms), easing natural, e a regra de sempre justificar o propósito de uma animação.
- **Tag de prioridade — base legal:** Lei 10.048/2000, com a redação atualizada pela Lei 14.626/2023 — as 9 categorias de atendimento prioritário no Brasil (pessoa com deficiência, pessoa com TEA, idoso, gestante, lactante, pessoa com criança de colo, obesidade, mobilidade reduzida, doador de sangue). Usada como lista fixa e oficial, eliminando a necessidade de campo de justificativa livre.
- **Painel Administrativo — dashboard operacional vs. analítico:** pesquisa sobre relatórios simples para pequenas operações — a distinção entre dashboard operacional (tempo real, decisão imediata) e analítico (histórico, decisão posterior) como justificativa pra separar Monitor de Fila de Relatórios; princípio de que cada KPI deve sustentar uma decisão real, e de evitar gráficos que exigem interação pra serem entendidos.
- **Gestão de usuários e papéis:** pesquisa de mercado sobre admin panels e produtos SaaS B2B (incluindo o princípio do menor privilégio) — papéis nomeados e pequenos em vez de matriz de permissão granular para equipes pequenas; descrever cada papel em linguagem simples no exato momento em que é atribuído; nunca deixar a conta sem nenhum administrador restante.
- **Filtro por dentista nos Relatórios:** pesquisa de padrões de filtro em dashboards/SaaS — dropdown como escolha certa pra listas curtas e fixas de categorias (vs. abas ou checkboxes, reservados pra outros cenários de comparação/multiseleção).
- **Colunas de tabela de relatório e formato de data:** pesquisa de UX de tabelas de dados — ordenar colunas pela lógica do usuário (aqui, cronológica) em vez da lógica de quem construiu o sistema; formatos de data com mês por extenso e ano completo evitam a ambiguidade de abreviações numéricas com barra, especialmente relevante em relatórios que cruzam meses.
- **Foto do paciente e acessibilidade pra baixa alfabetização:** não achamos um precedente de mercado específico de "foto em painel de chamada de fila" — registrado honestamente como lacuna. O que sustenta a decisão é o princípio mais geral, confirmado em múltiplas fontes independentes de acessibilidade em saúde: conteúdo baseado em imagem supera texto pra pacientes de baixa alfabetização (inclusive em estudo clínico sobre material educativo multimídia), e o teste prático de "se entende em 5 segundos a 3 metros de distância" pra sinalização digital de sala de espera.
- **Badge de alerta e protocolo de tempo de espera:** pesquisa de padrões de notificação (badge não pode acumular sem zerar, ou vira ruído que o usuário aprende a ignorar) e de escalonamento de SLA em sistemas de suporte (regra baseada em tempo só funciona se disparar automaticamente e notificar o responsável certo, sem depender de alguém vigiar o relógio) — confirmam o desenho de badge-que-zera-sozinho + alerta automático usados nesta seção.

---

## 12. Inventário final — 20 telas (26/08, fechamento do pacote)

Checkpoint antes de passar pro design visual. Todas as telas abaixo existem, foram testadas, e têm anotações completas (pin na tela ⇄ item na legenda, verificado programaticamente nas 20).

| Grupo | Telas | Variantes |
|---|---|---|
| **Painel de TV** | 1 | Chamada em destaque · Dentista sem sala · Fila vazia · Falha prolongada |
| **G1 · Login** | 1 | Padrão · Erro de credenciais · Cadastro por convite |
| **G2 · Monitor de Fila** | 1 | Padrão · Fila vazia · Carregando · Erro de sincronização · Papel Profissional |
| **G3 · Configurações de Alerta** | 1 | (tela única) |
| **G4 · Salas & Vínculos** | 1 | Salas · preenchida · Salas · vazia · Vínculos · padrão · Vínculos · sincronizando · Vínculos · erro |
| **G5 · Relatórios** | 1 | Padrão (3 períodos + filtro por dentista, interativos dentro da mesma tela) |
| **G6 · Usuários** | 1 | Padrão (com fluxo de convite completo: formulário → link → convite pendente) |

**Total: 7 macro-telas, 20 variantes renderizadas.**

**O que fica de fora deliberadamente, não por esquecimento:** wireframe mobile/tablet (10.2), modo demo (10.1, decisão da clínica), gestão de conteúdo/mídia (10.1, decisão da clínica), variantes de vazio/erro pras telas G5/G6 (proporcionalidade — são telas de escopo adicional, replicar todo o conjunto de estados nelas violaria o mesmo YAGNI que guiou o resto do projeto), servidor de e-mail/SMTP pra convites (10.1, decisão da clínica — resolvido com link copiável em vez de envio automático).