Files
gestao_de_manutencao/documentacao/fluxo_de_dados_e_sincronizacao.md

8.9 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 a Google Drive API v3 (GoogleDriveSyncService.kt) para upload de fotos das OSs na pasta do Google Drive 15WJIdzrykXWRSC5Xy4Ci5Cr7gq6FqMxK.

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

  1. Captura e Armazenamento Local (Offline-First): As fotos capturadas pela Câmera ou selecionadas da Galeria são armazenadas em filesDir/os_photos/ e registradas na Room DB.
  2. Upload para o Google Drive: No momento do sync, o MaintenanceRepository.kt lê as fotos pendentes e aciona o GoogleDriveSyncService.kt, que faz o upload multipart usando a Service Account drive-fotos-gestaoosparada.apikey.json para a pasta do Drive 15WJIdzrykXWRSC5Xy4Ci5Cr7gq6FqMxK.
  3. Link Público e Sincronismo com Google Sheets: O serviço define a permissão pública (anyone with link - reader) e obtém o webViewLink, atualizando a Room DB e a aba history do Google Sheets.
  4. Soft Delete: A exclusão de fotos no app não remove os arquivos fisicamente da pasta do Google Drive, mas executa uma chamada PATCH adicionando o sufixo _DELETED ao arquivo e atualiza os registros locais.

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

  • com.example.data.remote.GoogleDriveSyncService: Gerencia autenticação via Service Account, upload multipart de fotos e soft delete no Google Drive.
  • 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, 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.