24 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:
- 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.
- Ú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.
- Desacoplamento Baseado em Estados: A interface de usuário (UI) é reativa e responde a fluxos de estado assíncronos (
StateFlowda biblioteca Kotlin Coroutines) expostos pela ViewModel. - 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 comFlowe operaçõessuspend).
model/MaintenanceActivity.kt: Entidades Room (MaintenanceActivity,OSUpdateHistory), enumeradorActivityStatuse auxiliares de formatação/parsing de 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/MaintenanceRepository.kt: Mediador de dados, processamento de planilhas locais (CSV) e algoritmo central de reconciliação de estado.
ui/(Camada de Apresentação)components/AppLogo.kt: Logotipo customizado desenhado via Canvas vetorial utilizando cores da marca.
screens/MaintenanceDashboardScreen.kt: Tela única modularizada contendo o painel principal, listas, modais e logs de histórico.
theme/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.
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 nopercentualExecucao:0%->ActivityStatus.NAO_INICIADO("Não iniciado")1%a99%->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 detipo = "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. |
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:
- Configuração em Compilação: Puxada da chave de ambiente do sistema
SHEETS_CREDENTIALS_JSONinjetada via Secrets Gradle Plugin noBuildConfig. - 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:
-
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
resumoseja diferente de "não" (garantindo a exclusão de tarefas puramente administrativas/agrupadoras).
-
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 peloImageCompressor.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 comtimestamp,level(ERROR,WARN,INFO),tag,messageestackTrace. - 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 porSelectionContainerdo 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):
- Download do Escopo: O repositório baixa a lista mestra de OSs brutas da aba
projectatravés do serviço sheets. - Download das Transações Globais: Baixa a totalidade dos logs registrados na aba
history. - Leitura das Transações Locais: Carrega todos os logs de
os_update_historysalvos localmente na base SQLite. - 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.
- 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,fotoPathe o timestamp da última atualizaçãolastUpdated). - Se não houver nenhum log correspondente, a OS assume valores padrão (
percentualExecucao = 0).
- Para cada OS identificada no download da aba
- 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_historyquaisquer logs baixados da nuvem que ainda não existiam localmente.
- Limpa a tabela local de atividades (
- 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 abahistorydo Google Sheets, alterando localmente o status de sincronização das OSs correspondentes parasynced = 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).
- Filtra e remove aspas extras (
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: UmStateFlowunificado construído usando o operadorcombineque 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
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.
- Configura o Scaffold principal com uma barra superior contendo o logotipo vetorial (
DashboardMetrics(Painel de Indicadores):- Exibe cartões informativos atualizados dinamicamente: Total de OS, OS Não Iniciadas, Em Andamento e Concluídas.
FilterPillsRow(Filtros Avançados):- Exibe fileiras horizontais de chips roláveis para aplicar filtros com contadores numéricos dinâmicos para cada categoria.
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).
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.
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.