Files
gestao_de_manutencao/documentacao/fluxo_de_dados_e_sincronizacao.md
2026-07-15 17:11:40 +00:00

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:

  1. Camada de UI (Jetpack Compose): A tela MaintenanceDashboardScreen.kt reage às mudanças de estado expostas pelo MaintenanceViewModel.kt.
  2. ViewModel (MaintenanceViewModel.kt): Gerencia o fluxo de estados (UI State) utilizando StateFlow e lida com ações do usuário (filtragem, atualização de progresso, importação de CSV, disparo de sincronização).
  3. 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).
  4. 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 (cargill_maintenance_db) é salvo no diretório privado do aplicativo dentro do armazenamento interno do aparelho: /data/data/com.example/databases/cargill_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:

  1. O repositório busca do banco local todas as atividades de manutenção que possuem a flag synced = false (obtidas por dao.getUnsyncedActivities()).
  2. Aplica um atraso artificial de 2,5 segundos (delay(2500)) usando Corrotinas para emular a latência de uma chamada de rede real.
  3. 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).
  4. 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".
  5. 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 atributos synced: Boolean (indica se a OS local está pareada com o servidor) e lastUpdated: 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étodo synchronizeWithBackend(), 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étodo syncWithBackend(), 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:

  1. 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.
  2. Resolução de Conflitos (LWW): Quando o aplicativo sincronizar, ele deve comparar o lastUpdated local da OS com o lastUpdated presente na linha correspondente da aba activities no Sheets. Se o lastUpdated do Sheets for mais novo, o aplicativo deve baixar a alteração. Se o lastUpdated local for mais novo, o app deve enviar e atualizar a planilha.