---
id: modelagem-de-dados
title: Modelagem de dados
description: Modelo lógico relacional do sistema, com tabelas, colunas, chaves estrangeiras e relações direcionadas.
type: data-model
status: defined
visibility: public
tags: sge/modelagem, sge/schema, sge/banco-de-dados
related: dominio-e-modelo-de-dados, modelo-de-dados-nucleo, modelo-de-dados-acesso, modelo-de-dados-historico, ciclos-de-status, migrations
source_refs: content/modelo-de-dados-nucleo.md, content/modelo-de-dados-acesso.md, content/modelo-de-dados-historico.md
diagram: modelo-dados-schema
---
Esta é a referência visual do modelo lógico relacional. Cada caixa representa uma tabela e cada linha representa uma coluna com seu tipo. `PK` identifica a chave primária, `FK` a chave estrangeira e `UK` a unicidade. As setas acompanham a relação entre as tabelas; a coluna marcada como `FK` identifica o vínculo sem repetir texto sobre a linha.

> **Diagrama: Modelo lógico — visão geral**
> Visão das cinco tabelas centrais que conectam identidade, solicitação, estágio e documentos.
> Leitura semântica: A conta possui vínculos; um vínculo autoriza a solicitação; a solicitação origina o estágio; e o estágio referencia documentos gerados. Avaliações ficam no recorte de execução.
> Fonte semântica: `diagrams/modelo-dados-schema.json`
> Dados estruturados: `api/diagrams/modelo-dados-schema.json`
> Fonte declarativa: `diagrams/sources/modelo-dados-schema.mmd`

> [!info] Nível de detalhe
> Os diagramas mostram a estrutura e as colunas que orientam as relações. O contrato completo de cada tabela — tipos, nulabilidade, índices, unicidade, exclusão e regras condicionais — está nas notas de [Migrations](doc:migrations), que são a fonte de verdade para implementação.

## Identidade e cadastros

Contas, dados pessoais, cidades, endereços e vínculos formam o contexto institucional. Campus, curso e tipo de estágio são cadastros que restringem o escopo do processo.

> **Diagrama: Esquema lógico — identidade e cadastros**
> Tabelas e colunas de identidade, dados pessoais, cidades, endereços, campus e vínculos institucionais.
> Leitura semântica: A conta possui dados pessoais e vínculos; cidades são catalogadas pelo código IBGE, endereços apontam para elas e cadastros mantêm endereços atuais.
> Fonte semântica: `diagrams/modelo-nucleo-identidade.json`
> Dados estruturados: `api/diagrams/modelo-nucleo-identidade.json`
> Fonte declarativa: `diagrams/sources/modelo-nucleo-identidade.mmd`

Detalhes dos contratos: [cities](doc:migration-01a-cities), [addresses](doc:migration-01-addresses), [user_personal_data](doc:migration-02-user-personal-data), [campuses](doc:migration-03-campuses), [affiliations](doc:migration-04-affiliations), [courses](doc:migration-09-courses) e [internship_types](doc:migration-11-internship-types).

## Contexto de acesso

O mesmo conjunto de tabelas aparece isolado abaixo para deixar explícito o recorte usado por Gates e Policies: uma conta pode possuir vários vínculos, e cada vínculo carrega tipo, campus e curso.

> **Diagrama: Esquema lógico — contexto de acesso**
> Tabelas e colunas de conta, campus, curso e vínculo institucional usadas no contexto de autorização.
> Leitura semântica: Uma conta exerce vários vínculos; cada vínculo referencia campus e curso, carrega o tipo funcional e define o escopo das Policies.
> Fonte semântica: `diagrams/modelo-acesso-erd.json`
> Dados estruturados: `api/diagrams/modelo-acesso-erd.json`
> Fonte declarativa: `diagrams/sources/modelo-acesso-erd.mmd`

Leia também [Pessoas e responsabilidades](doc:pessoas-e-responsabilidades) e [Matriz de autorização](doc:matriz-de-autorizacao).

## Solicitação e formalização

Uma solicitação é criada por um vínculo discente, recebe dados de curso, tipo e concedente, e pode acumular correções e evidências privadas antes da formalização.

> **Diagrama: Esquema lógico — solicitação e formalização**
> Tabelas e colunas que registram a solicitação e os cadastros usados para formalizar o estágio.
> Leitura semântica: A solicitação é enviada por um vínculo discente, referencia curso, tipo e concedente, e mantém o estado que conduz à formalização.
> Fonte semântica: `diagrams/modelo-nucleo-solicitacao.json`
> Dados estruturados: `api/diagrams/modelo-nucleo-solicitacao.json`
> Fonte declarativa: `diagrams/sources/modelo-nucleo-solicitacao.mmd`

As relações que completam a formalização ficam neste recorte: [correções e evidências](../diagrams/modelo-solicitacao-apoio.html).

> **Diagrama: Esquema lógico — apoio da solicitação**
> Tabelas relacionadas à formalização do estágio, correções e evidências privadas.
> Leitura semântica: Uma solicitação pode originar um estágio e receber várias correções e evidências; cada registro preserva sua própria chave e estado.
> Fonte semântica: `diagrams/modelo-solicitacao-apoio.json`
> Dados estruturados: `api/diagrams/modelo-solicitacao-apoio.json`
> Fonte declarativa: `diagrams/sources/modelo-solicitacao-apoio.mmd`

Detalhes dos contratos: [granting_parties](doc:migration-12-granting-parties), [supervisor_registration_requests](doc:migration-12a-supervisor-registration-requests), [granting_party_registration_requests](doc:migration-12b-granting-party-registration-requests), [internship_requests](doc:migration-19-internship-requests), [emancipation_evidences](doc:migration-19a-emancipation-evidences) e [internship_request_corrections](doc:migration-20-internship-request-corrections).

## Execução do estágio

Depois do aceite, o estágio concentra as vigências de jornada, pausas, o cálculo baseado no calendário nacional, estadual e municipal aplicável à cidade/UF do endereço histórico do local de trabalho, pedidos de cancelamento e avaliação do supervisor.

> **Diagrama: Esquema lógico — execução do estágio**
> Tabelas e colunas que controlam endereço de trabalho, feriados, vigência, jornadas, pausas e cancelamento.
> Leitura semântica: O estágio usa os feriados nacionais, estaduais e municipais aplicáveis ao endereço do local de trabalho, possui jornadas, pausas e exceções e pode receber um pedido de cancelamento; a avaliação é detalhada no contrato próprio.
> Fonte semântica: `diagrams/modelo-nucleo-execucao.json`
> Dados estruturados: `api/diagrams/modelo-nucleo-execucao.json`
> Fonte declarativa: `diagrams/sources/modelo-nucleo-execucao.mmd`

Detalhes dos contratos: [internships](doc:migration-15-internships), [internship_pauses](doc:migration-17-internship-pauses), [avaliações](doc:migration-18-supervisor-evaluations), [internship_cancellation_requests](doc:migration-21-internship-cancellation-requests), [holidays](doc:migration-22-holidays), [internship_calendar_overrides](doc:migration-22-internship-calendar-overrides) e [internship_work_schedules](doc:migration-23-internship-work-schedules).

## Documentos e versões

Templates são catálogos; versões são imutáveis depois da ativação; documentos gerados preservam a versão e o snapshot usado no processo.

> **Diagrama: Esquema lógico — documentos e versões**
> Tabelas e colunas do catálogo de templates, suas versões e documentos produzidos no estágio.
> Leitura semântica: Um template possui versões imutáveis; cada documento gerado referencia a versão usada, o estágio e os dados congelados da geração.
> Fonte semântica: `diagrams/modelo-documentos-schema.json`
> Dados estruturados: `api/diagrams/modelo-documentos-schema.json`
> Fonte declarativa: `diagrams/sources/modelo-documentos-schema.mmd`

| Tabela | Papel | Contrato |
| --- | --- | --- |
| `document_templates` | catálogo de modelos por campus ou globais | [Migration 13](doc:migration-13-document-templates) |
| `template_versions` | versões, variáveis e validação do arquivo | [Migration 14](doc:migration-14-template-versions) |
| `generated_documents` | documento gerado ou registrado no estágio | [Migration 16](doc:migration-16-generated-documents) |

## Histórico e comunicação

O histórico operacional separa auditoria, notificação, mensagem e tentativa de transporte. Um registro não substitui o outro. `activity_log` não recebe uma seta porque registra `subject` e `causer` de forma polimórfica: seu alvo depende do tipo gravado em cada linha.

> **Diagrama: Esquema lógico — histórico e comunicação**
> Auditoria polimórfica, notificações, mensagens e tentativas de entrega.
> Leitura semântica: Activity log registra sujeito e causador de forma polimórfica; notificações podem originar mensagens e cada mensagem possui tentativas de entrega append-only.
> Fonte semântica: `diagrams/modelo-historico.json`
> Dados estruturados: `api/diagrams/modelo-historico.json`
> Fonte declarativa: `diagrams/sources/modelo-historico.mmd`

Detalhes dos contratos: [activity_log](doc:migration-base-04-activity-log), [notifications](doc:migration-05-notifications), [email_messages](doc:migration-06-email-messages) e [email_delivery_attempts](doc:migration-07-email-delivery-attempts).

## Regras do modelo

- FKs apontam para cadastros atuais; snapshots e cópias históricas de endereço preservam os valores usados em um processo já iniciado. Cada cadastro ou registro histórico usa sua própria linha de `addresses`, mesmo quando os valores coincidem.
- A solicitação origina no máximo um estágio, mas correções e evidências podem ser várias.
- `internships` é o agregado operacional: jornadas, pausas, documentos, avaliações e cancelamentos dependem dele.
- Templates podem ter muitas versões, mas um documento gerado referencia apenas a versão usada na geração.
- Notificações podem originar mensagens; cada mensagem pode ter várias tentativas de entrega.
- A autorização nasce do vínculo ativo, não de uma permissão gravada em tabela.

Para estados e transições, consulte [Ciclos de status](doc:ciclos-de-status). Para o contrato textual consolidado, consulte [Domínio e modelo de dados](doc:dominio-e-modelo-de-dados).