From 730fb15ff356a21cd699836abc2dab0399df0d87 Mon Sep 17 00:00:00 2001 From: Jhony Cesar Date: Mon, 27 Jul 2026 18:04:44 -0400 Subject: [PATCH] docs: add technical documentation for simulated and truncated features --- .../recursos_simulados_e_truncados.md | 97 +++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 documentacao/recursos_simulados_e_truncados.md diff --git a/documentacao/recursos_simulados_e_truncados.md b/documentacao/recursos_simulados_e_truncados.md new file mode 100644 index 0000000..1e31021 --- /dev/null +++ b/documentacao/recursos_simulados_e_truncados.md @@ -0,0 +1,97 @@ +# Listagem de Recursos Simulados e Truncados + +Durante a análise técnica do código fonte do aplicativo de Gestão de Manutenção de Parada da Cargill, foram identificados recursos que possuem comportamento simulado (mockado) ou que foram implementados de forma parcial/truncada (stubs ou no-ops). + +Abaixo está o levantamento detalhado de cada um desses elementos, com suas respectivas localizações de arquivos e descrições técnicas. + +--- + +## 1. Captura e Anexo de Fotos de Campo (Simulador de Câmera) + +* **Status:** **Simulado (Mockado)** +* **Arquivos Relacionados:** + * [`MaintenanceDashboardScreen.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/ui/screens/MaintenanceDashboardScreen.kt) (linhas ~1038-1044 e ~1205-1238) + * [`MaintenanceActivity.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/data/model/MaintenanceActivity.kt) (campo `fotoPath`) +* **Descrição Técnica:** + O aplicativo não possui integração real com as APIs de hardware de câmera do Android (como `CameraX` ou `Camera2`) nem abre um seletor de arquivos de imagens (Intent de galeria). + Em vez disso, no modal de atualização de progresso (`EditActivityBottomSheet`), exibe-se uma lista horizontal (`LazyRow`) contendo quatro categorias pré-definidas de imagem fictícia: + * *"Turbina"* -> registra o caminho `"ic_turbine_mock"` + * *"Fiação Elétrica"* -> registra o caminho `"ic_electrical_mock"` + * *"Mancal Engraxado"* -> registra o caminho `"ic_gear_mock"` + * *"Caldeira Lavada"* -> registra o caminho `"ic_boiler_mock"` +* **Impacto/Limitação:** O aplicativo apenas salva caminhos de strings estáticas no banco SQLite local (Room) e sincroniza este texto na aba `history` do Google Sheets, sem de fato capturar ou fazer upload de arquivos de imagem binários. + +--- + +## 2. Controle e Simulação de Conectividade de Rede + +* **Status:** **Truncado (No-op / Hardcoded)** +* **Arquivos Relacionados:** + * [`MaintenanceViewModel.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/ui/viewmodel/MaintenanceViewModel.kt) (linhas ~63 e ~204-207) + * [`MaintenanceDashboardScreen.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/ui/screens/MaintenanceDashboardScreen.kt) (linhas ~81 e ~215-224) +* **Descrição Técnica:** + A ViewModel possui uma flag interna `internetAvailable` baseada em `MutableStateFlow` e expõe um método chamado `toggleInternet(available: Boolean)`. No entanto: + * O estado de inicialização é fixado em `true`. + * O método `toggleInternet(...)` força o estado de volta para `true` de maneira incondicional: + ```kotlin + fun toggleInternet(available: Boolean) { + // App is always online. + _internetAvailable.value = true + } + ``` + * Não há integração com o `ConnectivityManager` do Android para ouvir de forma dinâmica o estado real da rede móvel ou Wi-Fi do aparelho. +* **Impacto/Limitação:** O recurso de simulação de queda de rede (modo offline planejado para controle em tela) está desativado. O aplicativo sempre assume que está online, e o ícone de nuvem na barra superior permanece constantemente em modo "Conectado/Nuvem Verde". + +--- + +## 3. Escrita de Ordens de Serviço Mestre na Planilha (`project`) + +* **Status:** **Truncado (No-op)** +* **Arquivos Relacionados:** + * [`GoogleSheetsSyncService.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/data/remote/GoogleSheetsSyncService.kt) (linhas ~576-582) +* **Descrição Técnica:** + A função `pushActivitiesToSheet` é responsável por sincronizar novas OSs criadas ou importadas localmente de volta para a aba principal da planilha remota. No entanto, ela foi intencionalmente esvaziada (tornando-se um método sem ação/no-op): + ```kotlin + fun pushActivitiesToSheet( + toUpdateRemote: List>, + toAppendRemote: List + ) { + // No-op to respect read-only project sheets requirement + } + ``` +* **Impacto/Limitação:** Caso o usuário importe novas ordens de serviço via planilha CSV local, essas OSs ficarão restritas ao banco de dados do dispositivo móvel local. O aplicativo não tentará escrevê-las na aba `project` no Google Sheets, respeitando a regra de que a aba mestre de projetos é de leitura exclusiva do aplicativo. + +--- + +## 4. Contador de Conflitos na Sincronização + +* **Status:** **Truncado (Simplificado)** +* **Arquivos Relacionados:** + * [`MaintenanceRepository.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/data/repository/MaintenanceRepository.kt) (linhas ~278-281) +* **Descrição Técnica:** + Durante a finalização do sincronismo bidirecional, a resposta de sucesso (`SyncResult.Success`) retorna as métricas de itens sincronizados e conflitos resolvidos. No entanto, o valor de conflitos resolvidos é fixado estaticamente em `0`: + ```kotlin + SyncResult.Success( + syncedItems = reconciledActivities.size, + conflictsResolved = 0 + ) + ``` +* **Impacto/Limitação:** Embora o repositório realize de forma bem-sucedida a reconciliação (resolvendo concorrência com base no timestamp da transação mais recente), o aplicativo não calcula ou expõe de forma quantitativa quantos conflitos de concorrência foram identificados e solucionados na execução atual do lote. + +--- + +## 5. Carga de Dados Inicial em Caso de Falha de Conexão (Fallback) + +* **Status:** **Simulado (Mock Data Fallback)** +* **Arquivos Relacionados:** + * [`MaintenanceViewModel.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/ui/viewmodel/MaintenanceViewModel.kt) (linhas ~154-173) + * [`MaintenanceRepository.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/data/repository/MaintenanceRepository.kt) (método `loadSampleData()`, linhas ~180-211) +* **Descrição Técnica:** + Durante a primeira inicialização do aplicativo, o sistema tenta sincronizar com a planilha do Google Sheets. Se a conexão falhar ou as credenciais forem inválidas, o ViewModel intercepta a falha e invoca a carga de dados de exemplo estáticos (`loadSampleData()`): + ```kotlin + // Safe offline fallback in case of no connectivity or invalid credentials + _syncStatusMessage.value = "Usando dados modelo: ${result.message}" + repository.loadSampleData() + ``` + Esses dados de modelo criam ordens de serviço simuladas (`OS-2`, `OS-5`, `OS-6`, `OS-8`, `OS-10`, `OS-11`, `OS-1024`, `OS-16`) diretamente no Room local para demonstração do aplicativo. +* **Impacto/Limitação:** O comportamento garante que o app não apareça em branco na primeira execução sem rede, mas introduz ordens de serviço fictícias que não estão cadastradas na planilha remota Google Sheets.