Especificação da funcionalidade: paridade do legado em repositórios separados¶

Branch da funcionalidade: 002-legacy-repo-parity

Criado em: 2026-08-04

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

Entrada: Descrição do usuário: "Reescrever as especificações do que falta reestruturar da arquitetura antiga em apps/ para os repositórios separados."

Contexto e objetivo¶

O workspace ainda contém a aplicação legada em apps/, que é a referência de comportamentos já entregues. O produto Prontuare passa a ser operado por dois repositórios de produto: web e API. Esta especificação define a paridade que precisa ser comprovada ou reconstruída antes que o legado possa ser retirado.

Não se trata de copiar a arquitetura antiga. Cada comportamento legado deve ser preservado, deliberadamente adaptado ao modelo atual (o profissional é dono dos seus dados, sem entidade clínica nesta fase), ou formalmente aposentado.

Cenários de usuário e testes¶

História de usuário 1 - Continuar o trabalho clínico sem regressão (Prioridade: P1)¶

Como psicólogo, quero acessar minha conta, cadastrar e consultar pacientes, registrar atendimentos e gerenciar os dados relacionados ao paciente no Prontuare, para continuar meu trabalho sem depender da aplicação legada.

Motivo da prioridade: Pacientes, atendimentos e acesso seguro são o núcleo do produto. Qualquer perda nesse fluxo impede o uso diário.

Teste independente: Em uma conta nova, o profissional cria uma conta, conclui o perfil mínimo, cadastra um paciente, atualiza seus dados, cria um atendimento, consulta o histórico e confirma que outro usuário não consegue visualizar esses dados.

Cenários de aceitação:

Dado um profissional sem sessão, Quando ele cria uma conta e entra, Então vê somente sua própria área de trabalho e pode encerrar a sessão.
Dado um profissional autenticado, Quando ele cria, edita, ativa ou inativa um paciente, Então a lista e a ficha do paciente refletem a alteração sem expor dados de outro profissional.
Dado um paciente ativo, Quando o profissional cria ou revisa um atendimento, Então a data, o texto e o histórico de versões permanecem vinculados ao paciente e disponíveis para consulta.
Dado uma conta gratuita com cinco pacientes, Quando o profissional tenta cadastrar o sexto, Então recebe uma explicação clara do limite e nenhuma informação é perdida.

História de usuário 2 - Manter agenda e integrações confiáveis (Prioridade: P1)¶

Como psicólogo, quero criar, alterar e cancelar agendamentos, e conectar uma agenda Google ou Microsoft quando essa integração estiver configurada, para manter meus atendimentos organizados.

Motivo da prioridade: Agenda é um fluxo existente e uma integração externa sensível; uma conexão incompleta não pode produzir eventos duplicados ou ocultar falhas ao profissional.

Teste independente: O profissional cria e altera um agendamento de um paciente. Em ambiente com provedor configurado, conecta uma agenda, sincroniza um agendamento e identifica claramente o resultado ou a falha.

Cenários de aceitação:

Dado um paciente ativo, Quando o profissional agenda, remarca ou cancela um atendimento, Então a agenda e a ficha do paciente mostram o estado atual correto.
Dado uma integração de calendário não configurada ou indisponível, Quando o profissional tenta conectá-la, Então recebe mensagem específica de indisponibilidade, sem erro genérico e sem criar conexão parcial.
Dado uma agenda conectada, Quando uma sincronização falha, Então o agendamento local permanece íntegro, o estado da sincronização é visível e a ação pode ser repetida sem duplicar o evento externo.

História de usuário 3 - Aplicar formulários e manter respostas auditáveis (Prioridade: P1)¶

Como psicólogo, quero criar formulários personalizados, aplicá-los a pacientes e consultar respostas posteriores, para manter avaliações e registros estruturados junto à ficha correta.

Motivo da prioridade: Formulários dinâmicos e respostas por paciente já existem no legado e são dados clínicos que não podem desaparecer numa troca técnica.

Teste independente: O profissional cria um formulário com campos suportados, publica uma versão, registra uma resposta para um paciente e consulta essa resposta depois de editar o modelo.

Cenários de aceitação:

Dado um profissional autenticado, Quando ele cria ou altera um formulário válido, Então os campos, validações e opções aparecem como definidos.
Dado uma versão publicada aplicada a um paciente, Quando o modelo é alterado posteriormente, Então a resposta anterior continua legível com a versão que lhe deu origem.
Dado um paciente pertencente ao profissional, Quando ele registra, edita ou consulta uma resposta, Então somente esse profissional pode acessá-la e o paciente correto é identificado.

História de usuário 4 - Concluir perfil e reduzir erro de cadastro (Prioridade: P2)¶

Como profissional, quero concluir e atualizar meu perfil e preencher dados brasileiros com assistência de consulta quando disponível, para reduzir erros de cadastro sem depender de ferramentas externas.

Motivo da prioridade: O legado já oferece onboarding, perfil profissional e consultas de CEP, CNPJ e CFP. Esses recursos não devem ser silenciosamente perdidos, embora não bloqueiem o primeiro atendimento.

Teste independente: Uma nova conta conclui o perfil individual ou de pessoa jurídica; um profissional consulta um dado suportado e consegue corrigir manualmente qualquer resultado ausente.

Cenários de aceitação:

Dado uma conta recém-criada, Quando o profissional informa o tipo de atuação e os dados obrigatórios do perfil, Então o sistema indica se o perfil está pronto e permite revisá-lo depois.
Dado um serviço de consulta disponível, Quando o profissional fornece um CEP, CNPJ ou identificação profissional válido, Então os dados retornados são apresentados para conferência antes de salvar.
Dado um serviço de consulta indisponível ou um valor inválido, Quando o profissional faz a consulta, Então recebe um motivo compreensível e continua podendo preencher os campos manualmente.

História de usuário 5 - Usar documentos e assistência por IA com controle humano (Prioridade: P2)¶

Como psicólogo, quero manter documentos vinculados ao paciente e iniciar a assistência de escrita de um atendimento sem perder controle do texto, para centralizar material clínico com segurança.

Motivo da prioridade: A ficha legada contém a área de documentos e o produto atual introduz assistência por IA. Ambos exigem contratos explícitos antes de serem apresentados como disponíveis.

Teste independente: O profissional abre a área de documentos de um paciente e identifica ações realmente disponíveis. Quando inicia uma assistência de escrita configurada, recebe um rascunho revisável; se cancelar, o texto clínico permanente não é alterado.

Cenários de aceitação:

Dado a ficha de um paciente, Quando o profissional acessa documentos, Então vê somente documentos e ações suportadas; capacidades ainda não entregues são explicitamente indisponíveis, não simuladas.
Dado uma assistência de escrita iniciada, Quando ela estiver em processamento, Então o estado, o cancelamento e a origem do conteúdo são claros para o profissional.
Dado uma sugestão gerada, Quando o profissional a aceita, edita ou descarta, Então somente uma ação humana explícita altera o atendimento salvo.

Casos limítrofes¶

Uma sessão expira enquanto o profissional edita dados clínicos: o sistema informa a necessidade de entrar novamente e não confirma uma alteração não persistida como salva.
Um link para paciente, atendimento, resposta ou documento inexistente ou sem permissão mostra uma tela compreensível, sem detalhes internos e sem dados de outro profissional.
Uma migração de dados antiga contém campos que não existem no modelo atual: os dados são preservados, mapeados ou declarados como não migráveis antes de qualquer troca de base.
Falhas de rede, provedor externo ou armazenamento não são mostradas como sucesso e registram uma causa diagnosticável sem vazar dados clínicos.
O profissional tenta anexar ou processar áudio sem consentimento explícito: o processamento não é iniciado.

Requisitos¶

Requisitos funcionais¶

FR-001: O workspace MUST manter uma matriz de paridade que classifique cada fluxo legado como preservado, adaptado, pendente ou aposentado, com a evidência correspondente.
FR-002: O produto MUST oferecer autenticação, recuperação de acesso, sessão e encerramento de sessão com respostas seguras, específicas e compreensíveis.
FR-003: O produto MUST permitir que um profissional seja o único dono de seus pacientes, atendimentos, respostas de formulário, documentos e agenda; nesta fase não existe entidade clínica compartilhada.
FR-004: O produto MUST preservar o fluxo de pacientes do legado: listar, pesquisar, criar, consultar ficha, editar dados e alterar o estado de atividade.
FR-005: O produto MUST limitar uma conta gratuita a cinco pacientes e comunicar de forma acionável a necessidade de plano antes de um sexto cadastro.
FR-006: O produto MUST preservar agendamento, remarcação, cancelamento, visualização por período e visualização na ficha do paciente.
FR-007: O produto MUST permitir integração opcional e segura com Google e Microsoft Calendar, incluindo conexão, desconexão, sincronização repetível e comunicação clara de configuração, autorização ou falha de provedor.
FR-008: O produto MUST preservar formulários personalizados, respostas vinculadas ao paciente e a imutabilidade da versão aplicada em respostas históricas.
FR-009: O produto MUST preservar onboarding e edição do perfil profissional, incluindo perfil individual ou pessoa jurídica, sem reintroduzir a entidade clínica nesta fase.
FR-010: O produto MUST oferecer consulta assistida de CEP, CNPJ e CFP quando o serviço correspondente estiver disponível, sempre com conferência e edição manual pelo profissional.
FR-011: O produto MUST definir para documentos por paciente as operações efetivamente suportadas, autorização, histórico, retenção e comportamento de indisponibilidade antes de expor upload ou download como funcional.
FR-012: A assistência por IA MUST produzir somente rascunhos revisáveis, exigir consentimento para áudio, permitir cancelamento e nunca salvar uma decisão clínica automaticamente.
FR-013: Toda interface web MUST consumir contratos publicados e versionados pela API; nenhum fluxo pode depender de rotas, formatos ou dados exclusivos do monorepo legado.
FR-014: Cada mudança de comportamento ou de dados MUST ter decisão de compatibilidade, migração ou aposentadoria antes da remoção do código legado.
FR-015: Cada fluxo classificado como preservado MUST ter teste automatizado e uma evidência de navegação real contra API e banco locais antes de ser dado como pronto.
FR-016: A interface deve iniciar em pt-BR e oferecer inglês e espanhol; nomes técnicos e rotas permanecem em inglês.

Entidades principais¶

Profissional: Pessoa autenticada que possui e administra seus próprios dados, pacientes e configurações de plano.
Paciente: Pessoa acompanhada pelo profissional, com ficha, status e dados de contato.
Atendimento: Registro clínico datado, com conteúdo revisável, versões e eventual rascunho de assistência de escrita.
Agendamento: Compromisso vinculado a um paciente, com horário, duração, estado e eventual resultado de sincronização de agenda.
Conexão de calendário: Autorização de um profissional para sincronizar agenda com um provedor externo.
Formulário e versão: Modelo personalizado de campos e a versão usada para interpretar respostas históricas.
Resposta de formulário: Dados respondidos para um paciente, ligados a uma versão de formulário.
Documento de paciente: Arquivo e seus metadados, vinculados a um paciente com regras de acesso, retenção e auditoria.
Direito do plano: Regra que define os limites e capacidades disponíveis à conta, incluindo o teto gratuito de pacientes.

Critérios de sucesso¶

Resultados mensuráveis¶

SC-001: A matriz de paridade cobre 100% dos fluxos identificados em apps/api-core, apps/web, packages e testes legados, sem item sem estado ou decisão registrada.
SC-002: Um profissional consegue concluir conta, perfil mínimo, cadastro de paciente e primeiro atendimento em até 10 minutos em ambiente limpo.
SC-003: 100% dos fluxos classificados como preservados têm cenário de aceitação automatizado e evidência de execução ponta a ponta antes da retirada do legado.
SC-004: Em testes de isolamento, 100% das tentativas de acessar dados de outro profissional são recusadas sem revelar o recurso solicitado.
SC-005: Em ambiente com provedor configurado, criar, alterar, cancelar e repetir uma sincronização de agenda não gera eventos externos duplicados em 100% do conjunto de testes.
SC-006: A área de documentos e a assistência por IA nunca apresentam como concluída uma capacidade sem contrato, autorização e revisão humana definidos.

Premissas¶

A aplicação em apps/ é referência de comportamento, não de arquitetura ou de contratos que precisam ser mantidos literalmente.
Os únicos repositórios de produto neste ciclo são prontuare-web e prontuare-api; processamento de trabalho em segundo plano, quando necessário, pertence ao mesmo repositório e ciclo operacional da API.
specs/ no workspace é a fonte de verdade para especificações, planos e tarefas; não haverá repositório separado para agentes ou specs.
A entidade clínica multiusuário do legado está fora de escopo até aprovação explícita; a propriedade de dados é individual.
Documentos completos e processamento de áudio podem permanecer indisponíveis até que retenção, armazenamento, consentimento e auditoria sejam aprovados.
A migração de dados de uma base legada para a base Prontuare é um trabalho posterior e não deve ser executada durante a paridade de contratos sem uma especificação própria aprovada.

Fora do escopo¶

Exclusão do monorepo legado ou das bases de dados existentes antes de a matriz de paridade estar completa e aprovada.
Entidade clínica, colaboração entre profissionais, permissões organizacionais ou cobrança real além do controle de direito para o limite gratuito.
Diagnóstico, recomendação, decisão clínica ou salvamento automático por IA.