Gerador de Laudos por Imagens Anexas — Generate Report With Attachment
A funcionalidade Gerador de Laudos por Imagens Anexas utiliza um provider de IA para gerar um laudo estruturado a partir do link de um anexo (imagem de exame) e do contexto do exame/paciente.
Está disponível no modal de anexos aberto a partir do laudário ou do viewer do portal legado. O botão Gerar laudo com IA só é exibido quando a funcionalidade está configurada e ativa e o anexo selecionado é do tipo Imagens do Exame — para demais tipos de anexo, o botão não aparece.
Os dois fluxos compartilham o mesmo endpoint, modal de resultado e opção de aplicar no editor; apenas o caminho de acesso ao modal de anexos difere.
Para quem é
| Persona | Quem é | O que faz aqui |
|---|---|---|
| Usuário do laudário | quem edita o exame no laudário | abre anexos pelo laudário, seleciona imagem de exame e gera o laudo com IA |
| Usuário do viewer | quem visualiza o exame no viewer | abre anexos pelo viewer, seleciona imagem de exame 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, estar no contexto de laudo (
isReport) e o anexo ativo ser do tipo Imagens do Exame (classificacao_anexos == 2).
Visibilidade do botão: no modal de anexos (laudário ou viewer), Gerar laudo com IA só aparece se a funcionalidade estiver configurada e o anexo em foco for Imagens do Exame. Anexos de outros tipos não exibem o botão, mesmo com a IA habilitada.
Pré-requisitos
- Portal legado com laudário ou viewer aberto para um exame.
- Modal de anexos aberto a partir do laudário (
isReport/is-laudo) ou do viewer integrado ao laudário. - Termo de uso de IA aceito (unidade e/ou usuário, conforme escopo da configuração).
- Funcionalidade Generate Report With Attachment (
generate_report_with_attachment) 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.
- Anexo ativo do tipo Imagens do Exame (
classificacao_anexos == 2), comidelinkválidos.
Diagrama de sequência
Fluxo compartilhado após abrir o modal de anexos:
Etapas
Dois fluxos de geração: Através da interface do laudário e através da interface do Viewer:
Fluxo pelo laudário
1. Abrir o laudário
Na lista de exames do portal legado, localize o exame e clique em Abrir Laudário.
2. Abrir anexos e selecionar imagem de exame
Com o laudário aberto, acione o botão de anexos e selecione um anexo do tipo Imagens do Exame. Somente nesse tipo o botão Gerar laudo com IA é exibido.
3. Gerar o laudo a partir do anexo
Clique em Gerar laudo com IA. A interface valida o anexo, monta o contexto do exame/paciente e:
- se já existir laudo em cache (mesmo anexo, usuário e idioma), reabre o modal com esse conteúdo; ou
- envia a requisição para a AI-API.
Enquanto a geração está em andamento, o botão fica desabilitado (loading).
4. Visualizar resultado no modal
Após resposta bem-sucedida (ou cache), um modal exibe o laudo gerado e observações (quando houver).
5. Aplicar no documento (opcional)
No modal, o usuário pode usar este laudo no editor do laudário, copiar, ou reformular a resposta com um novo prompt.
Fluxo pelo viewer
1. Abrir o viewer
Na listagem de exames, abra o exame no viewer integrado ao laudário.
2. Abrir anexos e selecionar imagem de exame
No viewer, acione o botão de anexos e selecione um anexo do tipo Imagens do Exame. As mesmas regras de visibilidade do botão Gerar laudo com IA se aplicam.
3. Gerar o laudo a partir do anexo
Clique em Gerar laudo com IA — mesmo comportamento de validação, cache e chamada à AI-API descrito no fluxo pelo laudário.
4. Visualizar resultado no modal
5. Aplicar no documento (opcional)
O laudo pode ser aplicado no editor do laudário (expandido à direita do viewer), copiado ou reformulado.
Dados enviados (exemplo) — comum aos dois fluxos:
| Grupo | Campos |
|---|---|
| Unidade | companyId |
| Idioma | language (pt-BR, es-ES, en-US) |
| Anexo | attachment[].id, attachment[].attachmentLink |
| Exame | modalidade, descrição do estudo, preparação (marcações clínicas) |
| Paciente | sexo, idade |
Campos / entradas
| Campo / origem | Descrição |
|---|---|
companyId | ID da unidade (empresa) |
language | Idioma da resposta (pt-BR, es-ES, en-US) |
attachment[].id | ID do anexo ativo |
attachment[].attachmentLink | URL/link do anexo |
attachment[].context.modality | Modalidade do exame |
attachment[].context.studyDescription | Descrição do estudo |
attachment[].context.studyPreparation | Marcações clínicas do exame |
attachment[].context.patient.sex | Sexo do paciente (M / F) |
attachment[].context.patient.age | Idade do paciente |
Saída esperada
| Campo | Descrição |
|---|---|
generatedReports[].body | Laudo gerado a partir do anexo |
generatedReports[].observations | Observações retornadas pela IA (quando houver) |
No modal, o item generatedReports[0] é expandido como body / observations (método generate_report_with_attachment_ai).
Endpoints utilizados
| Endpoint | Descrição |
|---|---|
AI_API POST /report/attachment | Envia o link do anexo 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: Generate Report With Image Link — OpenAPI
Regras de negócio
| ID | Regra | Comportamento esperado |
|---|---|---|
| RN-01 | Fora do contexto de laudo | Botão não aparece (isReport falso) — vale para anexos abertos pelo laudário ou pelo viewer. |
| RN-02 | Anexo não é Imagens do Exame | Botão não aparece (classificacao_anexos != 2). |
| RN-03 | Configuração inativa | Botão não aparece (hasGenerateReportWithAttachment falso). |
| RN-04 | Anexo sem link ou id | Toast de erro; a IA não é chamada. |
| RN-05 | Geração já em andamento | Nova ação é ignorada (isGeneratingReportFromAttachmentAI). |
| RN-06 | Cache hit | Modal abre com laudo cacheado; não chama a AI-API. |
| RN-07 | Resposta sem generatedReports[0] | Toast de erro; o modal não abre. |
| RN-08 | Reformular | Novo prompt não pode estar vazio. |
| RN-09 | Escopo | Portal legado; modal de anexos no laudário ou no viewer. |
Mapeamento de erros
| Situação | Resposta da API | Comportamento |
|---|---|---|
Anexo sem link ou id | Toast de erro: não foi possível obter as informações do anexo necessárias para gerar o laudo. A IA não é chamada. | |
API retorna sucesso sem generatedReports[0] | AI_API POST /report/attachment | Toast de erro: não foi possível gerar o laudo a partir do anexo. O modal não abre. |
| API de geração falha (erro HTTP / integração) | AI_API POST /report/attachment | Toast de erro traduzido pelo resolvedor de erros da IA (ou mensagem padrão: não foi possível gerar o laudo a partir do anexo). O modal não abre. |
| Configuração da funcionalidade não encontrada (unidade) | AI_API POST /report/attachment | Toast de atenção indicando ausência de configuração na unidade. |
| Configuração da funcionalidade não encontrada (usuário) | AI_API POST /report/attachment | 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 /report/attachment | Toast de atenção dizendo que a configuração não foi encontrada. |
| Provider/modelo inválido ou descontinuado | AI_API POST /report/attachment | 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 /report/attachment | Toast de erro da integração IA (título pode incluir o provider). |
| Erro genérico do provider / BadRequest | AI_API POST /report/attachment | 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 /report/attachment | Toast de erro de operação / timeout do processamento. |
| Confirmar “Usar este” sem conteúdo válido no retorno do modal | Toast de erro: não foi possível adicionar o laudo gerado ao editor. | |
| Falha ao abrir/fechar a janela do modal de IA | Toast de erro: ocorreu um erro ao abrir ou fechar a janela. | |
| Reformular resposta com prompt vazio | Toast de atenção: o novo prompt não pode estar vazio. Nada é enviado. | |
Reformular resposta — resposta vazia / sem response | AI_API POST /reformulate/response | Toast de erro: não foi possível reformular o laudo. O conteúdo do modal permanece o anterior. |
| Reformular resposta — API falha | AI_API POST /reformulate/response | Toast de erro traduzido pelo resolvedor de erros da IA (ou mensagem padrão: não foi possível reformular o laudo). O conteúdo do modal não muda. |