docs: adiciona documentação completa do banco de dados - Documenta estrutura atual do Supabase - Adiciona diagramas ER e relacionamentos - Inclui pol��ticas de seguran��a e ��ndices - Documenta triggers e fun����es

CHANGELOG.md

@@ -120,6 +120,17 @@ e este projeto adere ao [Semantic Versioning](https://semver.org/lang/pt-BR/).
 - Timer de gravação no Modo Foco
 - Transições suaves entre modos
 - Controles flutuantes durante o Modo Foco
+- Documentação completa da estrutura do banco de dados em `/docs/banco-dados.md`:
+  - Escolas e Classes
+  - Sistema de Alunos
+  - Histórias
+  - Interesses
+  - Sistema de Conquistas
+  - Sistema Fonético completo
+  - Relacionamentos e índices
+  - Políticas de segurança
+  - Triggers e funções
+  - Considerações de performance
 
 ### Modificado
 - Componente AudioRecorder atualizado para suportar Modo Foco
@@ -133,3 +144,7 @@ e este projeto adere ao [Semantic Versioning](https://semver.org/lang/pt-BR/).
 - Callbacks de início e fim de gravação
 - Sistema de transição entre modos normal e foco
 - Otimização de performance para transições suaves
+- Atualização das definições de tabelas para refletir a estrutura atual do Supabase
+- Adição de diagramas ER para visualização dos relacionamentos
+- Documentação de índices e políticas de segurança
+- Inclusão de considerações de performance e backup

docs/banco-dados.md

@@ -0,0 +1,315 @@
+# 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 

docs/controles-texto.md

@@ -0,0 +1,117 @@
+# Controles de Texto
+
+## Visão Geral
+Os controles de texto são um conjunto de funcionalidades que permitem aos usuários personalizar a apresentação do texto para melhor legibilidade e compreensão.
+
+## Componentes Principais
+
+### 1. TextControls
+Componente principal que agrupa todos os controles de texto.
+
+#### Seção 1: Controles de Formatação Básica
+- **Maiúsculas/Minúsculas**
+  - Alterna entre texto em maiúsculas e minúsculas
+  - Útil para leitores iniciantes
+  - Mantém estado global da preferência
+
+- **Sílabas**
+  - Ativa/desativa a separação silábica
+  - Ajuda na compreensão da estrutura das palavras
+  - Usa hífens para separação visual
+
+- **Destaque de Palavras**
+  - Realça palavras sequencialmente
+  - Auxilia no acompanhamento da leitura
+  - Velocidade ajustável
+
+#### Seção 2: Controles de Formatação Avançada
+- **Tamanho da Fonte**
+  - Range: 12px - 32px
+  - Incrementos de 2px
+  - Ícone visual indicativo
+
+- **Espaçamento entre Letras**
+  - Ajuste fino do kerning
+  - Melhora legibilidade
+  - Suporte para necessidades especiais
+
+- **Espaçamento entre Palavras**
+  - Controle da distância entre palavras
+  - Facilita a leitura
+  - Ajuda na compreensão do texto
+
+- **Altura da Linha**
+  - Ajuste do espaçamento vertical
+  - Melhora conforto visual
+  - Previne confusão entre linhas
+
+### 2. AdaptiveText
+Componente que implementa as transformações de texto.
+
+```typescript
+interface AdaptiveTextProps {
+  text: string;
+  isUpperCase: boolean;
+  preserveWhitespace?: boolean;
+  highlightSyllables?: boolean;
+}
+```
+
+## Funcionalidades Técnicas
+
+### 1. Gestão de Estado
+- Uso de hooks personalizados para gerenciar preferências
+- Persistência de configurações por usuário
+- Sincronização em tempo real
+
+### 2. Transformações de Texto
+- Conversão maiúsculo/minúsculo
+- Separação silábica
+- Destaque sequencial de palavras
+
+### 3. Acessibilidade
+- Suporte a ARIA labels
+- Alto contraste
+- Feedback visual claro
+- Suporte a leitores de tela
+
+## Integração com Modo Foco
+- Controles permanecem acessíveis
+- Transições suaves
+- Estado preservado entre modos
+
+## Exemplos de Uso
+
+### Implementação Básica
+```typescript
+<TextControls
+  fontSize={18}
+  onFontSizeChange={handleFontSizeChange}
+  letterSpacing={0.5}
+  onLetterSpacingChange={handleLetterSpacingChange}
+  wordSpacing={2}
+  onWordSpacingChange={handleWordSpacingChange}
+  lineHeight={1.5}
+  onLineHeightChange={handleLineHeightChange}
+/>
+```
+
+### Uso com AdaptiveText
+```typescript
+<AdaptiveText
+  text="Exemplo de texto adaptativo"
+  isUpperCase={isUpperCase}
+  highlightSyllables={isSyllablesEnabled}
+/>
+```
+
+## Considerações de Performance
+- Memoização de componentes
+- Otimização de re-renders
+- Lazy loading de recursos
+
+## Próximas Melhorias
+1. Adicionar mais opções de formatação
+2. Implementar temas personalizados
+3. Melhorar algoritmo de separação silábica
+4. Adicionar suporte a mais idiomas 

docs/geracao-historia.md

@@ -0,0 +1,166 @@
+# Geração de Histórias
+
+## Visão Geral
+O sistema de geração de histórias permite criar conteúdo personalizado baseado em parâmetros fornecidos pelo usuário, utilizando IA para gerar narrativas educativas e envolventes.
+
+## Parâmetros de Entrada
+
+### StoryChoices
+```typescript
+interface StoryChoices {
+  protagonist: string;         // Nome/tipo do protagonista
+  setting: string;            // Ambiente da história
+  theme: string;              // Tema principal
+  genre: string;              // Gênero da história
+  educationalGoal: string;    // Objetivo educacional
+  ageGroup: string;           // Faixa etária
+  length: 'short' | 'medium' | 'long'; // Extensão da história
+  complexity: 'easy' | 'medium' | 'hard'; // Nível de complexidade
+  language: 'pt-BR';          // Idioma (fixo em português)
+}
+```
+
+## Modos de Entrada
+
+### 1. Formulário
+- Interface gráfica com campos estruturados
+- Validação em tempo real
+- Sugestões pré-definidas
+- Preview instantâneo
+
+### 2. Comando de Voz
+- Reconhecimento de fala natural
+- Extração automática de parâmetros
+- Confirmação por voz
+- Correção por voz ou texto
+
+### 3. Texto Livre
+- Processamento de linguagem natural
+- Identificação de parâmetros-chave
+- Sugestão de complementos
+- Refinamento interativo
+
+## Fluxo de Geração
+
+### 1. Coleta de Parâmetros
+```typescript
+// Exemplo de validação de parâmetros
+const validateStoryParams = (choices: StoryChoices): boolean => {
+  return (
+    !!choices.protagonist &&
+    !!choices.setting &&
+    !!choices.theme &&
+    !!choices.genre &&
+    !!choices.educationalGoal &&
+    !!choices.ageGroup
+  );
+};
+```
+
+### 2. Processamento
+1. **Validação**
+   - Verificação de campos obrigatórios
+   - Validação de conteúdo apropriado
+   - Checagem de restrições de idade
+
+2. **Preparação**
+   - Formatação dos parâmetros
+   - Ajuste de complexidade
+   - Definição de estrutura
+
+3. **Geração**
+   - Criação do conteúdo via IA
+   - Revisão automática
+   - Formatação do texto
+
+### 3. Pós-processamento
+- Verificação de adequação
+- Ajustes de formatação
+- Adição de metadados
+- Geração de recursos visuais
+
+## Controles de Qualidade
+
+### 1. Adequação de Conteúdo
+- Filtro de conteúdo impróprio
+- Verificação de complexidade
+- Adequação à faixa etária
+- Alinhamento educacional
+
+### 2. Estrutura Narrativa
+- Coerência da história
+- Desenvolvimento de personagens
+- Arco narrativo apropriado
+- Conclusão educativa
+
+### 3. Linguagem
+- Vocabulário adequado
+- Estruturas gramaticais
+- Pontuação correta
+- Ritmo de leitura
+
+## Integração com Modo Foco
+
+### 1. Formatação Adaptativa
+- Ajuste automático de fonte
+- Espaçamento otimizado
+- Quebras de linha estratégicas
+- Destaque de palavras-chave
+
+### 2. Recursos de Acessibilidade
+- Suporte a leitura em voz alta
+- Marcadores visuais
+- Controles de navegação
+- Ajustes de contraste
+
+## Armazenamento
+
+### 1. Estrutura de Dados
+```typescript
+interface Story {
+  id: string;
+  title: string;
+  content: string;
+  parameters: StoryChoices;
+  metadata: {
+    wordCount: number;
+    readingTime: number;
+    complexity: number;
+    keywords: string[];
+  };
+  created_at: string;
+  updated_at: string;
+}
+```
+
+### 2. Indexação
+- Busca por parâmetros
+- Filtros de complexidade
+- Tags educacionais
+- Histórico de geração
+
+## Próximas Melhorias
+
+1. **Personalização Avançada**
+   - Perfis de aprendizado
+   - Adaptação dinâmica
+   - Temas customizados
+   - Integração curricular
+
+2. **Geração Multimodal**
+   - Ilustrações automáticas
+   - Efeitos sonoros
+   - Animações simples
+   - Recursos interativos
+
+3. **Análise de Impacto**
+   - Métricas de engajamento
+   - Progresso educacional
+   - Feedback do usuário
+   - Ajustes automáticos
+
+4. **Colaboração**
+   - Edição compartilhada
+   - Biblioteca de recursos
+   - Compartilhamento social
+   - Feedback comunitário 

docs/gravacao-audio.md

@@ -0,0 +1,151 @@
+# Sistema de Gravação de Áudio
+
+## Visão Geral
+O sistema de gravação de áudio permite aos alunos gravar suas leituras para análise posterior, com integração ao Modo Foco e recursos de acessibilidade.
+
+## Componentes
+
+### 1. AudioRecorder
+Componente principal responsável pela gravação de áudio.
+
+#### Props
+```typescript
+interface AudioRecorderProps {
+  storyId: string;
+  studentId: string;
+  onAudioUploaded: (audioUrl: string) => void;
+  onRecordingStart?: () => void;
+  onRecordingStop?: () => void;
+  focusModeActive?: boolean;
+  onFocusModeToggle?: () => void;
+}
+```
+
+### 2. Estados de Gravação
+- **Não Iniciado**: Exibe botão "Iniciar Gravação"
+- **Gravando**: Exibe botão "Parar Gravação"
+- **Gravado**: Exibe opções de ouvir e enviar
+- **Enviando**: Exibe indicador de progresso
+
+## Funcionalidades
+
+### 1. Controle de Gravação
+- Início/parada de gravação
+- Feedback visual do estado atual
+- Integração com Modo Foco
+- Controle de permissões do microfone
+
+### 2. Processamento de Áudio
+- Formato: WebM
+- Armazenamento temporário em Blob
+- Conversão e compressão antes do upload
+- Validação de qualidade
+
+### 3. Upload e Armazenamento
+- Upload para Supabase Storage
+- Geração de URLs públicas
+- Organização por aluno/história
+- Backup e cache
+
+### 4. Integração com Modo Foco
+- Ativação automática do Modo Foco
+- Desativação ao finalizar gravação
+- Sincronização de estados
+- Transições suaves
+
+## Fluxo de Gravação
+
+### 1. Início da Gravação
+```typescript
+const startRecording = async () => {
+  // 1. Ativar Modo Foco
+  if (!focusModeActive && onFocusModeToggle) {
+    onFocusModeToggle();
+  }
+
+  // 2. Solicitar permissões
+  const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+
+  // 3. Configurar gravador
+  mediaRecorderRef.current = new MediaRecorder(stream);
+
+  // 4. Iniciar gravação
+  mediaRecorderRef.current.start();
+};
+```
+
+### 2. Finalização da Gravação
+```typescript
+const stopRecording = () => {
+  // 1. Parar gravação
+  mediaRecorderRef.current?.stop();
+
+  // 2. Liberar recursos
+  mediaRecorderRef.current?.stream.getTracks().forEach(track => track.stop());
+
+  // 3. Desativar Modo Foco
+  if (focusModeActive && onFocusModeToggle) {
+    onFocusModeToggle();
+  }
+};
+```
+
+### 3. Upload do Áudio
+```typescript
+const uploadAudio = async () => {
+  // 1. Preparar arquivo
+  const filePath = `${studentId}/${storyId}/${fileId}.webm`;
+
+  // 2. Fazer upload
+  await supabase.storage
+    .from('recordings')
+    .upload(filePath, audioBlob);
+
+  // 3. Obter URL pública
+  const { publicUrl } = supabase.storage
+    .from('recordings')
+    .getPublicUrl(filePath);
+
+  // 4. Criar registro
+  await supabase
+    .from('story_recordings')
+    .insert({
+      id: fileId,
+      story_id: storyId,
+      student_id: studentId,
+      audio_url: publicUrl
+    });
+};
+```
+
+## Tratamento de Erros
+
+### 1. Permissões
+- Verificação de disponibilidade do microfone
+- Solicitação de permissões do usuário
+- Feedback claro em caso de negação
+
+### 2. Gravação
+- Monitoramento de qualidade
+- Detecção de silêncio
+- Limite de duração
+- Feedback de volume
+
+### 3. Upload
+- Retry em caso de falha
+- Limpeza de arquivos temporários
+- Validação de formato
+- Feedback de progresso
+
+## Considerações de Segurança
+- Validação de tipos de arquivo
+- Sanitização de nomes de arquivo
+- Controle de acesso por usuário
+- Expiração de URLs temporárias
+
+## Próximas Melhorias
+1. Adicionar visualização de forma de onda
+2. Implementar edição básica de áudio
+3. Melhorar feedback de qualidade
+4. Adicionar suporte a mais formatos
+5. Implementar detecção de ruído 

docs/modo-foco.md

@@ -0,0 +1,90 @@
+# Modo Foco
+
+## Visão Geral
+O Modo Foco é uma funcionalidade projetada para melhorar a experiência de leitura e gravação de histórias, focando na concentração e acessibilidade.
+
+## Funcionalidades
+
+### 1. Ativação Automática
+- Inicia automaticamente ao começar uma gravação
+- Desativa automaticamente ao parar a gravação
+- Pode ser ativado/desativado manualmente através do botão dedicado
+
+### 2. Interface Adaptativa
+- Remove distrações visuais durante a leitura
+- Aumenta o foco no texto atual
+- Transições suaves entre estados
+
+### 3. Controles de Acessibilidade
+- Ajuste de tamanho da fonte (12px - 32px)
+- Controle de espaçamento entre letras
+- Controle de espaçamento entre palavras
+- Ajuste de altura da linha
+- Velocidade de leitura personalizável
+
+### 4. Organização dos Controles
+#### Seção 1 (Controles Principais)
+- Maiúsculas/Minúsculas
+- Sílabas
+- Destacar palavras
+
+#### Seção 2 (Controles de Formatação)
+- Tamanho da fonte
+- Espaçamento entre letras
+- Espaçamento entre palavras
+- Altura da linha
+- Velocidade de leitura
+
+### 5. Indicadores Visuais
+- Ícones intuitivos para cada função
+- Feedback visual do estado atual
+- Timer de gravação
+- Destaque de palavras durante a leitura
+
+## Estilos e Temas
+- Modo claro com fundo suave
+- Contraste adequado para leitura
+- Sombras sutis para hierarquia visual
+- Design responsivo para diferentes tamanhos de tela
+
+## Integração
+- Componente `AudioRecorder` para gravações
+- Componente `TextControls` para formatação
+- Sistema de destaque de palavras
+- Gerenciamento de estado global
+
+## Uso Técnico
+
+### Ativação do Modo Foco
+```typescript
+// Em AudioRecorder
+const startRecording = async () => {
+  if (!focusModeActive && onFocusModeToggle) {
+    onFocusModeToggle();
+  }
+  // ... resto do código
+};
+```
+
+### Desativação do Modo Foco
+```typescript
+// Em AudioRecorder
+const stopRecording = () => {
+  // ... código de parada da gravação
+  if (focusModeActive && onFocusModeToggle) {
+    onFocusModeToggle();
+  }
+};
+```
+
+## Considerações de Acessibilidade
+- Alto contraste para melhor legibilidade
+- Suporte a diferentes tamanhos de fonte
+- Controles de espaçamento para dislexia
+- Feedback visual claro das ações
+
+## Próximos Passos
+1. Implementar persistência das preferências do usuário
+2. Adicionar mais opções de temas
+3. Expandir controles de acessibilidade
+4. Melhorar feedback de progresso da leitura 

docs/processamento-audio.md

@@ -0,0 +1,150 @@
+# Processamento de Áudio (Edge Function)
+
+## Visão Geral
+O sistema de processamento de áudio é uma Edge Function que analisa gravações de leitura, fornecendo métricas detalhadas sobre fluência, pronúncia e compreensão.
+
+## Estrutura de Dados
+
+### AudioRecord
+```typescript
+interface AudioRecord {
+  id: string
+  story_id: string
+  student_id: string
+  audio_url: string
+  status: 'pending_analysis' | 'processing' | 'completed' | 'error'
+  analysis: any
+  created_at: string
+  transcription: string | null
+  processed_at: string | null
+  error_message: string | null
+  fluency_score: number | null
+  pronunciation_score: number | null
+  accuracy_score: number | null
+  comprehension_score: number | null
+  words_per_minute: number | null
+  pause_count: number | null
+  error_count: number | null
+  self_corrections: number | null
+  strengths: string[]
+  improvements: string[]
+  suggestions: string | null
+}
+```
+
+## Fluxo de Processamento
+
+### 1. Recebimento da Requisição
+- Validação inicial dos dados recebidos
+- Configuração de CORS e headers
+- Inicialização do logger
+
+### 2. Processamento Principal
+O processamento ocorre em etapas sequenciais:
+
+1. **Verificação e Atualização de Status**
+   - Verifica existência do registro
+   - Cria registro se necessário
+   - Atualiza status para 'processing'
+
+2. **Processamento do Áudio**
+   - Transcrição via Whisper API
+   - Análise do texto transcrito
+
+3. **Análise da Leitura**
+   - Cálculo de métricas de fluência
+   - Avaliação de pronúncia
+   - Identificação de pontos fortes e melhorias
+
+4. **Atualização do Banco**
+   - Preparação dos dados de análise
+   - Verificação pré-update
+   - Atualização do registro
+   - Verificação pós-update
+
+## Tratamento de Erros
+
+### 1. Validação de Dados
+```typescript
+if (!data?.record?.id || !data?.record?.audio_url) {
+  throw new Error('Dados inválidos: ID ou URL do áudio ausentes')
+}
+```
+
+### 2. Atualização de Status de Erro
+- Em caso de falha, atualiza o registro com status 'error'
+- Armazena mensagem de erro para diagnóstico
+- Retorna resposta com detalhes do erro
+
+## Métricas Analisadas
+
+### Pontuações
+- Fluência (0-100)
+- Pronúncia (0-100)
+- Precisão (0-100)
+- Compreensão (0-100)
+
+### Métricas Quantitativas
+- Palavras por minuto
+- Contagem de pausas
+- Contagem de erros
+- Autocorreções
+
+### Feedback Qualitativo
+- Pontos fortes identificados
+- Áreas para melhoria
+- Sugestões personalizadas
+
+## Logs e Monitoramento
+
+### Eventos Registrados
+- Recebimento de requisição
+- Atualizações de status
+- Resultados de processamento
+- Erros e exceções
+
+### Formato dos Logs
+```typescript
+logger.info('event_name', 'Descrição do evento', {
+  contextData: 'dados adicionais'
+})
+```
+
+## Considerações de Segurança
+
+### 1. Autenticação
+- Validação de tokens
+- Verificação de permissões
+- Controle de acesso por usuário
+
+### 2. Dados Sensíveis
+- Sanitização de inputs
+- Validação de URLs
+- Proteção contra injeção
+
+### 3. Rate Limiting
+- Controle de requisições
+- Proteção contra sobrecarga
+- Cache de resultados
+
+## Próximas Melhorias
+
+1. **Análise Avançada**
+   - Detecção de padrões de erro
+   - Análise de entonação
+   - Reconhecimento de emoção
+
+2. **Performance**
+   - Otimização de processamento
+   - Cache distribuído
+   - Processamento em lote
+
+3. **Feedback**
+   - Relatórios detalhados
+   - Visualizações gráficas
+   - Recomendações personalizadas
+
+4. **Integração**
+   - Webhooks para notificações
+   - API para consultas em tempo real
+   - Exportação de dados