# Agenda do Médico — mudanças da v2: guia para desenvolvimento

**Para quem é:** o time de desenvolvimento (back-end, banco e front-end) que implementou a Agenda do Médico com os documentos da série v1. Este guia diz o que mudar para chegar à v2.1.
**Base de comparação (o que foi desenvolvido):** Definição v1.16, Especificação v1.19, Protótipo v1.14 (`.md` + `.html`), Mapeamento de Banco de Dados v1.9 e Cenários de Teste v1.6. Os arquivos estão em `Definições e especificações/Agenda do Médico/Histórico/`.
**Destino:** Definição v2.1, Especificação v2.1, Protótipo v2.1, Mapeamento v2.1 e Cenários de Teste v2.1. A série v2 foi fechada em 29/10/2026 e os arquivos estão em `Agenda do Médico/Histórico/`.
**Linha do tempo da v2:**

- 26/10/2026 (versões 1.17 e 1.18 da Definição, posteriores à base): filtro pelas clínicas a que o médico tem acesso.
- 27/10/2026: cores e nome do status vindos da API, Cancelado cinza com os textos riscados, troca do formato de `status` no mesmo deploy, nome "Em atendimento".
- 27/10/2026, v2.0: abertura da série, sem mudança de conteúdo.
- 28/10/2026, v2.1: nome "Aguardando recepção".

**Situação:** v1.0, 29/10/2026. **Versão final e fechada.** A v2.1 foi para desenvolvimento, e este guia não recebe mais mudanças. O que mudar a partir da v3.0 está em `Agenda do Médico - mudanças da v3 - guia para desenvolvimento.md`.

**Como ler.** Este documento resume as diferenças; não substitui a especificação. A regra completa, os critérios de aceitação e os SQLs estão nos documentos v2.1, citados em cada item. O guia foi montado a partir da comparação do corpo dos documentos (base × v2.1), não só dos Históricos. Cada mudança traz a sua origem:

- **D-CM-nnn**: decisão do solicitante registrada no Registro de Decisões da Central do Médico (a decisão vale para as duas telas). Pode implementar.
- **DT-nnn**: decisão transversal do projeto (`Para IA/Decisões Transversais do Projeto.md`). Pode implementar.
- **[PROPOSTA]**: proposta do Designer, sem decisão. Não tratar como requisito.

---

## 1. Resumo por camada

| Camada | O que muda | Seção |
|---|---|---|
| Banco | Leitura da tabela nova `IpTerminologia.DomEstadoAgendaConsulta` (cores do status) e de `TermoTraducao` para o nome do status; filtro por clínicas com acesso nas três consultas; coluna `IdChClinica` no `INCLUDE` do índice proposto | 2 |
| Back-end: contrato | `status` deixa de ser texto e vira objeto `{ domain, name, colors }`, trocado no mesmo deploy do front | 3.1 |
| Back-end: regras | Só consultas e bloqueios das clínicas a que o médico tem acesso, em `GET /day`, `days-with-appointments` e `next-appointment-date` | 3.2 |
| Front | Chip e avatar com as cores de `status.colors`; chip neutro quando `colors` não vem; Cancelado cinza preenchido com todos os textos do item riscados, exceto chip e avatar; regras de tela por `status.domain` | 4 |
| i18n | Nome do status vem traduzido da API (`status.name`); o front deixa de usar o catálogo de rótulos de status; novos textos "Em atendimento" e "Aguardando recepção" | 5 |
| Tema e cores | Classes `.chip-status` e `.avatar-status` do Design System, seção 4; tokens `--color-status-*` deixam de ser a fonte das cores do chip e do avatar na Agenda | 6 |
| Testes | 4 casos novos e 1 reescrito; mudanças de texto em vários casos; 105 → 109 casos | 7 |

Não mudam: regras de tags, bloqueios, fuso, navegação, atualização automática, layout (fora o item cancelado), endpoints `days-with-appointments` e `next-appointment-date` (contrato), busca do cabeçalho.

---

## 2. Banco de dados e parâmetros

| Item | Base (v1.9) | v2.1 | Origem | Fonte |
|---|---|---|---|---|
| `IpTerminologia.DomEstadoAgendaConsulta` | Não usada | Lida para `status.colors`. Estrutura: `CodEstado char(3)` (PK), `Descricao varchar(30)`, `CorClaroTexto`, `CorClaroFundo`, `CorEscuroTexto`, `CorEscuroFundo` (`char(7) NULL`, `#RRGGBB`). Base global: as mesmas cores para todas as clínicas. A tabela foi criada em 27/10/2026 e ainda não está na Biblioteca de Schema (DDL) | DT-016 | Mapeamento v2.1, 4.1 e "Tabelas novas"; Log de Mudanças Estruturais, 27/10/2026 |
| Chave status × `CodEstado` | — | `scheduled` → `A`; `waiting` → `D`; `checked` → `G`; `consultation` → `J`; `finished` → `M`; `canceled` → `X` (a mesma tabela vale para o painel de Consultas da Central) | DT-016 | Mapeamento v2.1, "Domínios" |
| `TermoTraducao` | Só o rótulo do modo de atendimento | Também o nome do status: `Termo` = `CodEstado`, `Origem` = `DomEstadoAgendaConsulta`, `Idioma` = `ClienteEmpresa.IdiomaOficial`. Sem tradução, vai a própria chave (`CodEstado`) e a anomalia é registrada no log técnico (DT-011, regra já existente para o modo de atendimento) | DT-016, DT-011 | Mapeamento v2.1, 4.1 |
| Filtro por clínica | "Sem filtro por clínica" | `Agenda.IdChClinica IN (SELECT IdChClinica FROM {ClinicasDoMedico})` em 4.1 (`GET /day`, inclusive `blocks`), 4.2 e 4.3. `{ClinicasDoMedico}` é montada pela aplicação uma vez por sessão e definida no Mapeamento da Central do Médico (v5.13, Seção 4, bloco "Clínicas em que o médico atende"): clínicas do cliente da sessão a que o usuário tem acesso (`ClientePerfilAcessoUsuario`), traduzidas para `IdChClinica` por `SegEmpresa` e `Clinica` | D-CM-067, D-CM-068 | Mapeamento v2.1, 4.1 a 4.3, "Filtros do endpoint" |
| Índice proposto `IX_Agenda_IdChRecurso_TipoAgenda_DhAgendaIniUTC` | `INCLUDE (Situacao, IdPaciente, DhAgendaFimUTC, RemovidoEm)` | `INCLUDE (…, IdChClinica)`, porque a coluna passa a ser lida no filtro. Continua **[PROPOSTA]**, a confirmar com o time de banco | — | Mapeamento v2.1, "Índices" |
| Indicador `EstadoAgendaConsulta` (`IpTerminologia.Indicadores`) | — | Será descontinuado depois que `DomEstadoAgendaConsulta` estiver em uso. Não remover antes disso | D-CM-081 | Mapeamento v2.1, "Tabelas novas" |
| Seeds a conferir | — | Cores dos seis status nos dois temas (`DomEstadoAgendaConsulta`, contra o Design System, seção 4) e os nomes dos seis status em pt-BR, en-US e es-419 (`TermoTraducao`) | — | Mapeamento v2.1, seeds |

Sem mudança: `ClienteEmpresa.FusoHorarioOficial`, padrão de auditoria em `UnidadeAtendimento` e as demais tabelas já estavam na base. Nenhum parâmetro novo.

---

## 3. Back-end: mudanças por endpoint

### 3.1 Mudanças de contrato (`GET /api/v1/agenda/doctor/day`)

| Campo | Base (Especificação v1.19) | v2.1 | Origem |
|---|---|---|---|
| `appointments[].status` | Texto: `scheduled \| waiting \| checked \| consultation \| finished \| canceled` | Objeto `{ domain, name, colors }` | DT-016 |
| `status.domain` | — | O valor que antes vinha em `status`, de `AppointmentStatus()` (mesma precedência da base). É o campo que o front usa para as regras: grupos de realizadas e canceladas, destaque lateral e sinalizador de atraso | DT-016 |
| `status.name` | — | Nome já traduzido para o idioma da clínica; é o texto do chip | DT-016 |
| `status.colors` | — | `{ light: { background, text }, dark: { background, text } }`, em `#RRGGBB`. Vem com os quatro valores ou não vem: se alguma das quatro colunas de `DomEstadoAgendaConsulta` estiver NULL, `colors` fica fora da resposta | DT-016 |

**Deploy:** back-end e front-end trocam o formato de `status` (de texto para objeto) **no mesmo deploy**, sem período com os dois formatos (D-CM-080).

Exemplo (Especificação v2.1, `GET /day`):

```json
"status": { "domain": "finished", "name": "Finalizado",
  "colors": { "light": { "background": "#EDE7FA", "text": "#6A4FC4" },
              "dark":  { "background": "#302F52", "text": "#C0AFED" } } }
```

Os demais campos de `appointments` e `blocks`, e o contrato de `days-with-appointments` e `next-appointment-date`, não mudam.

### 3.2 Regras e consultas

- **Escopo pelas clínicas com acesso (D-CM-068, D-CM-070):** os três endpoints devolvem só consultas e bloqueios das clínicas do cliente a que o médico tem acesso. Uma consulta agendada antes numa clínica a que o médico perdeu o acesso não aparece em nenhum dia, nem conta nos dias com consulta, nem na navegação para o próximo ou anterior dia com consulta. Os registros continuam no banco. Perder o acesso à clínica não tira o acesso ao paciente. Fontes: Definição v2.1, RN-AGM-002; Especificação v2.1, CA-008.9; Mapeamento v2.1, 4.1 a 4.3.
- **Clínica no item (RN-AGM-017 a):** a regra não muda; a contagem de clínicas de `ClinicVisible()` é a mesma de `{ClinicasDoMedico}`. Se o médico passa a ter acesso a uma só clínica, a clínica deixa de aparecer nos itens. Na base, o Mapeamento dizia que não havia consulta numa clínica sem acesso; isso foi corrigido.
- **Nome e cores do status:** leitura descrita na seção 2. O fuso, o "hoje" e os horários continuam no fuso da clínica em que o usuário entrou, agora para as consultas das clínicas a que ele tem acesso.

---

## 4. Front-end: mudanças por área

| Área | Base | v2.1 | Origem | Fonte |
|---|---|---|---|---|
| Chip de status | Cores por tokens `--color-status-{status}-bg`/`-fg`; texto pelo catálogo de rótulos | Classe `.chip-status` com o par de `status.colors` do tema vigente; texto = `status.name`. Sem `colors`: chip neutro do Design System (fundo `neutral-light`, texto `neutral-darker`) | DT-016 | Especificação v2.1, tabela de componentes (Chip) |
| Avatar de iniciais (só em telas largas) | Fundo e texto do par do status; Cancelado com contorno | Classe `.avatar-status`: fundo = `status.colors.{tema}.background`; iniciais sempre em `color-neutral-darker`, nos dois temas. O avatar representa o paciente, e o status aparece nele só de forma sutil. Sem `colors`, usa o mesmo fundo neutro | DT-016 | Especificação v2.1, tabela de componentes (Avatar) |
| Troca de tema | — | Chip e avatar mudam de cor na hora, sem nova chamada ao servidor: as cores dos dois temas já vêm na resposta | DT-016 | Cenários v2.1, CT-AGM-UI-10 |
| Regras de tela | Lidas de `status` (texto) | Lidas de `status.domain`: grupos de realizadas e canceladas, borda lateral (Recepcionado, Aguardando recepção), sinalizador de atraso | DT-016 | Especificação v2.1, `GET /day` |
| Item cancelado (grupo de canceladas) | Chip "Cancelado" com contorno e fundo transparente; avatar de contorno; só o horário de início e término riscado | Chip "Cancelado" em **cinza preenchido** (cores da API, como os demais). **Todos os textos do item riscados:** horário de início e término, nome e diagnósticos, modo de atendimento, tags, complemento e informações complementares (clínica, unidade, convênio, classificação). **Não são riscados:** o chip de status, o avatar e o ícone de 1ª Consulta. O leitor de tela não anuncia o risco; o nome acessível do item já traz o status | Pedido do solicitante sobre a proposta da equipe de front-end (27/10/2026), DT-016 | Especificação v2.1, "Status 'Cancelado'", grupos e CA-005.2 |
| Clínicas sem acesso | — | Nada a fazer no front: o filtro é do back-end (seção 3.2) | D-CM-068 | Especificação v2.1, CA-008.9 |

O Protótipo v2.1 (`.html`) mostra tudo isso com o mock `STATUS_API` (`domain`, `name`, `colors`, com os valores de `DomEstadoAgendaConsulta`).

---

## 5. Internacionalização

| Item | Base | v2.1 | Origem |
|---|---|---|---|
| Rótulos de status | Catálogo da Central do Médico (Seção 2.3); "Cancelado" = termo `status-cancelado` (Seção 2.6) | Vêm traduzidos da API em `status.name` (`TermoTraducao`). A Agenda não usa mais o catálogo de rótulos de status no front | DT-016 |
| "Em Atendimento" | Texto do catálogo | **"Em atendimento"**, como cadastrado em `TermoTraducao` | D-CM-082 |
| "Aguardando Recepção" | Texto do catálogo | **"Aguardando recepção"**, como cadastrado em `TermoTraducao` | D-CM-084 |

Os demais textos (MSG-EAGM, MSG-TAGM, MSG-BAGM) não mudam.

---

## 6. Tema, cores e tokens

- As cores do chip e do avatar de status vêm de `status.colors`, aplicadas pelas classes `.chip-status` e `.avatar-status` do Design System, seção 4 (valores, regra de cálculo e aplicação estão lá). O front escolhe o par pelo tema e não mantém paleta fixa (DT-016).
- Os tokens `--color-status-*` deixam de ser a fonte das cores do chip e do avatar nesta tela. No Design System de 27/10/2026, `--color-status-canceled-border` foi removido e `--color-status-canceled-bg`/`-fg` mudaram (ver `Para Desenvolvedores/Mudanças no Design System - guia para desenvolvimento.md`, linha de 27/10/2026).
- A Especificação passa a citar o Design System nas seções 1 a 11 (antes, 1 a 6). Fora as cores de status, nenhuma outra mudança do Design System posterior à base entrou no texto da Agenda v2.1. As demais mudanças do Design System estão no guia citado acima.

---

## 7. Testes e massa de dados

Para testar a versão que já está em desenvolvimento, use os Cenários v1.6. Para esta entrega, use os **Cenários de Teste v2.1** (109 casos; cobertura 52/52 CA e 4/4 EX). A massa é a mesma: `Central do Médico (Cockpit)/CargaCMZero.xlsx` e `Infra-estrutura/CargaSegGlobal.xlsx`, data-base 23/09/2026. As tabelas `DomEstadoAgendaConsulta` e `TermoTraducao` precisam estar carregadas.

| Caso | Situação | O que testa |
|---|---|---|
| CT-AGM-CTX-11 **(BD)** | Novo | Retirar o acesso do Dr. 9 à Gama Norte (`RemovidoEm` em `ClientePerfilAcessoUsuario`): a agenda 166 e o bloqueio 169 somem; o calendário e a navegação ignoram esses dias; a clínica deixa de aparecer nos itens |
| CT-AGM-API-09 **(API)** | Novo | `status` como objeto, com os valores de `DomEstadoAgendaConsulta` para `X` e `G` |
| CT-AGM-API-10 **(BD)** | Novo | `CorEscuroFundo` NULL para `X`: `colors` não vem e o chip e o avatar ficam neutros; os textos continuam riscados |
| CT-AGM-UI-10 | Novo | Troca de tema sem recarregar e sem chamada a `/day` |
| CT-AGM-RES-02 | Reescrito | Canceladas com chip cinza preenchido e todos os textos riscados, exceto o chip; avatar com iniciais sem risco |
| LIS-01, LIS-03, LIS-08, RES-07, RES-10, UI-07, MSG-02 | Texto ajustado | Nomes "Em atendimento" e "Aguardando recepção" |

---

## 8. Pendências que podem mudar o desenvolvimento

Sem mudança em relação à base (Mapeamento v2.1, "Pendências"):

1. Trilha de auditoria (NGS1.07.03, estágio 1): mecanismo transversal ainda não mapeado. CT-AGM-API-08 continua não executável.
2. **[PROPOSTA]** Diagnóstico com prontuário futuro: estender à Agenda a regra da Central (não exibir diagnóstico cujo `PEP.DataInicioUTC` é posterior ao dia exibido). Aguarda decisão; **não implementar**.
3. Divergência de tipo `Agenda.IdAgendaClassificacao` (`int`, sem FK) × PK `smallint` de `AgendaClassificacao` (Log de Mudanças, 07/10/2026). O join funciona.
4. **[PROPOSTA]** Índice novo em `Agenda` (agora com `IdChClinica` no `INCLUDE`) e migração de `Status = 'I'` para `RemovidoEm` em `UnidadeAtendimento`.

Novo item, só de banco: `DomEstadoAgendaConsulta` precisa entrar na Biblioteca de Schema (DDL), numa nova extração.

---

## 9. Rastreabilidade: mudança → decisão → documento

| Mudança | Decisão | Documentos (versão em que entrou) |
|---|---|---|
| Só as clínicas a que o médico tem acesso | D-CM-067, D-CM-068 | Definição v1.17; Especificação v1.20 (CA-008.9); Mapeamento v1.10; Cenários v1.7 (CTX-11) |
| Perder o acesso à clínica tira as agendas dela, não o paciente | D-CM-070 | Definição v1.18 |
| `status` como objeto; cores de `DomEstadoAgendaConsulta`; nome de `TermoTraducao` | DT-016 | Especificação v1.21; Protótipo v1.15; Mapeamento v1.11; Cenários v1.8 (API-09, API-10, UI-10) |
| Cancelado cinza preenchido, textos riscados exceto chip e avatar; iniciais do avatar em `neutral-darker` | Respostas do solicitante de 27/10/2026, sobre a proposta da equipe de front-end (DT-016) | Especificação v1.21; Protótipo v1.15; Cenários v1.8 (RES-02) |
| Troca do formato de `status` no mesmo deploy | D-CM-080 | Especificação v1.22 |
| Indicador `EstadoAgendaConsulta` a descontinuar | D-CM-081 | Mapeamento v1.12 |
| "Em atendimento" | D-CM-082 | Especificação v1.22; Protótipo v1.16; Cenários v1.9 |
| "Aguardando recepção" | D-CM-084 | Especificação v2.1; Protótipo v2.1; Cenários v2.1 |

As versões 1.17 a 1.22 e 2.0 estão em `Agenda do Médico/Histórico/`, com o detalhe de cada rodada no Histórico de Versões de cada arquivo.

---

## Histórico de Versões

- **v1.0** (29/10/2026) — Guia criado a pedido do solicitante: "gere um documento de diferenças entre a versão que foi para desenvolvimento com a atual da agenda do médico e adicione em Para Desenvolvedores. Vou mandar essas mudanças para desenvolvimento e fechamos nova versão." Ele compara a base de desenvolvimento (Definição v1.16, Especificação v1.19, Protótipo v1.14, Mapeamento v1.9, Cenários v1.6) com a v2.1. A comparação foi feita no corpo dos documentos, linha a linha, e conferida com os Históricos de Versões. Segue a estrutura do guia da Central do Médico (DOC-009). O guia nasce fechado: a v2.1 foi para desenvolvimento, e as mudanças seguintes ficam no guia da v3.