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:
- Camada de UI (Jetpack Compose): A tela
MaintenanceDashboardScreen.ktreage às mudanças de estado expostas peloMaintenanceViewModel.kt. - ViewModel (
MaintenanceViewModel.kt): Gerencia o fluxo de estados (UI State) utilizandoStateFlowe lida com ações do usuário (filtragem, atualização de progresso, importação de CSV, disparo de sincronização). - 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). - 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?
- 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 emfilesDir/os_photos/e registrado no Room DB. - Upload Único para o Firebase Storage: Durante a sincronização, o
MaintenanceRepository.ktlê as fotos pendentes locais e aciona oFirebaseStorageSyncService.kt. Fotos que já possuem URL remota (http://ouhttps://) 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 pastaphotos/OS_{numeroOs}/. - URL de Download e Sincronismo com Google Sheets: O serviço obtém a
downloadUrldo 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 abahistorydo Google Sheets. - 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.ktcom umRetryInterceptorcustomizado 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. - Soft Delete e Consistência Local: A exclusão de fotos executa um Soft Delete no Firebase Storage (adicionando o sufixo
_DELETEDao arquivo) e atualiza incrementalmente os registros das tabelasMaintenanceActivity,OSUpdateHistoryeOSFindingno Room DB local. A sincronização respeita a marcação_DELETEDlocal, impedindo que fotos deletadas reapareçam. - 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 peloAppLogger.ktna tabelaAppLogdo Room DB e ficam acessíveis para consulta na aba Histórico de Logs da tela de Configurações. - 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 oImageLoaderFactorydo 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
achadosno Google Sheets. No entanto, o evento de exclusão permanece registrado na abahistorypara fins de auditoria inalterável.