Entidades e relacionamentos · Organização

Conteúdo aprovado pelo responsável

Responsável: Kalyl Lamarck
Referência do material fornecido: Decisões de Kalyl Lamarck na conversa de 04–05/10/2026 sobre a Gestão do núcleo (núcleo, área, subnúcleo, situação, liderança e membros importados do lsa-gestao); plano aprovado ~/.claude/plans/glimmering-forging-whisper.md, Etapa 1; nead-hub-api origin/development@d519015: src/organization/entities/** (org_areas, org_nucleus_area_assignments, org_subnuclei, org_subnucleus_assignments) e src/users/entities/** (nuclei, user_nuclei); lsa-gestao a18a90b (unidades, designacoes, lotacoes, vinculos); diagrama derivado das relações desta página. Atualização com as decisões de Kalyl Lamarck de 05/10/2026: alcance do Acesso de Área sobre os núcleos da sua área; lista de núcleos legíveis no menu; catálogo de tipos de reunião REU001 a REU011 importado do lsa-gestao; pessoas sem conta relatadas na importação; código do subnúcleo a definir. Conformação ao implementado em nead-hub-api feat/gestao-nucleos@12f3168 (openapi/openapi.json, migration 1791206307221-gestao-nucleos, src/nucleus-meetings/entities/meeting-type.entity.ts, src/scripts/gestao-nuclei-import.ts), a pedido de Kalyl Lamarck em 05/10/2026.
Aprovação: Kalyl Lamarck · 2026-10-05

Diagrama

Estrutura da organização

Carregando diagrama…

Ver código Mermaid

erDiagram
  ORG_AREAS ||--o{ ORG_NUCLEUS_AREA_ASSIGNMENTS : "areaId"
  NUCLEI ||--o{ ORG_NUCLEUS_AREA_ASSIGNMENTS : "nucleusId"
  NUCLEI ||--o{ ORG_SUBNUCLEUS_ASSIGNMENTS : "nucleusId"
  ORG_SUBNUCLEI ||--o{ ORG_SUBNUCLEUS_ASSIGNMENTS : "subnucleusId"
  NUCLEI ||--o{ USER_NUCLEI : "nucleusId"
  USERS ||--o{ USER_NUCLEI : "userId"

O modelo é físico (TypeORM sobre PostgreSQL). Área, núcleo e subnúcleo têm tabelas próprias, cada uma com situação e vigência. O pertencimento do núcleo à área e do subnúcleo ao núcleo fica em tabelas de vínculo com vigência, para que a estrutura de um dia passado possa ser consultada. O vínculo de uma conta com o núcleo, com o papel de membro ou de liderança, fica em user_nuclei, a mesma tabela usada por Identidade e acesso.

Área (`org_areas`)

Atributo	Tipo	Obrigatório	Regra
`id`	UUID, chave primária	Gerado	—
`sigla`	varchar(40), única	Sim	Gravada em maiúsculas, sem espaço nas pontas.
`name`	varchar(255)	Sim	Nome por extenso.
`description`	varchar(1000)	Não	Texto livre.
`status`	enum `ativo`, `em_desenvolvimento`, `inativo` ou `encerrado`	Gerado	Nasce `ativo`.
`effectiveFrom`	data	Sim	Primeiro dia de vigência.
`effectiveTo`	data	Não	Último dia de vigência, inclusive; nulo enquanto vigente.
`authorUserId`	UUID, FK → `users` (`SET NULL`)	Não	Quem fez a última escrita.
`createdAt`, `updatedAt`	timestamptz	Gerado	—

Núcleo (`nuclei`)

Atributo	Tipo	Obrigatório	Regra
`id`	UUID, chave primária	Gerado	—
`sigla`	varchar(16), única	Sim	Gravada em maiúsculas. Identifica o núcleo nas rotas e nas designações.
`name`	varchar	Sim	Nome por extenso.
`status`	enum `ativo`, `em_desenvolvimento`, `inativo` ou `encerrado`	Gerado	Nasce `ativo`.
`effectiveFrom`	data, padrão do banco `CURRENT_DATE`	Gerado	Primeiro dia de vigência.
`effectiveTo`	data	Não	Último dia de vigência, inclusive; nulo enquanto vigente.
`createdAt`, `updatedAt`	timestamptz	Gerado	—

Vínculo do núcleo com a área (`org_nucleus_area_assignments`)

Atributo	Tipo	Obrigatório	Regra
`id`	UUID, chave primária	Gerado	—
`nucleusId`	UUID, FK → `nuclei` (`CASCADE`)	Sim	Núcleo ligado.
`areaId`	UUID, FK → `org_areas` (`RESTRICT`)	Sim	Área a que o núcleo pertence nesta versão.
`effectiveFrom`	data	Sim	Primeiro dia do vínculo.
`effectiveTo`	data	Não	Último dia do vínculo, inclusive; nulo enquanto aberto.
`authorUserId`	UUID, FK → `users` (`SET NULL`)	Não	Quem escreveu o vínculo.
`createdAt`	timestamptz	Gerado	—

Um índice único parcial admite um só vínculo aberto (effectiveTo nulo) por núcleo.

Subnúcleo (`org_subnuclei`)

Atributo	Tipo	Obrigatório	Regra
`id`	UUID, chave primária	Gerado	—
`codigo`	varchar(40), único	Sim	Começa pela sigla do núcleo seguida de `-`.
`name`	varchar(255)	Sim	Nome por extenso.
`description`	varchar(1000)	Não	Texto livre.
`status`	enum `ativo`, `em_desenvolvimento`, `inativo` ou `encerrado`	Gerado	Nasce `ativo`.
`effectiveFrom`	data	Sim	Primeiro dia de vigência.
`effectiveTo`	data	Não	Último dia de vigência, inclusive; nulo enquanto vigente.
`authorUserId`	UUID, FK → `users` (`SET NULL`)	Não	Quem fez a última escrita.
`createdAt`, `updatedAt`	timestamptz	Gerado	—

Vínculo do subnúcleo com o núcleo (`org_subnucleus_assignments`)

Atributo	Tipo	Obrigatório	Regra
`id`	UUID, chave primária	Gerado	—
`subnucleusId`	UUID, FK → `org_subnuclei` (`CASCADE`)	Sim	Subnúcleo ligado.
`nucleusId`	UUID, FK → `nuclei` (`RESTRICT`)	Sim	Núcleo a que o subnúcleo pertence nesta versão.
`effectiveFrom`	data	Sim	Primeiro dia do vínculo.
`effectiveTo`	data	Não	Último dia do vínculo, inclusive; nulo enquanto aberto.
`authorUserId`	UUID, FK → `users` (`SET NULL`)	Não	Quem escreveu o vínculo.
`createdAt`	timestamptz	Gerado	—

Um índice único parcial admite um só vínculo aberto por subnúcleo.

Vínculo da conta com o núcleo (`user_nuclei`)

Atributo	Tipo	Obrigatório	Regra
`userId`	UUID, FK → `users` (`CASCADE`)	Sim	Parte da chave primária composta.
`nucleusId`	UUID, FK → `nuclei` (`CASCADE`)	Sim	Parte da chave primária composta.
`role`	enum `member` ou `leader`, padrão `member`	Sim	`leader` marca a liderança do núcleo; `member`, o integrante.
`createdAt`	timestamptz	Gerado	—

Tipo de reunião (`meeting_types`)

Atributo	Tipo	Obrigatório	Regra
`code`	varchar(16), chave primária	Sim	Código do catálogo do lsa-gestao, de `REU001` a `REU011`.
`name`	varchar(255)	Sim	Nome do tipo de reunião.
`frequency`	varchar(64)	Não	Frequência prevista.
`format`	varchar(64)	Não	Formato previsto.
`defaultAgenda`	jsonb, lista de textos, padrão `[]`	Gerado	Itens da pauta padrão.
`nucleusApplicable`	boolean, padrão `false`	Gerado	`true` nos tipos que a Página do Núcleo agenda: `REU002` a `REU005`.
`createdAt`, `updatedAt`	timestamptz(3)	Gerado	—

Só a importação escreve o catálogo. O tipo de reunião não tem relação com um núcleo específico; a reunião do núcleo o referencia, conforme a Gestão do núcleo.

Relações e cardinalidades

Relação	Cardinalidade	Obrigatória	Integridade
Área → vínculos com núcleos	1 : N	Não, do lado da área	FK `areaId`, `RESTRICT`.
Núcleo → vínculos com área	1 : N, no máximo um aberto	Não, do lado do núcleo	FK `nucleusId`, `CASCADE`; índice único parcial.
Núcleo → vínculos com subnúcleos	1 : N	Não, do lado do núcleo	FK `nucleusId`, `RESTRICT`.
Subnúcleo → vínculos com núcleo	1 : N, no máximo um aberto	Não, do lado do subnúcleo	FK `subnucleusId`, `CASCADE`; índice único parcial.
Núcleo → contas vinculadas	N : N por `user_nuclei`	Não	FKs com `CASCADE`; chave composta impede vínculo repetido.

Ciclo de vida

As unidades nascem na importação do lsa-gestao, com situação ativo. A unidade extinta no lsa-gestao tem a vigência encerrada na data de extinção; se ainda não existe no Hub, não é criada. O encerramento da vigência substitui a exclusão: a unidade encerrada continua consultável nos dias em que esteve vigente. O vínculo da conta com o núcleo é criado pela importação, a partir das lotações e designações vigentes do lsa-gestao. O catálogo de tipos de reunião também nasce na importação. O subnúcleo só é criado quando a sua sigla no lsa-gestao já começa pela sigla do núcleo seguida de -; os demais aparecem no relatório da importação.