Contatos

O papel do módulo

Contatos é o cadastro relacional usado pelo restante do James. Ele guarda as pessoas e entidades com quem o usuário se relaciona, sem transformar essas pessoas em contas de login. O mesmo contato pode aparecer em grupos, acertos, mensagens compartilhadas e no histórico de auditoria.

O módulo trabalha com duas entidades:

• Contato: nome, categoria de relacionamento, data de nascimento, telefones, e-mails, notas e avatar.
• Grupo de contatos: conjunto nomeado de contatos, com notas próprias, usado para organizar o cadastro e selecionar participantes de uma divisão de conta.

Diagram Design · Mermaid · arraste para mover · Ctrl/⌘ + scroll para zoom

−

100%

+ReporTela cheiaAbrir inteiro ↗

Renderizando diagrama declarativo…

Leitura semântica

Contatos e grupos possuem uma relação muitos-para-muitos representada pela tabela CONTACT_CONTACT_GROUP; os dados complementares do contato ficam no próprio registro.

Fluxo de uso

Encontrar e filtrar contatos

A listagem /contacts combina:

• busca por nome ou notas;
• filtro por categoria de relacionamento;
• filtro por grupo;
• ordenação pelos contatos mais recentes;
• paginação de 18 resultados por página.

A busca usa unaccent e ILIKE no PostgreSQL, portanto consegue procurar sem depender de acentos. A ordenação usa similaridade para priorizar os resultados mais próximos do termo pesquisado.

Criar e editar

Em /contacts/create e /contacts/{contact}/edit, os campos disponíveis são:

Telefones e e-mails são mantidos como arrays JSON no registro do contato. O rótulo diferencia, por exemplo, Celular, Trabalho e Principal sem exigir uma tabela para cada telefone ou e-mail.

Grupos de contatos

O CRUD de grupos fica em /contacts/groups:

1. Crie um grupo com nome único e, opcionalmente, notas em Markdown.
2. Selecione contatos existentes para compor o grupo.
3. Edite o grupo para substituir sua lista de contatos.
4. Abra o grupo para consultar seus participantes.

O vínculo é muitos-para-muitos. Remover um contato de um grupo não remove o contato, seus acertos nem suas notas. Os grupos também aparecem nos filtros da listagem e podem ser usados para selecionar participantes no módulo de Acertos.

Avatares e privacidade

O avatar não é salvo como uma URL pública no contato. A implementação usa a coleção avatar da Spatie Media Library:

1. A imagem é processada e convertida para WebP.
2. O recorte é centralizado em 200 × 200 pixels.
3. A coleção aceita apenas um arquivo por contato.
4. O arquivo é salvo no disco privado avatars.
5. A rota autenticada contacts.avatar serve o arquivo somente quando ele existe.

O usuário pode trocar ou remover o avatar na edição. O acesso ao arquivo passa pela aplicação, em vez de expor diretamente o caminho do storage.

Detalhes, notas e acertos

A tela /contacts/{contact} reúne:

• avatar, nome, categoria e data de nascimento;
• todos os telefones e e-mails rotulados;
• saldo do contato no módulo de Acertos;
• grupos associados e o modal para sincronizar os grupos;
• notas renderizadas em Markdown;
• metadados do registro e os últimos eventos de auditoria.

O contato é a referência obrigatória dos acertos individuais. Por isso, cadastrar ou corrigir uma pessoa aqui mantém o nome, avatar e categoria consistentes nas outras telas.

Lixeira e exclusão permanente

Excluir um contato pela tela principal executa soft delete e o envia para /contacts/trashed. A lixeira mantém busca, filtro por categoria, paginação de até 50 itens e duas ações:

• Restaurar: devolve o contato à listagem normal.
• Excluir permanentemente: limpa a coleção de avatar e executa a exclusão física do contato.

A exclusão normal não apaga imediatamente o arquivo nem o histórico. A exclusão permanente é a operação irreversível e deve ser usada somente quando o registro não for mais necessário.

Auditoria

Contatos e grupos registram criação, atualização e exclusão; o contato também registra restauração e exclusão permanente. O activity log grava somente campos preenchíveis que realmente mudaram. Consulte Auditoria e logs para entender filtros, diff e autoria das alterações.

Rotas principais

Referências

• Acertos — usa contatos como participantes e calcula saldos por pessoa.
• Traits e helpers — inclui busca e componentes compartilhados.
• Decisões arquiteturais — decisões sobre Media Library e notas em Markdown.