docs: update project documentation to include detailed Room entities, sync flow, and README execution guide

This commit is contained in:
Jhony Cesar
2026-08-06 12:17:57 -04:00
parent 6345aac22e
commit 3578697d60
3 changed files with 276 additions and 124 deletions

View File

@@ -115,20 +115,57 @@ Representa o estado atualizado de uma Ordem de Serviço (OS).
* `1%` a `99%` -> `ActivityStatus.EM_ANDAMENTO` ("Em andamento")
* `100%` -> `ActivityStatus.CONCLUIDO` ("Concluído")
### 3.2. Entidade: `OSUpdateHistory` (Tabela: `os_update_history`)
Armazena a trilha detalhada de atualizações aplicadas a cada OS. É o elemento fundamental para o sincronismo transacional.
### 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` | `Long` | Primária (Auto) | Identificador sequencial do log. |
| `numeroOs` | `String` | - | Relaciona o registro à OS correspondente. |
| `timestamp` | `Long` | - | Data/hora exata em que o log foi registrado. |
| `percentualAnterior`| `Int` | - | Progresso antes do salvamento da alteração. |
| `percentualNovo` | `Int` | - | Novo progresso cadastrado pelo usuário. |
| `observacao` | `String?` | - | Observação descritiva inserida no momento da atualização. |
| `fotoPath` | `String?` | - | Foto de evidência vinculada a este incremento de progresso. |
| `recurso` | `String` | - | Identificação do responsável que executou a modificação. |
| `emailEditor` | `String?` | - | Email da conta do Google do usuário editor (auditoria). |
| `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. |
---