Gerador de laudos por imagens — Check Image
A funcionalidade Gerador de laudos por imagens (check_image) utiliza um provider de IA para analisar imagens capturadas no viewer e gerar um laudo estruturado, com base no contexto do exame e do paciente.
O fluxo ocorre no new viewer (iframe) integrado ao portal legado: o usuário seleciona imagens agrupadas por série (até 12 no total), aciona o botão de IA em qualquer imagem selecionada e o portal envia o conjunto via postMessage, chama a AI-API e insere o HTML gerado diretamente no editor do laudário (TinyMCE), com o painel de laudo expandido à direita do viewer. Não há modal de IA nem reformulação neste fluxo.
A configuração é por modalidade (MR, CT, CR, DX, etc.): o escopo enviado na requisição é scope-type: modality e scope-value igual à modalidade do exame.
Para quem é
| Persona | Quem é | O que faz aqui |
|---|---|---|
| Gestor | perfil administrativo da unidade | gera laudo a partir das imagens no viewer |
| Proprietário | perfil com acesso ampliado | gera laudo a partir das imagens no viewer |
| Médico | radiologista / laudador | gera sugestão de laudo pelas imagens e revisa no editor |
| Residente | médico em formação | gera sugestão de laudo pelas imagens, conforme permissões |
Permissão: exige perfil GESTOR, PROPRIETARIO, MEDICO ou RESIDENTE. Demais perfis recebem aviso e a IA não é chamada.
Pré-requisitos
- Portal legado com new viewer aberto para um exame (com laudário disponível para receber o conteúdo).
- Perfil GESTOR, PROPRIETARIO, MÉDICO ou RESIDENTE.
- Termo de uso de IA aceito (unidade e/ou usuário, conforme escopo da configuração).
- Funcionalidade Check Image (
check_image) ativa e configurada para a modalidade do exame:- na unidade — ver Configuração por empresa;
- no usuário — ver Configuração por usuário.
- Provider, modelo e token válidos para a modalidade.
- Entre 1 e 12 imagens selecionadas no viewer (total entre todas as séries).
- Editor do laudário carregado (para aplicar o resultado).
Diagrama de sequência
Fluxo principal — seleção de imagens e geração do laudo:
Diferença em relação às funcionalidades do laudário: não abre
modalMobileIAe não chamaPOST /reformulate/response.
Etapas
1. Abrir o new viewer
Na listagem de exames do portal legado, abra o exame no new viewer integrado ao laudário.
2. Selecionar imagens no viewer
As imagens do exame são organizadas em séries — cada série contém uma ou mais imagens. Use a barra lateral e a área de exibição para escolher quais imagens enviar à IA (entre 1 e 12 no total).
2.1 Agrupamento por séries
O agrupamento é feito por série: cada série possui uma ou mais imagens. As séries são listadas na barra lateral esquerda, com um checkbox que, quando marcado, seleciona todas as imagens daquela série de uma vez.
2.2 Dividir a exibição
O usuário pode dividir a exibição das imagens de uma mesma série em múltiplos painéis, facilitando a visualização e a seleção individual.
2.3 Selecionar uma série inteira
Ao marcar o checkbox ou selecionar todas as imagens de uma série, a série correspondente fica marcada na barra lateral.
2.4 Selecionar entre séries
Imagens de duas ou mais séries podem ser selecionadas — totalmente (série inteira) ou parcialmente (apenas algumas imagens de cada série), respeitando o limite de 12 imagens no total.
3. Acionar a IA e receber o laudo no editor
Com uma ou mais imagens selecionadas, clique no botão de IA exibido em qualquer imagem marcada — todas as imagens selecionadas (até 12) serão enviadas juntas.
O portal valida permissão e quantidade. Se houver cache para o conjunto de imageIds (ordenado), o idioma e o usuário, reutiliza o HTML; caso contrário, monta FormData e chama a AI-API com escopo de modalidade.
Após resposta bem-sucedida (ou cache), o HTML de check[0].body é inserido diretamente no editor do laudário (TinyMCE) e o painel de laudo é expandido à direita do viewer — sem modal de IA.
Dados enviados (exemplo):
| Grupo | Campos |
|---|---|
| Imagens | images (blobs PNG), imagesMeta (JSON com imageId, série, índice, etc.) |
| Unidade / usuário | companyId, userId |
| Exame | modality, studyDescription, studyPreparation |
| Paciente | patientSex, patientAge |
| Idioma | language (pt-BR, es-ES, en-US) |
| Headers de escopo | scope-type: modality, scope-value: <modalidade> |
Campos / entradas
| Campo / origem | Descrição |
|---|---|
images | Arquivos de imagem capturados no viewer (FormData) |
imagesMeta | Metadados das imagens (JSON) |
companyId | ID da unidade — também no path da URL |
userId | ID do usuário logado |
modality | Modalidade do exame (define o escopo da config IA) |
studyDescription | Descrição do estudo |
studyPreparation | 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 |
|---|---|
check[].body | HTML do laudo gerado a partir das imagens (aplicado no editor) |
Endpoints utilizados
| Endpoint | Descrição |
|---|---|
AI_API POST /check/images/{companyId} | Envia imagens (multipart) e contexto do exame/paciente; retorna o laudo em check[].body. |
→ Detalhe técnico: Check Images — OpenAPI
Regras de negócio
| ID | Regra | Comportamento esperado |
|---|---|---|
| RN-01 | Perfil sem permissão | Toast de atenção; a IA não é chamada. |
| RN-02 | Nenhuma imagem selecionada | Toast de atenção; a IA não é chamada. |
| RN-03 | Mais de 12 imagens | Toast de atenção; a IA não é chamada. |
| RN-04 | Cache hit | Insere HTML cacheado no editor; não chama a AI-API. |
| RN-05 | Resposta sem check[0].body | Toast de erro; nada é aplicado no editor. |
| RN-06 | Laudo/editor não carregado | Toast de atenção; o conteúdo não é aplicado. |
| RN-07 | Configuração ausente (CONFIGURATION_NOT_FOUND) | Toast específico de gerador indisponível (não usa as mensagens genéricas de unidade/usuário). |
| RN-08 | Escopo | New viewer + laudário; sem modal e sem reformular. |
| RN-09 | Configuração | Por modalidade (check_image + scope_value). |
Mapeamento de erros
| Situação | Resposta da API | Comportamento |
|---|---|---|
| Perfil sem permissão (fora de GESTOR/PROPRIETARIO/MEDICO/RESIDENTE) | Toast de atenção: gerador de laudos por imagens por IA não disponível. A IA não é chamada. | |
| Viewer não enviou imagens / nenhuma selecionada | Toast de atenção: não foi possível capturar as imagens para realizar a análise com IA. | |
| Mais de 12 imagens | Toast de atenção: só é possível analisar até doze imagens. | |
API retorna sucesso sem check[0].body | AI_API POST /check/images/{companyId} | Toast de erro: não foi possível analizar as imagens com IA. Nada é aplicado no editor. |
| API de verificação falha (erro HTTP / integração) | AI_API POST /check/images/{companyId} | Toast de erro traduzido pelo resolvedor de erros da IA (ou mensagem padrão: não foi possível analizar as imagens com IA). |
| Configuração da funcionalidade não encontrada | AI_API POST /check/images/{companyId} | Toast de atenção: gerador de laudos por imagens por IA não disponível (caso especial de CONFIGURATION_NOT_FOUND para check_image). |
| Provider/modelo inválido ou descontinuado | AI_API POST /check/images/{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 /check/images/{companyId} | Toast de erro da integração IA (título pode incluir o provider). |
| Erro genérico do provider / BadRequest | AI_API POST /check/images/{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 /check/images/{companyId} | Toast de erro de operação / timeout do processamento. |
| Laudo/editor ainda não carregado ao aplicar o resultado | Toast de atenção: não foi possível adicionar o laudo. Tente novamente após o carregamento do laudário. |