A árvore organizacional e relações pai-filho

A página Estrutura organizacional (/org-structure) é o melhor lugar no GCM para ver o formato da sua igreja. É uma árvore literal — cada unidade de nível 1 é uma raiz, cada nível 2 aninha sob ela, e assim por diante até as folhas.

Esta página é sobre ler e navegar na árvore. Criar unidades vive em Criando unidades; gerenciar os nomes dos patamares vive em Definindo níveis.

Anatomia de uma linha

Cada unidade renderiza como uma linha na árvore com estes elementos, da esquerda para a direita:

• Um chevron expandir/recolher se a unidade tem filhos. Desabilitado quando não há descendentes.
• Um ícone — prédio para ativo, arquivo para arquivado.
• O nome. Nomes longos se quebram em uma segunda linha em vez de truncar em "Dow…".
• Um badge de nível ("Filial", "Centro") — o rótulo singular do patamar.
• Um chip de contagem de membros com um ícone Users. Passe o mouse para o tooltip exato.
• O nome do líder se um está atribuído, em uma linha menor abaixo. Líderes não atribuídos mostram uma dica âmbar esmaecida "Nenhum líder atribuído" quando você tem permissão de gestão, para que você possa identificar lacunas em um relance.
• O endereço se definido.
• Uma linha de ações ao passar o mouse com os controles de atribuir líder, editar e arquivar.

Expandindo a árvore

Clique no chevron em qualquer unidade com filhos para expandir. Os filhos renderizam com um nível de recuo a mais com um conector de linha de árvore vertical. Clique de novo para recolher.

Três atalhos na barra de ferramentas:

• Expandir tudo — abre cada linha de uma só vez. Bom para identificar lacunas.
• Recolher tudo — fecha tudo de volta para o nível 1.
• Selecionar tudo — usado com ações em massa, veja abaixo.

O estado de expansão vive só no estado do componente — atualize a página e você volta para tudo-recolhido. Isso é intencional; para organizações com centenas de unidades, a visão tudo-expandido é difícil de gerenciar.

Estatísticas de resumo

Acima da árvore, dois cartões de estatística em forma de pílula mostram:

• N unidades — total de unidades ativas em todos os níveis.
• N membros atribuídos — soma da contagem de membros de cada unidade. (Nota: um membro atribuído no nível 1 e no nível 3 conta duas vezes entre os níveis, mas só uma vez para o total de membros da organização em outros lugares. Essa estatística mostra a contagem de atribuições, não a contagem distinta de membros.)

Essas pílulas são codificadas por cor — primária para unidades, azul para membros — e servem como uma verificação rápida de saúde.

Entrando em uma unidade

Clique na linha de uma unidade para selecioná-la (a linha destaca em azul primário). Clicar no nome de uma unidade filho no breadcrumb no topo da página de detalhes da unidade te leva um nível para cima. O padrão de URL é:

• /org-structure — a visão de árvore.
• /hierarchy/:levelIndex — a página de nível (grade de cartões de cada unidade nesse nível).
• /hierarchy/:levelIndex/:unitId — a página de detalhes da unidade.

A página de detalhes da unidade é a visão de alto esforço. Inclui:

• Um cartão herói com o nome da unidade, pílula do líder, contagem de membros e badge do pai.
• Blocos de estatística para contagem de unidades filhas, total de membros na subárvore, média de membros por filho e razão "líderes atribuídos" (por exemplo, "2 / 7").
• O cartão de endereço e a pré-visualização de mapa embutida se map_location ou estimated_map_location está definido.
• Um painel Unidades filhas com abas ativas e arquivadas, controles de ordenação e cartões clicáveis.
• Um painel Membros com linhas de atribuição buscáveis, paginadas e removíveis.

Breadcrumbs são clicáveis

No topo de cada página de detalhes de unidade, o breadcrumb é Estrutura organizacional → <nome plural do nível> → <nome da unidade>. Clique em qualquer segmento para voltar.

Regras pai-filho

Cada unidade abaixo do nível 1 tem exatamente um pai. As regras que a UI aplica:

1. Uma unidade não pode ser seu próprio pai. O seletor exclui o id da própria unidade.
2. Uma unidade não pode ser descendente de si mesma. O reparentamento valida isso implicitamente via a restrição de nível (você só pode escolher um pai um nível acima).
3. Um pai deve estar no nível imediatamente acima. Uma célula de nível 4 não pode ser parente diretamente de uma filial de nível 1 — precisa passar por um nível 2 e um nível 3.
4. Unidades de nível 1 não têm pai. O seletor não aparece no diálogo de criação para o nível 1.

Essas são proteções de UI; o banco também tem uma check constraint correspondente ao #3.

Operações em massa

Uma vez que a caixa de seleção de qualquer unidade é marcada, uma barra fixa de ação em massa aparece no topo da árvore com estas opções:

• Arquivar — oculta suavemente as unidades selecionadas (e todos seus descendentes — a cascade é automática).
• Excluir — abre um assistente de reatribuição. Veja abaixo.
• Limpar — descarta a seleção.

Em uma página de nível (grade de cartões) você também ganha Editar pai — reparente várias unidades pares para um único novo pai em uma operação. O seletor exclui as unidades selecionadas para prevenir auto-parentamento.

O assistente de reatribuição da exclusão

Excluir uma unidade que tem filhos ou membros dispara um diálogo de guarda com duas perguntas:

O que deve acontecer com as unidades filhas?

• Excluí-las também (o padrão — cascade recursiva).
• Movê-las para uma unidade irmã que você escolhe de um dropdown.

O que deve acontecer com os membros?

• Desatribuí-los (remover a linha de member_unit_assignments). Eles permanecem como membros; só perdem o vínculo de unidade.
• Reatribuí-los para uma unidade irmã que você escolhe.

O assistente conta os dois antes de rodar para que você veja "12 membros atribuídos" e a lista de nomes de unidades filhas antes de confirmar. Uma vez que você clica em Excluir permanentemente, a operação roda como uma sequência: reparentamento de filho → reatribuição de membro → limpeza de user-unit-assignment → exclusão suave nas unidades.

Hard-delete é irreversível pela UI

Uma vez que o assistente roda, as linhas excluídas têm deleted_at definido e são invisíveis ao app. Restaurá-las requer uma correção direta no banco pelo suporte. Prefira Arquivar para qualquer coisa que você possa trazer de volta.

Como a árvore busca

A árvore usa duas queries:

• org_units — cada linha ativa para a organização, ordenada por level_index então name.
• org_units_archived — mesma query com archived_at IS NOT NULL.

As duas são cacheadas por 2 minutos via React Query. Mutações (criar, editar, arquivar, excluir) invalidam o cache para que a árvore atualize automaticamente. Se as contagens de badge alguma vez parecerem velhas, navegue para fora e de volta — isso força um refetch.

Próximos passos

• Atribua membros às unidades em sua árvore.
• Atribua líderes e pastores de unidade para dar escopo a visões de usuário.
• Arquivar e restaurar quando o formato da sua árvore muda.