{
  "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"
  ],
  "sourceRefs": [
    "content/modelo-de-dados-nucleo.md",
    "content/modelo-de-dados-acesso.md",
    "content/modelo-de-dados-historico.md"
  ],
  "authors": [],
  "updated": null,
  "diagram": "modelo-dados-schema",
  "body": "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.\n\n{{diagram:modelo-dados-schema}}\n\n> [!info] Nível de detalhe\n> 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.\n\n## Identidade e cadastros\n\nContas, 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.\n\n{{diagram:modelo-nucleo-identidade}}\n\nDetalhes 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).\n\n## Contexto de acesso\n\nO 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.\n\n{{diagram:modelo-acesso-erd}}\n\nLeia também [Pessoas e responsabilidades](doc:pessoas-e-responsabilidades) e [Matriz de autorização](doc:matriz-de-autorizacao).\n\n## Solicitação e formalização\n\nUma 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.\n\n{{diagram:modelo-nucleo-solicitacao}}\n\nAs relações que completam a formalização ficam neste recorte: [correções e evidências](../diagrams/modelo-solicitacao-apoio.html).\n\n{{diagram:modelo-solicitacao-apoio}}\n\nDetalhes 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).\n\n## Execução do estágio\n\nDepois 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.\n\n{{diagram:modelo-nucleo-execucao}}\n\nDetalhes 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).\n\n## Documentos e versões\n\nTemplates 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.\n\n{{diagram:modelo-documentos-schema}}\n\n| Tabela | Papel | Contrato |\n| --- | --- | --- |\n| `document_templates` | catálogo de modelos por campus ou globais | [Migration 13](doc:migration-13-document-templates) |\n| `template_versions` | versões, variáveis e validação do arquivo | [Migration 14](doc:migration-14-template-versions) |\n| `generated_documents` | documento gerado ou registrado no estágio | [Migration 16](doc:migration-16-generated-documents) |\n\n## Histórico e comunicação\n\nO 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.\n\n{{diagram:modelo-historico}}\n\nDetalhes 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).\n\n## Regras do modelo\n\n- 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.\n- A solicitação origina no máximo um estágio, mas correções e evidências podem ser várias.\n- `internships` é o agregado operacional: jornadas, pausas, documentos, avaliações e cancelamentos dependem dele.\n- Templates podem ter muitas versões, mas um documento gerado referencia apenas a versão usada na geração.\n- Notificações podem originar mensagens; cada mensagem pode ter várias tentativas de entrega.\n- A autorização nasce do vínculo ativo, não de uma permissão gravada em tabela.\n\nPara 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).",
  "sections": [
    {
      "id": "identidade-e-cadastros",
      "level": 2,
      "title": "Identidade e cadastros",
      "text": "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.   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).",
      "line": 8
    },
    {
      "id": "contexto-de-acesso",
      "level": 2,
      "title": "Contexto de acesso",
      "text": "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.   Leia também [Pessoas e responsabilidades](doc:pessoas-e-responsabilidades) e [Matriz de autorização](doc:matriz-de-autorizacao).",
      "line": 16
    },
    {
      "id": "solicitacao-e-formalizacao",
      "level": 2,
      "title": "Solicitação e formalização",
      "text": "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.   As relações que completam a formalização ficam neste recorte: [correções e evidências](../diagrams/modelo-solicitacao-apoio.html).   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).",
      "line": 24
    },
    {
      "id": "execucao-do-estagio",
      "level": 2,
      "title": "Execução do estágio",
      "text": "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.   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).",
      "line": 36
    },
    {
      "id": "documentos-e-versoes",
      "level": 2,
      "title": "Documentos e versões",
      "text": "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.   | 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) |",
      "line": 44
    },
    {
      "id": "historico-e-comunicacao",
      "level": 2,
      "title": "Histórico e comunicação",
      "text": "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.   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).",
      "line": 56
    },
    {
      "id": "regras-do-modelo",
      "level": 2,
      "title": "Regras do modelo",
      "text": "- 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).",
      "line": 64
    }
  ],
  "sourcePath": "content/modelagem-de-dados.md",
  "visuals": [
    {
      "id": "modelo-acesso-erd",
      "kind": "db-schema",
      "title": "Esquema lógico — contexto de acesso",
      "description": "Tabelas e colunas de conta, campus, curso e vínculo institucional usadas no contexto de autorização.",
      "summary": "Uma conta exerce vários vínculos; cada vínculo referencia campus e curso, carrega o tipo funcional e define o escopo das Policies.",
      "renderMode": "mermaid",
      "api": "api/diagrams/modelo-acesso-erd.json",
      "human": "diagrams/modelo-acesso-erd.html"
    },
    {
      "id": "modelo-dados-schema",
      "kind": "db-schema",
      "title": "Modelo lógico — visão geral",
      "description": "Visão das cinco tabelas centrais que conectam identidade, solicitação, estágio e documentos.",
      "summary": "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.",
      "renderMode": "mermaid",
      "api": "api/diagrams/modelo-dados-schema.json",
      "human": "diagrams/modelo-dados-schema.html"
    },
    {
      "id": "modelo-documentos-schema",
      "kind": "db-schema",
      "title": "Esquema lógico — documentos e versões",
      "description": "Tabelas e colunas do catálogo de templates, suas versões e documentos produzidos no estágio.",
      "summary": "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.",
      "renderMode": "mermaid",
      "api": "api/diagrams/modelo-documentos-schema.json",
      "human": "diagrams/modelo-documentos-schema.html"
    },
    {
      "id": "modelo-historico",
      "kind": "db-schema",
      "title": "Esquema lógico — histórico e comunicação",
      "description": "Auditoria polimórfica, notificações, mensagens e tentativas de entrega.",
      "summary": "Activity log registra sujeito e causador de forma polimórfica; notificações podem originar mensagens e cada mensagem possui tentativas de entrega append-only.",
      "renderMode": "mermaid",
      "api": "api/diagrams/modelo-historico.json",
      "human": "diagrams/modelo-historico.html"
    },
    {
      "id": "modelo-nucleo-execucao",
      "kind": "db-schema",
      "title": "Esquema lógico — execução do estágio",
      "description": "Tabelas e colunas que controlam endereço de trabalho, feriados, vigência, jornadas, pausas e cancelamento.",
      "summary": "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.",
      "renderMode": "mermaid",
      "api": "api/diagrams/modelo-nucleo-execucao.json",
      "human": "diagrams/modelo-nucleo-execucao.html"
    },
    {
      "id": "modelo-nucleo-identidade",
      "kind": "db-schema",
      "title": "Esquema lógico — identidade e cadastros",
      "description": "Tabelas e colunas de identidade, dados pessoais, cidades, endereços, campus e vínculos institucionais.",
      "summary": "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.",
      "renderMode": "mermaid",
      "api": "api/diagrams/modelo-nucleo-identidade.json",
      "human": "diagrams/modelo-nucleo-identidade.html"
    },
    {
      "id": "modelo-nucleo-solicitacao",
      "kind": "db-schema",
      "title": "Esquema lógico — solicitação e formalização",
      "description": "Tabelas e colunas que registram a solicitação e os cadastros usados para formalizar o estágio.",
      "summary": "A solicitação é enviada por um vínculo discente, referencia curso, tipo e concedente, e mantém o estado que conduz à formalização.",
      "renderMode": "mermaid",
      "api": "api/diagrams/modelo-nucleo-solicitacao.json",
      "human": "diagrams/modelo-nucleo-solicitacao.html"
    },
    {
      "id": "modelo-solicitacao-apoio",
      "kind": "db-schema",
      "title": "Esquema lógico — apoio da solicitação",
      "description": "Tabelas relacionadas à formalização do estágio, correções e evidências privadas.",
      "summary": "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.",
      "renderMode": "mermaid",
      "api": "api/diagrams/modelo-solicitacao-apoio.json",
      "human": "diagrams/modelo-solicitacao-apoio.html"
    }
  ],
  "apiVersion": 1
}