Entidades e relacionamentos · Gestão do núcleo

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 reunião ordinária e extraordinária com número NN/AAAA-TIPO ou NN/AAAA-EXT, ata única por reunião (rascunho e registrada, conflito de versão), resolução objetiva (ementa, considerando, comando, vigência opcional, revogação e ata de origem, signatário gerado) e documento timbrado anexado ao núcleo; modelo físico conforme nead-hub-api feat/gestao-nucleos@12f3168: migration 1791206307221-gestao-nucleos (nucleus_meetings, meeting_minutes, resolutions, meeting_types), src/nucleus-meetings, src/meeting-minutes, src/resolutions e src/nucleus-letterhead; entidades existentes work_items, work_item_people, nuclei e documents conforme as páginas da Área de Trabalho, de Identidade e acesso e da Organização; conformação ao implementado pedida por Kalyl Lamarck em 05/10/2026; diagrama derivado das relações desta página. Decisão de Kalyl Lamarck de 05/10/2026, antes da aprovação: ata e resolução não são geradas pelo Ogma; o documento é gerado no próprio Hub, em HTML, no modelo de lista descritiva em duas colunas do Storybook do Lamarck Hub, em página própria (/gestao/{sigla}/atas/{id} e /gestao/{sigla}/resolucoes/{id}), com botão Imprimir e cabeçalho e rodapé do escritório só na impressão; a lista de documentos do núcleo mostra atas registradas e resoluções a partir dos próprios registros, mais anexos outro. Confirmado em nead-hub-api feat/gestao-nucleos@0e5fd0c. Sem coluna document_id em meeting_minutes e resolutions, conforme a migração em feat/gestao-nucleos@0e5fd0c. Respostas e aprovação de Kalyl Lamarck em 06/10/2026 ('Siga e conclua', aceitando todas as sugestões), transmitidas pela coordenação da tarefa, para nead-hub-docs#27 e #29 (issue-mãe nead-hub#341): Página da Presidência (rota /gestao/presidencia) aberta pela Alta Gestão e pelo Acesso Global, com todos os núcleos, as reuniões do catálogo, as reuniões de todos os núcleos exceto as sigilosas em agenda única com filtro por núcleo, e lista única, só de leitura, de resoluções e atas registradas com filtro por núcleo; ação Agendar reunião no topo; sem histórico consolidado por ora. Página da Área (rota /gestao/areas/{sigla}) aberta pelo Acesso de Área da sua área e pela Alta Gestão e Acesso Global em qualquer área, não pela liderança de núcleo; mostra os núcleos da área, as reuniões do catálogo, as reuniões e as resoluções dos núcleos da área, sem documentos, sem histórico e sem ações próprias. As palavras presidencia e areas ficam reservadas e nenhum núcleo pode usá-las como sigla; entrada no menu do usuário por um item Presidência e um item por área na seção Núcleos, só para quem pode abrir cada página. Atas das reuniões fora do núcleo aparecem na Página da Presidência e na Página da Área em que a reunião aparece; são escritas e registradas por elas e, na Página do Núcleo, são só leitura. Ata em tempo real: editam quem já edita hoje (RN-GESTAO-006 e RN-GESTAO-035); Pauta, Deliberações e presentes e ausentes se atualizam na hora; avatares e cursor com nome e cor; edições no mesmo trecho combinadas automaticamente; sem conexão, edição bloqueada com aviso até reconectar, recebendo o texto atual ao voltar; ao registrar, grava-se o último texto de cada um, a ata fecha na hora para todos e quem a tem aberta recebe aviso; sem histórico de versões, e o histórico do núcleo registra só a criação e o registro da ata. Histórico do núcleo: o filtro de tipo chama-se Composição; reuniões fora do núcleo não entram no histórico do núcleo. Contratos da API conferidos em nead-hub-api development@311fb9b, com os PRs #161, #162, #163, #165 e #166 mesclados: reuniões e documentos no histórico do núcleo, reunião fora do núcleo fora do feed e, na transcrição, conferência que começou entre 15 minutos antes do início marcado e o fim previsto, sem ligação a nenhuma reunião quando duas reuniões da mesma sala se sobrepõem.
Aprovação: Kalyl Lamarck · 2026-10-06

Diagrama

Reunião, ata, resolução e documento

Carregando diagrama…

Ver código Mermaid

erDiagram
  WORK_ITEMS ||--o| NUCLEUS_MEETINGS : "work_item_id"
  NUCLEI ||--o{ NUCLEUS_MEETINGS : "nucleus_id"
  MEETING_TYPES |o--o{ NUCLEUS_MEETINGS : "type_code"
  WORK_ITEMS ||--o| MEETING_MINUTES : "work_item_id"
  NUCLEI ||--o{ MEETING_MINUTES : "nucleus_id"
  NUCLEI ||--o{ RESOLUTIONS : "nucleus_id"
  MEETING_MINUTES |o--o{ RESOLUTIONS : "meeting_minutes_id"
  RESOLUTIONS |o--o{ RESOLUTIONS : "revokes_id"
  USERS ||--o{ MEETING_MINUTES : "author_user_id"
  USERS ||--o{ RESOLUTIONS : "author_user_id"

O diagrama mostra as chaves estrangeiras das tabelas da Gestão do núcleo. A designação do núcleo como responsável pela reunião é uma referência lógica de work_item_people, sem chave estrangeira, descrita na Área de Trabalho. O catálogo meeting_types está descrito na Organização.

Modelo físico

O modelo é físico (TypeORM sobre PostgreSQL). A reunião do núcleo é um Trabalho do tipo Compromisso, categoria meeting, com o núcleo designado como responsável; a tabela nucleus_meetings acrescenta a ele a natureza, o tipo e o número. A ata e a resolução têm tabelas próprias, ligadas ao núcleo. A ata aponta para a reunião de origem; a resolução pode apontar para a ata de que nasceu e para a resolução que revoga. O documento de cada uma é gerado no próprio Hub, em HTML, a partir do registro; não há arquivo guardado.

Reunião do núcleo (Compromisso `meeting`)

A reunião usa os campos do Trabalho documentados na Área de Trabalho. Os campos abaixo são os que a Gestão do núcleo lê.

Atributo	Tipo	Obrigatório	Regra
`kind`	`appointment`	Sim	A reunião é um Compromisso.
`category`	`meeting`	Sim	Categoria de reunião.
`title`	string	Sim	Título da reunião.
`body`	text	Não	Pauta da reunião.
`scheduledAt`	data-hora	Não	Hora marcada; mudar este campo é remarcar.
`durationMin`	inteiro	Não	Duração prevista.
`location`	string	Não	Local; mudar este campo é remarcar.
`meetingUrl`	string	Não	Endereço do encontro remoto, usado em Ingressar; mudar este campo é remarcar.
`meetingFormat`	`in_person`, `remote` ou `hybrid`	Não	Formato do encontro.
`status`	`pending`, `completed`, `cancelled` ou `postponed`	Gerado	Situação da reunião.
`nucleos`	array de siglas	Derivado	Contém a sigla do núcleo designado como responsável.

Número da reunião (`nucleus_meetings`)

Atributo	Tipo	Obrigatório	Regra
`id`	UUID, chave primária	Gerado	—
`workItemId`	UUID, FK → `work_items` (`RESTRICT`), único	Sim	O Compromisso da reunião; um número por reunião.
`nucleusId`	UUID, FK → `nuclei` (`RESTRICT`)	Sim	Núcleo que agendou.
`kind`	enum `ordinaria` ou `extraordinaria`	Sim	Ausente na criação, vale `extraordinaria`.
`typeCode`	varchar(16), FK → `meeting_types` (`RESTRICT`)	Na ordinária	Tipo do catálogo aplicável ao núcleo; nulo na extraordinária.
`series`	varchar(16)	Gerado	O código do tipo na ordinária; `EXT` na extraordinária.
`number`	integer	Gerado	Sequencial por núcleo, série e ano.
`year`	integer	Gerado	Ano da data marcada da reunião; sem data marcada, o ano corrente no fuso do escritório.
`createdAt`	timestamptz(3)	Gerado	—

O índice único (nucleusId, series, year, number) impede números repetidos. O número nasce na mesma transação que cria o Compromisso, com a linha do núcleo travada, e é apresentado como NN/AAAA-SÉRIE, por exemplo 03/2026-REU003 ou 01/2026-EXT.

Ata (`meeting_minutes`)

Atributo	Tipo	Obrigatório	Regra
`id`	UUID, chave primária	Gerado	—
`workItemId`	UUID, FK → `work_items` (`RESTRICT`), único	Sim	Reunião de origem; cada reunião tem no máximo uma ata. A ata leva o número da reunião.
`nucleusId`	UUID, FK → `nuclei` (`RESTRICT`)	Derivado	Núcleo responsável pela reunião, derivado da designação dela.
`content`	text, padrão `''`	Não	Texto da ata; um parágrafo por deliberação.
`agenda`	jsonb, lista de textos, padrão `[]`	Não	Itens da pauta.
`attendees`	jsonb, lista de `{name, role}`, padrão `[]`	Não	Presentes, com o papel de cada um na reunião; nome e papel de 1 a 255 caracteres.
`absentees`	jsonb, lista de `{name, role}`, padrão `[]`	Não	Ausentes, com o papel de cada um.
`status`	enum `draft` ou `registered`, padrão `draft`	Gerado	Passa a `registered` no registro.
`version`	integer	Gerado	Aumenta a cada salvamento. Na API vigente, a escrita informa a versão que leu; a edição simultânea (RN-GESTAO-043) deixa de recusar por versão, e o destino do campo será definido com o canal de edição simultânea, a criar.
`authorUserId`	UUID, FK → `users` (`RESTRICT`)	Gerado	Quem criou a ata.
`registeredAt`	timestamptz(3)	Gerado	Instante do registro; nulo enquanto rascunho.
`registeredBy`	UUID, FK → `users` (`SET NULL`)	Gerado	Quem registrou; nulo enquanto rascunho ou após a exclusão do usuário.
`createdAt`, `updatedAt`	timestamptz(3)	Gerado	—

Resolução (`resolutions`)

Atributo	Tipo	Obrigatório	Regra
`id`	UUID, chave primária	Gerado	—
`nucleusId`	UUID, FK → `nuclei` (`RESTRICT`)	Sim	Núcleo que resolve.
`number`	integer	Gerado	Sequencial por núcleo e por ano; exibido com dois dígitos.
`year`	integer	Gerado	Ano do registro, no fuso do escritório.
`ementa`	varchar(1000)	Sim	Uma linha que resume a resolução; a entrada aceita de 1 a 160 caracteres.
`considerando`	text	Sim	O problema que motiva a resolução, em um ou mais parágrafos.
`comando`	text	Sim	A decisão, em parágrafos corridos, sem artigos nem dispositivos numerados.
`effectiveFrom`	date	Gerado	Início de vigência; sem informação, a data do registro no fuso do escritório.
`status`	enum `vigente`, `revogada` ou `cumprida`, padrão `vigente`	Gerado	Só sai de `vigente`.
`revokesId`	UUID, FK → `resolutions` (`RESTRICT`)	Não	Resolução vigente do mesmo núcleo revogada por esta.
`meetingMinutesId`	UUID, FK → `meeting_minutes` (`RESTRICT`)	Não	Ata registrada do mesmo núcleo de que a resolução nasceu.
`authorUserId`	UUID, FK → `users` (`RESTRICT`)	Gerado	Quem registrou a resolução.
`createdAt`, `updatedAt`	timestamptz(3)	Gerado	—

O índice único (nucleusId, year, number) impede números repetidos no núcleo; o registro trava a linha do núcleo antes de ler o maior número. O signatário não é coluna: o documento da resolução o mostra com o nome de quem registra e a função “Liderança do Núcleo <nome do núcleo>”.

Relações e cardinalidades

Relação	Cardinalidade	Obrigatória	Integridade
Núcleo → reuniões	1 : N, pela designação `assignee` com alvo `org_unit`	Do lado da reunião do núcleo	Referência lógica em `work_item_people`, criada na mesma transação do Compromisso.
Compromisso → número da reunião	1 : 0..1	Do lado do número	FK única `workItemId`, `RESTRICT`.
Tipo de reunião → números	1 : N	Não, do lado do número	FK `typeCode`, `RESTRICT`.
Compromisso → ata	1 : 0..1	Do lado da ata	FK única `workItemId`, `RESTRICT`.
Núcleo → atas e resoluções	1 : N	Do lado da ata e da resolução	FK `nucleusId`, `RESTRICT`.
Ata → resoluções	1 : N	Não	FK `meetingMinutesId`, `RESTRICT`.
Resolução → resolução revogada	N : 0..1	Não	FK `revokesId`, `RESTRICT`.

Ciclo de vida

A reunião recebe o número no agendamento. A ata, quando existe, nasce em rascunho ligada a uma reunião do núcleo, recebe a edição simultânea dos editores (a criar na API; hoje, salvamentos com controle de versão) e, ao ser registrada, passa a só leitura e ganha página própria de documento. A resolução nasce vigente com o próximo número do núcleo no ano do registro e página própria de documento; enquanto vigente, pode passar a revogada ou a cumprida.