feat: implement OSFinding management to support tracking safety, maintenance, and observation findings with automated synchronization.

This commit is contained in:
Jhony Cesar
2026-08-05 20:35:17 -04:00
parent 1cb8578e9b
commit 2b6ec33837
9 changed files with 832 additions and 47 deletions

View File

@@ -89,20 +89,34 @@ Esta aba armazenará a lista de todas as ordens de serviço ativas na planta.
| **`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.
### 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 (Cabeçalho da Coluna A, B, C...) | Tipo Sugerido | Descrição / Observações |
| Nome da Coluna | 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. |
| **`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)
Esta aba armazena os registros ativos de Achados de Segurança, Achados de Manutenção e a Última Observação associados a cada OS.
| 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.
### 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.