Modelagem de Dados e SQL

O que é

• Modelagem de dados descreve quais informações o sistema armazena, como se relacionam e quais regras de integridade devem valer.
• O modelo entidade-relacionamento (ER) é o ponto de partida; depois converte-se em tabelas no banco relacional.
• SQL (Structured Query Language) é a linguagem padrão para criar estruturas (DDL), manipular dados (DML) e consultar (SELECT).
• Modelo e consultas alinhados aos requisitos evitam dados duplicados, inconsistências e consultas lentas na exportação de relatórios.

Conceitos do modelo ER

• Entidade: objeto de negócio persistente (ex.: Usuário, Atividade, Log de exportação).
• Atributo: propriedade da entidade (tipo, tamanho, obrigatoriedade, valor padrão).
• Relacionamento: associação entre entidades (1:1, 1:N, N:N) com cardinalidade e opcionalidade.
• Chave primária (PK): identifica unicamente cada linha; chave estrangeira (FK) referencia outra tabela.
• Normalização (1FN, 2FN, 3FN): reduz redundância — ex.: não repetir nome do gestor em cada atividade se já existe em Usuário.

Exemplo visual — diagrama ER

• Diagrama simplificado do cenário usado nos tópicos ADS (consulta de atividades e RF-012 exportar PDF).
• Um gestor (Usuário) possui muitas Atividades; cada exportação gera registro em Log de exportação.

SQL essencial

• DDL: CREATE TABLE, ALTER, índices (INDEX), constraints (NOT NULL, UNIQUE, CHECK, FOREIGN KEY).
• DML: INSERT, UPDATE, DELETE — sempre preferir transações quando várias tabelas participam do mesmo fluxo.
• Consultas: SELECT com WHERE, JOIN (INNER, LEFT), GROUP BY, HAVING, ORDER BY, LIMIT.
• Índices em colunas de filtro (ex.: data_hora da Atividade) melhoram desempenho do relatório e da exportação PDF.
• Views podem encapsular consultas complexas usadas pela API e pelo gerador de PDF.

Boas práticas

• Nomear tabelas e colunas de forma consistente (snake_case em PostgreSQL/MySQL).
• Documentar dicionário de dados: significado de cada campo e origem no negócio.
• Evitar SELECT * em produção; projetar apenas colunas necessárias.
• Parametrizar consultas na aplicação (prepared statements) para prevenir SQL injection.
• Planejar migrações versionadas (Flyway, Liquibase) em vez de alterar banco manualmente em produção.

Modelo textual — dicionário de dados (campo)

• Registre cada coluna relevante antes de implementar a API ou o relatório.

────────────────────────────────────────────────────────────
DICIONÁRIO DE DADOS — CAMPO
────────────────────────────────────────────────────────────

Tabela:          [nome_tabela]
Coluna:          [nome_coluna]
Tipo lógico:     [texto | inteiro | data/hora | boolean | decimal]
Tipo físico:     [VARCHAR(255) | TIMESTAMP WITH TIME ZONE | ...]
Obrigatório:     [Sim | Não]
Chave:           [PK | FK → tabela.coluna | —]
Descrição:       [significado no negócio]
Regra / RN:      [validação, domínio de valores]
Origem RF:       [RF-xxx]
Exemplo:         [valor válido]

────────────────────────────────────────────────────────────
EXEMPLO
────────────────────────────────────────────────────────────

Tabela:          atividade
Coluna:          data_hora
Tipo lógico:     data/hora do evento
Tipo físico:     TIMESTAMPTZ NOT NULL
Obrigatório:     Sim
Chave:           —
Descrição:       Momento em que a atividade foi registrada ou alterada
Regra / RN:      Armazenar em UTC; exibir no fuso do usuário (BUG-09)
Origem RF:       RF-008, RF-012
Exemplo:         2026-05-15T14:30:00Z

Modelo textual — script SQL (consulta para PDF)

• Consulta parametrizada usada pelo serviço de exportação (RF-012).

────────────────────────────────────────────────────────────
CONSULTA SQL — EXPORTAÇÃO PDF (RF-012)
────────────────────────────────────────────────────────────

-- Parâmetros: :id_usuario, :data_inicio, :data_fim (TIMESTAMPTZ)

SELECT
    a.id_atividade,
    a.data_hora,
    a.descricao,
    a.tipo,
    a.status
FROM atividade a
WHERE a.id_usuario = :id_usuario
  AND a.data_hora >= :data_inicio
  AND a.data_hora <  :data_fim + INTERVAL '1 day'
ORDER BY a.data_hora ASC;

-- Índice recomendado:
-- CREATE INDEX idx_atividade_usuario_data
--   ON atividade (id_usuario, data_hora);

-- Após gerar PDF, inserir auditoria:
-- INSERT INTO log_exportacao (id_usuario, periodo_inicio, periodo_fim, hash_arquivo)
-- VALUES (...);