T-330 - Devolver ao auditor o áudio de uma entrada por voz

• Componente: api, com a rota nova em contracts/http/openapi.yaml no mesmo PR, sujeito a autorização.
• Depende de: T-305, que cria a fatia auditoria e a política de acesso do auditor na API.
• Data máxima: 12/11/2026
• Estimativa: 3 pontos (Fibonacci)

Entregável

• Rota GET /auditoria/jobs/{id}/entradas/{entradaId}/audio especificada em contracts/http/openapi.yaml.
• Rota implementada na fatia auditoria, devolvendo o áudio gravado da entrada.
• Testes da rota nos casos de sucesso, de acesso negado e de entrada sem áudio.

Descrição

O auditor precisa ouvir o áudio enviado pelo usuário para conferir se a transcrição foi feita corretamente. A PO decidiu isso na T-314. O áudio de cada entrada por voz, inicial ou de correção, fica gravado em submissoes.binario, com o formato em submissoes.formato. A consulta de auditoria (GET /auditoria/jobs/{id}, T-304 e T-305) lista as entradas com o formato do áudio, mas sem o binário. Nenhuma rota devolve o áudio. Esta tarefa cria essa rota.

Contexto e decisões tomadas

• O áudio vem por uma rota própria, e não dentro do JSON da consulta, porque chega a 5 MB por entrada (AudioSubmissao.LIMITE) e só é baixado quando o auditor quer ouvi-lo.
• A rota segue a política das outras rotas de auditoria: permitida só ao auditor, sem conferência de posse, só leitura.
• entradaId é o id da submissão, o mesmo que aparece em entradas na consulta do job.
• O formato gravado é sempre webm, ogg, wav ou mp4, validado no envio (AudioSubmissao.ler). O tipo da resposta é audio/<formato>, escolhido numa lista fechada desses quatro valores.
• O áudio é dado pessoal do usuário. A resposta não é guardada em cache, e nenhum log, métrica ou span inclui o conteúdo.

Escopo

Dentro do escopo

• A rota em openapi.yaml, a menção a ela na descrição de entradas da consulta do job, a leitura do áudio e o controlador na fatia auditoria, os testes e a linha da rota na matriz da DEC-087.

Fora do escopo

• O reprodutor na tela do auditor (T-331).
• Mudar a gravação, o formato ou a retenção do áudio.
• Devolver o áudio ao profissional de RH.

Requisitos

1. Antes de editar contracts/, pedir autorização conforme contract-change (.agents/skills/contract-change/SKILL.md), informando a rota nova, o produtor (API), o consumidor (frontend), a compatibilidade (rota nova; nada existente muda) e as validações.
2. Especificar a rota com as respostas 200 (corpo binário, em audio/webm, audio/ogg, audio/wav ou audio/mp4), 401 sem sessão, 403 sem_permissao para quem não é auditor e 404. O 404 usa job_nao_encontrado quando o job não existe e um código próprio quando a entrada não é do job ou não é de voz. Na descrição de entradas da consulta do job, dizer que o áudio das entradas por voz é obtido por esta rota.
3. Ler o binário e o formato só entre as entradas que a consulta do job lista, pela mesma regra da T-305, para que o id de uma submissão de outro job responda 404.
4. Responder com Content-Type montado a partir da lista fechada de formatos e com Cache-Control: no-store.
5. Registrar a entrega e a recusa num log com job_id, o id da entrada, o formato e o tamanho, sem o conteúdo. Volume e duração ficam com as métricas HTTP que a stack já fornece, sem métrica de domínio nova.
6. Acrescentar a rota à "Matriz HTTP vigente" da DEC-087, permitida só ao auditor.

Contexto técnico

• Entradas: submissoes.binario e submissoes.formato da entrada do job.
• Saídas: o áudio da entrada.
• Componentes afetados: contracts/http/openapi.yaml, a fatia auditoria da API (T-305) e docs/decisoes/dec-087.md.
• Restrições: só o auditor acessa; nenhum conteúdo de áudio em log; nenhum tipo de resposta vindo de texto livre.
• Referências: api/src/main/java/synapse/api/submissoes/AudioSubmissao.java, api/src/main/java/synapse/api/submissoes/SubmissoesRepository.java (lerAudio, a leitura usada pela transcrição), contract-change (.agents/skills/contract-change/SKILL.md), skill de logging da API (api/.agents/skills/logging/SKILL.md).

Critérios de aceitação

• O auditor recebe o áudio de uma entrada por voz, com o tipo correspondente ao formato gravado.
• O profissional de RH recebe 403, e uma requisição sem sessão recebe 401.
• A entrada de formulário ou de texto, a entrada de outro job e o job inexistente recebem 404.
• A especificação valida em python contracts/validar-exemplos.py.

Definição de concluído (DoD)

• Autorização registrada antes da edição de contracts/.
• make check na api e o gate dos quatro componentes sem falha.
• Logs da rota serializados conferidos, sem conteúdo do áudio.