T-312 - Gravar o modelo da transcrição e expô-lo na consulta de auditoria

• Componente: api, com o schema novo em contracts/domain/ e o campo na resposta de auditoria no mesmo PR, sujeito a autorização.
• Depende de: T-305.
• Data máxima: 13/11/2026
• Estimativa: 3 pontos (Fibonacci)

Entregável

• Schema contracts/domain/modelo-transcricao.schema.json, com exemplo.
• Coluna submissoes.transcricao_modelo, gravada junto com a transcrição.
• Campo nas entradas da resposta de GET /auditoria/jobs/{id}.

Descrição

A entrada por voz é transcrita pela API com a Deepgram, e o texto transcrito é a origem da regra extraída. Nada registra qual modelo transcreveu cada áudio. O modelo está fixo na chamada (model=nova-3 em ClienteDeepgram.java) e pode mudar sem deixar rastro nos registros antigos. Esta tarefa grava o modelo com a transcrição e o expõe na consulta de auditoria da API. A exibição na tela do auditor é uma tarefa própria.

Contexto e decisões tomadas

• A API é a única produtora e a única leitora da coluna. O codegen lê só submissoes.transcricao. Por isso o schema novo e a coluna entram no mesmo PR da API.
• modelo-llm.schema.json não serve, porque descreve chamadas a modelos de linguagem e exige parâmetros de geração. O schema novo tem provedor e modelo obrigatórios e versao opcional.
• A resposta da Deepgram pode trazer metadados do modelo usado. Quando trouxer, o registro usa o nome e a versão informados. Quando não trouxer, usa deepgram e o modelo pedido na chamada, sem versão.
• A coluna é opcional e sem backfill. Fica nula nas entradas de formulário e de texto, na submissão de voz ainda não transcrita e nas gravadas antes da coluna.

Escopo

Dentro do escopo

• ClienteDeepgram.java, ProcessadorTranscricao.java, SubmissoesRepository.gravarTranscricao, a migration, o schema, o campo na especificação HTTP, a documentação do banco e a leitura na fatia auditoria.

Fora do escopo

• Trocar o provedor ou o modelo de transcrição.
• Exibir o modelo ao profissional de RH.
• Exibir o modelo na tela do auditor.

Requisitos

1. Antes de editar contracts/, pedir autorização conforme contract-change (.agents/skills/contract-change/SKILL.md), informando o schema novo, o campo novo na resposta de auditoria, o produtor e o consumidor (API e frontend), a compatibilidade (aditiva) e as validações.
2. Criar o schema e o exemplo, e registrá-lo em contracts/examples/manifesto.json.
3. Conferir na documentação da Deepgram e numa resposta real (TranscricaoRealTests) onde a resposta de /v1/listen informa o modelo e a versão, e ler esses campos em ClienteDeepgram sem tornar a transcrição dependente deles. Uma resposta sem os metadados continua válida.
4. ClienteDeepgram.transcrever passa a devolver o texto e o modelo, e o processador repassa os dois a gravarTranscricao, que grava a coluna no mesmo UPDATE da transcrição.
5. Criar o changeset com o próximo número livre, com ADD COLUMN transcricao_modelo jsonb e rollback. Atualizar modelo-dados.dbml com a nota da coluna.
6. Acrescentar o campo opcional às entradas da resposta de auditoria em openapi.yaml e incluí-lo na leitura da fatia auditoria.
7. O log transcription finished pode citar o nome do modelo, que é um valor de conjunto limitado. Nenhum log inclui o texto transcrito nem o corpo da resposta.

Contexto técnico

• Entradas: resposta da Deepgram.
• Saídas: submissoes.transcricao_modelo e o campo na consulta de auditoria.
• Componentes afetados: api/src/main/java/synapse/api/submissoes/ClienteDeepgram.java, api/src/main/java/synapse/api/submissoes/ProcessadorTranscricao.java, api/src/main/java/synapse/api/submissoes/SubmissoesRepository.java, a migration nova e a fatia auditoria.
• Restrições: a falha em ler os metadados não falha a transcrição; nenhuma chave de API em log.
• Referências: ClienteDeepgramTests (api/src/test/java/synapse/api/submissoes/ClienteDeepgramTests.java), ProcessadorTranscricaoTests (api/src/test/java/synapse/api/submissoes/ProcessadorTranscricaoTests.java), TranscricaoRealTests (api/src/test/java/synapse/api/submissoes/TranscricaoRealTests.java), migrations (api/.agents/skills/migrations/SKILL.md).

Critérios de aceitação

• Uma resposta com os metadados grava o nome e a versão informados.
• Uma resposta sem os metadados grava deepgram e o modelo pedido, e a transcrição conclui normalmente.
• A consulta de auditoria de um job de voz mostra o modelo na entrada transcrita.
• python contracts/validar-exemplos.py passa.

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 transcrição serializados conferidos sem texto transcrito.