Files
gestao_de_manutencao/documentacao/arquitetura/arquitetura_do_sistema.md

25 KiB

Documentação de Arquitetura do Sistema: Gestão de Manutenção (Gestão Parada OS)

Esta documentação descreve de forma abrangente a arquitetura de software, a estrutura de dados, o design da interface e os fluxos de sincronização do aplicativo Android de Gestão de Manutenção de Parada.

O aplicativo foi projetado sob uma filosofia offline-first para atender a técnicos e inspetores que executam suas rotinas de manutenção em áreas industriais da planta com cobertura de rede instável ou inexistente.


1. Visão Geral do Sistema e Princípios de Arquitetura

O aplicativo adota uma arquitetura inspirada nos princípios de Clean Architecture e estruturada no padrão MVVM (Model-View-ViewModel) combinado com o Repository Pattern.

Diretrizes Arquiteturais:

  1. Offline-First (Resiliência Local): Toda operação de leitura e gravação de progresso das Ordens de Serviço (OS) ocorre prioritariamente na base local do dispositivo.
  2. Única Fonte de Verdade (Single Source of Truth - SSoT): O banco de dados local Room atua como a única fonte de verdade para a camada de apresentação (UI). A UI nunca lê diretamente da rede.
  3. Desacoplamento Baseado em Estados: A interface de usuário (UI) é reativa e responde a fluxos de estado assíncronos (StateFlow da biblioteca Kotlin Coroutines) expostos pela ViewModel.
  4. Reconciliação por Event Sourcing (Transaction-based Sync): A integridade entre os dispositivos dos técnicos é garantida por meio de um log transacional descentralizado sincronizado bidirecionalmente com o Google Sheets.
graph TD
    subgraph Camada de UI (Jetpack Compose)
        A[MainActivity] --> B[MaintenanceDashboardScreen]
        B -->|Exibe Métricas| B1[DashboardMetrics]
        B -->|Filtra Lista| B2[FilterPillsRow]
        B -->|Lista Elementos| B3[OSListItemCard]
        B -->|Ações e Logs| B4[EditActivityBottomSheet]
        B -->|Importação| B5[ImporterConsoleSheet]
    end

    subgraph Camada de Negócio e Estado (ViewModel)
        C[MaintenanceViewModel]
    end

    subgraph Camada de Repositório (Repository)
        D[MaintenanceRepository]
    end

    subgraph Camada de Dados Local (Room / SQLite)
        E[AppDatabase]
        F[MaintenanceDao]
        G[(SQLite Database)]
        E --> F
        F --> G
    end

    subgraph Camada de Dados Remota (Google Sheets API)
        H[GoogleSheetsSyncService]
        I[(Planilha Google Sheets)]
    end

    B <-->|Observa Estados / Dispara Ações| C
    C <-->|Invoca Lógica de Negócio| D
    D <-->|Leitura/Escrita Local| F
    D <-->|Dispara Sincronização| H
    H <-->|Requisições HTTP REST / OAuth2| I

2. Mapa do Código Fonte (Estrutura de Pastas)

A estrutura do código fonte está localizada no pacote com.example e é organizada da seguinte maneira:

  • app/src/main/java/com/example/
    • MainActivity.kt: Classe de entrada que inicializa a base de dados, repositório, fábrica do ViewModel e renderiza a tela principal Compose.
    • data/ (Camada de Dados)
      • local/
        • AppDatabase.kt: Definição do banco Room e migração destrutiva para fins de teste.
        • MaintenanceDao.kt: Consultas locais SQL (queries reativas com Flow e operações suspend).
      • model/
        • MaintenanceActivity.kt: Entidades Room (MaintenanceActivity, OSUpdateHistory), enumerador ActivityStatus e auxiliares de formatação/parsing de data.
        • DeviceAccessInfo.kt: Estrutura de dados contendo detalhes de hardware, software, e-mail do Google SSO e timestamp do último acesso.
      • remote/
        • GoogleSheetsSyncService.kt: Serviço de integração HTTP com a API v4 do Google Sheets, englobando serialização JSON (Moshi), autenticação e mapeamento de planilhas (project, history, achados, usage_history).
      • repository/
        • MaintenanceRepository.kt: Mediador de dados, processamento de planilhas locais (CSV) e algoritmo central de reconciliação de estado.
    • util/ (Utilitários)
      • DeviceUtils.kt: Utilitário de extração de metadados do aparelho (ANDROID_ID, modelo, versão do Android e versão do app).
      • TimeGuardManager.kt: Validador de hora do sistema e prevenção de data retroativa.
    • ui/ (Camada de Apresentação)

3. Camada de Dados Local e Modelagem (Room Database)

A persistência de dados local baseia-se no Room sobre o SQLite. São mapeadas duas entidades principais em MaintenanceActivity.kt.

3.1. Entidade: MaintenanceActivity (Tabela: maintenance_activities)

Representa o estado atualizado de uma Ordem de Serviço (OS).

Campo Tipo Chave Descrição
numeroOs String Primária Código de identificação único da OS (ex: OS-1024).
descricao String - Descrição curta do serviço de manutenção.
setor String - Área física na planta (ex: UTILIDADES, CALDEIRA, REFINARIA).
equipe String - Especialidade técnica encarregada (ex: Mecânica, Elétrica, Lubrificação).
recurso String - Nome do inspetor ou técnico atualmente encarregado.
dataInicio String - Data de início prevista/real da atividade.
dataFim String - Data de término prevista da atividade.
percentualExecucao Int - Progresso de conclusão medido de 0 a 100.
observacoes String? - Último comentário ou observação adicionado à OS.
fotoPath String? - Caminho local ou URL de imagem contendo evidência fotográfica.
synced Boolean - Flag indicando se as atualizações locais foram enviadas à nuvem.
lastUpdated Long - Timestamp UNIX (milissegundos) da última modificação.
  • Propriedade Computada status (ActivityStatus): Definida dinamicamente baseando-se no percentualExecucao:
    • 0% -> ActivityStatus.NAO_INICIADO ("Não iniciado")
    • 1% a 99% -> ActivityStatus.EM_ANDAMENTO ("Em andamento")
    • 100% -> ActivityStatus.CONCLUIDO ("Concluído")

3.3. Entidade: OSFinding (Tabela: os_findings)

Armazena os achados ativos e observações vinculados a cada OS. É a fonte exclusiva para a galeria de fotos do aplicativo.

Campo Tipo Chave Descrição
id String Primária UUID único do achado.
numeroOs String Indexado Código da OS associada.
tipo String Indexado Tipo: "FOTO", "OBS", "SEGURANCA" ou "MANUTENCAO".
descricao String - Descrição técnica do achado ou "Foto anexada".
timestamp Long - Timestamp UNIX de criação/edição.
responsavel String - Nome do responsável pela inclusão.
emailEditor String? - E-mail do usuário editor no Google SSO.
fotoPath String? - Caminhos de foto concatenados por |.
synced Boolean Indexado true se sincronizado com a aba achados do Google Sheets.

Tipo Exclusivo FOTO: Registros de foto possuem tipo = "FOTO". Cada OS possui no máximo 1 linha de tipo = "FOTO" com todas as fotos ativas da OS concatenadas por |.

3.4. Entidade: AppLog (Tabela: app_logs)

Registra falhas, avisos e exceções de sistema exibidos na tela de Configurações -> Histórico de Logs de Diagnóstico.

Campo Tipo Chave Descrição
id Long Primária (Auto) ID sequencial do log.
timestamp Long - Timestamp da ocorrência.
level String - "INFO", "WARN", "ERROR".
tag String - Tag do componente de origem (ex: PhotoDisplayError).
message String - Mensagem descritiva.
stackTrace String? - Rastreamento detalhado da exceção.

3.5. Entidade: SyncConflictLog (Tabela: sync_conflict_logs)

Registra desvios e consolidações ocorridas durante a reconciliação de dados com o Google Sheets.

Campo Tipo Chave Descrição
id Long Primária (Auto) ID do log de conflito.
numeroOs String - Código da OS afetada.
timestamp Long - Timestamp UNIX da ocorrência.
fieldName String - Campo afetado (ex: percentualExecucao).
localValue String - Valor salvo no aparelho local.
remoteValue String - Valor recebido do Google Sheets.
resolvedValue String - Valor final consolidado.
resolutionStrategy String - Estratégia aplicada (ex: LWW_LOCAL_WIN).

3.6. Entidade: UserAccess (Tabela: user_access)

Gerencia o nível de acesso e permissões das contas de usuário autenticadas no aplicativo.

Campo Tipo Chave Descrição
email String Primária E-mail do usuário da conta Google.
nivelAcesso String - Permissão: "ADMIN", "ENCO" ou "VISUALIZADOR".
lastUpdated Long - Timestamp da atualização de acesso.

3.7. Entidade: AppConfig (Tabela: app_config)

Armazena configurações globais, links úteis e versão da base de dados (database_epoch) lidos da aba config da planilha online Google Sheets.

Campo Tipo Chave Descrição
key String Primária Identificador único da chave (ex: Link1, DescricaoLink1, database_epoch).
value String - Valor da chave de configuração (ex: URL ou texto).
description String? - Descrição complementar da chave de configuração.

4. Integração Remota (Google Sheets API v4)

A comunicação em nuvem é operada pelo serviço GoogleSheetsSyncService.kt.

4.1. Mecanismo de Autenticação OAuth2

O serviço usa a biblioteca oficial com.google.auth:google-auth-library-oauth2-http para gerar tokens temporários bearer. A chave de serviço JSON é resolvida dinamicamente através de dois caminhos:

  1. Configuração em Compilação: Puxada da chave de ambiente do sistema SHEETS_CREDENTIALS_JSON injetada via Secrets Gradle Plugin no BuildConfig.
  2. Fallback Local: Leitura direta de arquivo na pasta local de ativos: app/src/main/assets/chaveacesso_sheets.apikey.json.
googleCredentials = GoogleCredentials.fromStream(stream)
    .createScoped(listOf("https://www.googleapis.com/auth/spreadsheets"))

4.2. Estrutura das Planilhas de Dados (Spreadsheet ID: 1sbFovBl-RMMY6lIVdhze_ZOA9cZK01y3vPLCMWLnfpo)

O aplicativo mapeia duas abas na planilha remota:

  1. Aba project (Origem de Dados - Somente Leitura):

    • Contém as atividades macro da fábrica exportadas do software de planejamento (ex: MS Project).
    • O aplicativo extrai a hierarquia de tópicos (coluna Estrutura de Tópicos) analisando níveis numéricos (ex: 1.1, 1.1.1).
    • Identificação de Setor: Obtém o nome do setor a partir do título do nível imediatamente superior ou principal ("grandparent outline").
    • Identificação de Nós Folha: Apenas linhas finais da hierarquia (que não são pai de nenhuma outra) são mapeadas como tarefas/OSs executáveis.
    • Filtro de Resumo: Ignora linhas cujo valor na coluna resumo seja diferente de "não" (garantindo a exclusão de tarefas puramente administrativas/agrupadoras).
  2. Aba history (Log de Transações - Leitura/Escrita):

    • Registra auditavelmente cada modificação efetuada por usuários (progresso, observação, foto, responsável e email).

4.3. Integração com o Firebase Storage (FirebaseStorageSyncService.kt)

A gestão e armazenamento de arquivos de mídia (fotos das ordens de serviço) é centralizada no Firebase Storage através do serviço FirebaseStorageSyncService.kt.

  • Projeto e Bucket Firebase: gestao-parada-os.firebasestorage.app (autenticado com Google Sign-in / Firebase SDK).
  • Pasta Destino na Nuvem: Diretórios organizados por OS (photos/OS_{numeroOs}/).
  • Processamento, HEIC e Compressão (ImageCompressor.kt): Fotos capturadas pela câmera ou selecionadas da galeria (incluindo o formato HEIC/HEIF) passam pelo ImageCompressor.kt. O app decodifica a imagem, corrige a orientação EXIF, limita a resolução para até 1920x1920 px e compacta iterativamente para garantir tamanho final <= 500 KB por foto antes do armazenamento local e upload.
  • Estratégia Offline-First, Múltiplas Fotos & Envio Único: As fotos são salvas em armazenamento local privado (filesDir/os_photos/). O aplicativo suporta o anexo de múltiplas fotos por atualização, concatenadas pelo delimitador | (ex: url1|url2|url3). Durante a sincronização, o app realiza o upload assíncrono para o Firebase Storage e obtém a URL pública de download (downloadUrl). Fotos que já possuem URL remota são ignoradas, evitando reenvios duplicados.
  • Regra de Exclusão (Soft Delete): A exclusão de uma foto executa um Soft Delete no Firebase Storage, renomeando o arquivo na mesma pasta para incluir o sufixo _DELETED (ex: OS_1001_1722780000_DELETED.jpg), mantendo a rastreabilidade enquanto atualiza os registros da aplicação.

4.4. Sistema de Registro e Histórico de Logs (AppLogger.kt)

O aplicativo dispõe de um subsistema de auditoria e diagnóstico local para registro de falhas, erros de rede, problemas no Google Drive/Sheets e avisos de sincronização:

  • Tabela Room DB (app_logs): Armazena os eventos com timestamp, level (ERROR, WARN, INFO), tag, message e stackTrace.
  • Utilitário AppLogger.kt: Gerencia a gravação assíncrona thread-safe no banco local e emissão no Logcat.
  • Interface de Diagnóstico (SettingsScreen.kt): Botão "Histórico de Logs" exibe os logs em um modal dialog envolvido por SelectionContainer do Jetpack Compose, permitindo a seleção e cópia de textos pelo usuário.

5. Fluxo de Dados e Algoritmo de Sincronização

A sincronização de dados adota uma variação simplificada de Event Sourcing, onde o estado final de um objeto é derivado a partir da soma histórica de suas transações.

       [Google Sheets]                        [App Local (Room)]
       
       Aba "project" 
    (Lista Mestra de OS)
             |
             | 1. Download OSs
             v
     [Mapeador de Folhas] 
  (Extrai Setores/Equipes)
             |
             +-----------------------+
                                     |
                                     v
       Aba "history" ----------> [Mesclagem de Históricos] <--------- Tabela Local
   (Histórico de Transações)    (Dedup por OS + Timestamp)          "os_update_history"
                                     |
                                     | 2. Determina maior progresso por OS
                                     v
                           [Atualiza atividades Room]
                                     |
                                     | 3. Insere logs ausentes localmente
                                     v
                               [Tabela Local]
                                     |
                                     | 4. Envia logs pendentes locais
                                     v
                               Aba "history"

Algoritmo Detalhado de Reconciliação (synchronizeWithBackend):

  1. Download do Escopo: O repositório baixa a lista mestra de OSs brutas da aba project através do serviço sheets.
  2. Download das Transações Globais: Baixa a totalidade dos logs registrados na aba history.
  3. Leitura das Transações Locais: Carrega todos os logs de os_update_history salvos localmente na base SQLite.
  4. Mesclagem e Eliminação de Duplicidades:
    • Une ambas as listas de logs (remotos + locais).
    • Aplica uma cláusula de distinção (distinctBy) utilizando a chave composta "${numeroOs}_${timestamp}".
    • Ordena todos os logs de forma decrescente com base no timestamp.
  5. Reconstrução do Estado da Atividade:
    • Para cada OS identificada no download da aba project, o repositório busca seu histórico filtrado na lista consolidada de logs.
    • Como a lista está ordenada do mais recente para o mais antigo, o primeiro log correspondente define o estado final da OS (determinando percentualExecucao, observacoes, fotoPath e o timestamp da última atualização lastUpdated).
    • Se não houver nenhum log correspondente, a OS assume valores padrão (percentualExecucao = 0).
  6. Atualização da Base Local (Room):
    • Limpa a tabela local de atividades (clearAllActivities()) para remover quaisquer OSs excluídas do escopo do planejamento central.
    • Insere o lote de atividades reconciliadas e reconstruídas (insertActivities()).
    • Salva na tabela local os_update_history quaisquer logs baixados da nuvem que ainda não existiam localmente.
  7. Envio de Atualizações Offline:
    • Filtra todos os logs locais que não existiam na lista de logs baixada do Sheets.
    • Dispara um envio em lote (pushHistoryToSheet()) para anexar essas linhas na aba history do Google Sheets, alterando localmente o status de sincronização das OSs correspondentes para synced = true.

6. Lógica de Importação de Planilhas Locais (CSV)

O aplicativo permite a carga offline direta de dados por meio da importação de arquivos CSV formatados (geralmente gerados a partir do Excel).

  • Detecção Dinâmica de Delimitador: O repositório analisa a primeira linha do arquivo e define se o separador estrutural é ponto e vírgula (;) ou vírgula (,).
  • Mapeamento de Cabeçalhos por Palavras-Chave (Case-Insensitive):
    • OS: Procura por "os", "numero", "número".
    • Descrição: Procura por "desc", "atividade", "ação".
    • Setor: Procura por "setor", "area", "área".
    • Equipe: Procura por "equipe", "eq", "disc", "tipo".
    • Responsável: Procura por "resp", "encarregado", "dono".
    • Início: Procura por "inicio", "início", "start".
    • Fim: Procura por "fim", "end", "termino", "término".
    • Progresso (%): Procura por "pct", "%", "percent", "exec".
  • Saneamento de Dados (Sanitization):
    • Filtra e remove aspas extras (").
    • Converte e limpa percentuais, interpretando valores textuais.
    • Padroniza os nomes de setores e equipes (ex: converte variações de escrita para termos padrão como Preparação, Extração, Caldeira, Mecânica, Elétrica).

7. Camada de Apresentação e Estado (UI & Jetpack Compose)

A camada visual é baseada em componentes reativos do Jetpack Compose e gerenciada pelo MaintenanceViewModel.kt.

7.1. Fluxos de Estado na ViewModel

A ViewModel consolida entradas de múltiplos canais para gerar fluxos reativos finais para a tela:

  • _selectedSetor, _selectedEquipe, _selectedStatus, _selectedDataInicio, _selectedRecurso: Controlam filtros ativos de pílulas.
  • _searchQuery: String de busca em tempo real digitada pelo usuário.
  • filteredActivities: Um StateFlow unificado construído usando o operador combine que reavalia a filtragem da lista local sempre que qualquer filtro ou a barra de busca é alterada.
val filteredActivities: StateFlow<List<MaintenanceActivity>> = combine(
    repository.allActivities,
    _selectedSetor,
    _selectedEquipe,
    _selectedStatus,
    _selectedDataInicio,
    _selectedRecurso,
    _searchQuery
) { ... }

7.2. Principais Composables da Tela

  1. MaintenanceDashboardScreen (Tela Central):
    • Configura o Scaffold principal com uma barra superior contendo o logotipo vetorial (AppLogo), status da conexão, botão de sincronização (SyncNow), dados do usuário autenticado e ferramenta de busca.
  2. DashboardMetrics (Painel de Indicadores):
    • Exibe cartões informativos atualizados dinamicamente: Total de OS, OS Não Iniciadas, Em Andamento e Concluídas.
  3. FilterPillsRow (Filtros Avançados):
    • Exibe fileiras horizontais de chips roláveis para aplicar filtros com contadores numéricos dinâmicos para cada categoria.
  4. OSListItemCard (Cartão da OS):
    • Renderiza detalhes essenciais de cada atividade de manutenção.
    • Apresenta uma barra de progresso colorida baseada no percentual de conclusão.
    • Mostra um ícone de nuvem que muda de cor (verde para sincronizado, laranja com exclamação para alterações pendentes offline).
  5. EditActivityBottomSheet (Modal de Edição):
    • Permite que o técnico configure o progresso atual através de um slider, digite observações, insira evidências e confirme sua identidade.
    • Contém a linha do tempo (Timeline) que exibe cronologicamente cada transação obtida via selectedActivityHistory.
  6. ImporterConsoleSheet (Console de Importação):
    • Modal utilitário para disparar importações CSV externas e repopular a base de dados com dados de teste/demonstração.

8. Decisões de Design de UI e Identidade Visual (Design System)

A interface de usuário foi desenhada de forma a respeitar a identidade corporativa da marca, garantindo legibilidade e uso ideal em campo.

  • Paleta de Cores Customizada:
    • BrandGreen (#005F40): Cor principal aplicada em botões chave, barras de título e destaques de progresso concluído.
    • BrandBlack (#1A1A1A): Tom escuro predominante no fundo em modo escuro.
    • BrandLightGreen (#E8F5E9): Utilizado como cor de fundo para badges e indicadores secundários.
    • LightGrey (#F5F7F6): Fundo claro suave para o modo diurno.
  • Componentes Premium M3:
    • Uso de Glassmorphism sutil nos diálogos e cartões de lista.
    • Transições suaves de recolhimento de modais.
    • Feedback tátil visual em cliques de botões (ripple effect customizado).
    • Layout responsivo que reorganiza colunas e métricas caso o aplicativo seja visualizado em modo paisagem ou tablets.