B2BCall-dialer/docs/CDR.md

# CDR (Call Detail Records)

Agente.md secao 152-160. Fecha o registro durável de chamadas e os
relatórios que dependem dele — até aqui, o estado de uma chamada só vivia
transitoriamente no canal Redis `b2bcall:events` (pub/sub sem histórico).

## Modelo

`calls`/`call_legs`/`call_events` (secao 153), tenant-scoped, RLS.
`dial_attempts` da especificação **não** virou uma tabela nova —
`CallAttempt` (fase Predictive Engine) já cobre exatamente esse conceito
(campanha, lead, timestamps, resultado); `Call.attemptId` liga um `Call` à
sua tentativa de discagem quando aplicável.

`Call.id` = o próprio `freeswitch_uuid` da perna principal (sem suporte a
transferência entre uuids nesta fase — `call_id`/`freeswitch_uuid`
coincidem por enquanto, campos mantidos separados só pra já bater com o
schema da especificação quando isso mudar).

`dispositions` (secao 89, "Call Center → Disposições"): personalizável por
tenant, mesmo padrão de `PauseReason`. `Call.dispositionId` aponta pra lá.

## Quem escreve: `apps/freeswitch-events/src/cdr.ts`

Cada `NormalizedEvent` relevante (`CALL_CREATED`, `CALL_RINGING`,
`CALL_ANSWERED`, `CALL_BRIDGED`, `CALL_ENDED`, `AGENT_OFFERED_CALL`,
`AGENT_BRIDGE_FAILED`, `QUEUE_MEMBER_LEFT`) faz um `upsert` em `Call`
(cria se for o primeiro evento visto pra aquele uuid, atualiza os campos
relevantes) e sempre insere uma linha em `call_events` — a trilha bruta.
`CALL_ENDED` também dispara o cálculo dos agregados em segundos (secao
155-156): `ringTime`/`waitTime`/`talkTime`/`durationSeconds`/
`billableSeconds` (`billableSeconds = talkTime` por enquanto, sem regra de
tarifação ainda — fase Billing).

**Simplificação deliberada**: quando a chamada tem fila associada, o
primeiro `CALL_BRIDGED` é tratado como o agente atendendo
(`agentAnswerAt = bridgeAt`) — não distingue bridge pro agente de um
eventual bridge intermediário (IVR, AVMD). Reavaliar se/quando esses
cenários existirem de verdade.

## Achado real: `AGENT_OFFERED_CALL`/`AGENT_BRIDGE_FAILED` não têm `Unique-ID`

Descoberto testando esta fase: esses dois `CC-Action` disparam de dentro
de uma thread interna do mod_callcenter (`outbound_agent_thread_run`), sem
contexto de channel — o header `Unique-ID` (de onde `normalizeEslEvent`
tira `callUuid`) simplesmente não existe nesses dois eventos (diferente de
`member-queue-end`, que dispara no channel do member e tem `Unique-ID`
normal). Sem correção, `cdr.ts` descartava os dois silenciosamente (guard
`if (!normalized.callUuid) return`) — `Call.queueId`/`agentId` nunca eram
preenchidos, mesmo com o bridge (ou a falha de bridge) acontecendo de
verdade.

Corrigido usando `CC-Member-Session-UUID` (`data.memberSessionUuid`) como
fallback quando `callUuid` não vem — é o mesmo uuid do channel member em
todos os casos, já usado pra correlação equivalente em
`apps/predictive-dialer/src/event-listener.ts`.

## Achado real: corrida entre `CALL_CREATED` e `CALL_ANSWERED`

`persistCallEvent` é chamado sem `await` no loop de eventos (fire-and-
forget, pra não travar o processamento dos próximos eventos ESL) — cada
chamada abre sua própria transação. Pra uma perna `null/dummy` (auto-
atende quase instantaneamente, sem ring de verdade), `CALL_CREATED` e
`CALL_ANSWERED` podem chegar tão perto um do outro que suas transações
concorrentes commitam fora de ordem, e quem quer que "ganhe" a corrida do
`upsert` (criar a linha) usava `now()` daquele momento como `createdAt` —
resultando em `answerAt` aparentemente **antes** de `createdAt`. Corrigido
passando `createdAt: new Date(normalized.occurredAt)` explicitamente no
branch de criação do upsert, em vez de depender do default `@default(now())`
do schema (que reflete "quando a linha foi inserida", não "quando o
evento realmente aconteceu").

## Relatórios (`apps/api/src/reports`)

- `GET /reports/queues` (secao 159): recebidas/atendidas/abandonadas/TME/
  TMA/Service Level/Abandon Rate por fila, a partir de `Call` agrupado por
  `queueId`. Service Level usa um limiar configurável (`slThresholdSeconds`,
  default 20s — a especificação não fixa um valor).
- `GET /reports/agents` (secao 158): tempo logado (`AgentSession`), tempo
  pausado (`AgentPauseEvent`, timestamps explícitos), tempo em cada outro
  estado (`AgentStateEvent`, pareando eventos consecutivos do mesmo agente
  — sem uma tabela de "duração por estado" pronta, calculado on-the-fly),
  chamadas atendidas + TMA (`Call`).
- `GET /reports/campaigns` (secao 160): leads/attempts/answered/agent
  connected/busy/no answer/failed/callbacks/answer rate/contact rate/
  abandon rate a partir de `CallAttempt` + `Lead`; TME/TMA via `Call`
  (join por `attemptId`) e `CallAttempt.talkTimeSeconds`. "Valor
  Telefonia"/"Valor IA" ficam `null` — dependem de rating de uso, fase
  Billing, ainda não existe.

## `GET /calls` (secao 157) e disposição (secao 89)

Filtros: data (`from`/`to`), ramal, agente, fila, campanha, trunk,
telefone (`contains` em `callerNumber`/`calledNumber`), hangup cause,
disposição. Sempre escopado ao tenant do JWT — "platform admin poderá
filtrar tenant" (secao 157) ainda não existe (não há console cross-tenant
ainda).

`PATCH /calls/:id/disposition`: o próprio agente que atendeu marca a
disposição (compara `Call.agentId` contra o `Agent` do usuário
autenticado, nunca um `agentId` vindo do client); um supervisor
(`agents.manage`) pode marcar em nome de outro agente.

## Verificado ponta a ponta

```
Campanha com 5 leads, 1 agente sem SIP registrado de verdade (mesma
limitação de sempre neste laboratório — USER_NOT_REGISTERED):

3 leads deram ANSWERED (simulado) -> entraram na fila real:
  Call.queueId preenchido (via AGENT_OFFERED_CALL ou QUEUE_MEMBER_LEFT)
  Call.agentId preenchido num deles (via AGENT_OFFERED_CALL, fallback
    memberSessionUuid) — confirma a correção da correlação
  Call.hangupCause = USER_NOT_REGISTERED (via AGENT_BRIDGE_FAILED) até o
    hangup agendado sobrescrever com NORMAL_CLEARING no fim
  createdAt <= answerAt em todos (corrige a inversão da corrida)
  durationSeconds calculado corretamente (~60s, bateu com
    discard_abandoned_after)

GET /reports/queues -> received:3, abandoned:3, abandonRate:1
GET /reports/agents -> loggedInSeconds/availableSeconds corretos,
  callsAnswered:0 (nenhum bridge de verdade aconteceu)
GET /reports/campaigns -> leads:5, attempts:5, answered:3, busy:1,
  noAnswer:1, answerRate:0.6, abandonRate:1 — todos os números batendo
  com o que os logs do discador mostraram

POST /dispositions {"name":"Sem Interesse","code":"no_interest"}
PATCH /calls/:id/disposition -> disposição gravada (agente dono da
  chamada, ownership check correto)

`queue list` do FreeSWITCH mostra calls_abandoned=4 ao final,
confirmando o pipeline real por trás dos números agregados.
```

typecheck do workspace inteiro limpo.

## O que falta

- `extensionId`/`sipCallId`/`callerNumber`/`calledNumber` — não
  populados ainda (nenhum evento atual carrega esses dados de forma
  confiável; precisa de inspeção de headers adicionais do canal, ver
  docs/REALTIME.md "O que falta" pro mesmo tipo de lacuna em ramais).
- `direction` só distingue OUTBOUND (tem campanha) de INTERNAL (resto) —
  detecção de INBOUND de verdade precisa inspecionar `Call-Direction`/
  contexto do dialplan, não feito ainda.
- `call_legs` — schema existe, mas nada escreve nele ainda (só faz
  sentido de verdade com transferência entre uuids, que também não
  existe).
- Cross-tenant reports pra platform admin (secao 157) — sem console de
  plataforma ainda.
- Billing (`billableSeconds` sem tarifação, "Valor Telefonia"/"Valor IA"
  sempre null) — fase própria, ainda não iniciada.