Criando unidades organizacionais

Uma vez que seus níveis existem, você os preenche com unidades — as coisas reais que recebem um líder, uma contagem de membros e um pino no mapa. Uma unidade é uma linha na tabela org_units; a página em que você cai para ela é seu hub para tudo que aquela unidade faz.

Duas formas de entrar

O GCM deixa você criar unidades a partir de duas superfícies. Elas escrevem na mesma tabela; escolha a que se encaixa no momento.

Superfície	Boa para	URL
Árvore Estrutura organizacional	A imagem completa de cima para baixo. Sem arrastar, mas você vê cada nível de uma vez	/org-structure
Página de nível	Adicionar em lote pares no mesmo nível (12 células em sequência, digamos)	/hierarchy/3

A página de árvore é o destino padrão do módulo. Ela mostra unidades de nível 1 na raiz e te deixa expandir para entrar nos filhos delas.

Da página de árvore

Clique em Adicionar filial (ou seja lá como seu nível 1 se chama) no canto superior direito para criar uma unidade de nível superior. Para níveis mais baixos, expanda um pai, clique no menu de três pontos na linha e escolha Adicionar centro (ou seja lá como o próximo nível se chama).

O diálogo pede:

• Nome (obrigatório) — por exemplo, Filial Centro. Até duas linhas se quebram nos cartões, então nomes descritivos servem bem.
• Pai (obrigatório para níveis > 1) — escolhido de um dropdown buscável de unidades um nível acima. O seletor é filtrado para o nível certo automaticamente.
• Endereço (opcional) — endereço de rua em texto livre. Alimenta o módulo de mapa se você também definir uma localização no mapa.
• Localização no mapa (opcional) — abre um seletor Leaflet. Largue um pino ou cole lat/lng. Se você define um endereço mas não uma localização no mapa, o GCM enfileira um geocode em background e preenche estimated_map_location quando o resultado chega.

Clique em Criar. A nova linha aparece na árvore, a contagem de filhos do pai aumenta, a estatística "X unidades" do painel atualiza.

De uma página de nível

Se você está adicionando muitas unidades no mesmo nível — digamos doze células para uma filial — entre via a URL /hierarchy/3 (substitua pelo nível em que você está trabalhando). Você verá uma grade de cartões de cada unidade naquele nível filtrada pelo seletor de pai no topo.

O fluxo de trabalho de página de nível é o mesmo diálogo por baixo, mas você ganha:

• Um filtro de pai para que unidades recém-adicionadas usem o pai certo como padrão.
• Ações em massa — selecione 3 unidades e reparente-as para uma nova filial em um clique.
• Controles de ordenação — nome A–Z, contagem de membros decrescente, adicionadas recentemente.

Esse é o caminho mais rápido quando você está semeando muitas unidades de nível folha após uma reestruturação.

O que fica armazenado

Cada linha de unidade tem estas colunas que a UI faz aparecer:

Coluna	Tipo	Notas
id	UUID	Gerado no cliente
organization_id	UUID	Definido automaticamente a partir da sua sessão
level_index	int	O patamar ao qual a unidade pertence
parent_unit_id	UUID	Null no nível 1, obrigatório abaixo
name	text	Nome de exibição
address	text	Endereço postal opcional
map_location	text	Lat/lng opcional — vence sobre o estimado
estimated_map_location	text	Preenchido pelo geocoder quando o endereço está definido
leader_member_id	UUID	Opcional — veja Atribuir líderes
archived_at	timestamptz	Null para linhas ativas
deleted_at	timestamptz	Null para linhas visíveis; exclusão suave

Timestamps criado e atualizado + IDs de ator são escritos automaticamente. Você pode vê-los na página de detalhes da unidade na linha de "auditoria" logo abaixo do nome.

Editando uma unidade

Abra a unidade (clique em sua linha na árvore ou em seu cartão em uma página de nível). Clique em Editar no cabeçalho. O mesmo diálogo volta preenchido. Você pode mudar:

• O nome.
• O pai — mover a unidade move todos os descendentes dela junto. Membros na unidade ficam onde estão; a cascade só muda a forma da árvore.
• O endereço e a localização no mapa.

Salvar não pede confirmação. Os relatórios atualizam na próxima vez que reconsultam.

Mover unidades muda o escopo dos relatórios

Se você reparentar Centro Centro da Filial Sul para a Filial Norte, cada membro atribuído ao Centro Centro (e seus filhos) agora consolida para a Filial Norte. Painéis de presença de domingo podem se deslocar da noite para o dia — comunique a mudança antes de fazer.

Localização no mapa e o módulo de mapa

Definir map_location em uma unidade lhe dá um pino no módulo Mapa. A cor do pino é determinada pelo nível. O agrupamento de pinos liga em torno do nível 3+ se você tem muitas unidades em uma área pequena.

Você também pode deixar map_location em branco e deixar o endereço geocodar em background. A localização estimada popula estimated_map_location e o mapa mostra o pino numa cor levemente esmaecida para indicar que é um palpite.

Se o geocoding falha (endereço ruim, limite de taxa), o badge de status na página da unidade mostra pending → failed. Você pode consertar o endereço e clicar na unidade de novo para redisparar o geocoder.

Contagens de membros geradas automaticamente

O badge de contagem de membros em cada linha de unidade é computado via o RPC count_org_unit_members, não lendo linhas brutas. O RPC lida com a cascade — soma as próprias atribuições da unidade mais cada descendente. É por isso que mover uma unidade não quebra a contagem.

O badge atualiza em poucos segundos de uma mudança de atribuição. Se parecer velho, atualize a página; o React Query revalida no foco.

Perguntas comuns

Por que não posso arrastar unidades para reparentar? A árvore intencionalmente não tem affordance de arrastar porque movimentos de hierarquia cascateiam de formas não óbvias. O fluxo deliberado Editar → mudar pai → Salvar força um momento de reflexão.

Posso ter duas unidades com o mesmo nome? Sim. A UI não impõe unicidade porque Célula Norte pode legitimamente existir sob duas filiais diferentes. Se quer deduplicar, use o nome do pai como prefixo.

Qual é o máximo prático de unidades? Alguns milhares por organização foram testados. A renderização da árvore virtualiza quando você expande uma subárvore pesada; as queries paginam. Além de ~10.000 unidades, considere se algumas são na verdade membros (por exemplo, se cada lar é uma unidade) e reestruture.

Próximos passos

• Conectar relações pai-filho — ler a árvore, expandir e recolher, entrar.
• Atribuir membros — vincular pessoas às suas novas unidades brilhantes.
• Atribuir líderes — dar escopo aos pastores.