melhorando documentacao

This commit is contained in:
Jhony Cesar
2026-07-27 18:36:43 -04:00
parent 1f468880f9
commit 8e063f6c64
2 changed files with 127 additions and 11 deletions

View File

@@ -0,0 +1,122 @@
# Especificação de Design e Recursos Visuais
Esta documentação descreve os recursos visuais e a estrutura de tela do aplicativo **Gestão de Manutenção (Cargill Parada OS)** baseando-se no layout atual de produção (conforme print do app em execução).
O objetivo deste documento é servir de guia detalhado para inteligências artificiais (como Google Studio / Stitch) expandirem a complexidade do aplicativo, adicionando novas telas, fluxos de navegação e componentes visuais mais robustos.
---
## 1. Análise da Identidade Visual e Estilo (Design System)
O aplicativo utiliza um visual moderno que busca equilibrar a seriedade industrial com a identidade visual da marca Cargill.
* **Paleta de Cores:**
* **Fundo Geral:** Cinza neutro muito claro (`#F5F7F6` / `LightGrey`), reduzindo a fadiga visual sob luz solar em campo.
* **Cor Primária (Destaques da Marca):** Verde Cargill escuro (`#005F40`), utilizado no cabeçalho do usuário, botões de ação prioritários e nos chips selecionados.
* **Cor Secundária (Textos e Títulos):** Preto carvão (`#1A1A1A`), oferecendo alto contraste para textos e números.
* **Cores de Status (Feedback Visual):**
* *Concluído/Sincronizado:* Verde folha (`#E8F5E9` para fundo, `#005F40` para ícone/texto).
* *Em Andamento:* Azul suave (`#E3F2FD` para fundo, `#1E88E5` para o indicador de progresso e badges).
* *Não Iniciado:* Tons de cinza médio (`#ECEFF1` / `#78909C`).
* **Tipografia:** Fonte Sans-Serif limpa e de alta legibilidade, com variações de peso (Bold para títulos de OS e contadores métricos, Medium para subtítulos e chips, Regular para prazos e descrições).
* **Formatos e Contornos:** Uso de cartões elevados (`Card` / `Surface`) com cantos arredondados generosos (`16.dp` a `24.dp`), sombras suaves (`shadow` / `elevation` baixa) e bordas finas para delimitação visual clara.
---
## 2. Descrição Detalhada dos Componentes da Tela Principal
A tela única atual ([`MaintenanceDashboardScreen.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/ui/screens/MaintenanceDashboardScreen.kt)) está estruturada verticalmente nas seguintes seções:
### 2.1. Barra Superior de Controle (App Bar)
* **Título:** `"Gestão OS"` alinhado à esquerda.
* **Indicador de Conectividade:** Um Box quadrado verde-claro com um ícone de nuvem (`Cloud`) verde escuro, demonstrando se o app está online e pareado.
* **Ação de Sincronismo:** Botão circular com ícone de setas giratórias (`Sync`) que rotaciona visualmente quando o processo assíncrono de sincronização bidirecional com o Google Sheets está ativo.
* **Painel de Usuário:** Card do Google Sign-In exibindo a foto do perfil (ou inicial do nome `"J"`), o nome do usuário (`"Jhony"`), o e-mail (`"cesarjhony@gmail.com"`) e uma seta indicativa de dropdown para logout ou troca de conta.
### 2.2. Painel de Métricas da Parada (KPI Dashboard)
* **Estrutura:** Card branco elevado com cantos arredondados contendo o título `"Progresso Parada Industrial"` e subtítulo `"Visão Geral de Campo"`.
* **Gráfico de Progresso Global:** Um indicador de progresso circular (`CircularProgressIndicator` verde) localizado no canto superior direito, exibindo a porcentagem de tarefas finalizadas (atualmente em `2%`).
* **Contadores de Metas (Grid de Indicadores):** Quatro colunas horizontais exibindo:
* `▶ 595` / *Não Inic.* (Cinza)
* `☁ 9` / *Em Andam.* (Azul)
* `✔ 13` / *Concluídas* (Verde)
* `🔧 617` / *Total OSs* (Preto)
### 2.3. Campo de Pesquisa Dinâmica
* **Design:** Caixa de texto de largura total, com cantos arredondados, ícone de lupa (`Search`) e placeholder `"Buscar por OS, descrição..."`.
* **Comportamento:** Filtra a lista instantaneamente enquanto o usuário digita.
### 2.4. Grade Modular de Filtros (Chips de Categoria)
O app organiza os filtros em 5 linhas horizontais com rolagem lateral (`LazyRow`). Cada categoria inicia com o chip `"Todos"` ou `"Todas"` ativo na cor verde escura:
1. **Setor:** Opções como `"Todos"`, `"COGERAÇÃO"`, `"EXTRAÇÃO"`, `"PREPARAÇÃO"`.
2. **Equipe:** Opções como `"Todas"`, `"Mecânica"`, `"Elétrica"`, `"Confiabilidade"`.
3. **Status:** Opções como `"Todos"`, `"Não iniciado"`, `"Em andamento"`, `"Concluído"`.
4. **Data:** Opções como `"Todas"`, `"04/08/26"`, `"08/08/26"`, `"09/08/26"`.
5. **Recurso (Técnico):** Opções como `"Todos"`, `"ADILSON"`, `"AGIL"`, `"ALAN"`, `"ALEX"`.
### 2.5. Cartão de Cronograma Geral do Projeto
* **Título:** `"Ordens de Serviço (617)"` acompanhado de um ícone de maximizar/redimensionar grade no canto direito.
* **Barra de Progresso:** Um indicador linear horizontal (`LinearProgressIndicator` azul) que marca visualmente `75%` de avanço (progresso temporal do cronograma da parada).
* **Prazos:** Subtexto detalhado mostrando a janela de execução (ex: `"Prazo: qui. 27/08/26 07:00 até qui. 27/08/26 17:00"`).
### 2.6. Lista de Cartões de Ordens de Serviço (OS Cards)
* **Visual da Linha:** Um card branco com contorno fino e espaçamento confortável.
* **Código e Sincronismo:** Identificador da OS (ex: `"OS-1019"`) seguido de um ícone de nuvem com check verde indicando pareamento perfeito com o banco central.
* **Badge de Status:** Um marcador com cor temática no canto superior direito (ex: `"Em andamento"` com fundo azul claro e texto azul escuro).
* **Subtexto:** Código do TAG/Equipamento (ex: `"CV-101001"`).
---
## 3. Diretrizes para Adicionar Telas e Aumentar a Complexidade
Para expandir o aplicativo de sua estrutura atual de tela única ("Single Screen Dashboard") para um ecossistema multiplataforma robusto de campo, a inteligência artificial deve seguir as seguintes diretrizes de expansão:
```
[Fluxo de Navegação Sugerido]
+------------------------+
| Dashboard Principal | (Tela Atual)
+-----------+------------+
|
+---------------------+---------------------+
| (Clique na OS) | (Clique em Métricas/Analítico)
v v
+------------------------+ +------------------------+
| Detalhes da OS | | Dashboard Analítico M3 |
+--------+---------------+ +------------------------+
|
+---------------------+
| (Anexar Evidência) | (Ver Histórico)
v v
+-----------------+ +-----------------+
| Scanner & Foto | | Auditoria & |
| Real (CameraX) | | Timeline |
+-----------------+ +-----------------+
```
### 3.1. Proposta de Novas Telas
1. **Tela de Detalhes Aprofundados da OS (`OSDetailScreen`):**
* *Recurso:* Exibição de árvore de sub-tarefas (checklists de segurança, permissões de trabalho - PT).
* *Recurso:* Visualização e zoom de fotos anexadas em alta definição.
* *Recurso:* Lista de materiais e ferramentas necessárias separadas por equipe.
* *Recurso:* Campo para coleta de assinatura digital do inspetor e do supervisor de área para encerramento da OS.
2. **Tela de Linha do Tempo e Auditoria Geral (`TimelineAuditoriaScreen`):**
* *Recurso:* Feed contínuo contendo todas as atualizações de todas as OSs efetuadas pelos técnicos em campo na parada atual, exibindo quem alterou, quando alterou, o que alterou (observações) e fotos vinculadas.
3. **Tela de Métricas Analíticas Avançadas (`AnalyticsScreen`):**
* *Recurso:* Gráficos de barra de produtividade por Equipe (ex: Mecânica concluiu X%, Elétrica concluiu Y%).
* *Recurso:* Gráfico de linha acumulado ("S-Curve") comparando o planejado com o realizado.
* *Recurso:* Gráfico de quebras (Pareto) listando os setores com maior número de anomalias relatadas nas observações.
4. **Tela de Configurações do Planejador PCM (`SettingsScreen`):**
* *Recurso:* Formulário para alterar dinamicamente o ID da Planilha Google Sheets ativa.
* *Recurso:* Status de cota e conexão da API do Google, permitindo testar credenciais em tempo real.
* *Recurso:* Console para forçar limpezas na base SQLite ou exportar backup do banco de dados local.
### 3.2. Proposta de Recursos Técnicos para Implementação Visando Complexidade
1. **Câmera Nativa com Upload Real (Google Drive):**
* Substituir o simulador de fotos estáticas (`mockPhotos`) por uma tela de captura utilizando **CameraX**.
* A imagem tirada deve ser armazenada localmente temporizada em cache, e enviada ao Google Drive por meio de uma API assíncrona. O link público direto gerado pelo Drive deve ser gravado no campo `fotoPath` no banco local e subido para a aba `history` do Sheets.
2. **Scanner Integrado de QR Code / Código de Barras:**
* Adicionar um botão de câmera na barra de pesquisa.
* Ao clicar, abre-se um visor de scanner. O técnico aponta para a etiqueta física colada no motor ou bomba (TAG), o app decodifica o código (ex: `CV-101001`) e abre diretamente a tela de edição de progresso da OS vinculada àquela TAG.
3. **Sincronização em Segundo Plano Resiliente (WorkManager):**
* Substituir o clique manual em "Sincronizar" por um agendador automático em segundo plano que detecta conectividade Wi-Fi e envia logs pendentes sem travar ou exigir ação do inspetor.

View File

@@ -82,16 +82,10 @@ Abaixo está o levantamento detalhado de cada um desses elementos, com suas resp
## 5. Carga de Dados Inicial em Caso de Falha de Conexão (Fallback)
* **Status:** **Simulado (Mock Data Fallback)**
* **Status:** **Removido**
* **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)
* [`MaintenanceViewModel.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/ui/viewmodel/MaintenanceViewModel.kt)
* [`MaintenanceRepository.kt`](file:///home/cesarjhony/dev/projects/gestao_de_manutencao/app/src/main/java/com/example/data/repository/MaintenanceRepository.kt)
* **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.
Anteriormente, o sistema realizava o carregamento automático de dados simulados/modelo (`loadSampleData()`) caso ocorresse uma falha na primeira sincronização com as planilhas do Google Sheets ou através de botões manuais na UI. Este mecanismo de fallback de dados fictícios foi removido do aplicativo.
* **Impacto/Limitação:** O aplicativo não popula mais dados simulados automaticamente ou sob demanda na base SQLite local, garantindo integridade estrita aos dados reais vindos das planilhas Google Sheets ou de importação manual do CSV real do PCM. Se a sincronização inicial falhar e o banco local estiver vazio, o aplicativo exibirá a falha de sincronização e manterá a listagem limpa.