Agentes representam pessoas, coletivos e organizações culturais no ecossistema do Mapas Culturais.

Um Agente é a entidade central de perfil no Mapas Culturais. Todo usuário que se cadastra na plataforma recebe automaticamente um perfil de agente. Agentes podem ser donos de espaços, criar eventos, conduzir projetos e se inscrever em oportunidades.

Tipos de agente

A entidade usa um campo numérico de tipo (_type). Os rótulos e IDs exatos são configurados por instalação por meio do sistema de taxonomias e tipos de entidade. Administradores podem definir nomes de tipos e restringir quais usuários podem alterar o tipo de um agente.

Campos principais

Campos adicionais, como e-mail, telefone, site, documento e área de atuação, são armazenados como metadados e podem variar conforme a configuração da instalação.

Geolocalização

Agentes suportam geolocalização opcional via PostGIS. A localização é armazenada tanto em uma coluna point quanto em uma coluna geography para consultas espaciais. A flag publicLocation controla a visibilidade: se for false, as coordenadas são retornadas como (0,0) para usuários sem acesso a dados privados.

// A localização só é exposta se o agente tiver publicLocation = true
// ou se quem estiver visualizando tiver permissão para ver dados privados
function getLocation() {
    if ($this->publicLocation || $this->canUser('viewPrivateData')) {
        return $this->location;
    } else {
        return new \MapasCulturais\Types\GeoPoint(0, 0);
    }
}

Múltiplos agentes por usuário

Uma mesma conta de usuário pode gerenciar múltiplos perfis de agente. Um deles é designado como perfil do usuário, a identidade principal daquela conta.

Relações com outras entidades

Agentes são a entidade central de conexão da plataforma. Eles são proprietários de, ou participam de, todos os demais tipos de entidade:

Além da titularidade, agentes participam de relações entre agentes (AgentAgentRelation). São vínculos muitos-para-muitos que representam papéis como colaborador, parceiro ou vínculo institucional.

Completude de perfil

O módulo ProfileCompletion acompanha quanto do perfil de um agente foi preenchido. Ele calcula uma porcentagem de completude com base na presença de campos importantes, como nome, descrição curta, descrição longa, imagem de avatar, localização e tags. Um indicador visual é exibido na interface para incentivar o preenchimento.

Selos e verificação

Agentes podem receber selos de administradores ou de responsáveis por oportunidades. Esses selos servem para certificar ou verificar agentes, por exemplo confirmando identidade, vínculo institucional ou participação em um programa.

As relações de selo são armazenadas em AgentSealRelation. Certos selos podem travar campos, impedindo que o agente modifique dados que já foram verificados. A lista de campos travados é calculada a partir das relações de selo ativas.

// Selos podem travar campos do agente para impedir alterações
function getLockedFields() {
    $locked_field_seals = (array) $this->lockedFieldSeals;
    return !empty($locked_field_seals) ? array_keys($locked_field_seals) : [];
}

Tags e taxonomias

Agentes suportam classificação taxonômica por meio de relações de termos (AgentTermRelation). Tags, áreas de atuação e outros vocabulários são vinculados por esse sistema.

Criando um agente

Ciclo de status