Excluir áudio do exame — API

Remove um áudio de ditado do exame. A exclusão é lógica: a linha permanece no banco marcada como excluída, deixa de aparecer nas listagens e na busca, e o objeto correspondente é removido do storage.

Funcionamento

1. Autentica o ator e verifica a permissão exam:delete-audio no escopo do exame.
2. Busca o áudio pelo audioId e confirma que pertence ao examId da rota; um id inexistente, já excluído, ou pertencente a outro exame é tratado como não encontrado.
3. Marca o registro como excluído (deletedAt) e registra um evento de auditoria, na mesma transação.
4. Depois da transação confirmada, remove o objeto do storage. Essa remoção é melhor esforço: uma falha aqui só gera um log de aviso — não desfaz a exclusão lógica nem falha a resposta ao cliente.

Endpoints

Método	Rota	Descrição
DELETE	/v1/exams/{examId}/audios/{audioId}	Exclui logicamente um áudio do exame

Versão: v1

Swagger: DELETE /exams/{examId}/audios/{audioId} · Rota (Dev): http://localhost:3000/v1/exams/{examId}/audios/{audioId}

Lógica de decisão da rota (validações e permissão → desfechos):

Permissões

Rota	Guards	Permissão exigida
DELETE /exams/{examId}/audios/{audioId}	JwtAuthenticationGuard, AuthorizationGuard	exam:delete-audio (PermissionName.EXAM_DELETE_AUDIO), escopo resource sobre o exame (enforcement: rls)

Sem token válido → 401 UNAUTHENTICATED. Sem a permissão no escopo do exame → 403 FORBIDDEN_ACTION. Um áudio de um exame fora do escopo do ator é tratado como não encontrado (404), não como proibido.

Headers

Header	Obrigatório	Descrição
Authorization	Sim	Bearer <access_token>

Path parameters

Nome	Tipo	Obrigatório	Descrição
examId	uuid	Sim	Identificador do exame
audioId	uuid	Sim	Identificador do áudio a excluir

Query parameters

Nenhum.

Body

Nenhum.

Response

204 — sucesso: sem corpo.

Erros

Classe de erro	errorCode	Status	Quando ocorre
UnauthenticatedError	UNAUTHENTICATED	401	token ausente, inválido ou expirado
ForbiddenAction	FORBIDDEN_ACTION	403	ator sem exam:delete-audio no escopo do exame
(validação de payload)	BAD_REQUEST	400	examId/audioId não são uuid válidos
DiagnosisExamAudioNotFoundError	EXAM_AUDIO_NOT_FOUND	404	áudio inexistente, já excluído, ou pertencente a outro examId

Regras de negócio

ID	Regra	Comportamento esperado
RN-01	Exclusão é lógica	marca deletedAt; a linha permanece em diagnosis_exam_audios, apenas some das listagens/buscas ativas
RN-02	As colunas audioPath/audioName não são zeradas na exclusão	diferente do comportamento legado (que zerava audio_path/audio_nome no MySQL); no código atual elas continuam apontando para um caminho cujo objeto físico foi removido do storage
RN-03	O objeto é removido fisicamente do storage	ocorre depois que a exclusão lógica é confirmada, fora da transação; falha nessa remoção não é reportada ao cliente, só logada
RN-04	Excluir de novo, ou excluir um id que não pertence ao exame, devolve o mesmo erro	404 EXAM_AUDIO_NOT_FOUND tanto para "nunca existiu" quanto para "já foi excluído" quanto para "existe em outro exame"
RN-05	Toda exclusão audita e reprojeta a worklist	evento diagnosis.exam.audio-removed (ação EXAM_AUDIO_REMOVED), com o estado anterior (before: audioId, examId), e scheduleExamProjection(examId)

Compliance

Órgão / norma	Exigência	Como a rota atende
LGPD	trilha de exclusão	evento de auditoria diagnosis.exam.audio-removed, com actorUserId e o estado anterior do registro
HIPAA	integridade do registro (não apagar o rastro)	a linha permanece no banco (soft delete); o histórico de auditoria não é removido
ANVISA (retenção como registro médico)	A confirmar — responsável: time de Diagnosis/Compliance; data: 24/09/2026.	O código remove fisicamente o objeto de áudio do storage na exclusão (RN-02/RN-03), enquanto a linha do banco (nome, data, autor) permanece. Não há, neste levantamento, confirmação de que apagar o arquivo de voz — potencialmente parte do prontuário — atende às exigências de retenção de registro médico; esta é uma decisão de política de retenção, não um comportamento a corrigir sem definição de negócio.

Variáveis de ambiente

Nenhuma variável de ambiente é específica desta rota.

Tempo médio de resposta

A confirmar — responsável: time de Diagnosis; data: 24/09/2026. Não há medição publicada; não foi executado neste levantamento.

Requisitos não funcionais

Requisito	Definição
Idempotência	Não estritamente — repetir a chamada depois do sucesso devolve 404 em vez de 204, mas o estado final (áudio excluído) é o mesmo
Paginação	Não se aplica
Rate limit	Não há @Throttle nesta rota
Cache	Não
Auditoria	Sim — evento diagnosis.exam.audio-removed

Relacionado

• 🖥️ Tela: A confirmar — responsável: time de frontend; data: 24/09/2026. (a pasta docs/portal2/interface ainda não tem página de áudio nesta branch; este levantamento cobriu apenas o backend)
• 📂 Módulo: Áudio
• ⏮️ Etapa anterior: Ouvir e listar áudios