Referência de aplicação. Esta é uma arquitetura ilustrativa e uma lista de verificação de escopo, não um projeto de cliente verificado nem uma implantação medida. As tecnologias, o escopo de integração e os itens de entrega são acordados para o briefing real.
Cenário e restrições
Um produto de serviços no qual iOS e Android compartilham os mesmos fluxos de trabalho e uma equipe pequena precisa manter ambos. Três restrições moldam o design: redes móveis não confiáveis, ciclos de revisão das lojas de aplicativos que tornam as correções urgentes lentas e a necessidade de alterar regras de negócio sem distribuir uma nova versão.
Arquitetura
Camadas e responsabilidades
| Camada | Tecnologia | Responsável por |
|---|---|---|
| Aplicativo | Flutter (Dart), estruturado em UI / estado / repositório | Telas e interação. A camada de repositório é a única que sabe se os dados vieram da rede ou do cache local, mantendo o tratamento offline fora do código da UI. |
| Armazenamento local | SQLite (drift) + armazenamento seguro da plataforma | Entidades em cache, uma fila de saída de gravações pendentes e tokens em armazenamento seguro, em vez de preferências compartilhadas. |
| API | Go + Gin, rotas versionadas | Regras de negócio, validação e autorização. Versionada desde o primeiro dia porque versões antigas do aplicativo permanecem nas mãos dos usuários muito depois do lançamento. |
| Armazenamento | PostgreSQL | Dados transacionais; JSONB é usado para atributos genuinamente variáveis, em vez de ampliar as tabelas indefinidamente. |
| Cache / fila | Redis | Sessões, limitação de taxa, chaves de idempotência e fila de tarefas em segundo plano. |
| Push | FCM e APNs por trás de um único serviço de notificações | Uma única API interna para notificações; as diferenças entre plataformas são tratadas no servidor, não no aplicativo. |
| Administração | Painel administrativo em Vue | Gerenciamento de usuários, conteúdo e pedidos, além dos valores de configuração remota que alteram o comportamento do aplicativo sem um lançamento. |
Modelo de dados
As tabelas abaixo contêm as regras das quais todo o restante depende. Errar aqui é o que transforma uma demonstração funcional em um sistema que não pode ser estendido.
Entidades principais
| Entidade | Campos principais, relações e regras |
|---|---|
| user / auth_identity | Um usuário pode ter várias identidades (telefone, Apple, Google, WeChat). Separar a identidade do usuário é o que permite adicionar um método de login posteriormente sem uma migração. |
| device | Token de push, plataforma, versão do aplicativo e localidade por dispositivo. O direcionamento de notificações e os lançamentos graduais usam esses dados. |
| order / booking | A entidade de domínio com uma coluna de estado explícita e um registro de transições, para que a pergunta “como chegou a este estado” possa ser respondida pelo suporte. |
| outbox (lado do cliente) | Gravações locais enfileiradas com um UUID gerado pelo cliente. Esse UUID torna-se a chave de idempotência no servidor, o que torna segura a nova tentativa após um tempo limite. |
| sync_cursor | Marca d’água updated_at por usuário que orienta a sincronização incremental, para que o aplicativo busque alterações em vez de recarregar coleções inteiras. |
| remote_config | Configuração de chave-valor por versão do aplicativo e plataforma, permitindo alterar regras e sinalizadores de recursos sem enviar uma submissão à loja de aplicativos. |
Interfaces principais
Endpoints que transportam as regras de negócio
| Endpoint | Finalidade e observações sobre concorrência |
|---|---|
| POST /api/v1/auth/token | Emite um token de acesso de curta duração e um token de atualização rotativo. A rotação do token de atualização limita os danos de um token roubado em um dispositivo ao qual você não consegue acessar. |
| GET /api/v1/sync?since= | Busca incremental de registros alterados desde um cursor, paginada e limitada, para que um usuário que retorna após semanas offline não possa obter uma resposta sem limite. |
| POST /api/v1/orders | Aceita o UUID do cliente como chave de idempotência; uma nova tentativa após um tempo limite de rede retorna o pedido original em vez de criar uma duplicata. |
| POST /api/v1/devices | Registra ou atualiza o token de push, associado ao usuário e à versão do aplicativo para notificações direcionadas e graduais. |
| GET /api/v1/config | Retorna a configuração remota para a versão do aplicativo solicitante — o mecanismo que evita distribuir uma versão para alterar uma regra. |
Decisões técnicas
- Flutter em vez de duas bases de código nativas. Os fluxos de trabalho são compartilhados e a equipe é pequena, portanto o código de aplicativo compartilhado pode reduzir a manutenção duplicada onde os fluxos se sobrepõem; integrações de plataforma, verificações de dispositivo e lançamentos ainda exigem trabalho separado. Quando as plataformas realmente diferem — pagamentos, push e biometria — a diferença é isolada por trás de um canal de plataforma, em vez de vazar para o código compartilhado.
- Tolerante a offline, não offline-first. As leituras são armazenadas em cache e as gravações são enfileiradas em uma fila de saída, mas o servidor continua sendo a autoridade. O offline-first completo com resolução de conflitos custa consideravelmente mais e só vale a pena quando os usuários realmente trabalham desconectados por longos períodos.
- UUIDs gerados pelo cliente como chaves de idempotência. As redes móveis atingem o tempo limite no meio das solicitações rotineiramente. Sem isso, novas tentativas após tempos limite podem criar risco de pedidos duplicados, que precisa ser testado.
- API versionada desde o primeiro lançamento. Os usuários adiam as atualizações, portanto o servidor precisa continuar atendendo versões antigas. Adaptar o versionamento após o lançamento é muito mais caro do que começar com ele.
- Configuração remota para regras de negócio. Os lançamentos do cliente dependem da revisão da plataforma e da adoção pelos usuários. Limites compatíveis, textos e sinalizadores de recursos podem ser gerenciados no servidor quando as regras da plataforma permitirem; alterações que exigem uma nova versão do aplicativo mantêm essa dependência.
Metas hipotéticas de design
Os números abaixo são exemplos hipotéticos de planejamento de capacidade, não resultados medidos de clientes, uma recomendação de dimensionamento validada nem um SLA. Defina metas de aceitação específicas do projeto após definir a carga de trabalho, os dispositivos, os dados, o hardware e as dependências de terceiros; valide-as por meio de um piloto e de testes de carga antes de assumir uma meta de produção.
Metas de capacidade e desempenho
| Meta | Valor e suposição |
|---|---|
| Inicialização a frio até a primeira tela significativa | Menos de 2 segundos em um dispositivo Android intermediário, supondo que os dados em cache sejam renderizados enquanto a rede é atualizada em segundo plano. |
| Sincronização incremental | Carga útil de alterações inferior a 200 KB para um usuário que retorna normalmente, com o tamanho da página limitado para que um usuário ausente por muito tempo tenha uma degradação gradual em vez de atingir o tempo limite. |
| Latência da API | p95 inferior a 300 ms para leituras padrão, excluindo chamadas de terceiros cuja latência não controlamos. |
| Entrega de push | Defina e meça o tempo de enfileiramento no aplicativo e de confirmação do provedor. O tempo final de entrega pertence à plataforma e não é garantido por esta referência. |
O que a entrega inclui
- Código-fonte do aplicativo Flutter, do back-end Go e da administração Vue no seu repositório
- Configuração de compilação e assinatura para ambas as plataformas, além da preparação das listagens nas lojas
- Documentação da API, esquema do banco de dados e histórico de migrações
- Notas de implantação, acesso a monitoramento e logs, procedimento de backup e restauração
- Suporte para submissão à App Store e ao Google Play; o resultado e o prazo da revisão permanecem sob responsabilidade da Apple e do Google
Planejando isso para sua empresa
Os módulos acima são um ponto de partida, não um pacote fixo. Normalmente reduzimos a primeira versão a um fluxo de trabalho principal e um fluxo administrativo, depois ampliamos quando o uso real mostra onde a carga e os casos extremos realmente estão. Envie um briefing com escopo e nós o compararemos com esta arquitetura e informaremos quais partes você ainda não precisa.
