03 — Modelagem de Entidades — Dito e Feito¶

Esboço do modelo relacional do sistema, com as principais entidades, seus atributos e relacionamentos.

Entidades principais¶

1. `parlamentar`¶

Representa um deputado federal com seus dados cadastrais.

CREATE TABLE parlamentar (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    id_externo BIGINT UNIQUE, -- ID da API da Câmara
    nome_civil TEXT NOT NULL,
    nome_urna TEXT,
    sigla_partido VARCHAR(15),
    sigla_uf VARCHAR(2),
    foto_url TEXT,
    email TEXT,
    situacao TEXT, -- ex: "Exercício", "Afastado"
    dados_api JSONB, -- resposta bruta da API (opcional)
    criado_em TIMESTAMPTZ DEFAULT now(),
    atualizado_em TIMESTAMPTZ DEFAULT now()
);

2. `discurso`¶

Pronunciamentos feitos pelo parlamentar em plenário ou comissões.

CREATE TYPE fase_discurso AS ENUM (
    'Plenário', 'Comissão', 'CPI', 'Outro'
);

CREATE TABLE discurso (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    id_externo BIGINT UNIQUE,
    parlamentar_id UUID NOT NULL REFERENCES parlamentar(id) ON DELETE CASCADE,
    data_hora TIMESTAMPTZ NOT NULL,
    fase fase_discurso,
    sumario TEXT,
    transcricao TEXT, -- texto completo, se disponível
    palavras_chave TEXT[], -- extraídas por NLP
    dados_api JSONB,
    criado_em TIMESTAMPTZ DEFAULT now()
);

3. `proposicao`¶

Uma proposta legislativa (PL, PEC, MPV, etc.) que vai a votação.

CREATE TABLE proposicao (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    id_externo BIGINT UNIQUE,
    sigla_tipo VARCHAR(10), -- ex: "PL", "PEC", "MPV"
    numero INTEGER,
    ano INTEGER,
    ementa TEXT,
    keywords TEXT[],
    dados_api JSONB,
    criado_em TIMESTAMPTZ DEFAULT now()
);

4. `votacao`¶

Evento de votação em plenário sobre uma proposição.

CREATE TABLE votacao (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    id_externo TEXT UNIQUE, -- ID da API (pode ser string)
    proposicao_id UUID REFERENCES proposicao(id) ON DELETE SET NULL,
    data_hora TIMESTAMPTZ NOT NULL,
    descricao TEXT,
    aprovada BOOLEAN,
    dados_api JSONB,
    criado_em TIMESTAMPTZ DEFAULT now()
);

5. `voto`¶

O voto individual de um parlamentar em uma votação específica.

CREATE TYPE resultado_voto AS ENUM (
    'Sim', 'Não', 'Abstenção', 'Obstrução', 'Art. 17', 'Ausente'
);

CREATE TABLE voto (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    parlamentar_id UUID NOT NULL REFERENCES parlamentar(id) ON DELETE CASCADE,
    votacao_id UUID NOT NULL REFERENCES votacao(id) ON DELETE CASCADE,
    resultado resultado_voto NOT NULL,
    criado_em TIMESTAMPTZ DEFAULT now(),
    UNIQUE (parlamentar_id, votacao_id) -- um parlamentar vota uma vez por votação
);

6. `score_coerencia`¶

Score calculado pela IA comparando os discursos e votos de um parlamentar.

CREATE TABLE score_coerencia (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    parlamentar_id UUID NOT NULL REFERENCES parlamentar(id) ON DELETE CASCADE,
    discurso_id UUID REFERENCES discurso(id) ON DELETE SET NULL,
    votacao_id UUID REFERENCES votacao(id) ON DELETE SET NULL,
    score NUMERIC(5, 2) CHECK (score >= 0 AND score <= 100),
    similaridade_coseno FLOAT, -- métrica do modelo NLP
    modelo_usado TEXT, -- ex: "sentence-transformers/..."
    justificativa TEXT, -- explicação gerada pela IA
    calculado_em TIMESTAMPTZ DEFAULT now()
);

Diagrama de relacionamentos (texto)¶

parlamentar
    │
    ├──< discurso (1 parlamentar → N discursos)
    │
    ├──< voto (1 parlamentar → N votos)
    │ │
    │ └──> votacao (N votos → 1 votação)
    │ │
    │ └──> proposicao (N votações → 1 proposição)
    │
    └──< score_coerencia (1 parlamentar → N scores)
             ├──> discurso
             └──> votacao

Diagrama ER (Mermaid)¶

Cole este código em mermaid.live para visualizar o diagrama.

erDiagram
    PARLAMENTAR {
        uuid id PK
        bigint id_externo
        text nome_civil
        text nome_urna
        varchar sigla_partido
        varchar sigla_uf
    }

    DISCURSO {
        uuid id PK
        uuid parlamentar_id FK
        timestamptz data_hora
        text sumario
        text transcricao
        text[] palavras_chave
    }

    PROPOSICAO {
        uuid id PK
        bigint id_externo
        varchar sigla_tipo
        integer numero
        integer ano
        text ementa
    }

    VOTACAO {
        uuid id PK
        uuid proposicao_id FK
        timestamptz data_hora
        text descricao
        boolean aprovada
    }

    VOTO {
        uuid id PK
        uuid parlamentar_id FK
        uuid votacao_id FK
        resultado_voto resultado
    }

    SCORE_COERENCIA {
        uuid id PK
        uuid parlamentar_id FK
        uuid discurso_id FK
        uuid votacao_id FK
        numeric score
        float similaridade_coseno
        text modelo_usado
    }

    PARLAMENTAR ||--o{ DISCURSO : "faz"
    PARLAMENTAR ||--o{ VOTO : "realiza"
    VOTACAO ||--o{ VOTO : "contém"
    PROPOSICAO ||--o{ VOTACAO : "origina"
    PARLAMENTAR ||--o{ SCORE_COERENCIA : "recebe"
    DISCURSO ||--o{ SCORE_COERENCIA : "alimenta"
    VOTACAO ||--o{ SCORE_COERENCIA : "alimenta"

Decisões de modelagem¶

Decisão	Justificativa
UUID como PK	Evita exposição de sequência, facilita integração entre serviços
`id_externo` separado	Preserva o ID da API sem depender dele como PK
`dados_api JSONB`	Permite armazenar a resposta bruta para reprocessamento futuro
ENUM para `resultado_voto`	Garante integridade sem depender da aplicação
`UNIQUE (parlamentar_id, votacao_id)` em `voto`	Impede duplicidade de votos
`score_coerencia` como tabela separada	O cálculo pode ser refeito com modelos diferentes

03 — Modelagem de Entidades — Dito e Feito¶

Entidades principais¶

1. parlamentar¶

2. discurso¶

3. proposicao¶

4. votacao¶

5. voto¶

6. score_coerencia¶