docs: add technical documentation for simulated and truncated features

This commit is contained in:
Jhony Cesar
2026-07-27 18:04:44 -04:00
parent ddc1969651
commit 730fb15ff3

View File

@@ -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<Pair<MaintenanceActivity, Int>>,
toAppendRemote: List<MaintenanceActivity>
) {
// 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.