diff --git a/documentacao/arquitetura/arquitetura_do_sistema.md b/documentacao/arquitetura/arquitetura_do_sistema.md new file mode 100644 index 0000000..bd674db --- /dev/null +++ b/documentacao/arquitetura/arquitetura_do_sistema.md @@ -0,0 +1,300 @@ +# Documentação de Arquitetura do Sistema: Gestão de Manutenção (Cargill 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 da Cargill. + +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/) + * [`CargillLogo.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/ui/components/CargillLogo.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 (Cargill Green, Cargill Black, 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 Cargill. + * [`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):** + * 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 da Cargill vetorial (`CargillLogo`), 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 Cargill, garantindo legibilidade e uso ideal em campo. + +* **Paleta de Cores Customizada:** + * `CargillGreen` (`#005F40`): Cor principal aplicada em botões chave, barras de título e destaques de progresso concluído. + * `CargillBlack` (`#1A1A1A`): Tom escuro predominante no fundo em modo escuro. + * `CargillLightGreen` (`#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.