Collections & Items

Visão geral

Os módulos Collections e Items formam o coração do conteúdo gamer/colecionador do Geek Social. Modelagem chave:

• Cada collection tem um type (games, books, cardgames, boardgames, custom) e um schema dinâmico definido pelo dono
• Cada item pertence a uma collection e guarda valores em JSONB indexado pelas keys das field_definitions referenciadas

A separação entre field_definitions (catálogo global) e collection_field_schema (mapeamento por coleção) permite reusar campos entre coleções e respeitar ordenação custom.

Items podem transferir entre usuários via Vitrine — uma offer confirmada move o collection_id do item pro destinatário.

Entidades principais

Endpoints

Collections (11): create, list mine, list public, get, update, delete, upload icon, upload cover, attach/detach/update field do schema.

Items (7): list (com filtros dinâmicos), create, get, update, delete, upload cover, list public.

Ver API Reference — Collections e API Reference — Items.

Fluxos

Criar coleção com schema dinâmico

Criar item com fields validados

Listar items com filtros dinâmicos

Schema editing após coleção criada

Eventos de socket

Não emite eventos diretamente. Mas:

• Item adicionado com auto_share_to_feed dispara post no feed → cliente recebe via socket nas próximas atualizações de feed
• Item transferido (via offer) atualiza coleções de ambos os lados — frontend re-fetcha após notification:new (offer_completed)

Edge cases e regras especiais

• Tipo de coleção é imutável — mudaria semântica dos field defs
• Visibility é por coleção, não por item — mas tipo da coleção afeta quais field defs aparecem
• fields é JSONB merge no UPDATE — não precisa enviar todas as keys
• Items sem field_definition correspondente — possível se field foi detached do schema; valor preservado no JSONB
• Auto-criação de coleção destino em transferências — OffersService.ensureDestinationCollection cria coleção do tipo certo se receptor não tem
• asking_price e availability foram movidos pra listings na sessão 2026-04-28; código antigo pode mencionar
• Privacy friends_only filtra cross-user; o backend valida via friendsRepository.areFriends
• Field definition de sistema (is_system=true) não é editável pelo user; apenas hidden
• Collection_field_schema sem unique constraint em (collection_id, field_definition_id) — app evita duplicação mas DB não enforce (pendência)

Dependências entre módulos

• Friends — privacy gating cross-user
• Field Definitions — catálogo de campos disponíveis
• Posts — auto-share dispara post item_share
• Listings/Offers — item.collection_id muda em transferências
• Steam — workers steam.import-game populam items em batch
• Storage — upload de cover/icon