Documentação Abrangente pwE

Princípios e Pilares do Projeto

Desenvolvido sob rígidas normas de arquitetura e design (conforme o tema oficial definido em app_theme.dart), o pwE é sustentado por três pilares fundamentais:

Camadas Arquiteturais

A separação de responsabilidades assegura a facilidade de manutenção e alta cobertura de testes unitários:

• Camada de Domínio (Domain): Contém as regras de negócio puras (Entities, UseCases e contratos definidos). Veja a entidade da Lectio Divina no arquivo lectio_session.dart:
  Copiar

  // lib/features/lectio_divina/domain/entities/lectio_session.dart
  class LectioSession {
    final String id;
    final DateTime date;
    final String passage;
    final String emotion;
    final String meditation;
    final String prayer;
    final String contemplationResolution;
    final int streakDays;
  
    const LectioSession({
      required this.id,
      required this.date,
      required this.passage,
      required this.emotion,
      required this.meditation,
      required this.prayer,
      required this.contemplationResolution,
      required this.streakDays,
    });
  }

• Camada de Dados (Data): Contém a infraestrutura (Models, DataSources e as implementações concretas dos repositórios como em llm_remote_datasource.dart):
  Copiar

  // lib/features/lectio_divina/data/datasources/llm_remote_datasource.dart
  abstract class LlmRemoteDataSource {
    Future<MeditationModel> generateMeditation(MeditationRequestModel request);
  }
  
  class LlmRemoteDataSourceImpl implements LlmRemoteDataSource {
    final ApiClient apiClient;
  
    LlmRemoteDataSourceImpl({required this.apiClient});
  
    @override
    Future<MeditationModel> generateMeditation(MeditationRequestModel request) async {
      final response = await apiClient.post(
        '/v1/spiritual-advisor/meditate',
        data: request.toJson(),
      );
      return MeditationModel.fromJson(response.data);
    }
  }

• Camada de Apresentação (Presentation): Contém a interface do usuário (Widgets e Pages) e a gestão de estado complexa baseada em **Bloc** (veja em lectio_bloc.dart):
  Copiar

  // lib/features/lectio_divina/presentation/bloc/lectio_bloc.dart
  class LectioBloc extends Bloc<LectioEvent, LectioState> {
    final GetGuidedMeditation getGuidedMeditation;
    final SaveSession saveSession;
  
    LectioBloc({
      required this.getGuidedMeditation,
      required this.saveSession,
    }) : super(LectioInitial()) {
      on<StartSessionEvent>(_onStartSession);
      on<AdvanceToStepEvent>(_onAdvanceToStep);
      on<CompleteSessionEvent>(_onCompleteSession);
    }
  
    void _onStartSession(StartSessionEvent event, Emitter<LectioState> emit) {
      emit(LectioInProgress(step: LectioStep.reading, passage: event.passage));
    }
  }

Componentes da UI Focada

Estes elementos de interface criam uma atmosfera de introspecção na página immersive_reading_page.dart:

• ProgressiveTextReveal: Esconde trechos futuros por meio de desfoque (blur) até que o usuário faça scroll ou interaja com o texto, auxiliando a focar na leitura atual.
• HoldToSaveButton: Exige pressionar o botão por 2 segundos contínuos com resposta tátil para assegurar a intencionalidade de avanço de etapa, bloqueando cliques indesejados no silêncio da oração.
• ThinkingFeedback: Exibe mensagens motivacionais rotativas e espirituais enquanto a IA processa o prompt (Ex: "Unindo a sua oração aos coros celestes...").

Veja um exemplo prático de implementação do HoldToSaveButton, com lógica tátil e preenchimento gradual por tempo em Flutter:

// lib/features/lectio_divina/presentation/widgets/hold_to_save_button.dart
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

class HoldToSaveButton extends StatefulWidget {
  final VoidCallback onTrigger;
  final String label;

  const HoldToSaveButton({Key? key, required this.onTrigger, required this.label}) : super(key: key);

  @override
  _HoldToSaveButtonState createState() => _HoldToSaveButtonState();
}

class _HoldToSaveButtonState extends State<HoldToSaveButton> with SingleTickerProviderStateMixin {
  late AnimationController _controller;

  @override
  void initState() {
    super.initState();
    _controller = AnimationController(
      vsync: this,
      duration: const Duration(seconds: 2),
    );
    _controller.addStatusListener((status) {
      if (status == AnimationStatus.completed) {
        HapticFeedback.heavyImpact();
        widget.onTrigger();
        _controller.reset();
      }
    });
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onLongPressStart: (_) {
        HapticFeedback.mediumImpact();
        _controller.forward();
      },
      onLongPressEnd: (_) {
        if (_controller.status != AnimationStatus.completed) {
          _controller.reverse();
        }
      },
      child: AnimatedBuilder(
        animation: _controller,
        builder: (context, child) {
          return Container(
            height: 56,
            width: double.infinity,
            decoration: BoxDecoration(
              borderRadius: BorderRadius.circular(12),
              border: Border.all(color: Colors.amber.shade700, width: 1.5),
              gradient: LinearGradient(
                colors: [Colors.amber.shade800, Colors.amber.shade900],
                stops: [0.0, _controller.value],
              ),
            ),
            child: Center(
              child: Text(
                _controller.value > 0 ? 'Mantenha pressionado... ${(_controller.value * 100).toInt()}%' : widget.label,
                style: const TextStyle(fontWeight: FontWeight.bold, color: Colors.white),
              ),
            ),
          );
        },
      ),
    );
  }
}

Os Três Estágios da Maturidade

Especificações Técnicas de Inferência Local

• Modelo Utilizado: Gemma 4 (classe 2B) otimizado e quantizado para dispositivos móveis.
• Engine: Baseado na biblioteca **LiteRT-LM** rodando em canais de métodos nativos (`MethodChannel`) rápidos e eficientes. Gerenciado por llm_local_datasource.dart.
• Hardware Mínimo: Smartphones com 4GB de RAM livre, suporte a aceleração gráfica por GPU/NPU e ~1.3GB de espaço livre para o modelo quantizado.
• Indicador Visual de Privacidade: Sempre que a IA é processada localmente, o app apresenta um Escudo Dourado, atestando o isolamento do processamento.

Abaixo está a implementação prática de LlmLocalDataSourceImpl, demonstrando a invocação nativa e o fallback automático para a nuvem em caso de erro:

// lib/features/lectio_divina/data/datasources/llm_local_datasource.dart
import 'package:flutter/services.dart';
import 'package:pwe/features/lectio_divina/data/models/meditation_model.dart';
import 'package:pwe/features/lectio_divina/data/models/meditation_request_model.dart';
import 'package:pwe/features/lectio_divina/data/datasources/llm_remote_datasource.dart';

abstract class LlmLocalDataSource {
  Future<MeditationModel> generateMeditation(MeditationRequestModel request);
}

class LlmLocalDataSourceImpl implements LlmLocalDataSource {
  static const MethodChannel _channel = MethodChannel('pwe.app/gemma-inference');
  final LlmRemoteDataSource remoteFallback;
  final bool isGemmaEnabled;

  LlmLocalDataSourceImpl({
    required this.remoteFallback,
    required this.isGemmaEnabled,
  });

  @override
  Future<MeditationModel> generateMeditation(MeditationRequestModel request) async {
    if (!isGemmaEnabled) {
      return remoteFallback.generateMeditation(request);
    }

    try {
      final String? response = await _channel.invokeMethod<String>(
        'executeGemmaInference',
        {
          'prompt': request.toPrompt(),
          'max_tokens': 200,
          'temperature': 0.3,
        },
      );

      if (response == null || response.isEmpty) {
        throw PlatformException(code: 'EMPTY_RESPONSE', message: 'Gemma local retornou vazio.');
      }

      return MeditationModel.fromLocalText(response, request.passage);
    } catch (e) {
      // Fallback transparente em caso de indisponibilidade ou falha de inferência local
      return remoteFallback.generateMeditation(request);
    }
  }
}

Funcionamento e Arquitetura do OCR

Integrando o Google ML Kit Vision, o processo é inteiramente offline e ágil:

Abaixo está o exemplo prático de integração com o ML Kit OCR para extração offline de texto bíblico nas páginas físicas da Bíblia:

// lib/features/lectio_divina/data/datasources/ocr_local_datasource.dart
import 'dart:io';
import 'package:google_ml_kit/google_ml_kit.dart';

abstract class OcrLocalDataSource {
  Future<String> extractTextFromImage(File imageFile);
}

class OcrLocalDataSourceImpl implements OcrLocalDataSource {
  final TextRecognizer _textRecognizer = GoogleMlKit.vision.textRecognizer();

  @override
  Future<String> extractTextFromImage(File imageFile) async {
    final inputImage = InputImage.fromFile(imageFile);
    try {
      final RecognizedText recognizedText = await _textRecognizer.processImage(inputImage);
      
      // Filtra e limpa o texto para remover ruídos e marcas indesejadas do reconhecimento
      String rawText = recognizedText.text;
      return _refineBiblicalText(rawText);
    } catch (e) {
      throw Exception('Erro ao processar imagem via ML Kit OCR: ${e.toString()}');
    }
  }

  String _refineBiblicalText(String input) {
    return input
        .replaceAll('\n', ' ')
        .replaceAll(RegExp(r'\s+'), ' ')
        .trim();
  }

  void dispose() {
    _textRecognizer.close();
  }
}

Árvore de Pastas

lib/
├── core/                        # Núcleo compartilhado
│   ├── di/                      # Container GetIt (injection_container.dart)
│   ├── error/                   # Failures e Exceptions (Either)
│   ├── network/                 # REST Clients e configurações de rede
│   ├── routes/                  # Configurações de rotas com GoRouter
│   └── theme/                   # Estilos visuais e paletas do aplicativo
├── features/                    # Módulos de domínio isolados
│   ├── lectio_divina/           # Domínio principal de Leitura Orante
│   │   ├── data/                # DTOs, Repositórios e fontes de dados
│   │   ├── domain/              # Entidades, regras de negócios e UseCases
│   │   └── presentation/        # Controladores BLoC, widgets e páginas
│   ├── auth/                    # Gerenciamento de login e segurança
│   └── profile/                 # Controle de maturidade e preferências
└── main.dart                    # Configurações e bootstrap do app