Ditar laudo (texto) — Dictate Report Text
A funcionalidade Ditar Laudo — Texto Transcrito utiliza o microfone do navegador para transcrever a fala em texto e, em seguida, envia essa transcrição a um provider de IA para gerar um laudo estruturado, com base no contexto do exame e do paciente.
A funcionalidade está disponível na tela de laudário do portal legado: o usuário aciona o botão de microfone da IA, revisa/edita o texto transcrito e solicita a criação do laudo. O new viewer também pode disparar o mesmo endpoint/modal a partir da transcrição.
Para quem é
| Persona | Quem é | O que faz aqui |
|---|---|---|
| Usuário do laudário | quem acessa o exame no laudário | dita o conteúdo por voz, revisa a transcrição e gera o laudo com IA |
Permissão: diferente da RevisIA / ortografia / tradução, não há filtro por perfil GESTOR, PROPRIETARIO, MÉDICO ou RESIDENTE. Basta a configuração ativa. O botão não aparece se o usuário tiver IARA habilitada (
has_iaraetoken_iara).
Pré-requisitos
- Portal legado com laudário aberto para um exame.
- Termo de uso de IA aceito (unidade e/ou usuário, conforme escopo da configuração).
- Funcionalidade Dictate Reports Text (
dictate_reports_text) ativa e configurada:- na unidade — ver Configuração por empresa;
- no usuário — ver Configuração por usuário.
- Provider, modelo e token válidos para a funcionalidade.
- Navegador com SpeechRecognition (fluxo pensado para Google Chrome).
- Permissão de microfone concedida no navegador.
- Usuário sem IARA completa no perfil (sem
has_iara+token_iarajuntos). - Texto transcrito não vazio antes de clicar em criar laudo.
- Gravador de áudio não em gravação simultânea (
isRecordingdesabilita o botão).
Diagrama de sequência
Fluxo principal ao ditar e gerar o laudo:
Etapas
1. Abrir o laudário
Na lista de exames do portal legado, localize o exame e clique em Abrir Laudário.
2. Acionar a transcrição
Com o laudário aberto e a funcionalidade configurada, clique no botão de microfone (IA). O navegador solicita permissão de microfone (na primeira utilização) e inicia a captura de voz via SpeechRecognition (Chrome).
2.1 Transcrição ligada
Com a transcrição ligada, o microfone permanece ativo e o texto ditado é inserido automaticamente no campo de transcrição. O campo de texto fica bloqueado para digitação manual — apenas a fala é capturada.
Na primeira vez, o navegador exibe o prompt para permitir o uso do microfone; é necessário aceitar para o ditado funcionar.
2.2 Transcrição pausada
Ao pausar a transcrição, a captura de voz é interrompida e o campo de texto fica liberado para edição manual. Use este estado para revisar, corrigir ou complementar o texto antes de gerar o laudo. Retome o microfone quando quiser continuar ditando.
3. Criar o laudo a partir do texto
Revise o texto transcrito (edite manualmente com a transcrição pausada, conforme a etapa 2.2) e clique em Criar laudo IA. A interface envia a transcrição e o contexto do exame/paciente para a AI-API.
Dados enviados (exemplo):
| Grupo | Campos |
|---|---|
| Unidade | companyId |
| Transcrição | transcription (texto ditado) |
| Exame | descrição do estudo, preparação do estudo, modalidade |
| Paciente | sexo, idade |
| Idioma | language (pt-BR, es-ES, en-US) |
4. Visualizar resultado no modal
Após resposta bem-sucedida da API, um modal exibe:
- Laudo gerado — texto estruturado produzido pela IA a partir da transcrição;
- Observações — anotações retornadas pelo provider (quando houver).
5. Aplicar no documento (opcional)
No modal, o usuário pode adicionar ao laudo (insere o texto no editor), copiar, ou reformular a resposta com um novo prompt.
Campos / entradas
| Campo / origem | Descrição |
|---|---|
companyId | ID da unidade (empresa) |
transcription | Texto obtido da ditagem (campo audioEscreverIA; máx. 500 caracteres na UI) |
context.modality | Modalidade do exame |
context.studyDescription | Descrição do estudo |
context.studyPreparation | Preparação / marcações clínicas |
context.patient.sex | Sexo do paciente (M / F) |
context.patient.age | Idade do paciente |
language | Idioma da resposta (pt-BR, es-ES, en-US) |
Saída esperada
| Campo | Descrição |
|---|---|
dictatedReports[].body | Laudo gerado a partir da transcrição |
dictatedReports[].observations | Observações retornadas pela IA (quando houver) |
Endpoints utilizados
| Endpoint | Descrição |
|---|---|
AI_API POST /audio/dictated-report-transcribed | Envia a transcrição e o contexto do exame/paciente; retorna o laudo gerado. |
AI_API POST /reformulate/response | Reformula a resposta do modal com um novo prompt informado pelo usuário. |
→ Detalhe técnico: Dictate Report From Text — OpenAPI
Regras de negócio
| ID | Regra | Comportamento esperado |
|---|---|---|
| RN-01 | Navegador sem SpeechRecognition | Botão desabilitado (isCompativel falso), com tooltip orientando Chrome / uso do gravador. Transcrição não inicia. |
| RN-02 | Gravador em gravação | Botão do microfone IA desabilitado enquanto isRecording estiver ativo. |
| RN-03 | Usuário com IARA (has_iara + token_iara) | Botão da funcionalidade não é exibido. |
| RN-04 | Permissão de microfone negada | Toast de erro; ditagem não inicia. |
| RN-05 | Transcrição vazia ao criar laudo | Toast de erro; a IA não é chamada. |
| RN-06 | Configuração ausente / provider inválido | Toast via resolvedor de erros da IA (ou mensagem padrão de falha ao criar o laudo). |
| RN-07 | Reformular | Novo prompt não pode estar vazio. |
| RN-08 | Escopo | Portal legado; laudário (entrada principal deste doc). New viewer reutiliza o mesmo endpoint e modal. |
| RN-09 | Transcrição vazia no new viewer | Toast de atenção com chave distinta (NENHUMA_TRANSCRICAO_DETECTADA); no laudário usa NENHUM_AUDIO_DETECTADO. |
Mapeamento de erros
| Situação | Resposta da API | Comportamento |
|---|---|---|
| Navegador sem suporte a SpeechRecognition | Botão desabilitado (classe de indisponível) e tooltip indicando suporte no Chrome / uso do gravador. A ditagem não inicia. | |
| Permissão de microfone negada pelo navegador | Toast de erro: permissão de microfone negada. A ditagem não inicia. | |
| Erro ao consultar/acessar o microfone | Toast de erro: ocorreu um erro ao acessar o microfone. A ditagem não inicia. | |
| Clicar em Criar laudo IA com transcrição vazia | Toast de erro: nenhum áudio detectado. A IA não é chamada. | |
| API de geração a partir do texto falha (erro HTTP / integração) | AI_API POST /audio/dictated-report-transcribed | Toast de erro traduzido pelo resolvedor de erros da IA (ou mensagem padrão: não foi possível criar o laudo). O modal não abre. |
| Configuração da funcionalidade não encontrada (unidade) | AI_API POST /audio/dictated-report-transcribed | Toast de atenção indicando ausência de configuração na unidade. |
| Configuração da funcionalidade não encontrada (usuário) | AI_API POST /audio/dictated-report-transcribed | Toast de atenção indicando ausência de configuração do usuário. |
| Configuração de IA não encontrada (genérico / companyId) | AI_API POST /audio/dictated-report-transcribed | Toast de atenção dizendo que a configuração não foi encontrada. |
| Provider/modelo inválido ou descontinuado | AI_API POST /audio/dictated-report-transcribed | Toast de erro específico de modelo inválido/descontinuado (pode citar o modelo). |
| Token / chave de API inválida ou rejeitada pelo provider | AI_API POST /audio/dictated-report-transcribed | Toast de erro da integração IA (título pode incluir o provider). |
| Erro genérico do provider / BadRequest | AI_API POST /audio/dictated-report-transcribed | Toast com a mensagem tratada pelo resolvedor (ou a mensagem bruta do provider, conforme o tipo). |
| Timeout / job da IA estoura (pooling) | AI_API POST /audio/dictated-report-transcribed | Toast de erro de operação / timeout do processamento. |
| Reformular resposta com prompt vazio | Toast de atenção: o novo prompt não pode estar vazio. Nada é enviado. | |
Reformular resposta — erro do provider (AI_PROVIDER_ERROR) | AI_API POST /reformulate/response | Toast via resolvedor de erros da IA (fallback: não foi possível reformular o laudo). O conteúdo do modal não muda. |
| Reformular resposta — demais falhas HTTP / integração | AI_API POST /reformulate/response | Toast de erro com mensagem padrão: não foi possível reformular o laudo. O conteúdo do modal não muda. |