Especificação da funcionalidade: atendimentos com áudio, chat e Markdown¶

Branch da funcionalidade: Não criada — especificação em elaboração

Criado em: 2026-08-13

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

Entrada: Evoluir a tela de atendimentos para exibir todos os atendimentos completos em sequência, permitir escrita em editor Markdown, receber áudio por gravação ou arquivo e oferecer um chat de IA que ajude a construir um rascunho revisável do prontuário.

Objetivo do produto¶

Reduzir o esforço do psicólogo para registrar e consultar atendimentos sem esconder o histórico clínico. A tela deve funcionar como uma linha do tempo legível: o profissional percorre todos os atendimentos completos rolando a página, registra conteúdo estruturado em Markdown e pode usar áudio e conversa com IA para produzir um rascunho. Nada produzido pela IA se torna prontuário sem revisão e confirmação explícita do profissional.

Escopo¶

Dentro do escopo¶

Linha do tempo cronológica com todos os atendimentos do paciente e conteúdo completo na própria tela.
Criação e edição de atendimento com recursos de Markdown e visualização fiel do conteúdo salvo.
Preservação e consulta do histórico de versões de cada atendimento.
Upload de arquivo de áudio e gravação pelo microfone, com consentimento explícito antes do envio.
Estados visíveis de captura, upload, processamento, conclusão, cancelamento e falha.
Conversão do áudio em insumo textual para um rascunho de atendimento.
Chat contextual de IA para iniciar, complementar, corrigir e reorganizar o rascunho.
Transferência controlada do rascunho da IA para o editor, sem salvamento clínico automático.
Cancelamento pelo profissional e retenção limitada de áudio, transcrição, mensagens e sugestões.
Autorização por proprietário, paciente e CRP em todas as operações.
Cobertura automatizada e validação real de navegador dos fluxos de texto, áudio e chat.

Fora do escopo¶

Diagnóstico, prescrição, decisão clínica ou recomendação autônoma pela IA.
Gravação oculta, contínua ou iniciada sem uma ação direta do profissional.
Salvamento automático de uma sugestão da IA como prontuário definitivo.
Compartilhamento do áudio, transcrição ou chat com pacientes ou terceiros.
Videoconferência, chamadas em tempo real ou captura de áudio fora da página ativa.
Importação de áudio a partir de links externos.
Alteração retroativa de versões clínicas já registradas.

Cenários de usuário e testes (obrigatório)¶

História de usuário 1 - Consultar a linha do tempo completa (Prioridade: P1)¶

O psicólogo acessa a área de atendimentos e encontra todos os registros do paciente exibidos por completo, do mais recente para o mais antigo. Para recordar o atendimento anterior, basta continuar rolando a página, sem abrir cartões, modais ou páginas de detalhe.

Motivo da prioridade: A consulta longitudinal é o uso central da tela e precisa funcionar mesmo sem IA ou áudio.

Teste independente: Criar três atendimentos com conteúdos extensos e confirmar que os três textos completos, datas e versões aparecem em uma única página e na ordem correta.

Cenários de aceitação:

Dado um paciente com vários atendimentos, Quando o profissional abre a tela, Então todos aparecem completos do mais recente para o mais antigo.
Dado um atendimento longo, Quando ele é exibido na linha do tempo, Então seu conteúdo não é truncado e mantém títulos, listas, ênfases e demais estruturas Markdown.
Dado que um atendimento possui revisões, Quando o profissional abre seu histórico, Então todas as versões permanecem consultáveis sem substituir a versão atual na linha do tempo.
Dado que há muitos atendimentos, Quando a tela é carregada, Então o profissional consegue começar a leitura em até três segundos e carregar registros adicionais sem perder a posição de rolagem.

História de usuário 2 - Escrever e revisar em Markdown (Prioridade: P1)¶

O psicólogo cria ou edita um atendimento em um editor visual compatível com Markdown. Ele pode estruturar o registro com títulos, parágrafos, listas, citações, links e formatação básica, alternando entre edição e leitura sem perder conteúdo.

Motivo da prioridade: O editor é a fonte final do prontuário e deve ser confiável independentemente da origem manual, por áudio ou por IA.

Teste independente: Criar um atendimento usando cada estrutura suportada, salvar, recarregar e editar; o conteúdo e a representação Markdown devem permanecer equivalentes.

Cenários de aceitação:

Dado um novo atendimento, Quando o profissional escreve conteúdo formatado e salva, Então o Markdown persistido reproduz a mesma estrutura após recarregar.
Dado um atendimento existente, Quando o profissional o edita e salva, Então uma nova versão é criada e a anterior permanece disponível.
Dado conteúdo ainda não salvo, Quando o profissional tenta cancelar ou sair, Então recebe um aviso antes de perder alterações.
Dado conteúdo Markdown potencialmente inseguro, Quando ele é exibido, Então scripts e elementos executáveis não são executados.

História de usuário 3 - Enviar ou gravar áudio (Prioridade: P1)¶

O psicólogo escolhe um arquivo de áudio ou inicia uma gravação na própria tela. Antes da captura ou envio, confirma que possui consentimento adequado. Ele acompanha duração, tamanho e estado do processamento, podendo interromper ou descartar antes de aplicar o resultado.

Motivo da prioridade: Áudio é a principal nova forma de entrada e envolve dados clínicos altamente sensíveis.

Teste independente: Processar um arquivo sintético e uma gravação curta, confirmar os estados e obter texto utilizável; também negar microfone, cancelar e enviar formato inválido.

Cenários de aceitação:

Dado consentimento não confirmado, Quando o profissional tenta gravar ou enviar áudio, Então a operação permanece bloqueada e explica o requisito.
Dado consentimento confirmado e microfone permitido, Quando inicia e encerra uma gravação, Então pode ouvi-la, descartá-la ou enviá-la para processamento.
Dado um arquivo de áudio suportado, Quando é selecionado, Então nome, tipo, tamanho e duração são apresentados antes do envio.
Dado microfone negado, formato inválido, arquivo vazio, tamanho excessivo ou falha de rede, Quando ocorre a tentativa, Então nenhum prontuário é alterado e uma orientação acionável é exibida com identificador de suporte quando aplicável.
Dado áudio em processamento, Quando o profissional atualiza ou retorna à página, Então o estado é recuperado sem novo envio duplicado.
Dado processamento concluído, Quando o texto fica disponível, Então ele entra como insumo do rascunho e nunca como prontuário salvo automaticamente.

História de usuário 4 - Construir o rascunho em chat com IA (Prioridade: P2)¶

O psicólogo inicia uma conversa descrevendo o que deseja registrar, opcionalmente usando a transcrição do áudio. A IA faz perguntas quando faltam informações e propõe Markdown revisável. O profissional pode continuar conversando, solicitar ajustes e aplicar uma versão escolhida ao editor.

Motivo da prioridade: O chat torna a IA iterativa e controlável, mas depende do editor seguro e do processamento de áudio.

Teste independente: Iniciar um chat com dados sintéticos, responder a uma pergunta, pedir uma correção, recarregar a página e aplicar o rascunho ao editor sem salvar o atendimento automaticamente.

Cenários de aceitação:

Dado um atendimento em edição, Quando o profissional inicia o chat, Então vê claramente que a saída é uma sugestão de IA sujeita a revisão.
Dado contexto insuficiente, Quando a IA processa a solicitação, Então pode apresentar perguntas objetivas antes de propor o texto.
Dado uma conversa existente, Quando o profissional envia nova instrução, Então mensagens anteriores relevantes e o rascunho atual são considerados sem misturar dados de outro paciente.
Dado um rascunho proposto, Quando o profissional escolhe aplicá-lo, Então o conteúdo vai para o editor e ainda exige a ação separada de salvar o atendimento.
Dado que o profissional cancela a geração, Quando o cancelamento é confirmado, Então o processamento deixa de alterar o rascunho e o conteúdo manual do editor é preservado.
Dado indisponibilidade do provedor, Quando uma mensagem é enviada, Então a conversa e o texto manual permanecem recuperáveis e o produto oferece nova tentativa sem duplicar mensagens.

Casos de borda¶

Dois envios consecutivos do mesmo áudio não podem criar processamentos duplicados silenciosamente.
O navegador pode suspender a aba ou trocar o dispositivo de microfone durante a gravação.
Uma gravação pode terminar sem dados, exceder o limite ou usar tipo de mídia não reconhecido.
O profissional pode fechar a página com gravação ativa, upload incompleto, chat processando ou editor alterado.
O paciente pode ser desativado ou mudar de escopo CRP enquanto um processamento está em andamento.
Uma resposta atrasada da IA não pode sobrescrever alterações posteriores feitas manualmente.
Mensagens vazias, excessivamente longas ou repetidas devem ser recusadas sem erro interno.
A linha do tempo deve tratar ausência de atendimentos, centenas de registros e conteúdo Markdown antigo.

Requisitos (obrigatório)¶

Requisitos funcionais¶

FR-001: A tela de atendimentos DEVE exibir o conteúdo completo de todos os atendimentos acessíveis do paciente em uma linha do tempo do mais recente para o mais antigo.
FR-002: A linha do tempo DEVE preservar a posição de leitura ao carregar registros adicionais e DEVE oferecer acesso ao histórico de versões de cada atendimento.
FR-003: Criação e edição DEVEM usar um editor visual compatível com Markdown, com títulos, parágrafos, ênfase, listas, citações, links, desfazer/refazer e atalhos básicos.
FR-004: O conteúdo Markdown DEVE ser persistido sem perda semântica e exibido de forma segura, sem execução de conteúdo ativo.
FR-005: Toda revisão salva DEVE criar uma versão auditável, preservando autor, data clínica, instante da alteração e conteúdo anterior.
FR-006: O profissional DEVE confirmar consentimento antes de qualquer gravação ou upload de áudio.
FR-007: O produto DEVE permitir gravação de microfone com duração visível, pausa/encerramento, reprodução local, descarte e envio explícito.
FR-008: O produto DEVE permitir selecionar arquivos de áudio suportados e validar tipo, tamanho, conteúdo vazio e duração antes do envio.
FR-009: Upload e processamento DEVEM apresentar progresso e estados recuperáveis de aguardando, enviando, processando, concluído, cancelado e falhou.
FR-010: Repetições por reconexão ou duplo clique NÃO DEVEM criar ingestões duplicadas para a mesma tentativa.
FR-011: A transcrição e demais resultados do áudio DEVEM permanecer como material de rascunho até revisão explícita.
FR-012: O chat DEVE manter mensagens do profissional e da IA vinculadas a um único rascunho, paciente, proprietário e escopo profissional.
FR-013: A IA DEVE poder formular perguntas, propor Markdown e revisar uma proposta a partir de instruções subsequentes.
FR-014: Aplicar uma sugestão DEVE apenas atualizar o editor; salvar o prontuário DEVE continuar sendo uma ação separada e explícita.
FR-015: O produto DEVE impedir que respostas atrasadas sobrescrevam texto manual ou uma versão mais recente do rascunho sem confirmação.
FR-016: O profissional DEVE poder cancelar processamento e chat, preservando o conteúdo manual já escrito.
FR-017: Áudio, transcrição, conversa e sugestões DEVEM ter prazo de retenção explícito, expirar de forma verificável e nunca aparecer em logs operacionais.
FR-018: Toda operação DEVE validar sessão, propriedade do paciente e escopo CRP; acesso cruzado DEVE responder sem revelar existência de dados.
FR-019: Falhas esperadas DEVEM retornar mensagem segura e acionável, código estável e identificador de requisição; nenhuma validação do usuário pode resultar em erro interno genérico.
FR-020: Eventos de consentimento, ingestão, processamento, aplicação de sugestão, cancelamento e salvamento clínico DEVEM ser auditáveis sem armazenar conteúdo clínico no evento.
FR-021: A interface DEVE distinguir visualmente conteúdo manual, transcrição e sugestão da IA durante todo o fluxo.
FR-022: A funcionalidade DEVE ser utilizável por teclado e comunicar estados de gravação, progresso, erro e conclusão a tecnologias assistivas.

Entidades principais¶

Atendimento: registro clínico final de um paciente, com data clínica, conteúdo Markdown atual, autoria, escopo profissional e histórico de versões.
Versão do atendimento: fotografia imutável de cada salvamento do atendimento.
Rascunho assistido: espaço temporário que reúne instrução, estado, perguntas, sugestão Markdown e controle de concorrência antes do salvamento clínico.
Mensagem do rascunho: contribuição do profissional ou resposta da IA em uma conversa pertencente a um rascunho.
Ingestão de áudio: tentativa de gravação ou upload com consentimento, metadados, estado, prazo de retenção e vínculo opcional ao rascunho.
Transcrição: texto temporário derivado de uma ingestão, identificado como não revisado e nunca equivalente ao prontuário final.
Evento de auditoria: registro sem conteúdo clínico que comprova ações sensíveis e seus resultados.

Critérios de sucesso (obrigatório)¶

Resultados mensuráveis¶

SC-001: Em uma conta de teste com 50 atendimentos, o conteúdo dos primeiros registros fica disponível para leitura em até três segundos e registros adicionais carregam sem deslocar a posição atual.
SC-002: 100% das estruturas Markdown suportadas permanecem semanticamente equivalentes após criar, salvar, recarregar e revisar um atendimento.
SC-003: Um profissional consegue iniciar, encerrar, revisar e enviar uma gravação curta em até dois minutos, sem instrução externa.
SC-004: 100% dos cenários de microfone negado, arquivo inválido, upload interrompido e provedor indisponível preservam o texto manual e apresentam recuperação sem erro interno genérico.
SC-005: Nenhuma transcrição ou sugestão de IA é persistida como atendimento sem uma ação explícita de aplicação ao editor seguida de outra ação explícita de salvamento.
SC-006: Depois de recarregar a página durante processamento, o estado correto é recuperado em até cinco segundos e não surge uma ingestão duplicada.
SC-007: Nos testes de autorização, 100% das tentativas entre usuários, pacientes ou CRPs diferentes são bloqueadas sem exposição de dados.
SC-008: Uma conversa com ao menos três interações pode ser retomada após recarregar e aplicar sua proposta ao editor sem perda de mensagens ou do conteúdo manual.

Premissas e dependências¶

A conta já está autenticada, possui perfil profissional e CRP apto para operações clínicas.
Navegadores modernos oferecem captura de microfone; upload permanece disponível quando a permissão é negada.
A primeira versão aceita formatos de áudio comuns de navegador e arquivos amplamente suportados, com limites visíveis antes do envio.
O prazo exato de retenção é configurado operacionalmente e exibido ao profissional antes do consentimento; ao expirar, áudio, transcrição, mensagens e sugestões temporárias são removidos.
A sugestão usa apenas o paciente atual e o conteúdo que o profissional decidiu fornecer no rascunho; acesso indiscriminado a todo o prontuário não é presumido.
O editor final solicitado pelo responsável do produto será integrado pelo componente oficial indicado durante o planejamento técnico.
Processamento de áudio e IA dependem de provedores configurados; ambiente local usa implementações determinísticas para testes e nunca envia dados clínicos reais.