Files
gestao_de_manutencao/documentacao/fluxo_de_dados_e_sincronizacao.md

14 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           |   | - 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 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)

  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.