Ditar laudo (áudio) — Dictate Report Audio
A funcionalidade Ditar Laudo — Áudio utiliza o gravador do laudário para capturar um arquivo de áudio e enviá-lo a um provider de IA, que gera um laudo estruturado com base no áudio e no contexto do exame e do paciente.
A funcionalidade está disponível na tela de laudário do portal legado, no painel Gravador de voz: o usuário inicia a gravação pelo microfone, interrompe quando terminar o ditado e, então, clica em Criar laudo com IA para enviar o áudio ao provider. O new viewer também pode disparar o mesmo endpoint/modal a partir do áudio gravado.
Para quem é
| Persona | Quem é | O que faz aqui |
|---|---|---|
| Usuário do laudário | quem acessa o exame no laudário | grava o áudio no gravador 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 e um áudio gravado. Diferente do Dictate Report Text, o botão desta funcionalidade não é ocultado por 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 Audio (
dictate_reports_audio) 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.
- Permissão de microfone concedida no navegador (gravador).
- Áudio gravado disponível (
audioBlob); sem gravação, o botão Criar laudo com IA permanece desabilitado.
Diagrama de sequência
Fluxo principal ao gravar 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. Gravar e enviar o áudio
Com o laudário aberto e a funcionalidade configurada, use o painel Gravador de voz na barra lateral do laudário. O fluxo tem três ações: iniciar a gravação, interromper quando concluir o ditado e enviar o áudio para a IA.
2.1 Iniciar a gravação
Clique no botão de microfone no gravador para iniciar a captura de áudio. Na primeira utilização, o navegador solicita permissão de microfone — é necessário aceitar para gravar.
Enquanto a gravação não for concluída, o botão Criar laudo com IA permanece desabilitado (ícone de IA acinzentado).
2.2 Interromper a gravação
Com a gravação em andamento, clique novamente no botão de microfone (ou no controle equivalente do gravador) para interromper a captura. O áudio fica disponível no player do gravador; somente após interromper é possível prosseguir para o envio à IA.
2.3 Enviar o áudio para a IA
Após interromper a gravação, o gravador exibe a duração do áudio capturado (por exemplo, 0:00 / 0:02). O botão Criar laudo com IA é habilitado — clique nele para enviar o arquivo de áudio (multipart/form-data) e o contexto do exame/paciente para a AI-API.
Enquanto a geração está em andamento, o botão fica desabilitado (loading).
Dados enviados (exemplo):
| Grupo | Campos |
|---|---|
| Áudio | audio (arquivo audio.wav) |
| Unidade | companyId |
| Usuário | userId |
| Exame | studyDescription, studyPreparation, modality |
| Paciente | patientSex, patientAge |
| Idioma | language (pt-BR, es-ES, en-US) |
3. Visualizar resultado no modal
Após resposta bem-sucedida da API, um modal exibe:
- Laudo gerado — texto estruturado produzido pela IA a partir do áudio;
- Observações — anotações retornadas pelo provider (quando houver).
O áudio do gravador é limpo após o sucesso da geração.
4. 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 |
|---|---|
audio | Arquivo de áudio gravado (FormData, nome audio.wav) |
companyId | ID da unidade (empresa) — também no path da URL |
userId | ID do usuário logado |
modality | Modalidade do exame |
studyDescription | Descrição do estudo |
studyPreparation | Preparação / marcações clínicas (JSON) |
patientSex | Sexo do paciente (M / F) |
patientAge | 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 do áudio |
dictatedReports[].observations | Observações retornadas pela IA (quando houver) |
Endpoints utilizados
| Endpoint | Descrição |
|---|---|
AI_API POST /audio/dictated-report-audio/{companyId} | Envia o áudio (multipart) 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 With Audio — OpenAPI
Regras de negócio
| ID | Regra | Comportamento esperado |
|---|---|---|
| RN-01 | Sem áudio gravado | Botão Criar laudo com IA permanece desabilitado (ng-if exige audioBlob). |
| RN-02 | Chamada sem audioBlob | A função retorna em silêncio; a IA não é chamada (sem toast específico). |
| RN-03 | Permissão de microfone negada no gravador | Toast de erro; a gravação não inicia / não gera blob. |
| RN-04 | Configuração ausente / provider inválido | Toast via resolvedor de erros da IA (ou mensagem padrão de falha ao criar o laudo). |
| RN-05 | Sucesso na geração | Modal abre; áudio do gravador é removido (clique no botão de delete do gravador). |
| RN-06 | Reformular | Novo prompt não pode estar vazio. |
| RN-07 | Escopo | Portal legado; laudário (entrada principal deste doc). New viewer reutiliza o mesmo endpoint e modal (audio_transcription_ai). |
| RN-08 | Sem blob no new viewer | Toast de erro (NENHUM_AUDIO_DETECTADO); no laudário a chamada sem blob retorna em silêncio. |
Mapeamento de erros
| Situação | Resposta da API | Comportamento |
|---|---|---|
| Permissão de microfone negada no gravador (legado) | Toast de erro: permissão de microfone negada. A gravação não inicia; o botão de criar laudo IA não aparece. | |
| Erro ao buscar microfone (gravador novo) | Toast de erro ao buscar microfone. Sem dispositivo/gravação, não há audioBlob. | |
| Erro ao iniciar gravação (gravador novo) | Toast de erro ao iniciar gravação. Sem audioBlob, o botão de criar laudo IA não aparece. | |
| Sem áudio / botão indisponível | Botão oculto ou desabilitado. Se a ação for chamada sem blob, retorna sem toast e sem chamada à IA. | |
| API de geração a partir do áudio falha (erro HTTP / integração) | AI_API POST /audio/dictated-report-audio/{companyId} | 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-audio/{companyId} | 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-audio/{companyId} | 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-audio/{companyId} | 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-audio/{companyId} | 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-audio/{companyId} | 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-audio/{companyId} | 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-audio/{companyId} | 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. |