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