Documentação

2026-05-03 23:31:31 +01:00
commit d24cb3242a
167 changed files with 14263 additions and 0 deletions
--- a/documentação/06-guia-desenvolvimento-manutencao.md
+++ b/documentação/06-guia-desenvolvimento-manutencao.md
@@ -0,0 +1,356 @@
+# Guia de Desenvolvimento e Manutenção
+
+## Setup do Ambiente
+
+### 1. Pré-requisitos
+```bash
+# Instalar Flutter
+flutter doctor
+
+# Verificar ambiente
+flutter devices
+```
+
+### 2. Clonar e Configurar
+```bash
+git clone <repository-url>
+cd check_theeth_kids
+flutter pub get
+```
+
+### 3. Configurar Firebase
+- Baixar arquivos de configuração do console Firebase
+- Adicionar `google-services.json` (Android) e `GoogleService-Info.plist` (iOS)
+
+## Fluxo de Desenvolvimento
+
+### Branches
+- `main`: Produção
+- `develop`: Desenvolvimento
+- `feature/*`: Novas funcionalidades
+- `bugfix/*`: Correções de bugs
+
+### Comandos Diários
+```bash
+# Limpar e atualizar
+flutter clean && flutter pub get
+
+# Verificar código
+flutter analyze
+dart format .
+
+# Rodar testes
+flutter test
+
+# Build para teste
+flutter build apk --debug
+```
+
+## Padrões de Código
+
+### 1. BuildContext Seguro
+```dart
+// ✅ Correto
+if (!mounted) return;
+final result = await someAsyncOperation();
+if (!mounted) return;
+ScaffoldMessenger.of(context).showSnackBar(...);
+
+// ❌ Incorreto
+final result = await someAsyncOperation();
+ScaffoldMessenger.of(context).showSnackBar(...); // Pode causar erro
+```
+
+### 2. Nomenclatura
+```dart
+// ✅ Descritivo
+errorBuilder: (context, error, stackTrace) => ...
+
+// ❌ Underscores desnecessários
+errorBuilder: (context, _, __) => ...
+```
+
+### 3. Estruturas de Controle
+```dart
+// ✅ Com chaves
+if (condition) {
+  return value;
+}
+
+// ❌ Sem chaves
+if (condition)
+  return value;
+```
+
+## Manutenção do Quiz
+
+### Adicionar Nova Pergunta
+```dart
+// Em lib/quiz/quiz1.dart
+class Quiz21Screen extends StatelessWidget {
+  const Quiz21Screen({super.key, required this.currentScore, this.scopeId});
+  
+  // ... implementação
+  
+  @override
+  Widget build(BuildContext context) {
+    return QuizQuestionScreen(
+      title: 'Quiz 21/21',
+      question: 'Nova pergunta aqui...',
+      answers: const [
+        QuizAnswer(title: 'Opção 1', description: '...', weight: 2),
+        QuizAnswer(title: 'Opção 2', description: '...', weight: 5),
+        QuizAnswer(title: 'Opção 3', description: '...', weight: 3),
+      ],
+      currentScore: currentScore,
+      nextRoute: (context, nextScore) => MaterialPageRoute<void>(
+        builder: (_) => QuizResultScreen(finalScore: nextScore, maxScore: 105, scopeId: scopeId),
+      ),
+      isFinal: true,
+      showBackButton: true,
+    );
+  }
+}
+```
+
+### Atualizar Quiz Anterior
+```dart
+// No Quiz20Screen, atualizar nextRoute
+nextRoute: (context, nextScore) => MaterialPageRoute<void>(
+  builder: (_) => Quiz21Screen(currentScore: nextScore, scopeId: scopeId),
+),
+```
+
+## Manutenção do logged_home.dart
+
+### Adicionar Nova Funcionalidade
+1. Criar widget específico
+2. Adicionar ao `_HomeTabState` ou aba correspondente
+3. Testar com diferentes estados
+4. Verificar lint
+
+### Corrigir Erros Comuns
+```bash
+# Verificar problemas
+flutter analyze
+
+# Corrigir automaticamente
+dart fix --apply
+```
+
+## Deploy
+
+### Android
+```bash
+# Build release
+flutter build apk --release
+
+# Upload para Play Store
+# Usar Android Studio ou Google Play Console
+```
+
+### iOS
+```bash
+# Build release
+flutter build ios --release
+
+# Upload para App Store
+# Usar Xcode → Product → Archive
+```
+
+### Web
+```bash
+# Build web
+flutter build web
+
+# Deploy para Firebase Hosting ou similar
+firebase deploy --only hosting
+```
+
+## Troubleshooting Comum
+
+### Firebase Issues
+```bash
+# Limpar cache do Firebase
+flutter clean
+cd android && ./gradlew clean && cd ..
+cd ios && rm -rf Pods Podfile.lock && pod install && cd ..
+```
+
+### Build Issues
+```bash
+# Limpar completamente
+flutter clean
+flutter pub cache repair
+flutter pub get
+```
+
+### Emulator Issues
+```bash
+# Limpar dados do emulador
+flutter emulators --clean
+flutter emulators --launch <emulator_id>
+```
+
+## Performance
+
+### Monitoramento
+```dart
+// Usar Flutter DevTools
+flutter run --profile
+# Abrir: http://localhost:port/devtools/
+```
+
+### Otimizações
+- Usar `const` widgets onde possível
+- Evitar rebuilds desnecessários
+- Usar `ListView.builder` para listas longas
+- Implementar lazy loading para imagens
+
+## Segurança
+
+### Firebase Rules
+```javascript
+// Exemplo: firestore.rules
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+    match /users/{userId} {
+      allow read, write: if request.auth != null && request.auth.uid == userId;
+    }
+  }
+}
+```
+
+### Best Practices
+- Nunca expor API keys no código
+- Validar dados no cliente e servidor
+- Usar HTTPS para todas as comunicações
+- Implementar rate limiting
+
+## Backup e Recuperação
+
+### Backup Automático
+```bash
+# Script de backup
+#!/bin/bash
+DATE=$(date +%Y%m%d)
+tar -czf "backup_$DATE.tar.gz" --exclude='.git' --exclude='build' .
+```
+
+### Recuperação de Desastres
+1. Restaurar do backup mais recente
+2. Rodar `flutter pub get`
+3. Testar funcionalidades críticas
+4. Deploy para produção
+
+## Monitoramento
+
+### Logs e Erros
+```dart
+// Implementar logging
+import 'dart:developer' as developer;
+
+developer.log('Erro ao carregar dados', error: error);
+```
+
+### Analytics
+- Configurar Firebase Analytics
+- Monitorar eventos importantes
+- Acompanhar performance do app
+
+## Atualizações de Dependências
+
+### Processo Seguro
+```bash
+# Verificar atualizações
+flutter pub outdated
+
+# Atualizar uma por vez
+flutter pub upgrade package_name
+
+# Testar após cada atualização
+flutter test
+flutter analyze
+```
+
+### Versões Críticas
+- Firebase: Verificar breaking changes
+- Flutter: Aguardar estabilidade antes de atualizar
+- Packages: Verificar compatibilidade
+
+## Documentação
+
+### Manter Documentação Atualizada
+- Atualizar README.md após mudanças significativas
+- Documentar novas funcionalidades
+- Manter changelog
+
+### Code Comments
+```dart
+/// Widget principal do quiz com 20 perguntas
+/// 
+/// Responsável por gerenciar o fluxo completo do quiz,
+/// desde a primeira pergunta até o resultado final.
+class Quiz1Screen extends StatelessWidget {
+  // ...
+}
+```
+
+## Testes
+
+### Unit Tests
+```dart
+// test/quiz_test.dart
+void main() {
+  test('Quiz calculation should work correctly', () {
+    // Implementar testes
+  });
+}
+```
+
+### Integration Tests
+```dart
+// integration_test/app_test.dart
+void main() {
+  testWidgets('Quiz flow smoke test', (WidgetTester tester) async {
+    // Testar fluxo completo
+  });
+}
+```
+
+## Contato e Suporte
+
+### Equipe de Desenvolvimento
+- Desenvolvedor Principal: [Nome]
+- Firebase Admin: [Nome]
+- UI/UX Designer: [Nome]
+
+### Recursos Externos
+- [Flutter Documentation](https://docs.flutter.dev/)
+- [Firebase Documentation](https://firebase.google.com/docs)
+- [Dart Style Guide](https://dart.dev/guides/language/effective-dart/style)
+
+## Checklist de Release
+
+### Antes do Deploy
+- [ ] `flutter analyze` sem erros
+- [ ] Todos os testes passando
+- [ ] Versão atualizada no pubspec.yaml
+- [ ] Changelog atualizado
+- [ ] Backup criado
+- [ ] Testado em múltiplos dispositivos
+- [ ] Performance verificada
+- [ ] Segurança revisada
+
+### Pós-Deploy
+- [ ] Monitorar logs de erro
+- [ ] Verificar analytics
+- [ ] Coletar feedback dos usuários
+- [ ] Preparar hotfix se necessário
+
+## Conclusão
+
+Este guia serve como referência para desenvolvimento e manutenção contínua do projeto. Siga os padrões estabelecidos para garantir qualidade e consistência no código.
+
+Para dúvidas ou sugestões de melhoria deste guia, consulte a equipe de desenvolvimento.