9.0 KiB
Documentação do Fluxo de Dados e Sincronização do Aplicativo
Esta documentação resume as conversas e análises técnicas sobre o fluxo de dados, o armazenamento local, o mecanismo de sincronização e o planejamento de um banco de dados remoto baseado no Google Sheets para o aplicativo de manutenção.
1. Fluxo de Dados e Armazenamento Atual
Como o fluxo está desenhado?
O aplicativo adota uma arquitetura offline-first (local prioritário) baseada no padrão MVVM (Model-View-ViewModel) com Repository Pattern:
- Camada de UI (Jetpack Compose): A tela
MaintenanceDashboardScreen.ktreage às mudanças de estado expostas peloMaintenanceViewModel.kt. - ViewModel (
MaintenanceViewModel.kt): Gerencia o fluxo de estados (UI State) utilizandoStateFlowe lida com ações do usuário (filtragem, atualização de progresso, importação de CSV, disparo de sincronização). - Repository (
MaintenanceRepository.kt): Atua como a fonte única de verdade (Single Source of Truth), mediando o acesso aos dados entre a UI e a persistência local (e futuramente a remota). - Banco de Dados Local (Room -
AppDatabase.kt/MaintenanceDao.kt): Toda leitura e escrita de dados de ordens de serviço (OS) acontece primeiro no banco local (SQLite) do dispositivo.
+--------------------------+
| UI (Jetpack Compose) |
+------------+-------------+
| (Observa fluxos / dispara eventos)
v
+--------------------------+
| MaintenanceViewModel |
+------------+-------------+
| (Dispara lógica de negócio)
v
+--------------------------+
| MaintenanceRepository |
+------------+-------------+
| (Acessa dados locais)
v
+--------------------------+
| Room Database (Local DB) |
+--------------------------+
Como funciona o armazenamento?
O armazenamento é realizado por meio do Room Database, que é uma camada de abstração sobre o SQLite nativo do Android.
- O arquivo do banco de dados local (
maintenance_db) é salvo no diretório privado do aplicativo dentro do armazenamento interno do aparelho:/data/data/com.example/databases/maintenance_db.
Múltiplos usuários conseguem acessar a mesma base de dados diretamente?
Não. Por ser um banco de dados local e interno ao dispositivo, o arquivo SQLite é isolado e privado para a instância do aplicativo instalada naquele smartphone/tablet específico.
- Dois usuários rodando o aplicativo em celulares diferentes possuem bases de dados 100% distintas e isoladas.
- Para que múltiplos usuários compartilhem e visualizem os mesmos dados de manutenção, é indispensável implementar um servidor centralizado (ou um banco de dados na nuvem, como Google Sheets, Firebase, PostgreSQL, etc.) e um fluxo de sincronização bidirecional.
2. Análise da Sincronização Remota
A sincronização remota está realmente implementada?
Atualmente, a sincronização é SIMULADA (Mocked). Não há nenhuma conexão real HTTP, REST API, Firebase ou WebSocket ativa enviando dados para um servidor externo. O código simula perfeitamente o comportamento que um fluxo de rede real teria.
Como a simulação funciona?
No método synchronizeWithBackend() dentro de MaintenanceRepository.kt:
- O repositório busca do banco local todas as atividades de manutenção que possuem a flag
synced = false(obtidas pordao.getUnsyncedActivities()). - Aplica um atraso artificial de 2,5 segundos (
delay(2500)) usando Corrotinas para emular a latência de uma chamada de rede real. - Executa um algoritmo matemático simples de resolução de conflitos em cerca de 15% das ordens de serviço (usando o resto da divisão do hash do número da OS por 7).
- No cenário simulado de conflito, adota a estratégia "Last-Write-Wins" (Última escrita vence), assumindo que a alteração local feita no campo pelo inspetor é a mais recente e deve sobrescrever o "servidor".
- Atualiza todos os registros modificados localmente no banco Room para
synced = true.
Arquivos responsáveis por essa conexão e sincronização:
com.example.data.model.MaintenanceActivity: Contém os atributossynced: Boolean(indica se a OS local está pareada com o servidor) elastUpdated: Long(carimbo de data/hora em milissegundos para resolver conflitos de alteração concorrente).com.example.data.local.MaintenanceDao: Contém a consulta SQL@Query("SELECT * FROM maintenance_activities WHERE synced = 0")para extrair apenas o que foi alterado offline e precisa subir.com.example.data.repository.MaintenanceRepository: Contém o métodosynchronizeWithBackend(), que centraliza toda a lógica de preparação do lote de envio, simulação de rede e marcação de sincronizado.com.example.ui.viewmodel.MaintenanceViewModel: Contém o métodosyncWithBackend(), que executa a chamada ao repositório dentro de um escopo de Coroutine, altera o estado da tela para "Carregando" (Loading), lida com o resultado de sucesso ou falha, e atualiza a UI.
3. Estruturação para Integração com Google Sheets (Futuro)
Se você decidir usar o Google Sheets como seu banco de dados remoto centralizado para permitir que múltiplos dispositivos acessem e sincronizem os mesmos dados, você precisará criar uma planilha no Google Drive com duas abas (worksheets) principais para refletir a estrutura de dados atual do aplicativo.
Abaixo está o mapeamento exato de tabelas e colunas que você deve configurar no seu Google Sheets:
Tabela/Aba 1: activities (Ordens de Serviço de Manutenção)
Esta aba armazenará a lista de todas as ordens de serviço ativas na planta.
| Nome da Coluna (Cabeçalho da Coluna A, B, C...) | Tipo Sugerido | Descrição / Observações |
|---|---|---|
numeroOs |
Texto (Chave Primária) | Ex: OS-4010. Deve ser único nesta tabela. |
descricao |
Texto | Descrição detalhada da atividade de manutenção. |
setor |
Texto | Setor da fábrica (ex: Preparação, Extração, Caldeira, Refinaria, Envase). |
equipe |
Texto | Equipe técnica responsável (ex: Mecânica, Elétrica, Confiabilidade, Lubrificação). |
responsavel |
Texto | Nome do técnico ou encarregado responsável pela atividade. |
dataInicio |
Texto ou Data | Data programada para o início (ex: 30/06/2026). |
dataFim |
Texto ou Data | Data programada para conclusão (ex: 02/07/2026). |
percentualExecucao |
Número Inteiro | Progresso de execução de 0 a 100. |
observacoes |
Texto (Opcional) | Comentários, notas adicionais ou relato de anomalias encontradas. |
fotoPath |
Texto (URL) | Importante: O Sheets não armazena arquivos binários diretamente na célula de forma eficiente. O aplicativo deve fazer upload da foto para um servidor de arquivos ou pasta pública do Google Drive, e armazenar o link direto da imagem (URL) nesta coluna. |
lastUpdated |
Número Inteiro (Long) | Timestamp Unix em milissegundos (ex: 1783965742000). Essencial para saber qual dispositivo fez a alteração mais recente e evitar perda de dados. |
Tabela/Aba 2: history (Histórico de Atualizações das OS)
Esta aba registrará cada alteração feita em qualquer OS, permitindo auditoria detalhada de quem alterou o progresso e quando.
| Nome da Coluna (Cabeçalho da Coluna A, B, C...) | Tipo Sugerido | Descrição / Observações |
|---|---|---|
id |
Texto ou Número | Identificador único da linha do histórico (pode ser gerado como UUID no app ou auto-incremento). |
numeroOs |
Texto | Código da OS que foi atualizada (chave estrangeira relacionada à aba activities). |
timestamp |
Número Inteiro (Long) | Carimbo de data/hora em milissegundos de quando a atualização ocorreu. |
percentualAnterior |
Número Inteiro | Qual era o progresso antes dessa alteração (ex: 25). |
percentualNovo |
Número Inteiro | Qual o novo progresso registrado (ex: 50). |
observacao |
Texto (Opcional) | Comentário inserido pelo técnico justificando ou detalhando aquela atualização específica. |
fotoPath |
Texto (URL) | Link da foto tirada no momento desta atualização (se houver). |
responsavel |
Texto | Nome do profissional que realizou esta atualização de progresso. |
Dicas para a Integração com Google Sheets:
- API de Comunicação: Para conectar o app Android ao Google Sheets, você pode usar uma API REST intermediária feita no Google Apps Script (que recebe requisições POST/GET com JSON e escreve na planilha) ou usar diretamente a Google Sheets API via bibliotecas HTTP como Retrofit/Ktor.
- Resolução de Conflitos (LWW): Quando o aplicativo sincronizar, ele deve comparar o
lastUpdatedlocal da OS com olastUpdatedpresente na linha correspondente da abaactivitiesno Sheets. Se olastUpdateddo Sheets for mais novo, o aplicativo deve baixar a alteração. Se olastUpdatedlocal for mais novo, o app deve enviar e atualizar a planilha.