docs: update project documentation to include detailed Room entities, sync flow, and README execution guide
This commit is contained in:
40
README.md
40
README.md
@@ -1,21 +1,33 @@
|
|||||||
<div align="center">
|
# Aplicativo de Gestão de Manutenção de Parada (Android)
|
||||||
<img width="1200" height="475" alt="GHBanner" src="https://ai.google.dev/static/site-assets/images/share-ais-513315318.png" />
|
|
||||||
</div>
|
|
||||||
|
|
||||||
# Run and deploy your AI Studio app
|
Aplicativo Android **offline-first** desenvolvido em Kotlin e Jetpack Compose para gerenciamento, acompanhamento e auditoria de Ordens de Serviço (OS) em plantas industriais.
|
||||||
|
|
||||||
This contains everything you need to run your app locally.
|
---
|
||||||
|
|
||||||
View your app in AI Studio: https://ai.studio/apps/d5626d9c-db6d-4067-9ba1-e80d37ea164f
|
## 📚 Documentação Técnica do Projeto
|
||||||
|
|
||||||
## Run Locally
|
- **[Documentação de Fluxo de Dados, Salvamento e Sincronização](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/documentacao/fluxo_de_dados_e_sincronizacao.md)**:
|
||||||
|
- Estrutura completa das 6 tabelas do banco de dados local Room (`maintenance_activities`, `os_findings`, `os_update_history`, `app_logs`, `sync_conflict_logs`, `user_access`).
|
||||||
|
- Fluxo detalhado de salvamento de progresso e achados com tipo exclusivo `FOTO`.
|
||||||
|
- Processo de compactação (<= 500KB) e upload para Firebase Storage.
|
||||||
|
- Sincronização bidirecional com Google Sheets (abas `project`, `history` e `achados`).
|
||||||
|
- Carregamento e download de fotos **sob demanda** (On-Demand Loading) para múltiplos celulares sem erros HTTP 403.
|
||||||
|
|
||||||
**Prerequisites:** [Android Studio](https://developer.android.com/studio)
|
- **[Arquitetura do Sistema](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/documentacao/arquitetura/arquitetura_do_sistema.md)**:
|
||||||
|
- Diagramas de arquitetura MVVM + Repository Pattern.
|
||||||
|
- Mapeamento de componentes Compose, ViewModel e Room DAO.
|
||||||
|
- Algoritmo de reconciliação de dados e auditoria transacional.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
1. Open Android Studio
|
## 🚀 Como Executar o Projeto
|
||||||
2. Select **Open** and choose the directory containing this project
|
|
||||||
3. Allow Android Studio to fix any incompatibilities as it imports the project.
|
**Pré-requisitos:** [Android Studio](https://developer.android.com/studio) / JDK 17+
|
||||||
4. Create a file named `.env` in the project directory and set `GEMINI_API_KEY` in that file to your Gemini API key (see `.env.example` for an example)
|
|
||||||
5. Remove this line from the app's `build.gradle.kts` file: `signingConfig = signingConfigs.getByName("debugConfig")`
|
1. Abra o Android Studio.
|
||||||
6. Run the app on an emulator or physical device
|
2. Selecione **Open** e escolha a pasta deste projeto (`gestao_de_manutencao`).
|
||||||
|
3. Execute os testes unitários via linha de comando ou terminal do estúdio:
|
||||||
|
```bash
|
||||||
|
./gradle_9_3_1/gradle-9.3.1/bin/gradle test
|
||||||
|
```
|
||||||
|
4. Execute o aplicativo em um emulador ou dispositivo físico Android.
|
||||||
|
|||||||
@@ -115,20 +115,57 @@ Representa o estado atualizado de uma Ordem de Serviço (OS).
|
|||||||
* `1%` a `99%` -> `ActivityStatus.EM_ANDAMENTO` ("Em andamento")
|
* `1%` a `99%` -> `ActivityStatus.EM_ANDAMENTO` ("Em andamento")
|
||||||
* `100%` -> `ActivityStatus.CONCLUIDO` ("Concluído")
|
* `100%` -> `ActivityStatus.CONCLUIDO` ("Concluído")
|
||||||
|
|
||||||
### 3.2. Entidade: `OSUpdateHistory` (Tabela: `os_update_history`)
|
### 3.3. Entidade: `OSFinding` (Tabela: `os_findings`)
|
||||||
Armazena a trilha detalhada de atualizações aplicadas a cada OS. É o elemento fundamental para o sincronismo transacional.
|
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 |
|
| Campo | Tipo | Chave | Descrição |
|
||||||
| :--- | :--- | :--- | :--- |
|
| :--- | :--- | :--- | :--- |
|
||||||
| `id` | `Long` | Primária (Auto) | Identificador sequencial do log. |
|
| `id` | `String` | Primária | UUID único do achado. |
|
||||||
| `numeroOs` | `String` | - | Relaciona o registro à OS correspondente. |
|
| `numeroOs` | `String` | Indexado | Código da OS associada. |
|
||||||
| `timestamp` | `Long` | - | Data/hora exata em que o log foi registrado. |
|
| `tipo` | `String` | Indexado | Tipo: `"FOTO"`, `"OBS"`, `"SEGURANCA"` ou `"MANUTENCAO"`. |
|
||||||
| `percentualAnterior`| `Int` | - | Progresso antes do salvamento da alteração. |
|
| `descricao` | `String` | - | Descrição técnica do achado ou "Foto anexada". |
|
||||||
| `percentualNovo` | `Int` | - | Novo progresso cadastrado pelo usuário. |
|
| `timestamp` | `Long` | - | Timestamp UNIX de criação/edição. |
|
||||||
| `observacao` | `String?` | - | Observação descritiva inserida no momento da atualização. |
|
| `responsavel` | `String` | - | Nome do responsável pela inclusão. |
|
||||||
| `fotoPath` | `String?` | - | Foto de evidência vinculada a este incremento de progresso. |
|
| `emailEditor` | `String?` | - | E-mail do usuário editor no Google SSO. |
|
||||||
| `recurso` | `String` | - | Identificação do responsável que executou a modificação. |
|
| `fotoPath` | `String?` | - | Caminhos de foto concatenados por `\|`. |
|
||||||
| `emailEditor` | `String?` | - | Email da conta do Google do usuário editor (auditoria). |
|
| `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. |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|||||||
@@ -1,127 +1,230 @@
|
|||||||
# Documentação do Fluxo de Dados e Sincronização do Aplicativo
|
# Documentação do Fluxo de Dados, Salvamento e Sincronização
|
||||||
|
|
||||||
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.
|
Esta documentação detalha a arquitetura **offline-first**, a estrutura completa da base de dados local (Room SQLite) e remota (Google Sheets / Firebase Storage), além do fluxo detalhado de salvamento de informações e download de mídias sob demanda.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 1. Fluxo de Dados e Armazenamento Atual
|
## 1. Visão Geral da Arquitetura de Dados
|
||||||
|
|
||||||
### Como o fluxo está desenhado?
|
O aplicativo adota o padrão **MVVM (Model-View-ViewModel)** com **Repository Pattern** e filosofia **Offline-First**:
|
||||||
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) |
|
| UI (Jetpack Compose) |
|
||||||
+------------+-------------+
|
| - MaintenanceDashboardScreen |
|
||||||
| (Observa fluxos / dispara eventos)
|
| - EditActivityBottomSheet (Modal da OS) |
|
||||||
|
+--------------------------+----------------------------+
|
||||||
|
| Observa StateFlow / Dispara Ações
|
||||||
v
|
v
|
||||||
+--------------------------+
|
+-------------------------------------------------------+
|
||||||
| MaintenanceViewModel |
|
| MaintenanceViewModel |
|
||||||
+------------+-------------+
|
| - Gerencia estados da interface e busca |
|
||||||
| (Dispara lógica de negócio)
|
| - Valida níveis de acesso (Google SSO) |
|
||||||
|
+--------------------------+----------------------------+
|
||||||
|
| Executa Lógica de Negócio
|
||||||
v
|
v
|
||||||
+--------------------------+
|
+-------------------------------------------------------+
|
||||||
| MaintenanceRepository |
|
| MaintenanceRepository |
|
||||||
+------------+-------------+
|
| - Fonte Única de Verdade (Single Source of Truth) |
|
||||||
| (Acessa dados locais)
|
| - Orquestra gravação local e sync com nuvem |
|
||||||
v
|
+-------------------+-------------------+---------------+
|
||||||
+--------------------------+
|
| |
|
||||||
| Room Database (Local DB) |
|
Gravação | | Sincronização
|
||||||
+--------------------------+
|
Local v v Remota
|
||||||
|
+-----------------------+ +---------------------------+
|
||||||
|
| Room DB (SQLite) | | Google Sheets API v4 |
|
||||||
|
| - maintenance_activities | - Aba 'project' (Leitura) |
|
||||||
|
| - os_update_history | | - Aba 'history' (Audit) |
|
||||||
|
| - os_findings | | - Aba 'achados' (Linhas) |
|
||||||
|
| - app_logs | +---------------------------+
|
||||||
|
| - sync_conflict_logs | | Firebase Storage SDK |
|
||||||
|
| - user_access | | - Bucket de fotos / mídias|
|
||||||
|
+-----------------------+ +---------------------------+
|
||||||
```
|
```
|
||||||
|
|
||||||
### 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 (`maintenance_db`) é salvo no diretório privado do aplicativo dentro do armazenamento interno do aparelho: `/data/data/com.example/databases/maintenance_db`.
|
|
||||||
|
|
||||||
### Múltiplos usuários conseguem acessar a mesma base de dados diretamente?
|
## 2. Estrutura Completa da Base de Dados
|
||||||
**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.
|
O aplicativo utiliza o **Room Database** (`AppDatabase.kt`) sobre o SQLite interno no dispositivo (`/data/data/com.example/databases/maintenance_db`). A estrutura engloba 6 tabelas principais:
|
||||||
* 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.1. Tabela: `maintenance_activities` (Ordens de Serviço Ativas)
|
||||||
|
Armazena a lista principal das Ordens de Serviço (OS) de manutenção da planta.
|
||||||
|
|
||||||
|
| Campo | Tipo | Chave | Descrição / Regras |
|
||||||
|
| :--- | :--- | :--- | :--- |
|
||||||
|
| **`numeroOs`** | `String` | Primária | Código de identificação único da OS (ex: `OS-1503`). |
|
||||||
|
| **`descricao`** | `String` | - | Descrição técnica do trabalho de manutenção. |
|
||||||
|
| **`setor`** | `String` | - | Setor industrial da fábrica (ex: `EXTRAÇÃO`, `CALDEIRA`). |
|
||||||
|
| **`equipe`** | `String` | - | Disciplina responsável (ex: `Mecânica`, `Elétrica`). |
|
||||||
|
| **`recurso`** | `String` | - | Nome do inspetor ou encarregado atual. |
|
||||||
|
| **`dataInicio`** | `String` | - | Data planejada/real de início (ex: `01/07/2026`). |
|
||||||
|
| **`dataFim`** | `String` | - | Data planejada de conclusão. |
|
||||||
|
| **`percentualExecucao`** | `Int` | - | Progresso medido de `0` a `100`%. |
|
||||||
|
| **`observacoes`** | `String?` | - | Texto do comentário ou observação mais recente. |
|
||||||
|
| **`fotoPath`** | `String?` | - | Evidência fotográfica vinculada à atividade. |
|
||||||
|
| **`synced`** | `Boolean` | - | `true` se sincronizado com Google Sheets, `false` se pendente. |
|
||||||
|
| **`lastUpdated`** | `Long` | - | Timestamp UNIX (milissegundos) da última edição. |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 2. Análise da Sincronização Remota
|
### 2.2. Tabela: `os_findings` (Achados, Fotos e Observações)
|
||||||
|
Armazena os achados ativos associados a cada OS. É a **fonte exclusiva da galeria de fotos** do aplicativo.
|
||||||
|
|
||||||
### A sincronização remota está real e funcionalmente implementada?
|
| Campo | Tipo | Chave | Descrição / Regras |
|
||||||
**Sim, a sincronização é REAL e BIDIRECIONAL.** O aplicativo utiliza a **Google Sheets API v4** (`GoogleSheetsSyncService.kt`) para sincronizar a estrutura do projeto e logs de alteração, e o **Firebase Storage SDK** (`FirebaseStorageSyncService.kt`) para upload de fotos das OSs no Firebase Storage.
|
| :--- | :--- | :--- | :--- |
|
||||||
|
| **`id`** | `String` | Primária | Identificador único (UUID). |
|
||||||
|
| **`numeroOs`** | `String` | Indexado | Código da OS relacionada. |
|
||||||
|
| **`tipo`** | `String` | Indexado | Tipo do registro: `"FOTO"`, `"OBS"`, `"SEGURANCA"` ou `"MANUTENCAO"`. |
|
||||||
|
| **`descricao`** | `String` | - | Descrição do achado ou `"Foto anexada"`. |
|
||||||
|
| **`timestamp`** | `Long` | - | Timestamp UNIX da criação/edição. |
|
||||||
|
| **`responsavel`** | `String` | - | Nome do responsável pela gravação. |
|
||||||
|
| **`emailEditor`** | `String?` | - | E-mail da conta do Google do editor. |
|
||||||
|
| **`fotoPath`** | `String?` | - | Caminhos de fotos relativos ou locais concatenados por `\|`. |
|
||||||
|
| **`synced`** | `Boolean` | Indexado | Status de sincronização com a aba `achados` no Google Sheets. |
|
||||||
|
|
||||||
### Como o fluxo de sincronização e envio de fotos funciona?
|
> **Regra do Tipo Exclusivo `FOTO`**: Cada OS possui no máximo **1 registro ativo** de `tipo = "FOTO"` na tabela `os_findings` e na aba `achados` do Google Sheets. Todas as fotos daquela OS são concatenadas na coluna `fotoPath` com o caractere `|` (ex: `photos/OS_OS-1136/photo1.jpg|photos/OS_OS-1136/photo2.jpg`).
|
||||||
1. **Captura, Suporte HEIC e Compactação Local (Offline-First):** As fotos capturadas pela Câmera ou selecionadas da Galeria (nos formatos JPEG, PNG ou HEIC/HEIF) são processadas pelo `ImageCompressor.kt`. O app decodifica a imagem, corrige a orientação EXIF, reduz a resolução para no máximo 1920x1920 px se necessário, e compacta iterativamente para garantir tamanho final **<= 500 KB**. O arquivo resultante é armazenado em `filesDir/os_photos/` e registrado no Room DB.
|
|
||||||
2. **Upload Único para o Firebase Storage:** Durante a sincronização, o `MaintenanceRepository.kt` lê as fotos pendentes locais e aciona o `FirebaseStorageSyncService.kt`. Fotos que já possuem URL remota (`http://` ou `https://`) são ignoradas, garantindo que cada foto seja enviada apenas uma vez. As fotos pendentes são enviadas com trava de segurança de 500KB para a pasta `photos/OS_{numeroOs}/`.
|
|
||||||
3. **URL de Download e Sincronismo com Google Sheets:** O serviço obtém a `downloadUrl` do Firebase Storage, atualizando a Room DB. Ao reconciliar os históricos (`remoteHistory + localHistory`), o sistema prioriza as URLs remotas em relação a caminhos locais desatualizados, refletindo o link público na aba `history` do Google Sheets.
|
|
||||||
4. **Download Inteligente com Re-tentativas Automáticas (Retry & Cache):** Para garantir a exibição de fotos em ambientes de campo com oscilações de rede, o aplicativo utiliza o Coil configurado via `MainApplication.kt` com um `RetryInterceptor` customizado no OkHttp. Caso um download falhe por instabilidade de rede ou erro temporário do servidor, o app executa **até 3 tentativas** com **intervalo aleatório (jitter)** de 300ms a 1000ms. Fotos baixadas com sucesso são gravadas em um cache em disco dedicado de **50 MB** (`cacheDir/image_cache`), permitindo visualização offline instantânea de até ~100 fotos de 500KB.
|
|
||||||
5. **Soft Delete e Consistência Local:** A exclusão de fotos executa um Soft Delete no Firebase Storage (adicionando o sufixo `_DELETED` ao arquivo) e atualiza incrementalmente os registros das tabelas `MaintenanceActivity`, `OSUpdateHistory` e `OSFinding` no Room DB local. A sincronização respeita a marcação `_DELETED` local, impedindo que fotos deletadas reapareçam.
|
|
||||||
6. **Registro de Falhas no Histórico de Logs (`AppLogger`):** Todas as falhas de sincronização, erros de envio no Firebase e falhas no download de fotos (após o limite de 3 re-tentativas) são automaticamente registradas pelo `AppLogger.kt` na tabela `AppLog` do Room DB e ficam acessíveis para consulta na aba **Histórico de Logs** da tela de **Configurações**.
|
|
||||||
7. **Controle de Acesso para Usuários Sem Login:** Usuários não autenticados via conta do Google têm acesso exclusivamente à visualização dos dados. Ações de edição de progresso, alteração de observações, inclusão/edição/exclusão de Achados e exclusão de fotos de campo são bloqueadas na UI e validadas no `MaintenanceViewModel.kt`.
|
|
||||||
|
|
||||||
### Arquivos responsáveis pela conexão, sincronização e exibição de fotos:
|
|
||||||
* **`com.example.MainApplication`:** Configura o `ImageLoaderFactory` do Coil, interceptor OkHttp de retries automáticos com delay aleatório (300-1000ms), cache em memória (25% RAM) e cache em disco (50MB).
|
|
||||||
* **`com.example.util.AppLogger`:** Gerencia o registro persistente de logs de auditoria (WARN, ERROR, INFO) exibidos no painel da tela de Configurações.
|
|
||||||
* **`com.example.util.ImageCompressor`:** Utilitário responsável pelo decodificação de HEIC/HEIF/JPEG/PNG, rotação EXIF e compactação garantida de imagens para até 500KB.
|
|
||||||
* **`com.example.data.remote.FirebaseStorageSyncService`:** Gerencia upload seguro de fotos (com trava de 500KB) e soft delete no Firebase Storage.
|
|
||||||
* **`com.example.data.remote.GoogleSheetsSyncService`:** Gerencia autenticação via Service Account e reconciliação bidirecional com a planilha central do Google Sheets.
|
|
||||||
* **`com.example.data.repository.MaintenanceRepository`:** Centraliza a orquestração do sync, upload de mídias pendentes sem reenvios duplicados, resolução de conflitos (LWW) e soft delete.
|
|
||||||
* **`com.example.ui.viewmodel.MaintenanceViewModel`:** Gerencia os estados de sync na UI, disparos assíncronos, validação de permissões de acesso e callbacks de gerenciamento de fotos.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 3. Estruturação para Integração com Google Sheets (Futuro)
|
### 2.3. Tabela: `os_update_history` (Log de Transações de Auditoria)
|
||||||
|
Registra o histórico cronológico de cada atualização efetuada por usuários em uma OS.
|
||||||
|
|
||||||
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.
|
| Campo | Tipo | Chave | Descrição / Regras |
|
||||||
|
| :--- | :--- | :--- | :--- |
|
||||||
|
| **`id`** | `Long` | Primária (Auto) | Identificador sequencial do log. |
|
||||||
|
| **`numeroOs`** | `String` | - | Código da OS alterada. |
|
||||||
|
| **`timestamp`** | `Long` | - | Data/hora exata em milissegundos. |
|
||||||
|
| **`percentualAnterior`** | `Int` | - | Progresso antes da edição. |
|
||||||
|
| **`percentualNovo`** | `Int` | - | Progresso informado pelo usuário. |
|
||||||
|
| **`observacao`** | `String?` | - | Texto da observação ou tag de auditoria. |
|
||||||
|
| **`fotoPath`** | `String?` | - | Fotos anexadas nesta atualização. |
|
||||||
|
| **`recurso`** | `String` | - | Responsável pela ação. |
|
||||||
|
| **`emailEditor`** | `String?` | - | E-mail do usuário autenticado no Google. |
|
||||||
|
|
||||||
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)
|
### 2.4. Tabela: `app_logs` (Histórico de Diagnostic Log)
|
||||||
Esta aba armazenará a lista de todas as ordens de serviço ativas na planta.
|
Armazena registros de log e exceções de sistema exibidos na tela de **Configurações -> Histórico de Logs de Diagnóstico**.
|
||||||
|
|
||||||
| Nome da Coluna (Cabeçalho da Coluna A, B, C...) | Tipo Sugerido | Descrição / Observações |
|
| Campo | Tipo | Chave | Descrição / Regras |
|
||||||
| :--- | :--- | :--- |
|
| :--- | :--- | :--- | :--- |
|
||||||
| **`numeroOs`** | Texto (Chave Primária) | Ex: `OS-4010`. Deve ser único nesta tabela. |
|
| **`id`** | `Long` | Primária (Auto) | ID do log. |
|
||||||
| **`descricao`** | Texto | Descrição detalhada da atividade de manutenção. |
|
| **`timestamp`** | `Long` | - | Data/hora da ocorrência. |
|
||||||
| **`setor`** | Texto | Setor da fábrica (ex: `Preparação`, `Extração`, `Caldeira`, `Refinaria`, `Envase`). |
|
| **`level`** | `String` | - | Nível de severidade: `"INFO"`, `"WARN"`, `"ERROR"`. |
|
||||||
| **`equipe`** | Texto | Equipe técnica responsável (ex: `Mecânica`, `Elétrica`, `Confiabilidade`, `Lubrificação`). |
|
| **`tag`** | `String` | - | Tag de origem (ex: `PhotoDisplayError`, `FirebaseStorageSync`). |
|
||||||
| **`responsavel`** | Texto | Nome do técnico ou encarregado responsável pela atividade. |
|
| **`message`** | `String` | - | Mensagem descritiva da falha ou evento. |
|
||||||
| **`dataInicio`** | Texto ou Data | Data programada para o início (ex: `30/06/2026`). |
|
| **`stackTrace`** | `String?` | - | Rastreamento da pilha de exceções em falhas. |
|
||||||
| **`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 Auditoria das OS e Achados)
|
---
|
||||||
Esta aba registrará cada alteração feita em qualquer OS (avanços de progresso, observações e alterações/exclusões em Achados), permitindo auditoria detalhada de quem alterou e quando.
|
|
||||||
|
|
||||||
| Nome da Coluna | Tipo Sugerido | Descrição / Observações |
|
### 2.5. Tabela: `sync_conflict_logs` (Histórico de Conflitos de Sincronização)
|
||||||
| :--- | :--- | :--- |
|
Registra eventos de desvio ou resolução de conflitos ocorridos na sincronização com o Sheets.
|
||||||
| **`id`** | Texto ou Número | Identificador único da linha do histórico. |
|
|
||||||
| **`numeroOs`** | Texto | Código da OS atualizada. |
|
|
||||||
| **`timestamp`** | Número Inteiro (Long) | Timestamp Unix em milissegundos. |
|
|
||||||
| **`percentualAnterior`** | Número Inteiro | Progresso anterior da OS. |
|
|
||||||
| **`percentualNovo`** | Número Inteiro | Novo progresso da OS. |
|
|
||||||
| **`observacao`** | Texto (Opcional) | Detalhamento do evento, incluindo marcações auditadas como `"[Achado de Segurança Criado] ..."`, `"[Achado de Manutenção Excluído] ..."`. |
|
|
||||||
| **`fotoPath`** | Texto (URL) | Link da foto anexa. |
|
|
||||||
| **`responsavel`** | Texto | Nome do responsável pela ação. |
|
|
||||||
| **`email_editor`** | Texto | E-mail do usuário autenticado no Google que realizou a ação. |
|
|
||||||
|
|
||||||
### Tabela/Aba 3: `achados` (Achados de Segurança, Manutenção e Observações Ativas)
|
| Campo | Tipo | Chave | Descrição |
|
||||||
Esta aba armazena os registros ativos de Achados de Segurança, Achados de Manutenção e a Última Observação associados a cada OS.
|
| :--- | :--- | :--- | :--- |
|
||||||
|
| **`id`** | `Long` | Primária (Auto) | ID do evento de conflito. |
|
||||||
|
| **`numeroOs`** | `String` | - | OS afetada. |
|
||||||
|
| **`timestamp`** | `Long` | - | Timestamp da ocorrência. |
|
||||||
|
| **`fieldName`** | `String` | - | Campo afetado (ex: `percentualExecucao`). |
|
||||||
|
| **`localValue`** | `String` | - | Valor salvo no dispositivo. |
|
||||||
|
| **`remoteValue`** | `String` | - | Valor recebido do Google Sheets. |
|
||||||
|
| **`resolvedValue`**| `String` | - | Valor consolidado aplicado. |
|
||||||
|
| **`resolutionStrategy`** | `String` | - | Estratégia de resolução (ex: `LWW_LOCAL_WIN`). |
|
||||||
|
|
||||||
| Nome da Coluna | Tipo Sugerido | Descrição / Observações |
|
---
|
||||||
| :--- | :--- | :--- |
|
|
||||||
| **`id`** | Texto (UUID) | Identificador exclusivo do achado. |
|
|
||||||
| **`numeroOs`** | Texto | Código da OS relacionada. |
|
|
||||||
| **`tipo`** | Texto | Tipo do registro: `"OBS"`, `"SEGURANCA"` ou `"MANUTENCAO"`. |
|
|
||||||
| **`descricao`** | Texto | Texto descritivo do achado ou observação. |
|
|
||||||
| **`timestamp`** | Número Inteiro (Long) | Data/hora de criação ou alteração. |
|
|
||||||
| **`responsavel`** | Texto | Nome do responsável pelo registro. |
|
|
||||||
| **`email_editor`** | Texto | E-mail do editor autenticado. |
|
|
||||||
| **`fotoPath`** | Texto (URL) | Link de foto vinculada ao achado (opcional). |
|
|
||||||
|
|
||||||
> **Nota de Exclusão Física**: Quando um usuário exclui um achado ativo no app, o registro é fisicamente removido do Room e da aba `achados` no Google Sheets. No entanto, o evento de exclusão permanece registrado na aba `history` para fins de auditoria inalterável.
|
### 2.6. Tabela: `user_access` (Controle de Acesso de Usuários)
|
||||||
|
Armazena o nível de permissão associado aos e-mails cadastrados.
|
||||||
|
|
||||||
|
| Campo | Tipo | Chave | Descrição |
|
||||||
|
| :--- | :--- | :--- | :--- |
|
||||||
|
| **`email`** | `String` | Primária | E-mail do usuário da conta Google. |
|
||||||
|
| **`nivelAcesso`** | `String` | - | Permissão: `"ADMIN"`, `"ENCO"` (Encarregado) ou `"VISUALIZADOR"`. |
|
||||||
|
| **`lastUpdated`** | `Long` | - | Data de atualização da regra. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Fluxo Completo de Salvamento de Dados
|
||||||
|
|
||||||
|
### 3.1. Passos no Salvamento Local (Offline-First)
|
||||||
|
|
||||||
|
1. **Edição do Usuário na Interface (`EditActivityBottomSheet`)**:
|
||||||
|
- O usuário seleciona o progresso de execução (0-100%), edita observações e captura/anexa novas fotos na galeria da OS.
|
||||||
|
- Aciona o botão **Salvar Atualizações**.
|
||||||
|
|
||||||
|
2. **Processamento e Compactação de Fotos (`ImageCompressor.kt`)**:
|
||||||
|
- As fotos capturadas pela câmera ou selecionadas da galeria (formatos JPEG, PNG, HEIC/HEIF) são processadas.
|
||||||
|
- O aplicativo decodifica a foto, corrige a rotação baseando-se nos metadados EXIF, redimensiona se maior que 1920x1920 px e compacta com garantia de tamanho final **<= 500 KB**.
|
||||||
|
- A foto é salva no armazenamento interno do aplicativo (`filesDir/os_photos/OS_{numeroOs}_{timestamp}.jpg`).
|
||||||
|
|
||||||
|
3. **Gravação Transacional no Room Database (`MaintenanceRepository.kt`)**:
|
||||||
|
- **`maintenance_activities`**: Atualiza o percentual, a observação e altera o status para `synced = false`.
|
||||||
|
- **`os_findings`**: Busca se a OS já possui um achado de `tipo = "FOTO"`.
|
||||||
|
- Se existir: mescla o novo caminho com os caminhos anteriores usando `|` (`mergePreservingDeletedPhotos`), grava `synced = false` e atualiza o registro.
|
||||||
|
- Se não existir: cria um novo `OSFinding` com `tipo = "FOTO"`, `descricao = "Foto anexada"` e `synced = false`.
|
||||||
|
- **`os_findings` (Observação)**: Se houver observação de texto, atualiza/cria o achado de `tipo = "OBS"`.
|
||||||
|
- **`os_update_history`**: Insere uma nova linha de log contendo `percentualAnterior`, `percentualNovo`, `observacao`, `fotoPath`, `recurso` e o `emailEditor`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Fluxo de Sincronização Remota (Google Sheets & Firebase Storage)
|
||||||
|
|
||||||
|
### 4.1. Upload de Mídias ao Firebase Storage (`FirebaseStorageSyncService.kt`)
|
||||||
|
1. Ao iniciar o sync, `uploadPendingPhotos()` varre os registros de achados com arquivos locais no aparelho (`/data/user/0/.../files/os_photos/OS_...jpg`).
|
||||||
|
2. Garante o login silencioso no Firebase Auth via `ensureFirebaseAuth()`.
|
||||||
|
3. Faz o upload seguro da imagem compactada para o bucket na nuvem (`photos/OS_{numeroOs}/OS_{numeroOs}_{timestamp}.jpg`).
|
||||||
|
4. Obtém a `downloadUrl` oficial contendo o token de acesso (`?alt=media&token=...`), salva em cache de memória (`downloadUrlCache`), e converte o caminho da foto no banco local para o formato relativo normalizado `photos/OS_{numeroOs}/OS_{numeroOs}_{timestamp}.jpg`.
|
||||||
|
|
||||||
|
### 4.2. Sincronização com o Google Sheets (`GoogleSheetsSyncService.kt`)
|
||||||
|
O aplicativo sincroniza com três abas da planilha central:
|
||||||
|
|
||||||
|
1. **Aba `project` (Leitura Mestra)**: Carrega as ordens de serviço ativas.
|
||||||
|
2. **Aba `history` (Escrita de Auditoria)**: Envia novos registros da tabela `os_update_history`.
|
||||||
|
3. **Aba `achados` (Sincronização Bidirecional de Achados e Fotos)**:
|
||||||
|
- Limpa e converte caminhos de fotos locais para o formato relativo `photos/OS_.../*.jpg` via `cleanToStoragePath`.
|
||||||
|
- Reconcilia achados remotos e locais preservando alterações pendentes (`synced = false`).
|
||||||
|
- Agrupa e consolida os registros por `(numeroOs, tipo)` para garantir **no máximo 1 linha por OS com `tipo = "FOTO"`** contendo todas as fotos ativas concatenadas por `|`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Download e Exibição de Fotos Sob Demanda (On-Demand Loading)
|
||||||
|
|
||||||
|
Para evitar consumo desnecessário de dados móveis e garantir o carregamento correto em múltiplos dispositivos ou após a limpeza de dados do aplicativo:
|
||||||
|
|
||||||
|
```
|
||||||
|
[UI / Galeria de Fotos da OS]
|
||||||
|
|
|
||||||
|
v
|
||||||
|
[rememberResolvedPhotoModel(photoPath)]
|
||||||
|
|
|
||||||
|
+---> Arquivo existe em 'filesDir/os_photos/'?
|
||||||
|
| |
|
||||||
|
| +--> (SIM) --> Carrega do disco local instantaneamente
|
||||||
|
| |
|
||||||
|
| +--> (NÃO) --> Dispara download SOB DEMANDA via Coroutine
|
||||||
|
| |
|
||||||
|
| v
|
||||||
|
| [syncService.downloadPhotoFile(path)]
|
||||||
|
| |
|
||||||
|
| v
|
||||||
|
| [ensureFirebaseAuth()]
|
||||||
|
| |
|
||||||
|
| v
|
||||||
|
| [storageRef.getFile(localFile).await()]
|
||||||
|
| |
|
||||||
|
| v
|
||||||
|
| [Salva em filesDir/os_photos/OS_...jpg]
|
||||||
|
| |
|
||||||
|
| v
|
||||||
|
+<----------------------------+
|
||||||
|
|
|
||||||
|
v
|
||||||
|
[Coil renderiza imagem local sem erro HTTP 403]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Principais Benefícios do Download Sob Demanda:
|
||||||
|
- **Zero consumo desnecessário**: Fotos só são baixadas quando o usuário realmente abre a galeria da OS.
|
||||||
|
- **Suporte Múltiplos Celulares**: O segundo celular baixa nativamente a foto via SDK do Firebase Storage e salva no armazenamento local.
|
||||||
|
- **Resiliência e 100% Offline**: Após visualizada uma vez, a foto fica armazenada no disco local do aparelho, permitindo acesso offline em áreas sem cobertura de rede na fábrica.
|
||||||
|
- **Eliminação de Erros HTTP 403**: Ao ler a imagem direto do disco local, elimina-se qualquer rejeição de acesso por falta de token nas requisições HTTP REST.
|
||||||
|
|||||||
Reference in New Issue
Block a user