Snapshot: Filtro de data corrigido para dd/mm/aa
This commit is contained in:
109
documentacao/fluxo_de_dados_e_sincronizacao.md
Normal file
109
documentacao/fluxo_de_dados_e_sincronizacao.md
Normal file
@@ -0,0 +1,109 @@
|
||||
# Documentação do Fluxo de Dados e Sincronização do Aplicativo
|
||||
|
||||
Esta documentação resume as conversas e análises técnicas sobre o fluxo de dados, o armazenamento local, o mecanismo de sincronização e o planejamento de um banco de dados remoto baseado no Google Sheets para o aplicativo de manutenção.
|
||||
|
||||
---
|
||||
|
||||
## 1. Fluxo de Dados e Armazenamento Atual
|
||||
|
||||
### Como o fluxo está desenhado?
|
||||
O aplicativo adota uma arquitetura **offline-first** (local prioritário) baseada no padrão **MVVM (Model-View-ViewModel)** com **Repository Pattern**:
|
||||
|
||||
1. **Camada de UI (Jetpack Compose):** A tela `MaintenanceDashboardScreen.kt` reage às mudanças de estado expostas pelo `MaintenanceViewModel.kt`.
|
||||
2. **ViewModel (`MaintenanceViewModel.kt`):** Gerencia o fluxo de estados (UI State) utilizando `StateFlow` e lida com ações do usuário (filtragem, atualização de progresso, importação de CSV, disparo de sincronização).
|
||||
3. **Repository (`MaintenanceRepository.kt`):** Atua como a fonte única de verdade (Single Source of Truth), mediando o acesso aos dados entre a UI e a persistência local (e futuramente a remota).
|
||||
4. **Banco de Dados Local (Room - `AppDatabase.kt` / `MaintenanceDao.kt`):** Toda leitura e escrita de dados de ordens de serviço (OS) acontece primeiro no banco local (SQLite) do dispositivo.
|
||||
|
||||
```
|
||||
+--------------------------+
|
||||
| UI (Jetpack Compose) |
|
||||
+------------+-------------+
|
||||
| (Observa fluxos / dispara eventos)
|
||||
v
|
||||
+--------------------------+
|
||||
| MaintenanceViewModel |
|
||||
+------------+-------------+
|
||||
| (Dispara lógica de negócio)
|
||||
v
|
||||
+--------------------------+
|
||||
| MaintenanceRepository |
|
||||
+------------+-------------+
|
||||
| (Acessa dados locais)
|
||||
v
|
||||
+--------------------------+
|
||||
| Room Database (Local DB) |
|
||||
+--------------------------+
|
||||
```
|
||||
|
||||
### Como funciona o armazenamento?
|
||||
O armazenamento é realizado por meio do **Room Database**, que é uma camada de abstração sobre o **SQLite** nativo do Android.
|
||||
* O arquivo do banco de dados local (`cargill_maintenance_db`) é salvo no diretório privado do aplicativo dentro do armazenamento interno do aparelho: `/data/data/com.example/databases/cargill_maintenance_db`.
|
||||
|
||||
### Múltiplos usuários conseguem acessar a mesma base de dados diretamente?
|
||||
**Não.** Por ser um banco de dados **local e interno ao dispositivo**, o arquivo SQLite é isolado e privado para a instância do aplicativo instalada naquele smartphone/tablet específico.
|
||||
* Dois usuários rodando o aplicativo em celulares diferentes possuem bases de dados 100% distintas e isoladas.
|
||||
* Para que múltiplos usuários compartilhem e visualizem os mesmos dados de manutenção, é **indispensável** implementar um servidor centralizado (ou um banco de dados na nuvem, como Google Sheets, Firebase, PostgreSQL, etc.) e um fluxo de sincronização bidirecional.
|
||||
|
||||
---
|
||||
|
||||
## 2. Análise da Sincronização Remota
|
||||
|
||||
### A sincronização remota está realmente implementada?
|
||||
**Atualmente, a sincronização é SIMULADA (Mocked).** Não há nenhuma conexão real HTTP, REST API, Firebase ou WebSocket ativa enviando dados para um servidor externo. O código simula perfeitamente o comportamento que um fluxo de rede real teria.
|
||||
|
||||
### Como a simulação funciona?
|
||||
No método `synchronizeWithBackend()` dentro de `MaintenanceRepository.kt`:
|
||||
1. O repositório busca do banco local todas as atividades de manutenção que possuem a flag `synced = false` (obtidas por `dao.getUnsyncedActivities()`).
|
||||
2. Aplica um atraso artificial de 2,5 segundos (`delay(2500)`) usando Corrotinas para emular a latência de uma chamada de rede real.
|
||||
3. Executa um algoritmo matemático simples de resolução de conflitos em cerca de 15% das ordens de serviço (usando o resto da divisão do hash do número da OS por 7).
|
||||
4. No cenário simulado de conflito, adota a estratégia **"Last-Write-Wins"** (Última escrita vence), assumindo que a alteração local feita no campo pelo inspetor é a mais recente e deve sobrescrever o "servidor".
|
||||
5. Atualiza todos os registros modificados localmente no banco Room para `synced = true`.
|
||||
|
||||
### Arquivos responsáveis por essa conexão e sincronização:
|
||||
* **`com.example.data.model.MaintenanceActivity`:** Contém os atributos `synced: Boolean` (indica se a OS local está pareada com o servidor) e `lastUpdated: Long` (carimbo de data/hora em milissegundos para resolver conflitos de alteração concorrente).
|
||||
* **`com.example.data.local.MaintenanceDao`:** Contém a consulta SQL `@Query("SELECT * FROM maintenance_activities WHERE synced = 0")` para extrair apenas o que foi alterado offline e precisa subir.
|
||||
* **`com.example.data.repository.MaintenanceRepository`:** Contém o método `synchronizeWithBackend()`, que centraliza toda a lógica de preparação do lote de envio, simulação de rede e marcação de sincronizado.
|
||||
* **`com.example.ui.viewmodel.MaintenanceViewModel`:** Contém o método `syncWithBackend()`, que executa a chamada ao repositório dentro de um escopo de Coroutine, altera o estado da tela para "Carregando" (Loading), lida com o resultado de sucesso ou falha, e atualiza a UI.
|
||||
|
||||
---
|
||||
|
||||
## 3. Estruturação para Integração com Google Sheets (Futuro)
|
||||
|
||||
Se você decidir usar o **Google Sheets** como seu banco de dados remoto centralizado para permitir que múltiplos dispositivos acessem e sincronizem os mesmos dados, você precisará criar uma planilha no Google Drive com **duas abas (worksheets)** principais para refletir a estrutura de dados atual do aplicativo.
|
||||
|
||||
Abaixo está o mapeamento exato de tabelas e colunas que você deve configurar no seu Google Sheets:
|
||||
|
||||
### Tabela/Aba 1: `activities` (Ordens de Serviço de Manutenção)
|
||||
Esta aba armazenará a lista de todas as ordens de serviço ativas na planta.
|
||||
|
||||
| Nome da Coluna (Cabeçalho da Coluna A, B, C...) | Tipo Sugerido | Descrição / Observações |
|
||||
| :--- | :--- | :--- |
|
||||
| **`numeroOs`** | Texto (Chave Primária) | Ex: `OS-4010`. Deve ser único nesta tabela. |
|
||||
| **`descricao`** | Texto | Descrição detalhada da atividade de manutenção. |
|
||||
| **`setor`** | Texto | Setor da fábrica (ex: `Preparação`, `Extração`, `Caldeira`, `Refinaria`, `Envase`). |
|
||||
| **`equipe`** | Texto | Equipe técnica responsável (ex: `Mecânica`, `Elétrica`, `Confiabilidade`, `Lubrificação`). |
|
||||
| **`responsavel`** | Texto | Nome do técnico ou encarregado responsável pela atividade. |
|
||||
| **`dataInicio`** | Texto ou Data | Data programada para o início (ex: `30/06/2026`). |
|
||||
| **`dataFim`** | Texto ou Data | Data programada para conclusão (ex: `02/07/2026`). |
|
||||
| **`percentualExecucao`** | Número Inteiro | Progresso de execução de 0 a 100. |
|
||||
| **`observacoes`** | Texto (Opcional) | Comentários, notas adicionais ou relato de anomalias encontradas. |
|
||||
| **`fotoPath`** | Texto (URL) | **Importante:** O Sheets não armazena arquivos binários diretamente na célula de forma eficiente. O aplicativo deve fazer upload da foto para um servidor de arquivos ou pasta pública do **Google Drive**, e armazenar o **link direto da imagem (URL)** nesta coluna. |
|
||||
| **`lastUpdated`** | Número Inteiro (Long) | Timestamp Unix em milissegundos (ex: `1783965742000`). Essencial para saber qual dispositivo fez a alteração mais recente e evitar perda de dados. |
|
||||
|
||||
### Tabela/Aba 2: `history` (Histórico de Atualizações das OS)
|
||||
Esta aba registrará cada alteração feita em qualquer OS, permitindo auditoria detalhada de quem alterou o progresso e quando.
|
||||
|
||||
| Nome da Coluna (Cabeçalho da Coluna A, B, C...) | Tipo Sugerido | Descrição / Observações |
|
||||
| :--- | :--- | :--- |
|
||||
| **`id`** | Texto ou Número | Identificador único da linha do histórico (pode ser gerado como UUID no app ou auto-incremento). |
|
||||
| **`numeroOs`** | Texto | Código da OS que foi atualizada (chave estrangeira relacionada à aba `activities`). |
|
||||
| **`timestamp`** | Número Inteiro (Long) | Carimbo de data/hora em milissegundos de quando a atualização ocorreu. |
|
||||
| **`percentualAnterior`** | Número Inteiro | Qual era o progresso antes dessa alteração (ex: `25`). |
|
||||
| **`percentualNovo`** | Número Inteiro | Qual o novo progresso registrado (ex: `50`). |
|
||||
| **`observacao`** | Texto (Opcional) | Comentário inserido pelo técnico justificando ou detalhando aquela atualização específica. |
|
||||
| **`fotoPath`** | Texto (URL) | Link da foto tirada no momento desta atualização (se houver). |
|
||||
| **`responsavel`** | Texto | Nome do profissional que realizou esta atualização de progresso. |
|
||||
|
||||
### Dicas para a Integração com Google Sheets:
|
||||
1. **API de Comunicação:** Para conectar o app Android ao Google Sheets, você pode usar uma API REST intermediária feita no **Google Apps Script** (que recebe requisições POST/GET com JSON e escreve na planilha) ou usar diretamente a **Google Sheets API** via bibliotecas HTTP como Retrofit/Ktor.
|
||||
2. **Resolução de Conflitos (LWW):** Quando o aplicativo sincronizar, ele deve comparar o `lastUpdated` local da OS com o `lastUpdated` presente na linha correspondente da aba `activities` no Sheets. Se o `lastUpdated` do Sheets for mais novo, o aplicativo deve baixar a alteração. Se o `lastUpdated` local for mais novo, o app deve enviar e atualizar a planilha.
|
||||
Reference in New Issue
Block a user