Listings (Vitrine)

Visão geral

Listings são anúncios da Vitrine. Antes da sessão 2026-04-28, a info de "está disponível pra venda/troca?" ficava em items direto. Foi extraída pra cá pra modelar bem o ciclo active → paused → closed.

Listing é a fonte de verdade da disponibilidade — quando ativo, item está no mercado; quando closed, item voltou pra coleção comum (ou foi transferido).

Cada item pode ter no máximo 1 listing active (unique partial index). Múltiplos paused/closed históricos.

Entidades principais

Tabela	Papel
`listings`	Anúncio com status, availability, price, payment methods
`items`	Item anunciado

Endpoints

7 endpoints (em /listings e /marketplace):

Endpoint	Resumo
`POST /listings`	Criar anúncio
`GET /listings/mine`	Meus anúncios (filtra por status)
`PATCH /listings/:id`	Editar (availability, price, payment)
`PATCH /listings/:id/pause`	Pausar
`PATCH /listings/:id/resume`	Reativar
`DELETE /listings/:id`	Encerrar (ou hard delete com ?hard=true em closed)
`GET /marketplace`	Listing público (todos active de outros users)

Fluxos

Criar anúncio

Ciclo de vida e auto-rejeição de offers

Browse marketplace

Eventos de socket

Não emite eventos diretamente. Mas o auto-reject por close dispara offer_rejected notifications, que viram socket events via NotificationsService.

Edge cases e regras especiais

Disclaimer obrigatório — disclaimerAccepted: true no body, persistido como timestamp. Frontend deve mostrar texto antes do user marcar.
Múltiplos pagamentos — paymentMethods é array de pix|money|transfer|card|negotiate. Pelo menos 1 obrigatório se availability inclui sale.
Preço opcional pra trade — só obrigatório pra availability sale ou both.
Tipo de listing imutável — não há mudança de items entre listings; criar novo se quiser anunciar de outro modo.
Auto-rejeição em close: ofertas pendentes viram rejected automaticamente; ofertantes recebem notif. Acceptes que já estavam pending de confirm continuam (não cascade).
Hard delete só em closed — ativos/pausados precisam ser encerrados primeiro.
Listing closed mantém histórico — base pras avaliações e auditoria.
availability do item legado — alguns items antigos têm availability no JSONB (débito); migration removeu coluna mas não os dados.

Dependências entre módulos

Items — listing referencia item
Offers — auto-rejeição em close (via OffersRepository.autoRejectByListing)
Listing Ratings — avaliações pós-completed offers
Notifications — offer_rejected disparado em close
Friends — block esconde listings de gente bloqueada

Listings (Vitrine)

On this page