Especificação da funcionalidade: fechamento das lacunas pós-migração¶

Branch da funcionalidade: 003-post-migration-gaps

Criado em: 2026-08-10

Status: Rascunho — aguardando aprovação do responsável pelo produto

Entrada: Descrição do usuário: "Usar o PRD de refatoração do monorepo para serviços isolados e escrever todas as especificações necessárias para concluir as lacunas pós-migração."

Contexto e objetivo¶

O Prontuare já opera nos serviços isolados prontuare-web e prontuare-api, mas a auditoria do PRD identificou três lacunas: ausência do calendário visual, indicadores ainda estáticos no dashboard e falta de decisão explícita sobre consultas brasileiras externas. Esta iniciativa fecha essas lacunas sem reintroduzir o monorepo ou o modelo multi-tenant.

O calendário visual e o resumo do dashboard são entregas funcionais. CEP, CNPJ e CFP entram primeiro como uma decisão de produto e risco; nenhuma dependência externa nova será adicionada sem aprovação do owner.

Cenários de usuário e testes¶

História de usuário 1 - Visualizar e operar a agenda em um calendário (Prioridade: P1)¶

Como profissional autenticado, quero visualizar meus agendamentos em grades mensal e semanal, navegar entre períodos e abrir as ações do agendamento, para organizar minha rotina sem depender de uma lista ou de um calendário externo.

Motivo da prioridade: O PRD classifica a ausência da grade como P0; a agenda visual é o principal gap funcional da migração.

Teste independente: Com agendamentos do próprio profissional distribuídos por diferentes dias e horários, abrir /calendar, alternar entre mês e semana, navegar para outro período e selecionar um evento. A grade deve apresentar apenas os itens do intervalo e permitir chegar à edição ou criação sem usar a página de integrações.

Cenários de aceitação:

Dado um profissional com agendamentos no mês atual, Quando abre o calendário, Então visualiza os eventos nos dias e horários correspondentes, com identificação segura do paciente e estado do agendamento.
Dado a grade aberta, Quando alterna entre visão mensal e semanal ou navega para o período anterior/seguinte, Então o intervalo correto é carregado e a seleção de visão permanece durante a sessão de navegação.
Dado um evento visível, Quando o profissional o seleciona, Então consegue acessar os detalhes e as ações suportadas de editar ou cancelar.
Dado um espaço livre ou a ação de novo agendamento, Quando o profissional inicia o cadastro, Então o formulário recebe o período selecionado quando aplicável.
Dado uma agenda vazia, em carregamento ou com falha, Quando a grade é aberta, Então cada estado é distinguível e uma falha oferece nova tentativa sem apagar a navegação atual.
Dado o profissional deseja configurar sincronização externa, Quando acessa as configurações do calendário, Então encontra as conexões Google e Microsoft separadas da grade principal.

História de usuário 2 - Consultar indicadores reais do dia e do mês (Prioridade: P2)¶

Como profissional autenticado, quero ver no dashboard a quantidade de pacientes ativos, consultas de hoje, documentos gerados e receita mensal calculadas a partir dos meus dados, para entender rapidamente minha operação sem valores simulados.

Motivo da prioridade: O PRD classifica o dashboard parcial como P1. Valores simulados comprometem a confiança, mas não impedem o fluxo principal de agenda.

Teste independente: Preparar dados determinísticos do profissional, incluindo pacientes ativos/inativos, agendamentos em diferentes datas e estados, documentos e lançamentos financeiros no mês corrente; abrir o dashboard e comparar cada indicador com o conjunto preparado.

Cenários de aceitação:

Dado dados do profissional no fuso horário configurado, Quando abre o dashboard, Então os quatro indicadores são retornados por um único resumo consistente para o mesmo instante de referência.
Dado agendamentos hoje, Quando o resumo é calculado, Então "Consultas hoje" inclui os agendamentos não cancelados cujo início pertence ao dia local do profissional.
Dado documentos gerados e receita reconhecida no mês local corrente, Quando o resumo é calculado, Então cada card mostra seu total real e sua unidade correta.
Dado ausência de dados em uma métrica, Quando o dashboard carrega, Então mostra zero como resultado real, sem placeholder nem dado inventado.
Dado falha ao carregar o resumo, Quando o dashboard responde, Então não preserva valores antigos como atuais e oferece nova tentativa com mensagem segura.
Dado dois profissionais com dados distintos, Quando cada um consulta o resumo, Então nenhum agregado inclui dados do outro.

História de usuário 3 - Decidir e governar consultas externas brasileiras (Prioridade: P3)¶

Como responsável pelo produto, quero uma decisão registrada para CEP, CNPJ e CFP, incluindo valor, fonte, privacidade, custo, disponibilidade e fallback manual, para evitar reintroduzir serviços externos sem justificativa e impedir que a interface prometa validações inexistentes.

Motivo da prioridade: O PRD classifica esse item como P2 opcional. A decisão é obrigatória para encerrar a auditoria, mas a integração só será implementada em uma especificação posterior se aprovada.

Teste independente: Revisar o registro de decisão e verificar que cada consulta tem estado adotar, substituir ou aposentar, justificativa, riscos, comportamento manual e consequência explícita para a UI e API.

Cenários de aceitação:

Dado a auditoria das consultas legadas, Quando a decisão é concluída, Então CEP, CNPJ e CFP possuem decisões individuais, fonte avaliada e owner responsável.
Dado uma consulta aposentada ou ainda não aprovada, Quando o usuário preenche o cadastro, Então o preenchimento manual permanece possível e a interface não afirma ter validado o dado externamente.
Dado uma consulta aprovada para adoção, Quando a decisão é aceita, Então uma especificação própria é exigida antes da implementação, cobrindo contrato, consentimento quando aplicável, limites, falhas e observabilidade.

Casos limítrofes¶

Eventos que atravessam meia-noite ou mudanças de fuso são posicionados pelo fuso do profissional, preservando o instante original.
Eventos simultâneos ou parcialmente sobrepostos permanecem individualmente selecionáveis.
Agendamentos cancelados não contam em "Consultas hoje" e aparecem na grade somente quando a regra visual os mantiver explicitamente identificados como cancelados.
Um intervalo de calendário inválido ou excessivo é recusado sem consulta irrestrita.
A virada do dia ou do mês entre requisição e resposta usa um único instante de referência retornado no resumo.
Ausência de domínio de documentos ou financeiro produz estado unavailable, não um zero que sugira medição real.
Falhas de provedor de CEP, CNPJ ou CFP nunca bloqueiam o preenchimento manual nem salvam automaticamente dados retornados.

Requisitos¶

Requisitos funcionais¶

FR-001: O produto MUST manter /calendar como entrada da grade visual e disponibilizar conexões externas em /calendar/settings.
FR-002: A grade MUST oferecer visualizações mensal e semanal, navegação anterior, seguinte e hoje, e indicar o intervalo exibido.
FR-003: A grade MUST carregar somente agendamentos pertencentes ao profissional autenticado e contidos no intervalo solicitado.
FR-004: Cada evento MUST apresentar horário, estado e identificação do paciente suficiente para a tarefa, sem expor conteúdo clínico.
FR-005: O profissional MUST conseguir iniciar criação, edição e cancelamento a partir do contexto da grade usando os fluxos de agendamento existentes.
FR-006: A interface MUST distinguir carregamento, vazio, falha recuperável e dados carregados, mantendo a navegação do período durante uma nova tentativa.
FR-007: O calendário MUST ser utilizável por teclado e em viewport móvel, com alternativa legível em lista quando a grade não comportar interação segura.
FR-008: A API MUST expor um resumo autenticado do dashboard com referenceAt, fuso aplicado, pacientes ativos, consultas de hoje, documentos gerados no mês e receita mensal.
FR-009: O resumo MUST calcular todas as métricas para o mesmo profissional e instante de referência, sem combinar dados entre owners.
FR-010: "Consultas hoje" MUST contar agendamentos não cancelados iniciados dentro do dia local do profissional.
FR-011: "Pacientes ativos" MUST contar somente pacientes atualmente ativos do profissional.
FR-012: "Documentos gerados" MUST contar documentos concluídos no mês local; enquanto não existir uma fonte persistida e auditável, a métrica MUST ser marcada unavailable.
FR-013: "Receita mensal" MUST somar valores monetários reconhecidos no mês local e informar a moeda; enquanto não existir uma fonte financeira persistida e auditável, a métrica MUST ser marcada unavailable.
FR-014: O dashboard MUST substituir todos os valores simulados pelos valores ou estados de disponibilidade retornados no resumo.
FR-015: Falhas de resumo MUST usar o contrato seguro de erro do produto e permitir nova tentativa sem representar cache antigo como dado atual.
FR-016: A auditoria MUST registrar, para CEP, CNPJ e CFP, uma decisão individual entre adotar, substituir e aposentar, com justificativa, fonte, privacidade, custo, disponibilidade, limites e fallback.
FR-017: O preenchimento manual MUST permanecer disponível independentemente da decisão sobre consulta externa.
FR-018: A UI MUST diferenciar formatação local, dado informado pelo usuário e dado efetivamente consultado ou validado por fonte externa.
FR-019: Qualquer consulta externa aprovada MUST receber especificação e contrato próprios antes de código, credenciais ou dependências serem adicionados.
FR-020: Calendário e dashboard MUST ter verificação automatizada de isolamento por owner e fluxo real de navegador contra API e banco locais.

Entidades principais¶

Agendamento: Evento pertencente ao profissional, vinculado a paciente, com início, duração, fuso, estado e situação de sincronização.
Período do calendário: Intervalo semiaberto de consulta, visualização selecionada e fuso aplicado.
Resumo do dashboard: Fotografia dos agregados do profissional calculados em um instante e fuso comuns.
Métrica do dashboard: Valor real com unidade e disponibilidade, ou motivo explícito para indisponibilidade.
Decisão de consulta externa: Registro governado por tipo de dado, estado da decisão, fonte avaliada, riscos, fallback, owner e data de revisão.

Critérios de sucesso¶

Resultados mensuráveis¶

SC-001: Em 100% dos cenários de aceitação, um profissional localiza um agendamento do mês atual e acessa suas ações em até 30 segundos.
SC-002: As visões mensal e semanal exibem 100% dos agendamentos do intervalo de teste no dia e horário corretos, inclusive sobreposições e eventos em limites de dia.
SC-003: 95% das consultas de calendário e dashboard apresentam resultado ou estado de indisponibilidade em até 2 segundos no ambiente de validação.
SC-004: 100% das tentativas testadas de obter eventos ou métricas de outro profissional são recusadas ou excluídas sem revelar sua existência.
SC-005: Para um conjunto determinístico de dados, os quatro cards do dashboard coincidem em 100% com os totais esperados ou exibem unavailable quando não há fonte auditável.
SC-006: Nenhum card do dashboard exibe valor mockado, placeholder numérico ou zero apresentado como real quando a fonte estiver indisponível.
SC-007: CEP, CNPJ e CFP possuem 100% dos campos de decisão preenchidos e aprovados antes de a auditoria de migração ser encerrada.
SC-008: Os fluxos principais de calendário e dashboard passam em viewport desktop e móvel, por teclado e em navegador real com dados determinísticos.

Premissas¶

A autenticação, o modelo de ownership individual, pacientes e agendamentos atuais serão reutilizados.
O fuso padrão inicial é America/Sao_Paulo; o contrato aceita o fuso IANA efetivamente configurado para evolução futura.
A visão mensal é a entrada padrão no desktop; em telas estreitas a interface pode iniciar pela alternativa semanal ou em lista.
A criação e edição de agendamentos reutilizam as rotas e formulários existentes; drag-and-drop e redimensionamento direto estão fora de escopo nesta fase.
A sincronização Google/Microsoft continua com o contrato atual e não faz parte da reconstrução da grade, exceto pela mudança de navegação para configurações.
Documentos e receita somente serão calculados quando seus domínios possuírem fonte persistida e auditável; esta iniciativa não inventa um domínio financeiro nem um documento para satisfazer um card.
A decisão sobre serviços externos não autoriza sua implementação; aprovação positiva abre uma especificação separada.

Fora do escopo¶

Reintrodução de multi-tenancy, clínicas compartilhadas ou permissões entre profissionais.
Criação de novos domínios de faturamento, cobrança ou documentos apenas para preencher indicadores.
Drag-and-drop, redimensionamento de eventos, recorrência e convite de participantes no calendário.
Mudanças no OAuth2 ou na sincronização externa já existente.
Implementação de CEP, CNPJ ou CFP antes da decisão e de uma especificação dedicada.
Migração ou remoção física do código legado em apps/.