threads

Inbox de threads baseado em pastas (inbox, outbox, sent, archived, trash, starred) construído com agregação SQL bruta sobre inbox_message, além de estado de arquivamento/lixeira/estrela/leitura e exclusão permanente.

Caminho de origem: libraries/inbox/src/thread

Arquivo do módulo: thread.module.ts

Introdução

O submódulo Threads é o modelo de leitura da UI da caixa de correio: `inbox_thread` agrupa linhas relacionadas de `inbox_message` e as expõe por meio de seis pastas virtuais — `inbox`, `outbox`, `sent`, `archived`, `trash`, `starred` — calculadas por `ThreadService.resolveFolder` a partir de uma combinação do próprio `status` da thread (`open` | `archived` | `trash`), do seu flag `starred` e da direção/status de sua mensagem mais recente. Uma thread nunca é atribuída diretamente a uma coluna de pasta; `outbox` significa especificamente "aberta, sem estrela e cuja mensagem mais recente é uma mensagem de saída ainda `queued`" — no momento em que essa mensagem é enviada ou falha, a mesma thread reaparece em `sent` sem nenhuma operação explícita de mover.

`GET /inbox/threads` é implementado como uma única consulta SQL escrita à mão (via `Prisma.sql` / `$queryRaw`) em vez do query builder do Prisma, porque a pertinência à pasta, a agregação de labels (`json_agg` dos labels distintos entre todas as mensagens de uma thread), a detecção de não lidas (`EXISTS` sobre `inbox_message`) e as contagens de mensagens por thread precisam ser calculadas em relação ao conjunto de contas *acessíveis* ao usuário chamador em uma única passagem. Toda chamada de lista e detalhe é restringida por `InboxAccessService.listAccessibleAccountIds` / `assertThreadAccess`, de modo que um usuário só vê threads que tenham ao menos uma mensagem em uma conta da qual ele é proprietário ou membro (ou, para admin/admin-inbox, todas as contas).

Remover uma thread envolve duas operações distintas com graus diferentes de destrutividade. `PATCH /inbox/threads/:id/trash` é uma movimentação suave: ele define `inbox_thread.status = 'trash'`, mas primeiro encontra quaisquer mensagens de saída ainda `queued` naquela thread, cancela seus jobs de fila pendentes/agendados/em retentativa via `QueueJobService.cancel`, coloca essas mensagens em `status: failed` e grava um `mail_event` do tipo `failed` explicando que a mensagem foi removida da outbox pelo usuário — isso impede que um envio enfileirado saia silenciosamente depois que o usuário achou que o havia excluído. `DELETE /inbox/threads/:id/permanent` e `DELETE /inbox/threads/trash/empty` são exclusões definitivas: dentro de uma transação, elas removem cada linha de `mail_event` e `queue_job` ligada às mensagens da thread, excluem as próprias mensagens e, por fim, excluem a linha da thread — dados que não podem ser recuperados depois, diferentemente do status `trash`, que é apenas um filtro.

`PATCH /inbox/threads/:id/star` e `/unstar` atualizam o booleano `starred` via um `$executeRaw UPDATE` bruto em vez do cliente Prisma, e `/read` / `/unread` fazem atualização em lote do flag `unread` em todas as mensagens não excluídas da thread, restritas às contas acessíveis do chamador (não apenas a mensagem mais recente), de modo que threads parcialmente lidas compartilhadas entre múltiplos membros da caixa de correio são marcadas de forma consistente para as contas que o chamador pode ver.

Endpoints HTTP

10 endpoints

Lista paginada de threads em uma pasta, restrita às contas acessíveis ao chamador. Cada linha inclui a prévia da mensagem mais recente, o flag de não lida, o estado de estrela, a contagem de mensagens e os labels agregados da thread.

Query: page, pageSize, search, accountId?, folder? (inbox | outbox | sent | archived | trash | starred, default inbox), unreadOnly?

Obtém o detalhe completo da thread, incluindo cada mensagem (com destinatários e o mail_event mais recente) ordenada cronologicamente, além dos labels agregados. Inclui mensagens em soft delete quando a própria thread está na pasta trash.

Params: id (int)

Move uma thread para a pasta archived (status: archived).

Params: id (int)

Move uma thread para a pasta trash. Cancela quaisquer mensagens de saída ainda enfileiradas na thread (job de fila + status: failed + um mail_event de falha), de modo que um envio pendente não seja entregue depois que o usuário enviou a thread para a lixeira.

Params: id (int)

Exclui permanentemente uma thread e todas as suas mensagens, mail_events e linhas de queue_job. Irreversível.

Params: id (int)

Exclui permanentemente todas as threads atualmente na pasta trash em todas as contas acessíveis ao chamador.

Marca como lida cada mensagem não excluída da thread (dentro das contas acessíveis ao chamador).

Params: id (int)

Marca como não lida cada mensagem não excluída da thread (dentro das contas acessíveis ao chamador).

Params: id (int)

Adiciona estrela a uma thread (move-a para a pasta starred enquanto o status permanece open).

Params: id (int)

Remove a estrela de uma thread.

Params: id (int)