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.