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
```sql
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
```sql
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
```sql
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
```sql
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
```sql
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
```sql
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
```sql
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
```sql
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
```mermaid
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
```sql
-- 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)
```sql
-- 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
```sql
-- 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
```sql
-- 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