# Documentação do Fluxo de Dados, Salvamento e Sincronização Esta documentação detalha a arquitetura **offline-first**, a estrutura completa da base de dados local (Room SQLite) e remota (Google Sheets / Firebase Storage), além do fluxo detalhado de salvamento de informações e download de mídias sob demanda. --- ## 1. Visão Geral da Arquitetura de Dados O aplicativo adota o padrão **MVVM (Model-View-ViewModel)** com **Repository Pattern** e filosofia **Offline-First**: ``` +-------------------------------------------------------+ | UI (Jetpack Compose) | | - MaintenanceDashboardScreen | | - EditActivityBottomSheet (Modal da OS) | +--------------------------+----------------------------+ | Observa StateFlow / Dispara Ações v +-------------------------------------------------------+ | MaintenanceViewModel | | - Gerencia estados da interface e busca | | - Valida níveis de acesso (Google SSO) | +--------------------------+----------------------------+ | Executa Lógica de Negócio v +-------------------------------------------------------+ | MaintenanceRepository | | - Fonte Única de Verdade (Single Source of Truth) | | - Orquestra gravação local e sync com nuvem | +-------------------+-------------------+---------------+ | | Gravação | | Sincronização Local v v Remota +-----------------------+ +---------------------------+ | Room DB (SQLite) | | Google Sheets API v4 | | - maintenance_activities | - Aba 'project' (Leitura) | | - os_update_history | | - Aba 'history' (Audit) | | - os_findings | | - Aba 'achados' (Linhas) | | - app_logs | | - Aba 'usage_history' (Rastreamento)| | - sync_conflict_logs | +---------------------------+ | - user_access | | Firebase Storage SDK | +-----------------------+ | - Bucket de fotos / mídias| +---------------------------+ ``` --- ## 2. Estrutura Completa da Base de Dados O aplicativo utiliza o **Room Database** (`AppDatabase.kt`) sobre o SQLite interno no dispositivo (`/data/data/com.example/databases/maintenance_db`). A estrutura engloba 6 tabelas principais: ### 2.1. Tabela: `maintenance_activities` (Ordens de Serviço Ativas) Armazena a lista principal das Ordens de Serviço (OS) de manutenção da planta. | Campo | Tipo | Chave | Descrição / Regras | | :--- | :--- | :--- | :--- | | **`numeroOs`** | `String` | Primária | Código de identificação único da OS (ex: `OS-1503`). | | **`descricao`** | `String` | - | Descrição técnica do trabalho de manutenção. | | **`setor`** | `String` | - | Setor industrial da fábrica (ex: `EXTRAÇÃO`, `CALDEIRA`). | | **`equipe`** | `String` | - | Disciplina responsável (ex: `Mecânica`, `Elétrica`). | | **`recurso`** | `String` | - | Nome do inspetor ou encarregado atual. | | **`dataInicio`** | `String` | - | Data planejada/real de início (ex: `01/07/2026`). | | **`dataFim`** | `String` | - | Data planejada de conclusão. | | **`percentualExecucao`** | `Int` | - | Progresso medido de `0` a `100`%. | | **`observacoes`** | `String?` | - | Texto do comentário ou observação mais recente. | | **`fotoPath`** | `String?` | - | Evidência fotográfica vinculada à atividade. | | **`synced`** | `Boolean` | - | `true` se sincronizado com Google Sheets, `false` se pendente. | | **`lastUpdated`** | `Long` | - | Timestamp UNIX (milissegundos) da última edição. | --- ### 2.2. Tabela: `os_findings` (Achados, Fotos e Observações) Armazena os achados ativos associados a cada OS. É a **fonte exclusiva da galeria de fotos** do aplicativo. | Campo | Tipo | Chave | Descrição / Regras | | :--- | :--- | :--- | :--- | | **`id`** | `String` | Primária | Identificador único (UUID). | | **`numeroOs`** | `String` | Indexado | Código da OS relacionada. | | **`tipo`** | `String` | Indexado | Tipo do registro: `"FOTO"`, `"OBS"`, `"SEGURANCA"` ou `"MANUTENCAO"`. | | **`descricao`** | `String` | - | Descrição do achado ou `"Foto anexada"`. | | **`timestamp`** | `Long` | - | Timestamp UNIX da criação/edição. | | **`responsavel`** | `String` | - | Nome do responsável pela gravação. | | **`emailEditor`** | `String?` | - | E-mail da conta do Google do editor. | | **`fotoPath`** | `String?` | - | Caminhos de fotos relativos ou locais concatenados por `\|`. | | **`synced`** | `Boolean` | Indexado | Status de sincronização com a aba `achados` no Google Sheets. | > **Regra do Tipo Exclusivo `FOTO`**: Cada OS possui no máximo **1 registro ativo** de `tipo = "FOTO"` na tabela `os_findings` e na aba `achados` do Google Sheets. Todas as fotos daquela OS são concatenadas na coluna `fotoPath` com o caractere `|` (ex: `photos/OS_OS-1136/photo1.jpg|photos/OS_OS-1136/photo2.jpg`). --- ### 2.3. Tabela: `os_update_history` (Log de Transações de Auditoria) Registra o histórico cronológico de cada atualização efetuada por usuários em uma OS. | Campo | Tipo | Chave | Descrição / Regras | | :--- | :--- | :--- | :--- | | **`id`** | `Long` | Primária (Auto) | Identificador sequencial do log. | | **`numeroOs`** | `String` | - | Código da OS alterada. | | **`timestamp`** | `Long` | - | Data/hora exata em milissegundos. | | **`percentualAnterior`** | `Int` | - | Progresso antes da edição. | | **`percentualNovo`** | `Int` | - | Progresso informado pelo usuário. | | **`observacao`** | `String?` | - | Texto da observação ou tag de auditoria. | | **`fotoPath`** | `String?` | - | Fotos anexadas nesta atualização. | | **`recurso`** | `String` | - | Responsável pela ação. | | **`emailEditor`** | `String?` | - | E-mail do usuário autenticado no Google. | --- ### 2.4. Tabela: `app_logs` (Histórico de Diagnostic Log) Armazena registros de log e exceções de sistema exibidos na tela de **Configurações -> Histórico de Logs de Diagnóstico**. | Campo | Tipo | Chave | Descrição / Regras | | :--- | :--- | :--- | :--- | | **`id`** | `Long` | Primária (Auto) | ID do log. | | **`timestamp`** | `Long` | - | Data/hora da ocorrência. | | **`level`** | `String` | - | Nível de severidade: `"INFO"`, `"WARN"`, `"ERROR"`. | | **`tag`** | `String` | - | Tag de origem (ex: `PhotoDisplayError`, `FirebaseStorageSync`). | | **`message`** | `String` | - | Mensagem descritiva da falha ou evento. | | **`stackTrace`** | `String?` | - | Rastreamento da pilha de exceções em falhas. | --- ### 2.5. Tabela: `sync_conflict_logs` (Histórico de Conflitos de Sincronização) Registra eventos de desvio ou resolução de conflitos ocorridos na sincronização com o Sheets. | Campo | Tipo | Chave | Descrição | | :--- | :--- | :--- | :--- | | **`id`** | `Long` | Primária (Auto) | ID do evento de conflito. | | **`numeroOs`** | `String` | - | OS afetada. | | **`timestamp`** | `Long` | - | Timestamp da ocorrência. | | **`fieldName`** | `String` | - | Campo afetado (ex: `percentualExecucao`). | | **`localValue`** | `String` | - | Valor salvo no dispositivo. | | **`remoteValue`** | `String` | - | Valor recebido do Google Sheets. | | **`resolvedValue`**| `String` | - | Valor consolidado aplicado. | | **`resolutionStrategy`** | `String` | - | Estratégia de resolução (ex: `LWW_LOCAL_WIN`). | --- ### 2.6. Tabela: `user_access` (Controle de Acesso de Usuários) Armazena o nível de permissão associado aos e-mails cadastrados. | Campo | Tipo | Chave | Descrição | | :--- | :--- | :--- | :--- | | **`email`** | `String` | Primária | E-mail da conta Google. | | **`nivelAcesso`** | `String` | - | Nível de acesso: `"ADMIN"`, `"ENCO"` ou `"VISUALIZADOR"`. | | **`lastUpdated`** | `Long` | - | Timestamp da atualização de acesso. | --- ### 2.7. Tabela: `app_config` (Configurações, Links Úteis e Responsáveis) Armazena as configurações dinâmicas e links sincronizados da aba `config` da planilha online Google Sheets exibidos na Tela de Informações Importantes (`ImportantInfoScreen.kt`). | Campo | Tipo | Chave | Descrição / Regras | | :--- | :--- | :--- | :--- | | **`key`** | `String` | Primária | Chave de configuração (ex: `Link1`, `DescricaoLink1`, `Link4`, `DescricaoLink4`, `database_epoch`, `VersaoMinimaApp`, `PararAcessoApp`). | | **`value`** | `String` | - | Valor associado à chave (ex: URL, versão mínima ou flag `0`/`1`). | | **`description`** | `String?` | - | Descrição informativa da chave lida da coluna C (`descricao`). | > **Regra do 4º Link Condicional e Responsáveis**: > - Links 1, 2 e 3 possuem valores padrão de fallback na interface. > - O **4º link** (`Link4` e `DescricaoLink4`) é exibido **apenas se a chave e seu valor forem encontrados** na planilha online. Caso ausente ou em branco, permanece oculto. > - A Tela de Informações exibe a mensagem de status `"Sincronizado com o BD online"` e inclui um card fixo de **Responsáveis pelo Aplicativo** (Desenvolvedor: `cesarjhony+dev@gmail.com` e Responsável: `gabrielpizzinatto123@gmail.com`). > **Regras de Trava de Segurança e Bloqueio (`VersaoMinimaApp` e `PararAcessoApp`)**: > - `VersaoMinimaApp` (ex: `1.0.0`): Se a versão do aplicativo for estritamente inferior ao valor desta chave, o app exibe uma tela de bloqueio não minimizável (Full-Screen Overlay Modal) com a mensagem: *"Versão do app incompativel, você deve atualizar o app para continuar usando, procure o responsável e o desenvolvedor"*. > - `PararAcessoApp` (ex: `0` = liberado, `1` = bloqueado): Se esta chave for `1`, o app exibe uma tela de bloqueio não minimizável com a mensagem: *"App fora de operação, entrar em contato com o responsável e o desenvolvedor"*. > - Ambas as travas exibem os e-mails dos responsáveis com botões de ação para abrir o cliente de e-mail ou copiar o endereço, e **bloqueiam qualquer tentativa de sincronização ou leitura de dados**. --- ## 3. Fluxo Completo de Salvamento de Dados ### 3.1. Passos no Salvamento Local (Offline-First) 1. **Edição do Usuário na Interface (`EditActivityBottomSheet`)**: - O usuário seleciona o progresso de execução (0-100%), edita observações e captura/anexa novas fotos na galeria da OS. - Aciona o botão **Salvar Atualizações**. 2. **Processamento e Compactação de Fotos (`ImageCompressor.kt`)**: - As fotos capturadas pela câmera ou selecionadas da galeria (formatos JPEG, PNG, HEIC/HEIF) são processadas. - O aplicativo decodifica a foto, corrige a rotação baseando-se nos metadados EXIF, redimensiona se maior que 1920x1920 px e compacta com garantia de tamanho final **<= 500 KB**. - A foto é salva no armazenamento interno do aplicativo (`filesDir/os_photos/OS_{numeroOs}_{timestamp}.jpg`). 3. **Gravação Transacional no Room Database (`MaintenanceRepository.kt`)**: - **`maintenance_activities`**: Atualiza o percentual, a observação e altera o status para `synced = false`. - **`os_findings`**: Busca se a OS já possui um achado de `tipo = "FOTO"`. - Se existir: mescla o novo caminho com os caminhos anteriores usando `|` (`mergePreservingDeletedPhotos`), grava `synced = false` e atualiza o registro. - Se não existir: cria um novo `OSFinding` com `tipo = "FOTO"`, `descricao = "Foto anexada"` e `synced = false`. - **`os_findings` (Observação)**: Se houver observação de texto, atualiza/cria o achado de `tipo = "OBS"`. - **`os_update_history`**: Insere uma nova linha de log contendo `percentualAnterior`, `percentualNovo`, `observacao`, `fotoPath`, `recurso` e o `emailEditor`. --- ## 4. Fluxo de Sincronização Remota (Google Sheets & Firebase Storage) ### 4.1. Upload de Mídias ao Firebase Storage (`FirebaseStorageSyncService.kt`) 1. Ao iniciar o sync, `uploadPendingPhotos()` varre os registros de achados com arquivos locais no aparelho (`/data/user/0/.../files/os_photos/OS_...jpg`). 2. Garante o login silencioso no Firebase Auth via `ensureFirebaseAuth()`. 3. Faz o upload seguro da imagem compactada para o bucket na nuvem (`photos/OS_{numeroOs}/OS_{numeroOs}_{timestamp}.jpg`). 4. Obtém a `downloadUrl` oficial contendo o token de acesso (`?alt=media&token=...`), salva em cache de memória (`downloadUrlCache`), e converte o caminho da foto no banco local para o formato relativo normalizado `photos/OS_{numeroOs}/OS_{numeroOs}_{timestamp}.jpg`. ### 4.2. Sincronização com o Google Sheets (`GoogleSheetsSyncService.kt`) O aplicativo sincroniza com quatro abas da planilha central: 1. **Aba `project` (Leitura Mestra)**: Carrega as ordens de serviço ativas. 2. **Aba `history` (Escrita de Auditoria)**: Envia novos registros da tabela `os_update_history`. 3. **Aba `achados` (Sincronização Bidirecional de Achados e Fotos)**: - Limpa e converte caminhos de fotos locais para o formato relativo `photos/OS_.../*.jpg` via `cleanToStoragePath`. - Reconcilia achados remotos e locais preservando alterações pendentes (`synced = false`). - Agrupa e consolida os registros por `(numeroOs, tipo)` para garantir **no máximo 1 linha por OS com `tipo = "FOTO"`** contendo todas as fotos ativas concatenadas por `|`. 4. **Aba `usage_history` (Rastreamento do Último Acesso por Dispositivo)**: - Garante que a aba contenha os cabeçalhos: `device_id`, `dispositivo`, `email`, `nome_usuario`, `versao_android`, `versao_app`, `ultimo_acesso`, `status_sincronizacao`. - Executa **Upsert**: localiza a linha do dispositivo através do `device_id` (`Settings.Secure.ANDROID_ID` ou UUID). Se já existir, atualiza os dados e o timestamp do último acesso; se for um aparelho novo, cria uma nova linha na planilha. - Permite auditoria em tempo real de quantos e quais celulares acessaram o app online e qual conta do Google Sign-In foi utilizada. --- ## 5. Download e Exibição de Fotos Sob Demanda (On-Demand Loading) Para evitar consumo desnecessário de dados móveis e garantir o carregamento correto em múltiplos dispositivos ou após a limpeza de dados do aplicativo: ``` [UI / Galeria de Fotos da OS] | v [rememberResolvedPhotoModel(photoPath)] | +---> Arquivo existe em 'filesDir/os_photos/'? | | | +--> (SIM) --> Carrega do disco local instantaneamente | | | +--> (NÃO) --> Dispara download SOB DEMANDA via Coroutine | | | v | [syncService.downloadPhotoFile(path)] | | | v | [ensureFirebaseAuth()] | | | v | [storageRef.getFile(localFile).await()] | | | v | [Salva em filesDir/os_photos/OS_...jpg] | | | v +<----------------------------+ | v [Coil renderiza imagem local sem erro HTTP 403] ``` ### Principais Benefícios do Download Sob Demanda: - **Zero consumo desnecessário**: Fotos só são baixadas quando o usuário realmente abre a galeria da OS. - **Suporte Múltiplos Celulares**: O segundo celular baixa nativamente a foto via SDK do Firebase Storage e salva no armazenamento local. - **Resiliência e 100% Offline**: Após visualizada uma vez, a foto fica armazenada no disco local do aparelho, permitindo acesso offline em áreas sem cobertura de rede na fábrica. - **Eliminação de Erros HTTP 403**: Ao ler a imagem direto do disco local, elimina-se qualquer rejeição de acesso por falta de token nas requisições HTTP REST.