Files
gestao_de_manutencao/documentacao/arquitetura/arquitetura_do_sistema.md

358 lines
25 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.
* [`DeviceAccessInfo.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/data/model/DeviceAccessInfo.kt): Estrutura de dados contendo detalhes de hardware, software, e-mail do Google SSO e timestamp do último acesso.
* [`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 (`project`, `history`, `achados`, `usage_history`).
* [`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.
* `util/` (Utilitários)
* [`DeviceUtils.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/util/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`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/util/TimeGuardManager.kt): Validador de hora do sistema e prevenção de data retroativa.
* `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.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. |
---
## 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 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`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/data/remote/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`](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.