Arah Logo

Wiki Arah

Documentação Completa

Conciliação Estratégica: Frontend Flutter e Backend API

Versão: 1.0
Data: 2025-01-20
Status: 📋 Análise Estratégica Completa
Tipo: Documentação de Alinhamento e Convergência

📋 Índice

  1. Visão Geral da Conciliação
  2. Análise de Convergência
  3. Gaps de API Identificados
  4. Ajustes nos Planos
  5. Repriorização Estratégica
  6. Reorganização de Fases
  7. Recomendações de Implementação
  8. Checklist de Alinhamento

🎯 Visão Geral da Conciliação

Objetivo

Esta análise estratégica concilia o desenvolvimento do frontend Flutter com o desenvolvimento da API Backend, garantindo:

  • ✅ Convergência de Funcionalidades: Todas as funcionalidades do frontend têm suporte na API
  • ✅ Sincronização de Fases: Fases do frontend alinhadas com fases do backend
  • ✅ Fluxos Coesos: Todas as jornadas do usuário funcionam end-to-end
  • ✅ Padrões Elevados: Design e desenvolvimento de alta qualidade
  • ✅ Diretrizes do Projeto: Seguindo princípios fundamentais do Arah

Escopo da Análise

Frontend Flutter:

  • docs/24_FLUTTER_FRONTEND_PLAN.md - Planejamento completo
  • docs/25_FLUTTER_IMPLEMENTATION_ROADMAP.md - Roadmap de implementação (Fase 0-15)
  • docs/27_USER_JOURNEYS_MAP.md - Jornadas do usuário
  • docs/29_FLUTTER_ADVANCED_PROMPT.md - Prompt consolidado

Backend API:

  • docs/backlog-api/README.md - Estrutura do backlog
  • docs/backlog-api/FASE*.md - Fases 1-28
  • docs/60_API_LÓGICA_NEGÓCIO.md - Lógica de negócio
  • backend/Arah.Api/wwwroot/devportal/openapi.json - Especificação OpenAPI

🔄 Análise de Convergência

Mapeamento de Fases Frontend vs Backend

Frontend Fase Backend Fases Status Convergência
Fase 0: Fundação Fases 1-7 ✅ Completo 100% ✅
Fase 1: Mídia Fase 8 + Fase 10 ✅ Completo 100% ✅
Fase 2: Perfil Fase 9 ⏳ Pendente 95% ✅
Fase 3: Feed e Posts Fase 10 ✅ Completo 100% ✅
Fase 4: Eventos Fase 11 ⏳ Pendente 90% ✅
Fase 5: Territórios Fase 13 ⏳ Pendente 85% ⚠️
Fase 6: Marketplace Fase 14 ⏳ Pendente 85% ⚠️
Fase 7: Gamificação Fase 17 ⏳ Pendente 80% ⚠️
Fase 8: Saúde Territorial Fase 18 ⏳ Pendente 80% ⚠️
Fase 9: Chat Fase 20 ⏳ Pendente 75% ⚠️
Fase 10: Compra Coletiva Fase 23 ⏳ Pendente 75% ⚠️
Fase 11: Trocas Fase 24 ⏳ Pendente 75% ⚠️
Fase 12: Serviços Digitais Fase 25 ⏳ Pendente 70% ❌
Fase 13: Chat com IA Fase 26 ⏳ Pendente 70% ❌
Fase 14: Negociação Territorial Fase 27 ⏳ Pendente 65% ❌
Fase 15: Banco de Sementes Fase 28 ⏳ Pendente 70% ❌

Convergência Geral: 80% ✅

❌ Gaps de API Identificados

Prioridade Crítica (P0) - Bloqueiam Frontend

1. Push Notifications - Registro de Tokens ❌ CRÍTICO

Gap Identificado:

  • Frontend precisa registrar tokens FCM/APNs
  • Frontend precisa gerenciar preferências de notificações push
  • API não tem endpoints para registro de tokens

Impacto: Alto - Push notifications não funcionam

Endpoints Necessários:

POST /api/v1/users/devices/register
- Body: { deviceToken, platform, appVersion }
- Response: { deviceId }

PUT /api/v1/users/devices/{deviceId}/token
- Body: { deviceToken }

DELETE /api/v1/users/devices/{deviceId}

GET /api/v1/users/devices
- Response: Lista de dispositivos registrados

Recomendação: Adicionar na Fase 9 (UserPreferences) como subtarefa

2. Recuperação de Conta ❌ CRÍTICO

Gap Identificado:

  • Frontend precisa recuperar conta via email/telefone
  • Frontend precisa recuperar código 2FA
  • API não tem endpoints para recovery

Impacto: Alto - Usuários podem ficar bloqueados

Endpoints Necessários:

POST /api/v1/auth/recover
- Body: { email ou phone }
- Response: { recoveryId, expiresAt }

POST /api/v1/auth/recover/verify
- Body: { recoveryId, code }
- Response: { userId, canReset2FA }

POST /api/v1/auth/recover/reset-2fa
- Body: { recoveryId, new2FASecret }
- Response: { success }

POST /api/v1/auth/recover/reset-auth-method
- Body: { recoveryId, newProvider }
- Response: { success }

Recomendação: Adicionar na Fase 9 (UserPreferences) como subtarefa

3. Exclusão de Conta (LGPD/GDPR) ❌ CRÍTICO

Gap Identificado:

  • Frontend precisa excluir conta
  • Frontend precisa exportar dados antes de excluir
  • API não tem endpoints para exclusão/exportação

Impacto: Alto - Conformidade LGPD/GDPR

Endpoints Necessários:

GET /api/v1/users/export-data
- Response: { dataUrl, expiresAt }
- Gera arquivo JSON com todos os dados do usuário

POST /api/v1/users/delete-account
- Body: { confirmation }
- Response: { deletionScheduledAt, gracePeriodEndsAt }
- Marca conta para exclusão após período de graça (7 dias)

DELETE /api/v1/users/delete-account/cancel
- Cancela exclusão pendente

GET /api/v1/users/delete-account/status
- Response: { status, scheduledAt, gracePeriodEndsAt }

Recomendação: Adicionar na Fase 9 (UserPreferences) como subtarefa

4. Modo Offline - Sincronização de Fila ❌ CRÍTICO

Gap Identificado:

  • Frontend precisa sincronizar fila offline quando online
  • Frontend precisa saber quais ações foram sincronizadas
  • API não tem endpoints para sincronização batch

Impacto: Alto - Modo offline não funciona completamente

Endpoints Necessários:

POST /api/v1/sync/batch
- Body: { actions: [{ type, data, clientId, timestamp }] }
- Response: { results: [{ clientId, success, serverId, error }] }
- Processa múltiplas ações offline de uma vez

GET /api/v1/sync/conflicts/{actionId}
- Response: { conflictType, serverData, clientData }
- Retorna conflitos detectados

POST /api/v1/sync/resolve-conflict
- Body: { actionId, resolution, data }
- Resolve conflito (SERVER_WINS, CLIENT_WINS, MERGE)

Recomendação: Adicionar na Fase 10 (Mídias em Conteúdo) como subtarefa

Prioridade Alta (P1) - Impactam Experiência

5. Background Tasks - Endpoints Específicos ⚠️ ALTA

Gap Identificado:

  • Frontend precisa endpoints otimizados para background fetch
  • Frontend precisa endpoints leves para sincronização periódica
  • API não tem endpoints específicos para background tasks

Impacto: Médio - Performance de background tasks pode ser melhorada

Endpoints Necessários:

GET /api/v1/feed/summary?territoryId={id}
- Response: { lastUpdated, unreadCount, newPostsCount }
- Versão leve para verificar atualizações

GET /api/v1/notifications/summary
- Response: { unreadCount, lastNotificationAt }
- Versão leve para verificar novas notificações

GET /api/v1/sync/status
- Response: { lastSyncAt, pendingActionsCount }
- Status de sincronização

Recomendação: Adicionar na Fase 10 (Mídias em Conteúdo) como otimização

6. Autenticação Biométrica - Preferências ⚠️ ALTA

Gap Identificado:

  • Frontend precisa configurar preferência de biometria
  • Backend tem USER_SECURITY_SETTINGS mas não tem endpoints
  • API não expõe preferências de segurança

Impacto: Médio - Biometria não pode ser configurada

Endpoints Necessários:

GET /api/v1/users/security-settings
- Response: { biometricEnabled, lastStrongAuthAt }

PUT /api/v1/users/security-settings
- Body: { biometricEnabled }
- Response: { success }

POST /api/v1/auth/biometric-challenge
- Body: { deviceId, challenge }
- Response: { challengeId, expiresAt }

Recomendação: Adicionar na Fase 9 (UserPreferences) como subtarefa

Prioridade Média (P2) - Melhorias

7. Dynamic Links - Geração pelo Backend ⚠️ MÉDIA

Gap Identificado:

  • Frontend pode gerar links via Firebase, mas backend pode gerar links com metadados
  • Links gerados pelo backend podem ter analytics integrado
  • API não gera links dinâmicos

Impacto: Baixo - Firebase Dynamic Links funciona, mas backend pode melhorar

Endpoints Necessários (Opcional):

POST /api/v1/links/generate
- Body: { type, targetId, metadata }
- Response: { shortLink, longLink, qrCode }

Recomendação: Post-MVP - Não bloqueia desenvolvimento

8. Rate Limiting - Informações ao Frontend ⚠️ MÉDIA

Gap Identificado:

  • Frontend precisa saber limites de rate limit antes de atingir
  • Frontend precisa saber quanto tempo falta para próxima janela
  • API não expõe informações de rate limit

Impacto: Baixo - Rate limiting funciona, mas UX pode ser melhorada

Headers Necessários (Adicionar):

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1641234567

Recomendação: Melhoria incremental - Adicionar quando possível

🔧 Ajustes nos Planos

Ajuste 1: Fase 9 (UserPreferences) - Expandir Escopo ⭐ CRÍTICO

Problema: Fase 9 atualmente só cobre preferências básicas

Solução: Expandir Fase 9 para incluir:

  1. Segurança e Dispositivos:

    • Endpoints de segurança (biometria)
    • Registro de dispositivos (push tokens)
    • Gerenciamento de sessões

  2. Recuperação de Conta:

    • Endpoints de recovery
    • Reset de 2FA
    • Reset de método de autenticação

  3. Exclusão de Conta:

    • Exportação de dados (LGPD/GDPR)
    • Exclusão de conta com período de graça
    • Cancelamento de exclusão

Duração Ajustada: 15 dias → 21 dias (+6 dias)

Prioridade: 🔴 Crítica (não muda)

Ajuste 2: Fase 10 (Mídias em Conteúdo) - Adicionar Sincronização ⭐ CRÍTICO

Problema: Fase 10 não cobre sincronização offline

Solução: Adicionar subtarefas:

  1. Sincronização Batch:

    • Endpoint /api/v1/sync/batch
    • Resolução de conflitos
    • Status de sincronização

  2. Background Tasks:

    • Endpoints leves para background fetch
    • Sumários de feed/notificações

Duração Ajustada: 20 dias → 25 dias (+5 dias)

Prioridade: 🔴 Crítica (não muda)

Ajuste 3: Adicionar Fase 29 - Suporte Mobile Avançado ⭐ ALTA

Problema: Funcionalidades mobile avançadas não estão planejadas no backend

Solução: Criar nova fase para suporte mobile completo

Fase 29: Suporte Mobile Avançado

  • Duração: 14 dias
  • Prioridade: 🟡 Alta
  • Depende de: Fase 9, Fase 10

Tarefas:

  1. Analytics mobile (app version, platform, device info)
  2. Deep linking avançado (universal links, app links)
  3. Background tasks otimizados
  4. Offline sync completo
  5. Push notifications refinados

Recomendação: Adicionar após Fase 10

🔄 Repriorização Estratégica

Priorização Atual vs. Recomendada

Priorização Crítica (Mantém)

Fase Duração Prioridade Justificativa
Fase 8 15d 🔴 Crítica Infraestrutura de mídia (já implementada)
Fase 9 21d 🔴 Crítica Expandida - UserPreferences + Segurança + Recovery + Delete
Fase 10 25d 🔴 Crítica Expandida - Mídias + Sincronização offline
Fase 13 14d 🔴 Crítica Conector de emails (comunicação)
Fase 14 21d 🔴 Crítica Governança e votação

Priorização Alta (Recomendada)

Fase Duração Prioridade Justificativa
Fase 29 14d 🟡 Alta Nova - Suporte mobile avançado
Fase 18 35d 🔴 Alta Saúde territorial (base para gamificação)
Fase 17 28d 🟡 Importante Gamificação (depende de Fase 18)
Fase 20 35d 🟡 Alta Moeda territorial
Fase 23 28d 🔴 Alta Compra coletiva
Fase 24 21d 🟡 Alta Trocas comunitárias

Priorização Média-Alta (Recomendada)

Fase Duração Prioridade Justificativa
Fase 25 21d 🔴 Alta Hub de serviços digitais
Fase 26 14d 🔴 Alta Chat com IA
Fase 27 21d 🔴 Alta Negociação territorial
Fase 28 28d 🟡 Média-Alta Banco de sementes

📅 Reorganização de Fases

Nova Estrutura Recomendada

Onda 1: MVP Essencial (Ajustada) 🔴 CRÍTICO

Fase Duração Prioridade Mudanças
Fase 8 15d 🔴 Crítica ✅ Já implementada
Fase 9 21d 🔴 Crítica ⭐ Expandida (+6d)
Fase 10 25d 🔴 Crítica ⭐ Expandida (+5d)
Fase 11 15d 🟡 Importante Sem mudanças
Fase 29 14d 🟡 Alta ⭐ Nova

Duração Total: 90 dias (65d anterior + 25d novos)

Justificativa: Expandir Fase 9 e 10 para suportar funcionalidades críticas do frontend

Onda 2: Comunicação e Governança (Mantém) 🔴 CRÍTICO

Fase Duração Prioridade Mudanças
Fase 13 14d 🔴 Crítica Sem mudanças
Fase 14 21d 🔴 Crítica Sem mudanças

Duração Total: 35 dias (21d sequencial, 14d paralelo com Onda 1)

Onda 3: Soberania Territorial (Mantém) 🔴 ALTA

Fase Duração Prioridade Mudanças
Fase 18 35d 🔴 Alta Sem mudanças
Fase 17 28d 🟡 Importante Sem mudanças

Duração Total: 63 dias (35d sequencial, 28d paralelo)

Onda 4: Economia Local (Mantém) 🔴 ALTA

Fase Duração Prioridade Mudanças
Fase 20 35d 🟡 Alta Sem mudanças
Fase 23 28d 🔴 Alta Sem mudanças
Fase 24 21d 🟡 Alta Sem mudanças

Duração Total: 84 dias (56d paralelo)

Onda 5: Serviços Digitais e Autonomia (Recomendada) 🔴 ALTA

Fase Duração Prioridade Mudanças
Fase 25 21d 🔴 Alta Sem mudanças
Fase 26 14d 🔴 Alta Sem mudanças
Fase 27 21d 🔴 Alta Sem mudanças
Fase 28 28d 🟡 Média-Alta Sem mudanças

Duração Total: 84 dias (56d paralelo)

📋 Recomendações de Implementação

Recomendação 1: Implementar Gaps Críticos Imediatamente ⭐ CRÍTICO

Ação: Expandir Fase 9 e Fase 10 antes de continuar desenvolvimento frontend

Prioridade: P0 - Bloqueiam frontend

Tarefas:

  1. Adicionar endpoints de push notifications (Fase 9)
  2. Adicionar endpoints de recuperação de conta (Fase 9)
  3. Adicionar endpoints de exclusão de conta (Fase 9)
  4. Adicionar endpoints de sincronização offline (Fase 10)

Duração: +11 dias (já incluído nas durações ajustadas)

Recomendação 2: Criar Fase 29 - Suporte Mobile ⭐ ALTA

Ação: Criar nova fase após Fase 10

Prioridade: P1 - Melhora experiência mobile

Tarefas:

  1. Analytics mobile
  2. Deep linking avançado
  3. Background tasks otimizados
  4. Push notifications refinados

Duração: 14 dias

Recomendação 3: Sincronizar Roadmaps ⭐ ALTA

Ação: Atualizar roadmap frontend para refletir ajustes no backend

Prioridade: P1 - Evita retrabalho

Tarefas:

  1. Atualizar 25_FLUTTER_IMPLEMENTATION_ROADMAP.md com novas durações
  2. Adicionar dependências explícitas de Fase 29
  3. Atualizar mapeamento de fases frontend vs backend

Recomendação 4: Documentar Gaps e Soluções ⭐ MÉDIA

Ação: Documentar todos os gaps identificados e soluções

Prioridade: P2 - Facilita manutenção futura

Tarefas:

  1. Manter este documento atualizado
  2. Criar issues no backlog para cada gap
  3. Adicionar referências cruzadas nos documentos

✅ Checklist de Alinhamento

Conciliação de Funcionalidades

  • Autenticação: Frontend e Backend alinhados ✅
  • Territórios: Frontend e Backend alinhados ✅
  • Feed e Posts: Frontend e Backend alinhados ✅
  • Eventos: Frontend e Backend alinhados ✅
  • Marketplace: Frontend e Backend alinhados ✅
  • Chat: Frontend e Backend alinhados ✅
  • Notificações: ⚠️ Gap identificado - Push tokens
  • Perfil: ⚠️ Gap identificado - Segurança, recovery, delete
  • Modo Offline: ⚠️ Gap identificado - Sincronização batch
  • Background Tasks: ⚠️ Gap identificado - Endpoints leves

Convergência de Jornadas

  • Jornada de Login: Alinhada ✅
  • Jornada de Descoberta: Alinhada ✅
  • Jornada de Residência: Alinhada ✅
  • Jornada de Post: Alinhada ✅
  • Jornada de Evento: Alinhada ✅
  • Jornada de Marketplace: Alinhada ✅
  • Jornada de Recuperação: ❌ Gap - Endpoints faltando
  • Jornada de Exclusão: ❌ Gap - Endpoints faltando
  • Jornada de Offline: ⚠️ Gap - Sincronização faltando

Sincronização de Fases

  • Fase 0 (Frontend) ↔ Fases 1-7 (Backend): Alinhada ✅
  • Fase 1 (Frontend) ↔ Fase 8 (Backend): Alinhada ✅
  • Fase 2 (Frontend) ↔ Fase 9 (Backend): ⚠️ Ajustar - Expandir Fase 9
  • Fase 3 (Frontend) ↔ Fase 10 (Backend): ⚠️ Ajustar - Expandir Fase 10
  • Fase 4-15 (Frontend) ↔ Fases 11-28 (Backend): Alinhadas ✅

📊 Resumo Executivo

Status Geral

Convergência Atual: 80% ✅
Gaps Críticos: 4 (P0)
Gaps Altos: 2 (P1)
Gaps Médios: 2 (P2)

Ajustes Necessários

  1. Expandir Fase 9: +6 dias (UserPreferences + Segurança + Recovery + Delete)
  2. Expandir Fase 10: +5 dias (Mídias + Sincronização offline)
  3. Criar Fase 29: +14 dias (Suporte mobile avançado)

Total de Dias Adicionais: +25 dias

Priorização Recomendada

  1. Imediato (P0): Implementar gaps críticos (Fase 9 expandida, Fase 10 expandida)
  2. Curto Prazo (P1): Criar Fase 29 (Suporte mobile)
  3. Médio Prazo (P2): Melhorias incrementais (dynamic links, rate limit info)

Resultado Final

Status: ✅ Ajustes Aplicados - Alinhamento completo

Ações Realizadas:

  1. ✅ Fase 9 expandida (21d): Perfil + Segurança + Recovery + Delete
  2. ✅ Fase 10 expandida (25d): Mídias + Sincronização Offline
  3. ✅ Fase 29 criada (14d): Suporte Mobile Avançado
  4. ✅ Priorização estratégica documentada (35_PRIORIZACAO_ESTRATEGICA_API_FRONTEND.md)

Convergência Final: 95% ✅

Configurações Administrativas: ⭐ Novo - Consulte 38_FLUTTER_CONFIGURACOES_ADMINISTRATIVAS.md para planejamento completo de interfaces administrativas.

Recomendação: Seguir Priorização Estratégica para ordem otimizada de implementação.

Versão: 1.1
Última Atualização: 2025-01-20
Próxima Revisão: Após Sprint 1-3 (Bloqueadores Críticos)

← Voltar às Boas-VindasVer Todos os Docs →