13 KiB
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 | +---------------------------+
| - sync_conflict_logs | | Firebase Storage SDK |
| - user_access | | - 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 detipo = "FOTO"na tabelaos_findingse na abaachadosdo Google Sheets. Todas as fotos daquela OS são concatenadas na colunafotoPathcom 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 do usuário da conta Google. |
nivelAcesso |
String |
- | Permissão: "ADMIN", "ENCO" (Encarregado) ou "VISUALIZADOR". |
lastUpdated |
Long |
- | Data de atualização da regra. |
3. Fluxo Completo de Salvamento de Dados
3.1. Passos no Salvamento Local (Offline-First)
-
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.
-
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).
-
Gravação Transacional no Room Database (
MaintenanceRepository.kt):maintenance_activities: Atualiza o percentual, a observação e altera o status parasynced = false.os_findings: Busca se a OS já possui um achado detipo = "FOTO".- Se existir: mescla o novo caminho com os caminhos anteriores usando
|(mergePreservingDeletedPhotos), gravasynced = falsee atualiza o registro. - Se não existir: cria um novo
OSFindingcomtipo = "FOTO",descricao = "Foto anexada"esynced = false.
- Se existir: mescla o novo caminho com os caminhos anteriores usando
os_findings(Observação): Se houver observação de texto, atualiza/cria o achado detipo = "OBS".os_update_history: Insere uma nova linha de log contendopercentualAnterior,percentualNovo,observacao,fotoPath,recursoe oemailEditor.
4. Fluxo de Sincronização Remota (Google Sheets & Firebase Storage)
4.1. Upload de Mídias ao Firebase Storage (FirebaseStorageSyncService.kt)
- Ao iniciar o sync,
uploadPendingPhotos()varre os registros de achados com arquivos locais no aparelho (/data/user/0/.../files/os_photos/OS_...jpg). - Garante o login silencioso no Firebase Auth via
ensureFirebaseAuth(). - Faz o upload seguro da imagem compactada para o bucket na nuvem (
photos/OS_{numeroOs}/OS_{numeroOs}_{timestamp}.jpg). - Obtém a
downloadUrloficial 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 normalizadophotos/OS_{numeroOs}/OS_{numeroOs}_{timestamp}.jpg.
4.2. Sincronização com o Google Sheets (GoogleSheetsSyncService.kt)
O aplicativo sincroniza com três abas da planilha central:
- Aba
project(Leitura Mestra): Carrega as ordens de serviço ativas. - Aba
history(Escrita de Auditoria): Envia novos registros da tabelaos_update_history. - Aba
achados(Sincronização Bidirecional de Achados e Fotos):- Limpa e converte caminhos de fotos locais para o formato relativo
photos/OS_.../*.jpgviacleanToStoragePath. - 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 comtipo = "FOTO"contendo todas as fotos ativas concatenadas por|.
- Limpa e converte caminhos de fotos locais para o formato relativo
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.