Files
gestao_de_manutencao/documentacao/fluxo_de_dados_e_sincronizacao.md

9.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 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 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.