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
statusno 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):
"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-statuse.avatar-statusdo 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-borderfoi removido e--color-status-canceled-bg/-fgmudaram (verPara 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”):
- Trilha de auditoria (NGS1.07.03, estágio 1): mecanismo transversal ainda não mapeado. CT-AGM-API-08 continua não executável.
- [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. - Divergência de tipo
Agenda.IdAgendaClassificacao(int, sem FK) × PKsmallintdeAgendaClassificacao(Log de Mudanças, 07/10/2026). O join funciona. - [PROPOSTA] Índice novo em
Agenda(agora comIdChClinicanoINCLUDE) e migração deStatus = 'I'paraRemovidoEmemUnidadeAtendimento.
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.