Modelagem de dados

A modelagem é feita com ActiveRecord sobre PostgreSQL. As bases legadas (Syens e Salus) têm milhares de migrations e um domínio grande, então consistência e integridade são essenciais.

Princípios

• Nomes em inglês para tabelas, colunas e modelos; rótulos de interface via i18n.
• Integridade no banco e no modelo: toda regra importante tem validação no modelo e constraint no banco (not-null, chave estrangeira, unicidade).
• Multitenancy (Syens): tabelas com dados de escola carregam a chave de tenant (school_id ou equivalente), sempre presente, validada e indexada.
• Associações explícitas: declare belongs_to/has_many e respeite a cardinalidade real do domínio.

Validações: modelo e banco juntos

class Enrollment < ActiveRecord::Base
  belongs_to :student
  belongs_to :classroom
  belongs_to :school

  validates :student_id, :classroom_id, :school_id, presence: true
  validates :student_id, uniqueness: { scope: [:school_id, :school_year_id] }
end

# A mesma garantia precisa existir no banco (migration reversível)
class AddConstraintsToEnrollments < ActiveRecord::Migration
  def change
    add_foreign_key :enrollments, :schools
    change_column_null :enrollments, :school_id, false
    add_index :enrollments, [:school_id, :school_year_id, :student_id], unique: true
  end
end

Enumerações

Valores de domínio (situações, tipos) usam enumerações claras. O Syens mantém uma pasta enumerations/ para tipos de domínio; em projetos mais novos use o enum do Rails. Evite "números mágicos" espalhados pelo código.

Dicionário de dados

O Syens gera um dicionário de dados a partir do schema (db/data_dictionary.md e db/generate_data_dictionary.rb). Ao criar tabelas e colunas, use nomes descritivos e comente o que não for óbvio, para o dicionário continuar útil.

Mudanças de schema

• Toda alteração entra por migration reversível (veja Banco de dados).
• Adicione índices para colunas usadas em filtros, ordenação e joins.
• Em tabelas grandes, pense no impacto de uma migration antes de rodá-la em produção (bloqueios, tempo).