301 lines
20 KiB
Markdown
301 lines
20 KiB
Markdown
# 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):**
|
|
* 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<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.
|