# 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. ```mermaid 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/`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/) * [`MainActivity.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/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/`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/data/local/) * [`AppDatabase.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/data/local/AppDatabase.kt): Definição do banco Room e migração destrutiva para fins de teste. * [`MaintenanceDao.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/data/local/MaintenanceDao.kt): Consultas locais SQL (queries reativas com `Flow` e operações `suspend`). * [`model/`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/data/model/) * [`MaintenanceActivity.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/data/model/MaintenanceActivity.kt): Entidades Room (`MaintenanceActivity`, `OSUpdateHistory`), enumerador `ActivityStatus` e auxiliares de formatação/parsing de data. * [`remote/`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/data/remote/) * [`GoogleSheetsSyncService.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/data/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. * [`repository/`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/data/repository/) * [`MaintenanceRepository.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/data/repository/MaintenanceRepository.kt): Mediador de dados, processamento de planilhas locais (CSV) e algoritmo central de reconciliação de estado. * `ui/` (Camada de Apresentação) * [`components/`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/ui/components/) * [`AppLogo.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/ui/components/AppLogo.kt): Logotipo customizado desenhado via Canvas vetorial utilizando cores da marca. * [`screens/`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/ui/screens/) * [`MaintenanceDashboardScreen.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/ui/screens/MaintenanceDashboardScreen.kt): Tela única modularizada contendo o painel principal, listas, modais e logs de histórico. * [`theme/`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/ui/theme/) * [`Color.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/ui/theme/Color.kt): Definição de cores (BrandGreen, BrandBlack, etc.). * [`Theme.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/ui/theme/Theme.kt): Configuração do `MyApplicationTheme` (Material3) desabilitando dynamic colors para preservar a marca. * [`Type.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/ui/theme/Type.kt): Configuração tipográfica padrão. * [`viewmodel/`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/ui/viewmodel/) * [`MaintenanceViewModel.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/ui/viewmodel/MaintenanceViewModel.kt): Gerenciador de estados reativos e fábrica de injeção manual. --- ## 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](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/data/model/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.2. Entidade: `OSUpdateHistory` (Tabela: `os_update_history`) Armazena a trilha detalhada de atualizações aplicadas a cada OS. É o elemento fundamental para o sincronismo transacional. | Campo | Tipo | Chave | Descrição | | :--- | :--- | :--- | :--- | | `id` | `Long` | Primária (Auto) | Identificador sequencial do log. | | `numeroOs` | `String` | - | Relaciona o registro à OS correspondente. | | `timestamp` | `Long` | - | Data/hora exata em que o log foi registrado. | | `percentualAnterior`| `Int` | - | Progresso antes do salvamento da alteração. | | `percentualNovo` | `Int` | - | Novo progresso cadastrado pelo usuário. | | `observacao` | `String?` | - | Observação descritiva inserida no momento da atualização. | | `fotoPath` | `String?` | - | Foto de evidência vinculada a este incremento de progresso. | | `recurso` | `String` | - | Identificação do responsável que executou a modificação. | | `emailEditor` | `String?` | - | Email da conta do Google do usuário editor (auditoria). | --- ## 4. Integração Remota (Google Sheets API v4) A comunicação em nuvem é operada pelo serviço [`GoogleSheetsSyncService.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/data/remote/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`. ```kotlin 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 Google Drive (`GoogleDriveSyncService.kt`) A gestão e armazenamento de arquivos de mídia (fotos das ordens de serviço) é centralizada no Google Drive através do serviço [`GoogleDriveSyncService.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/data/remote/GoogleDriveSyncService.kt). * **Chave de Acesso:** Service Account autenticada via `app/src/main/assets/drive-fotos-gestaoosparada.apikey.json` (`fotos-gestao-os@gestaoosparada.iam.gserviceaccount.com`). * **Pasta Destino na Nuvem:** Google Drive Folder ID `15WJIdzrykXWRSC5Xy4Ci5Cr7gq6FqMxK`. * **Estratégia Offline-First & Múltiplas Fotos:** As fotos capturadas/selecionadas são salvas em armazenamento local privado (`filesDir/os_photos/`). O aplicativo suporta o anexo de **múltiplas fotos por atualização**, armazenando os caminhos/URLs concatenados pelo delimitador `|` (ex: `url1|url2|url3`), garantindo compatibilidade total com a Room DB e o Google Sheets. Durante a sincronização, o app realiza o upload multipart HTTP POST de cada foto para o Drive, ajusta as permissões do arquivo para leitura pública (`anyone with link`) e obtém as URLs diretas de visualização (`webViewLink`). * **Regra de Exclusão (Soft Delete):** A exclusão de uma foto não remove o arquivo da pasta remota no Google Drive. A API do Drive executa uma requisição `PATCH` alterando o nome do arquivo para incluir o sufixo `_DELETED` (ex: `OS_1001_1722780000_DELETED.jpg`), enquanto a aplicação remove o vínculo do registro ativo no banco de dados local e na planilha. * Guarda o log sequencial de alterações feitas por todos os inspetores. * Colunas configuradas: `id`, `numeroOs`, `timestamp`, `percentualAnterior`, `percentualNovo`, `observacao`, `fotoPath`, `responsavel`, `email_editor`. * Possui funcionalidade de **Self-Healing** (Auto-reparação): se a coluna `email_editor` não for encontrada no carregamento da planilha física, o app executa uma chamada PUT automática para inseri-la no cabeçalho na coluna correspondente. --- ## 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`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/ui/viewmodel/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. ```kotlin val filteredActivities: StateFlow> = 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.