Files
gestao_de_manutencao/documentacao/fluxo_de_dados_e_sincronizacao.md

12 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. Download Inteligente com Re-tentativas Automáticas (Retry & Cache): Para garantir a exibição de fotos em ambientes de campo com oscilações de rede, o aplicativo utiliza o Coil configurado via MainApplication.kt com um RetryInterceptor customizado no OkHttp. Caso um download falhe por instabilidade de rede ou erro temporário do servidor, o app executa até 3 tentativas com intervalo aleatório (jitter) de 300ms a 1000ms. Fotos baixadas com sucesso são gravadas em um cache em disco dedicado de 50 MB (cacheDir/image_cache), permitindo visualização offline instantânea de até ~100 fotos de 500KB.
  5. Soft Delete e Consistência Local: A exclusão de fotos executa um Soft Delete no Firebase Storage (adicionando o sufixo _DELETED ao arquivo) e atualiza incrementalmente os registros das tabelas MaintenanceActivity, OSUpdateHistory e OSFinding no Room DB local. A sincronização respeita a marcação _DELETED local, impedindo que fotos deletadas reapareçam.
  6. Registro de Falhas no Histórico de Logs (AppLogger): Todas as falhas de sincronização, erros de envio no Firebase e falhas no download de fotos (após o limite de 3 re-tentativas) são automaticamente registradas pelo AppLogger.kt na tabela AppLog do Room DB e ficam acessíveis para consulta na aba Histórico de Logs da tela de Configurações.
  7. Controle de Acesso para Usuários Sem Login: Usuários não autenticados via conta do Google têm acesso exclusivamente à visualização dos dados. Ações de edição de progresso, alteração de observações, inclusão/edição/exclusão de Achados e exclusão de fotos de campo são bloqueadas na UI e validadas no MaintenanceViewModel.kt.

Arquivos responsáveis pela conexão, sincronização e exibição de fotos:

  • com.example.MainApplication: Configura o ImageLoaderFactory do Coil, interceptor OkHttp de retries automáticos com delay aleatório (300-1000ms), cache em memória (25% RAM) e cache em disco (50MB).
  • com.example.util.AppLogger: Gerencia o registro persistente de logs de auditoria (WARN, ERROR, INFO) exibidos no painel da tela de Configurações.
  • com.example.util.ImageCompressor: Utilitário responsável pelo decodificação 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, validação de permissões de acesso 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 Auditoria das OS e Achados)

Esta aba registrará cada alteração feita em qualquer OS (avanços de progresso, observações e alterações/exclusões em Achados), permitindo auditoria detalhada de quem alterou e quando.

Nome da Coluna Tipo Sugerido Descrição / Observações
id Texto ou Número Identificador único da linha do histórico.
numeroOs Texto Código da OS atualizada.
timestamp Número Inteiro (Long) Timestamp Unix em milissegundos.
percentualAnterior Número Inteiro Progresso anterior da OS.
percentualNovo Número Inteiro Novo progresso da OS.
observacao Texto (Opcional) Detalhamento do evento, incluindo marcações auditadas como "[Achado de Segurança Criado] ...", "[Achado de Manutenção Excluído] ...".
fotoPath Texto (URL) Link da foto anexa.
responsavel Texto Nome do responsável pela ação.
email_editor Texto E-mail do usuário autenticado no Google que realizou a ação.

Tabela/Aba 3: achados (Achados de Segurança, Manutenção e Observações Ativas)

Esta aba armazena os registros ativos de Achados de Segurança, Achados de Manutenção e a Última Observação associados a cada OS.

Nome da Coluna Tipo Sugerido Descrição / Observações
id Texto (UUID) Identificador exclusivo do achado.
numeroOs Texto Código da OS relacionada.
tipo Texto Tipo do registro: "OBS", "SEGURANCA" ou "MANUTENCAO".
descricao Texto Texto descritivo do achado ou observação.
timestamp Número Inteiro (Long) Data/hora de criação ou alteração.
responsavel Texto Nome do responsável pelo registro.
email_editor Texto E-mail do editor autenticado.
fotoPath Texto (URL) Link de foto vinculada ao achado (opcional).

Nota de Exclusão Física: Quando um usuário exclui um achado ativo no app, o registro é fisicamente removido do Room e da aba achados no Google Sheets. No entanto, o evento de exclusão permanece registrado na aba history para fins de auditoria inalterável.