1. Território é a unidade central: Representa um lugar físico real, geográfico e neutro
2. Presença física é critério de vínculo: Geolocalização obrigatória para residentes (não é possível associar território remotamente no MVP)
3. Consulta exige cadastro: Feed, mapa e operações sociais exigem usuário autenticado
4. Visibilidade diferenciada: Conteúdo pode ser Público (todos) ou Apenas Moradores (RESIDENTS_ONLY)
5. Governança por Capabilities: Curator, Moderator, EventOrganizer (não são roles fixos, são capabilities empilháveis)
6. Feature Flags Territoriais: Funcionalidades podem ser ativadas/desativadas por território
7. Tudo é georreferenciado: Posts, eventos, assets têm GeoAnchors quando possível

• Território como referência: Território físico como unidade central
• Baixa excitação e foco: Design calmo, não manipulativo, focado em relevância territorial
• Silêncio funcional com hierarquia clara: Interface limpa, funcional, sem ruído visual
• Ação consciente e explícita: Interações claras, sem dark patterns
• Baixa fricção, alta fluidez: Experiência fluida sem atritos desnecessários

---

• Riverpod: ^2.5.0 (hooks_riverpod ^2.5.0)
  • Providers para dados de API (auto-refresh, cache)
  • Providers para estado local de UI (notifiers)
  • Providers para autenticação (global, persistido)
  • Providers para sessão territorial (contexto ativo)
  • Providers para preferências do usuário

• Dio: ^5.4.0
  • Cliente HTTP com interceptors customizados
  • Interceptor de autenticação (JWT Bearer token)
  • Interceptor de headers (X-Session-Id para território, X-Latitude/X-Longitude para geo)
  • Interceptor de retry com backoff exponencial
  • Interceptor de logging em desenvolvimento
  • Tratamento de rate limiting (429 Too Many Requests com Retry-After)

• intl: Internacionalização (pt-BR, en-US)
• package_info_plus: Informações da versão do app
• url_launcher: Abertura de links externos
• share_plus: Compartilhamento nativo
• image_picker: Seleção de imagens
• cached_network_image: Cache de imagens
• connectivity_plus: Verificação de conectividade
• permission_handler: Gerenciamento de permissões

Primary (Verde Floresta):

• forest50: #F0FDF4
• forest100: #DCFCE7
• forest200: #BBF7D0
• forest300: #86EFAC
• forest400: #4ADE80
• forest500: #22C55E (primary)
• forest600: #16A34A
• forest700: #15803D
• forest800: #166534
• forest900: #14532D

Secondary (Azul Céu):

• sky50 até sky900 (similar estrutura)

Tertiary (Tons Terrosos):

• earth50 até earth900 (similar estrutura)

Semânticos:

• success, warning, error, info (variantes 50-900)

Neutros (Light/Dark Mode):

• neutral50 até neutral900

Fonte Primária: Inter (com fallback system sans-serif)

Escala Tipográfica:

• Display: 64px/72px line height (bold)
• Heading1: 48px/56px (bold)
• Heading2: 36px/44px (semi-bold)
• Heading3: 24px/32px (semi-bold)
• Heading4: 20px/28px (semi-bold)
• BodyLarge: 18px/28px (regular)
• BodyMedium: 16px/24px (regular)
• BodySmall: 14px/20px (regular)
• Label: 14px/20px (medium)
• Caption: 12px/16px (regular)

Botões:

• Primary: Verde floresta, elevation 2, padding 16px vertical
• Secondary: Outline, border verde floresta, transparente
• Text: Sem background, apenas texto

Cards:

• Padrão: Elevation 1, border radius 12px, padding 16px
• Glass: Glassmorphism (background blur, transparência)

Inputs:

• TextField com label flutuante, helper text, error states
• Border radius 8px, padding 12px vertical

Métodos:

1. Google Sign-In (OAuth2)
2. Apple Sign-In (iOS)
3. Email/Telefone (futuro)

Fluxo:

1. Usuário seleciona método de login
2. OAuth/autenticação social
3. Backend valida e retorna JWT
4. Token armazenado em flutter_secure_storage
5. Token incluído em todas as requisições (interceptor Dio)

2FA (se habilitado):

1. Após login, verifica se 2FA habilitado
2. Mostra tela de código 2FA
3. Input de 6 dígitos
4. Verificação no backend

SSL/TLS Pinning (Produção):

• Validar certificados SSL em todas as requisições HTTPS
• Prevenir man-in-the-middle attacks
• Configurar SHA256 hashes dos certificados

Proteção de Dados Sensíveis:

• Criptografar cache local (Hive encryption)
• Proteger screenshots em telas sensíveis (Android)
• Limpar dados sensíveis de memória após uso
• Nunca armazenar dados sensíveis em logs

Jailbreak/Root Detection:

• Detectar dispositivos comprometidos
• Mostrar alerta ao usuário (modo aviso para MVP)
• Considerar bloqueio parcial de funcionalidades (pós-MVP)

Sanitização de Inputs:

• Validar e sanitizar todos os inputs client-side
• Remover tags HTML perigosas
• Validar formatos (email, URL, etc.)
• Limitar tamanhos de strings

Rate Limiting Local:

• Prevenir spam antes de atingir rate limit da API
• Limites: Posts (10/min), Eventos (5/min), Comentários (20/min)

1. authProvider (StateNotifier): Estado de autenticação
2. sessionProvider (StateNotifier): Território ativo (X-Session-Id)
3. userProvider (FutureProvider): Dados do usuário logado (GET /auth/me)
4. territoryProvider (FutureProvider): Dados do território ativo
5. preferencesProvider (StateNotifier): Preferências do usuário (tema, idioma)

Feed:

• feedProvider(territoryId): Lista de posts do território
• postProvider(postId): Detalhes de um post
• createPostProvider: Criar novo post

Territórios:

• territoriesNearbyProvider(lat, lng): Territórios próximos
• territoryProvider(territoryId): Detalhes de um território

Eventos:

• eventsProvider(territoryId): Lista de eventos
• eventProvider(eventId): Detalhes de um evento

Membresia:

• membershipProvider(territoryId): Vínculo do usuário no território
• joinRequestProvider(territoryId): Solicitação de residência

// Exemplo: Feed Provider
final feedProvider = FutureProvider.family<List<Post>, String>((ref, territoryId) async {
  final apiService = ref.watch(apiServiceProvider);
  final sessionId = ref.watch(sessionProvider).sessionId;
  
  return apiService.getFeed(territoryId: territoryId, sessionId: sessionId);
});

// Exemplo: Criar Post (StateNotifier)
final createPostProvider = StateNotifierProvider<CreatePostNotifier, CreatePostState>((ref) {
  return CreatePostNotifier(ref.watch(apiServiceProvider));
});

---

final appRouter = GoRouter(
  initialLocation: '/splash',
  routes: [
    // Splash e Onboarding
    GoRoute(path: '/splash', builder: (context, state) => SplashScreen()),
    GoRoute(path: '/onboarding', builder: (context, state) => OnboardingScreen()),
    
    // Autenticação
    GoRoute(path: '/login', builder: (context, state) => LoginScreen()),
    GoRoute(path: '/register', builder: (context, state) => RegisterScreen()),
    
    // App Principal (Shell Route)
    ShellRoute(
      builder: (context, state, child) => MainShell(child: child),
      routes: [
        GoRoute(path: '/feed', builder: (context, state) => FeedScreen()),
        GoRoute(path: '/map', builder: (context, state) => MapScreen()),
        GoRoute(path: '/events', builder: (context, state) => EventsListScreen()),
        GoRoute(path: '/notifications', builder: (context, state) => NotificationsScreen()),
        GoRoute(path: '/profile', builder: (context, state) => ProfileScreen()),
      ],
    ),
    
    // Rotas Detalhadas
    GoRoute(path: '/post/:id', builder: (context, state) {
      final postId = state.pathParameters['id']!;
      return PostDetailScreen(postId: postId);
    }),
    
    // Rotas Protegidas (com redirect)
    GoRoute(
      path: '/create-post',
      builder: (context, state) => CreatePostScreen(),
      redirect: (context, state) {
        final isAuthenticated = context.read(authProvider).isAuthenticated;
        if (!isAuthenticated) return '/login';
        return null;
      },
    ),
  ],
  redirect: (context, state) {
    // Redirect global (ex: verificar autenticação)
    return null;
  },
);

Autenticação:

• POST /auth/social-login - Login social
• GET /auth/me - Usuário logado
• POST /auth/refresh - Refresh token

Territórios:

• GET /territories/nearby - Territórios próximos
• GET /territories/{id} - Detalhes do território
• POST /territories/selection - Selecionar território ativo

Feed:

• GET /feed - Lista de posts (filtrado por território ativo)
• POST /feed - Criar post
• GET /feed/{id} - Detalhes do post
• POST /feed/{id}/likes - Curtir post
• POST /feed/{id}/comments - Comentar

Eventos:

• GET /events - Lista de eventos
• POST /events - Criar evento
• GET /events/{id} - Detalhes do evento
• POST /events/{id}/register - Inscrever-se

Membresia:

• POST /territories/{id}/enter - Entrar como VISITOR
• POST /memberships/{territoryId}/become-resident - Solicitar residência
• GET /memberships/{territoryId}/me - Meu vínculo

Moderação:

• POST /reports - Reportar conteúdo/usuário
• GET /moderation/cases - Casos de moderação (CURATOR/MODERATOR)

Todos os models devem ser gerados automaticamente a partir do openapi.json usando:

1. openapi-generator para gerar schemas Dart
2. json_serializable para fromJson/toJson

Exemplos de Models:

• User, Territory, TerritoryMembership
• Post, Event, Comment, Like
• Report, ModerationCase
• Notification, JoinRequest

---

Onboarding:

1. Splash screen (logo, 800ms fade-in)
2. Boas-vindas (se primeiro acesso)
3. Permissão de localização (com explicação de benefícios)
4. Autenticação social (Google, Apple)
5. Coleta de dados adicionais (nome, CPF/documento, telefone, endereço opcional)
6. Verificação 2FA (se habilitado)
7. Descoberta de territórios

Autenticação:

• Login social com OAuth2
• Armazenamento seguro de token
• Refresh automático de token
• Logout com limpeza de dados

Funcionalidades:

• Buscar territórios próximos (raio 25km)
• Visualizar detalhes do território
• Selecionar território ativo
• Entrar como VISITOR ou solicitar RESIDENT
• Verificar status de vínculo

Telas:

• TerritoryListScreen: Lista de territórios próximos (com mapa miniaturizado)
• TerritoryDetailScreen: Detalhes + ações (entrar, solicitar residência)
• TerritorySelectionScreen: Seletor de território ativo (se múltiplos vínculos)

Funcionalidades:

• Visualizar feed do território (PUBLIC + RESIDENTS_ONLY se RESIDENT)
• Paginação infinita (20 posts por página)
• Pull-to-refresh
• Filtros (tipo, data, localização)
• Interações (like, comentário, compartilhamento)

Visibilidade:

• VISITOR: Apenas posts PUBLIC
• RESIDENT: Posts PUBLIC + RESIDENTS_ONLY

Telas:

• FeedScreen: Lista de posts (scroll infinito)
• PostDetailScreen: Detalhes completos + comentários

Funcionalidades:

• Criar post (título opcional, conteúdo obrigatório)
• Tipo: NOTICE, ALERT, ANNOUNCEMENT
• Visibilidade: PUBLIC, RESIDENTS_ONLY
• Adicionar mídias (imagens/vídeos, até 10)
• GeoAnchor automático (derivado de mídias com EXIF)
• Preview antes de publicar

Validações:

• Conteúdo mínimo 10 caracteres, máximo 4000
• Título máximo 200 caracteres
• Apenas RESIDENT pode criar posts RESIDENTS_ONLY
• Sanções de posting respeitadas

Tela:

• CreatePostScreen: Formulário multi-step com preview

Funcionalidades:

• Visualizar mapa do território (polígono destacado)
• Pins de posts/eventos/assets georreferenciados
• Clustering de pins próximos
• Filtros por tipo (posts, eventos, alertas, assets)
• Bottom sheet ao tocar em pin
• Navegação para detalhes do item

Pins Coloridos:

• Post PUBLIC: Verde claro
• Evento PUBLIC: Azul
• Alerta PUBLIC: Laranja
• Asset PUBLIC: Terroso

Tela:

• MapScreen: Mapa Google Maps em tela cheia

Funcionalidades:

• Listar eventos do território
• Criar evento (apenas RESIDENT ou EVENT_ORGANIZER)
• Visualizar detalhes do evento
• Inscrever-se em evento
• Check-in no evento (quando próximo)
• Adicionar ao calendário

Telas:

• EventsListScreen: Lista de eventos (filtros: todos, próximos, acontecendo agora, passados)
• EventDetailScreen: Detalhes completos + ações
• CreateEventScreen: Formulário multi-step (informações, data/hora, localização, mídia)

Funcionalidades:

• Entrar como VISITOR (imediato)
• Solicitar residência (PENDING até aprovação)
• Verificar status de solicitação
• Upload de documento (opcional)
• Verificação por geolocalização

Telas:

• BecomeResidentScreen: Formulário de solicitação (verificação geo, documento, mensagem)
• MembershipStatusScreen: Status da solicitação (PENDING, APPROVED, REJECTED)

Funcionalidades:

• Visualizar perfil próprio
• Editar perfil (nome, bio, foto, preferências)
• Visualizar perfil de outros usuários
• Ver posts/eventos do usuário
• Seguir usuário (futuro)

Telas:

• ProfileScreen: Perfil próprio (editável)
• OtherUserProfileScreen: Perfil de outro usuário (somente leitura)

Funcionalidades:

• Reportar post/evento/usuário
• Revisar reports (CURATOR/MODERATOR)
• Aplicar sanções (territoriais ou globais)
• Bloquear/desbloquear usuários
• Ocultar/restaurar conteúdo

Telas:

• ModerationDashboardScreen: Dashboard de moderação (casos pendentes, estatísticas)
• ReportDetailScreen: Detalhes do report + ações

Funcionalidades:

• Listar notificações (in-app)
• Marcar como lida
• Preferências de notificação (por tipo)
• Push Notifications ⭐: FCM/APNs com deep linking
• Notificações Locais: Para lembrete de eventos, etc.
• Background Sync: Sincronizar notificações em background

Tipos de Notificações Push:

• Novo post no território
• Comentário no seu post
• Evento próximo/começando
• Solicitação de residência aprovada/rejeitada
• Report resolvido
• Mensagem de chat

Tela:

• NotificationsScreen: Lista de notificações (pull-to-refresh, paginação)

Configuração:

• Solicitar permissão de notificações
• Configurar preferências por tipo
• Silenciar por horário (DND)

Funcionalidades:

• Cache local inteligente (Hive)
• Sincronização automática ao voltar online
• Fila offline para ações pendentes
• Indicador visual de modo offline
• Resolução de conflitos

Dados Cacheados:

• Feed (últimos 50 posts)
• Eventos (próximos 30 eventos)
• Territórios (territórios recentes)
• Perfil (próprio e vínculos)

Ações Offline:

• Criar post (salvar localmente)
• Comentar (salvar localmente)
• Curtir (salvar localmente)
• Visualizar conteúdo cacheado

Sincronização:

• Detectar retorno de conexão (connectivity_plus)
• Processar fila offline automaticamente
• Notificar usuário sobre sincronização
• Resolver conflitos (last-write-wins ou diálogo)

Funcionalidades:

• Background Fetch: Atualizar feed periodicamente
• Background Sync: Sincronizar dados em background
• Background Upload: Upload de mídias em background
• Retry Automático: Retry de operações falhadas

Tarefas Periódicas:

• Sincronizar feed: A cada 15 minutos (se online)
• Sincronizar notificações: A cada 30 minutos (se online)
• Sincronizar fila offline: Quando online

Configuração:

• workmanager para tarefas periódicas
• Constraints: NetworkType.connected, requiresBatteryNotLow
• Frequência mínima: 15 minutos (iOS)

Funcionalidades:

• Compartilhar posts/eventos/territórios com links dinâmicos
• Links funcionam mesmo se app não instalado (redirecionam para loja)
• Links funcionam na web (redirecionam para app se instalado)
• Deep linking automático ao tocar em link

Implementação:

• Firebase Dynamic Links
• Universal Links (iOS) via apple-app-site-association
• App Links (Android) via assetlinks.json

Tipos de Links:

• https://Arah.page.link/post/{id} → PostDetailScreen
• https://Arah.page.link/event/{id} → EventDetailScreen
• https://Arah.page.link/territory/{id} → TerritoryDetailScreen

Funcionalidades:

• Recuperar acesso via email/telefone
• Recuperar código 2FA
• Reset de método de autenticação
• Código de recuperação (6 dígitos, válido por 15 minutos)

Fluxo:

1. Usuário solicita recuperação
2. Recebe código por email/SMS
3. Insere código
4. Redefine acesso (novo método de autenticação, reset 2FA)

Tela:

• AccountRecoveryScreen: Solicitar recuperação
• RecoveryCodeScreen: Inserir código
• ResetAccessScreen: Redefinir acesso

Funcionalidades:

• Excluir conta e dados pessoais
• Exportar dados antes de excluir
• Período de graça (7 dias) para cancelar exclusão
• Anonimização/deleção permanente após período de graça

Fluxo:

1. Usuário solicita exclusão nas configurações
2. Opção de exportar dados (JSON)
3. Confirmação dupla ("Tem certeza?", digitar "EXCLUIR")
4. Período de graça (7 dias)
5. Exclusão permanente após período

Tela:

• DeleteAccountScreen: Configurar exclusão
• AccountDeletionPendingScreen: Período de graça
• ExportDataScreen: Exportar dados (se solicitado)

class MyWidget extends ConsumerWidget {
  const MyWidget({super.key, required this.param});
  
  final String param;
  
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final state = ref.watch(someProvider);
    
    return Scaffold(
      appBar: AppBar(title: const Text('Title')),
      body: _buildBody(context, ref, state),
    );
  }
  
  Widget _buildBody(BuildContext context, WidgetRef ref, SomeState state) {
    if (state.isLoading) {
      return const LoadingIndicator();
    }
    
    if (state.hasError) {
      return ErrorWidget(error: state.error);
    }
    
    return _buildContent(context, ref, state);
  }
  
  Widget _buildContent(BuildContext context, WidgetRef ref, SomeState state) {
    // Implementação
  }
}

try {
  final result = await apiService.getData();
  // Processar resultado
} on DioException catch (e) {
  if (e.response?.statusCode == 401) {
    // Redirecionar para login
  } else if (e.response?.statusCode == 429) {
    // Rate limiting - aguardar e retry
  } else {
    // Outro erro - mostrar mensagem
  }
} catch (e, stackTrace) {
  // Capturar exceção não esperada
  ExceptionService.captureException(e, stackTrace: stackTrace);
}

• Criar projeto Flutter
• Configurar dependências (pubspec.yaml) - incluir todas as novas dependências de segurança e background
• Configurar estrutura de pastas
• Configurar tema Material 3 (light/dark)
• Configurar go_router
• Configurar Riverpod
• Configurar Dio (interceptors) - incluir SSL pinning em produção
• Configurar Firebase (Analytics, Crashlytics, Performance, Messaging, Dynamic Links)
• Configurar Sentry
• Configurar i18n
• Gerar models do OpenAPI
• Configurar autenticação biométrica ⭐
• Configurar push notifications ⭐
• Configurar background tasks ⭐
• Configurar modo offline ⭐

• Autenticação (login social, 2FA, biométrica ⭐)
• Onboarding
• Descoberta de territórios
• Seleção de território ativo
• Vínculo VISITOR/RESIDENT
• Feed territorial
• Criação de posts
• Mapa territorial
• Eventos
• Perfil
• Notificações (in-app + push ⭐)
• Modo offline ⭐
• Recuperação de conta ⭐
• Exclusão de conta (LGPD/GDPR) ⭐

• Testes unitários (críticos)
• Testes de widgets (principais)
• Testes de integração (fluxos principais)
• Testes de acessibilidade (WCAG AA) ⭐
• Testes de segurança (biometria, SSL pinning, jailbreak detection) ⭐
• Testes de modo offline ⭐
• Testes de push notifications ⭐
• Performance (FPS, memory, startup time)
• Observabilidade (métricas, logs, exceções)

---

• docs/28_FLUTTER_METRICS_LOGGING_EXCEPTIONS.md: Observabilidade completa
• docs/30_FLUTTER_TESTING_STRATEGY.md: Estratégia de testes (unit, widget, integration, golden)
• docs/31_FLUTTER_ACCESSIBILITY_GUIDE.md: Guia completo de acessibilidade (WCAG AA)
• docs/32_FLUTTER_I18N_GUIDE.md: Guia completo de internacionalização (pt-BR, en-US)