Files
gestao_de_manutencao/documentacao/fluxo_de_dados_e_sincronizacao.md

9.6 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 (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á real e funcionalmente implementada?

Sim, a sincronização é REAL e BIDIRECIONAL. O aplicativo utiliza a Google Sheets API v4 (GoogleSheetsSyncService.kt) para sincronizar a estrutura do projeto e logs de alteração, e o Firebase Storage SDK (FirebaseStorageSyncService.kt) para upload de fotos das OSs no Firebase Storage.

Como o fluxo de sincronização e envio de fotos funciona?

  1. Captura, Suporte HEIC e Compactação Local (Offline-First): As fotos capturadas pela Câmera ou selecionadas da Galeria (nos formatos JPEG, PNG ou HEIC/HEIF) são processadas pelo ImageCompressor.kt. O app decodifica a imagem, corrige a orientação EXIF, reduz a resolução para no máximo 1920x1920 px se necessário, e compacta iterativamente para garantir tamanho final <= 500 KB. O arquivo resultante é armazenado em filesDir/os_photos/ e registrado no Room DB.
  2. Upload Único para o Firebase Storage: Durante a sincronização, o MaintenanceRepository.kt lê as fotos pendentes locais e aciona o FirebaseStorageSyncService.kt. Fotos que já possuem URL remota (http:// ou https://) são ignoradas, garantindo que cada foto seja enviada apenas uma vez. As fotos pendentes são enviadas com trava de segurança de 500KB para a pasta photos/OS_{numeroOs}/.
  3. URL de Download e Sincronismo com Google Sheets: O serviço obtém a downloadUrl do Firebase Storage, atualizando a Room DB. Ao reconciliar os históricos (remoteHistory + localHistory), o sistema prioriza as URLs remotas em relação a caminhos locais desatualizados, refletindo o link público na aba history do Google Sheets.
  4. Soft Delete: A exclusão de fotos no app executa um Soft Delete no Firebase Storage (renomeando a referência no mesmo diretório adicionando o sufixo _DELETED) e atualiza os registros locais.

Arquivos responsáveis pela conexão e sincronização:

  • com.example.util.ImageCompressor: Utilitário responsável pelo decodecimento de HEIC/HEIF/JPEG/PNG, rotação EXIF e compactação garantida de imagens para até 500KB.
  • com.example.data.remote.FirebaseStorageSyncService: Gerencia upload seguro de fotos (com trava de 500KB) e soft delete no Firebase Storage.
  • com.example.data.remote.GoogleSheetsSyncService: Gerencia autenticação via Service Account e reconciliação bidirecional com a planilha central do Google Sheets.
  • com.example.data.repository.MaintenanceRepository: Centraliza a orquestração do sync, upload de mídias pendentes sem reenvios duplicados, resolução de conflitos (LWW) e soft delete.
  • com.example.ui.viewmodel.MaintenanceViewModel: Gerencia os estados de sync na UI, disparos assíncronos e callbacks de gerenciamento de fotos.

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.