story-generator/docs/banco-dados.md

Estrutura do Banco de Dados

Visão Geral

O banco de dados foi projetado para suportar um sistema educacional de leitura, geração de histórias e exercícios fonéticos, com foco em rastreamento de progresso e gamificação.

Entidades

1. Escolas e Classes

create table schools (
  id uuid primary key default uuid_generate_v4(),
  name text not null,
  address text,
  phone text,
  email text,
  director_name text,
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

create table classes (
  id uuid primary key default uuid_generate_v4(),
  school_id uuid references schools(id),
  teacher_id uuid references users(id),
  name text not null,
  grade text,
  year integer,
  period text,
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

create table students (
  id uuid primary key default uuid_generate_v4(),
  user_id uuid references users(id),
  class_id uuid references classes(id),
  reading_level text,
  birth_date date,
  active boolean default true,
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

2. Histórias

create table stories (
  id uuid primary key default uuid_generate_v4(),
  student_id uuid references users(id),
  title text not null,
  content jsonb not null,
  status text,
  theme_id uuid,
  subject_id uuid,
  character_id uuid,
  setting_id uuid,
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

3. Interesses

create table interests (
  id uuid primary key default uuid_generate_v4(),
  student_id uuid references users(id),
  category text not null,
  item text not null,
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

4. Sistema de Conquistas

create table achievement_types (
  id uuid primary key default uuid_generate_v4(),
  name varchar not null,
  description text,
  created_at timestamptz default now()
);

create table achievements (
  id uuid primary key default uuid_generate_v4(),
  name text not null,
  description text
);

5. Sistema Fonético

Categorias e Palavras

create table phonics_categories (
  id uuid primary key default uuid_generate_v4(),
  name varchar not null,
  description text,
  level integer,
  order_index integer,
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

create table phonics_words (
  id uuid primary key default uuid_generate_v4(),
  word varchar not null,
  phonetic_transcription varchar,
  syllables_count integer,
  created_at timestamptz default now()
);

create table phonics_word_audio (
  id uuid primary key default uuid_generate_v4(),
  word text not null,
  audio_url text,
  audio_path text,
  created_at timestamptz default now()
);

Exercícios

create table phonics_exercise_types (
  id uuid primary key default uuid_generate_v4(),
  name varchar not null,
  description text,
  created_at timestamptz default now()
);

create table phonics_exercises (
  id uuid primary key default uuid_generate_v4(),
  category_id uuid references phonics_categories(id),
  type_id uuid references phonics_exercise_types(id),
  title varchar not null,
  description text,
  difficulty_level integer,
  estimated_time_seconds integer,
  instructions text,
  points integer,
  is_active boolean default true,
  required_score double precision,
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

create table phonics_exercise_words (
  id uuid primary key default uuid_generate_v4(),
  exercise_id uuid references phonics_exercises(id),
  word_id uuid references phonics_words(id),
  is_correct_answer boolean,
  order_index integer,
  created_at timestamptz default now()
);

Mídia

create table media_types (
  id uuid primary key default uuid_generate_v4(),
  name varchar not null,
  description text,
  created_at timestamptz default now()
);

create table phonics_exercise_media (
  id uuid primary key default uuid_generate_v4(),
  exercise_id uuid references phonics_exercises(id),
  media_type_id uuid references media_types(id),
  url text,
  alt_text text,
  order_index integer,
  created_at timestamptz default now()
);

Conquistas Fonéticas

create table phonics_achievements (
  id uuid primary key default uuid_generate_v4(),
  type_id uuid references achievement_types(id),
  name varchar not null,
  description text,
  points integer,
  icon_url text,
  required_count integer,
  created_at timestamptz default now()
);

Relacionamentos

Hierarquia Principal

erDiagram
    Schools ||--o{ Classes : "has"
    Classes ||--o{ Students : "contains"
    Students ||--o{ Stories : "creates"
    Students ||--o{ Interests : "has"
    Students ||--o{ Achievements : "earns"
    
    PhonicsCategories ||--o{ PhonicsExercises : "contains"
    PhonicsExercises ||--o{ PhonicsExerciseWords : "has"
    PhonicsWords }|--o{ PhonicsExerciseWords : "used_in"
    PhonicsExercises ||--o{ PhonicsExerciseMedia : "has"
    MediaTypes ||--o{ PhonicsExerciseMedia : "defines"

Índices e Otimizações

Performance

-- Busca de exercícios por categoria
create index idx_exercises_category on phonics_exercises(category_id);

-- Busca de histórias por aluno
create index idx_stories_student on stories(student_id);

-- Busca de palavras por exercício
create index idx_exercise_words on phonics_exercise_words(exercise_id);

-- Busca por conteúdo de história
create index idx_stories_content on stories using gin (content);

Considerações de Segurança

RLS (Row Level Security)

-- Alunos só podem ver suas próprias histórias
create policy "Students view own stories" on stories
  for select using (auth.uid() = student_id);

-- Professores podem ver histórias de seus alunos
create policy "Teachers view class stories" on stories
  for select using (
    auth.uid() in (
      select teacher_id from classes c
      join students s on s.class_id = c.id
      where s.id = stories.student_id
    )
  );

Triggers

Atualização Automática

-- Atualizar student_progress após nova gravação
create trigger update_student_progress
  after insert or update on story_recordings
  for each row
  execute function update_student_progress();

-- Calcular duração da sessão de leitura
create trigger calculate_session_duration
  before update on reading_sessions
  for each row
  when (NEW.end_time is not null)
  execute function calculate_session_duration();

Funções

Análise de Progresso

-- Calcular nível de leitura
create function calculate_reading_level(
  student_id uuid
) returns text as $$
  -- Lógica de cálculo baseada em:
  -- - Média de palavras por minuto
  -- - Scores de fluência
  -- - Quantidade de histórias lidas
$$ language plpgsql;

-- Atualizar métricas de progresso
create function update_student_progress() returns trigger as $$
  -- Atualiza:
  -- - Médias de performance
  -- - Total de tempo lido
  -- - Histórias completadas
  -- - Pontos fortes e melhorias
$$ language plpgsql;

Considerações de Performance

1. Particionamento

• Gravações particionadas por mês
• Sessões particionadas por aluno
• Histórias particionadas por complexidade

2. Vacuum

• Análise regular de dead tuples
• Vacuum automático configurado
• Monitoramento de bloat

3. Cache

• Histórias populares em cache
• Métricas de progresso em cache
• Configurações de usuário em cache

Backup e Recuperação

1. Estratégia

• Backup completo diário
• WAL archiving contínuo
• Retenção de 30 dias
• Teste mensal de recuperação

2. Monitoramento

• Tamanho do banco
• Tempo de queries
• Uso de índices
• Deadlocks