feat: Documentação do Analytics

src/components/analytics/README.md

@@ -0,0 +1,265 @@
+# 📊 Sistema de Analytics
+
+Este diretório contém a implementação do sistema de analytics do Leiturama, utilizando Rudderstack como principal ferramenta de tracking.
+
+## 📦 Componentes
+
+### PageTracker
+Componente responsável pelo tracking automático de visualizações de página.
+
+```tsx
+// App.tsx
+<PageTracker />
+```
+
+### GoogleTagManager
+Componente para integração com Google Tag Manager.
+
+```tsx
+// App.tsx
+<GoogleTagManager gtmId="GTM-XXXXXX" />
+```
+
+## 🎯 Hooks Disponíveis
+
+### useButtonTracking
+
+Hook para rastreamento de interações com botões e elementos clicáveis.
+
+```typescript
+const { trackButtonClick } = useButtonTracking({
+  category?: string;    // Categoria do evento (default: 'interaction')
+  location?: string;    // Localização do botão (default: pathname atual)
+});
+
+// Uso:
+trackButtonClick('button-id', {
+  label: 'Botão de Login',
+  variant: 'primary',
+  position: 'header',
+  section: 'auth'
+});
+```
+
+### useFormTracking
+
+Hook para rastreamento de interações com formulários.
+
+```typescript
+const { 
+  trackFormStarted,
+  trackFormStepCompleted,
+  trackFormSubmitted,
+  trackFormError,
+  trackFormAbandoned,
+  trackFieldInteraction
+} = useFormTracking({
+  formId: string;       // ID único do formulário
+  formName: string;     // Nome descritivo do formulário
+  category?: string;    // Categoria (default: 'form')
+});
+
+// Exemplos de Uso:
+// Início do formulário
+trackFormStarted();
+
+// Completou um passo
+trackFormStepCompleted('dados-pessoais', true);
+
+// Submeteu o formulário
+trackFormSubmitted(true, { 
+  user_type: 'student' 
+});
+
+// Erro no formulário
+trackFormError('validation', 'Email inválido', 'email');
+
+// Abandonou o formulário
+trackFormAbandoned('payment');
+
+// Interação com campo
+trackFieldInteraction('email', 'focus');
+```
+
+### useStudentTracking
+
+Hook especializado para rastreamento de atividades do estudante.
+
+```typescript
+const {
+  trackStoryGenerated,
+  trackAudioRecorded,
+  trackExerciseCompleted,
+  trackInterestAdded,
+  trackInterestRemoved
+} = useStudentTracking();
+
+// Exemplo: Rastrear geração de história
+trackStoryGenerated({
+  story_id: 'story-123',
+  theme: 'aventura',
+  prompt: 'Uma história sobre...',
+  generation_time: 2.5,
+  word_count: 300,
+  student_id: 'student-123'
+});
+
+// Exemplo: Rastrear exercício completado
+trackExerciseCompleted({
+  exercise_id: 'ex-123',
+  story_id: 'story-123',
+  student_id: 'student-123',
+  exercise_type: 'pronunciation',
+  score: 85,
+  time_spent: 120
+});
+```
+
+### useErrorTracking
+
+Hook para rastreamento de erros e exceções.
+
+```typescript
+const { 
+  trackError,
+  trackErrorBoundary,
+  trackApiError
+} = useErrorTracking({
+  category?: string;    // Categoria (default: 'error')
+  userId?: string;      // ID do usuário
+  userEmail?: string;   // Email do usuário
+});
+
+// Exemplo: Rastrear erro genérico
+trackError(error, {
+  componentName: 'LoginForm',
+  action: 'submit',
+  metadata: { attempt: 2 }
+});
+
+// Exemplo: Rastrear erro de API
+trackApiError(error, '/api/login', 'POST', {
+  email: 'user@example.com'
+});
+```
+
+## 📝 Padrões de Nomenclatura
+
+### Eventos
+
+- Use snake_case para nomes de eventos
+- Formato: `{objeto}_{ação}`
+- Exemplos:
+  - `button_clicked`
+  - `form_submitted`
+  - `story_generated`
+  - `exercise_completed`
+
+### Propriedades
+
+- Use snake_case para nomes de propriedades
+- Categorize propriedades por namespace:
+  ```typescript
+  {
+    // Propriedades de página
+    page_url: string;
+    page_title: string;
+    
+    // Propriedades de usuário
+    user_id: string;
+    user_type: string;
+    
+    // Propriedades de elemento
+    element_type: string;
+    element_id: string;
+    
+    // Propriedades de formulário
+    form_id: string;
+    form_name: string;
+  }
+  ```
+
+### Categorias
+
+Categorias predefinidas disponíveis em `EVENT_CATEGORIES`:
+- `page`: Eventos de visualização de página
+- `user`: Eventos relacionados ao usuário
+- `story`: Eventos de histórias
+- `exercise`: Eventos de exercícios
+- `interaction`: Eventos de interação do usuário
+- `error`: Eventos de erro
+- `subscription`: Eventos de assinatura
+- `auth`: Eventos de autenticação
+- `navigation`: Eventos de navegação
+- `form`: Eventos de formulário
+
+## 🔨 Exemplos de Implementação
+
+### Botão com Tracking
+
+```typescript
+<Button
+  trackingId="signup-button"
+  variant="primary"
+  size="lg"
+  trackingProperties={{
+    category: EVENT_CATEGORIES.AUTH,
+    action: 'signup_click',
+    label: 'homepage_hero',
+    position: 'hero_section'
+  }}
+  onClick={handleSignup}
+>
+  Cadastre-se Agora
+</Button>
+```
+
+### Formulário com Tracking
+
+```typescript
+<Form
+  formId="signup-form"
+  formName="student-signup"
+  trackingProperties={{
+    category: EVENT_CATEGORIES.AUTH,
+    user_type: 'student',
+    source: 'homepage'
+  }}
+  onSubmit={handleSubmit}
+>
+  {/* campos do formulário */}
+</Form>
+```
+
+### Link com Tracking
+
+```typescript
+<Link
+  to="/dashboard"
+  trackingId="dashboard-link"
+  trackingProperties={{
+    category: EVENT_CATEGORIES.NAVIGATION,
+    section: 'sidebar',
+    position: 'top'
+  }}
+>
+  Dashboard
+</Link>
+```
+
+### Tracking de Erro em Try/Catch
+
+```typescript
+try {
+  await submitForm(data);
+} catch (error) {
+  errorTracking.trackError(error, {
+    componentName: 'SignupForm',
+    action: 'submit',
+    metadata: {
+      formData: data,
+      attempt: retryCount
+    }
+  });
+}
+```