B2BCall-dialer/docs/RECORDING.md

Gravação e Object Storage

Agente.md secao 90-94. Fecha a gravação de chamadas do Call Center e a abstração de storage por trás dela — a especificação lista "Recording" e "Object Storage" como dois passos separados na ordem de implementação (secao 232), mas eles são acoplados o suficiente (Recording precisa de um lugar pra guardar bytes) que ficaram nesta única fase.

packages/storage — ObjectStorageProvider (secao 92)

Abstração pequena: putObject(key, sourceFilePath), getObjectStream(key), deleteObject(key). Dois backends:

• LocalObjectStorageProvider: copia pro filesystem local, com uma checagem de path traversal (assertKeyInsideRoot) como última linha de defesa — mesmo a key sendo sempre construída no servidor, nunca vinda do client.
• S3ObjectStorageProvider: @aws-sdk/client-s3, preparado pra AWS S3 e MinIO (forcePathStyle, endpoint customizável). Nunca exercitado nesta sessão — não existe servidor S3/MinIO disponível neste laboratório.

getObjectStorageProvider() escolhe o backend por STORAGE_PROVIDER (local/s3) — cada processo (fs-events, apps/api) monta o seu a partir das mesmas variáveis de ambiente, nunca hardcoda qual backend usar.

Path (secao 93)

buildRecordingObjectKey(tenantId, callId, recordedAt) → tenants/{tenant_id}/recordings/YYYY/MM/DD/{call_id}.wav. Sempre montada no servidor a partir de dados já confiáveis — um tenant nunca consegue montar uma key que aponte pra dentro da pasta de outro.

Volumes: bind mount, não volume nomeado do Docker

Diferente dos outros compartilhamentos com o FreeSWITCH (gateways, filas), /recordings e /data/object-storage usam bind mount pra um diretório real do host (./data/recordings-spool, ./data/object-storage-local) — porque apps/api roda no host, não em Docker (mesma limitação de sempre, ver docs/NETWORK_ARCHITECTURE.md), e precisa ler os mesmos arquivos que fs-events escreve. LOCAL_STORAGE_ROOT tem valores diferentes por ambiente (.env: path do host; docker-compose.yml do fs-events: path Docker-interno pro mesmo diretório) — mesmo padrão já usado pra REDIS_URL.

Quem grava: apps/predictive-dialer/src/originate.ts

Só chamadas originadas pelo PredictiveDialerEngine com Campaign.recordingEnabled=true são gravadas nesta fase — é o único caminho de originate que o sistema controla hoje (chamadas manuais/ internas não passam por aqui ainda). Quando habilitado, o originate ganha duas channel variables extras:

• RECORD_STEREO=true (secao 91): canal A = cliente, canal B = agente, quando tecnicamente adequado.
• execute_on_answer='record_session /recordings/{uuid}.wav': roda assim que a chamada atende, antes da aplicação principal (&callcenter) começar.

O origination_uuid é pré-gerado em originate.ts (em vez de deixar o provider sortear um) porque o path de gravação precisa dele ANTES do comando de originate ser montado — esse mesmo uuid vira Call.id no CDR (fase CDR: Call.id = o próprio freeswitch_uuid), então o arquivo gravado e o registro do Call sempre têm o mesmo nome.

Quem sobe: apps/freeswitch-events/src/recording.ts

Disparado a partir de CALL_ENDED, sempre depois de persistCallEvent terminar (encadeado via .then(), não em paralelo) — uploadRecordingIfPresent lê Call.talkTime/durationSeconds, que é exatamente o que persistCallEvent acabou de calcular nesse mesmo evento (mesma classe de corrida já corrigida uma vez na fase CDR, evitada aqui por ordenação em vez de retry).

Checa se /recordings/{callId}.wav existe (com até 5 tentativas de 300ms — record_session pode levar um instante pra terminar o flush depois do hangup); se não existir, não faz nada (chamada não gravada, comportamento normal). Se existir: sobe pro object storage, calcula retentionUntil a partir de Plan.recordingRetentionDays (secao 94, null = sem limite), cria a linha Recording, apaga o arquivo do spool local.

API (apps/api/src/recordings)

GET /recordings (filtros: campanha, agente, data), GET /recordings/:id, GET /recordings/:id/audio — o áudio nunca é exposto via URL direta pro storage (nem presigned): sempre passa pelo controller autenticado, que faz storage.getObjectStream() e manda o stream direto na resposta (reply.send(stream) do Fastify aceita um Readable). Permissions recordings.view/recordings.download, já existiam desde a fase RBAC.

Retenção (secao 94)

Plan.recordingRetentionDays/transcriptionRetentionDays (o segundo ainda sem uso — fase AI/Transcrição). runRetentionSweep (apps/api/src/recordings/retention-sweep.ts) roda no boot do apps/api e depois a cada hora (setInterval — apps/api já é um processo de longa duração, não precisou de um serviço dedicado só pra isso): varre Recording com status=AVAILABLE e retentionUntil vencido (fan-out por tenant, mesmo padrão de trunk-status.ts), apaga o objeto no storage, marca status=DELETED — a linha em si nunca é apagada, fica como registro de auditoria.

Correção real achada testando esta fase

Recording.sizeBytes é BigInt no Prisma (arquivos podem, em teoria, passar de 2^31 bytes) — o serializador JSON padrão do Fastify não sabe lidar com BigInt e quebrava GET /recordings com 500 (TypeError: Do not know how to serialize a BigInt). Mesma classe de bug já corrigida uma vez no logger (packages/shared/src/logger.ts, fase Event Socket). Corrigido convertendo sizeBytes pra number na resposta (tamanho de gravação nunca chega perto de Number.MAX_SAFE_INTEGER).

Verificado ponta a ponta

Campanha com recordingEnabled:true, 5 leads, 2 ANSWERED simulados:
  record_session cria /recordings/{uuid}.wav no container do FreeSWITCH
    (confirmado: RIFF WAVE, PCM 16-bit, ESTÉREO, 8000Hz — RECORD_STEREO
    funcionando)
  CALL_ENDED -> upload pro object storage local, path exatamente
    tenants/{tenant}/recordings/2026/08/28/{uuid}.wav
  arquivo do spool apagado depois do upload confirmado
  Recording criado com sizeBytes/checksum reais, durationSeconds batendo
    com o talk_time do Call

GET /recordings -> lista os 2, sizeBytes serializado como number (sem
  crash de BigInt)
GET /recordings/:id/audio -> download autenticado, md5 idêntico ao
  arquivo original no object storage

Teste de retenção: marquei retentionUntil como já vencido, rodei
  runRetentionSweep() -> objeto apagado do storage, status vira DELETED,
  GET /recordings (lista) não mostra mais, GET /recordings/:id ainda
  mostra (auditoria), GET /recordings/:id/audio -> 404

typecheck do workspace inteiro limpo.

O que falta

• Chamadas manuais/internas (não originadas pelo discador) não são gravadas — sem um caminho de originate próprio pra elas ainda.
• S3ObjectStorageProvider nunca testado contra um MinIO/S3 real.
• max_recording_storage_gb (Plan) existe mas não é aplicado — nada verifica quota de espaço usado antes de gravar.
• Transcrição (secao 95+, IA) — próxima fase.