# PlatformSistemas

<!-- Test for auto-sync -->
Sistema de gestão integrada desenvolvido em React + TypeScript + Vite.

## 🚀 Repositório

- **Remote**: https://git.itguys.com.br/itguys_dev/Workspace
- **Branch**: `frontend_React`

## 📋 Índice

- [Início Rápido](#início-rápido)
- [Scripts Disponíveis](#scripts-disponíveis)
- [Git Auto-Sync](#git-auto-sync)
- [Estrutura do Projeto](#estrutura-do-projeto)
- [Tecnologias](#tecnologias)
- [Desenvolvimento](#desenvolvimento)

## 🎯 Início Rápido

### Pré-requisitos

- Node.js (v18 ou superior)
- npm ou yarn
- Git

### Instalação

```bash
# Clone o repositório
git clone https://git.itguys.com.br/itguys_dev/Workspace.git
cd PlatformSistemas

# Instale as dependências
npm install

# Configure as variáveis de ambiente
cp .env.example .env
# Edite o arquivo .env com suas configurações

# Inicie o servidor de desenvolvimento
npm run dev
```

## 📜 Scripts Disponíveis

```bash
# Desenvolvimento
npm run dev              # Inicia o servidor de desenvolvimento

# Build
npm run build            # Gera build de produção
npm run preview          # Preview do build de produção

# Qualidade de Código
npm run lint             # Executa ESLint

# Git Auto-Sync
npm run git:sync         # Inicia monitoramento Git com build automático
npm run git:sync:nobuild # Inicia monitoramento Git sem build automático

# Agentes de Automação
npm run agent:git:commit      # Commit automático por dia
npm run agent:git:commit:dry  # Dry-run do commit automático
npm run agent:docs:update     # Atualização automática de documentação
npm run agent:check           # Verificação do orchestrator
```

## 🔄 Git Auto-Sync

O **Git Auto-Sync** é um sistema de automação que monitora alterações no projeto e realiza commits/push automáticos.

### Como Usar

```bash
# Com build automático (recomendado para produção)
npm run git:sync

# Sem build automático (mais rápido para desenvolvimento)
npm run git:sync:nobuild
```

### Características

- ✅ Monitoramento em tempo real de alterações
- ✅ Debounce de 10 segundos (agrupa alterações)
- ✅ Build automático antes de cada commit
- ✅ Filtragem inteligente de arquivos
- ✅ Mensagens de commit descritivas

### Documentação Completa

Para mais detalhes, consulte [GIT-AUTO-SYNC.md](./GIT-AUTO-SYNC.md)

## 📁 Estrutura do Projeto

```
PlatformSistemas/
├── src/
│   ├── components/      # Componentes reutilizáveis
│   │   ├── shared/      # Componentes compartilhados
│   │   └── ui/          # Componentes Shadcn UI
│   ├── features/        # Features do sistema (Domain-Driven)
│   │   ├── auth/        # Autenticação
│   │   ├── financeiro-cnab/  # CNAB - Remessas e Pagamentos
│   │   ├── financeiro-v2/    # Financeiro V2 - Contas a Receber/Pagar
│   │   ├── fleet-v2/    # Gestão de Frota V2
│   │   ├── gr/          # Gestão de Registros (GR)
│   │   ├── rh/          # Recursos Humanos
│   │   ├── workspace/   # Workspace Financeiro
│   │   ├── autolab/     # AutoLab - Gestão de Oficina
│   │   ├── dev-tools/   # Ferramentas de Desenvolvimento
│   │   └── portal/      # Portal Principal
│   ├── services/        # Serviços e APIs
│   ├── hooks/           # Custom hooks globais
│   ├── utils/           # Utilitários
│   └── index.css        # Estilos globais
├── docs/                # Documentação do projeto
├── .agent/              # Agentes de automação
├── public/              # Arquivos públicos
├── .env                 # Variáveis de ambiente
├── git-auto-sync.ps1    # Script de automação Git
└── package.json         # Dependências e scripts
```

## 🎯 Módulos e Ambientes

### 👥 RH (Recursos Humanos)
Módulo desenvolvido para atender integralmente as demandas dos setores de RH e Departamento Pessoal.
- **Funcionalidades**: Gestão de funcionários, controle de ponto eletrônico, processamento de benefícios e cálculos trabalhistas.
- **Destaque**: Dashboards de contratos de experiência e acompanhamento de admissões.

### 💰 CNAB (Financeiro Remessas)
Módulo financeiro especializado na interface bancária e automação de pagamentos.
- **Funcionalidades**: Geração e gerenciamento de remessas CNAB, cadastro de favorecidos, processamento de arquivos de retorno e validação de pagamentos TED/PIX.

### 🚛 Prafrota (Gestão de Frota)
Sistema robusto para o controle operacional de frotas de veículos.
- **Funcionalidades**: Cadastro técnico de veículos, monitoramento em tempo real, gestão de manutenções preventivas/corretivas e controle de abastecimentos.

### 🏦 Financeiro_V2 + Workspace
Solução avançada para gestão financeira estratégica e operacional.
- **Funcionalidades**: Gestão de contas a pagar e receber, fluxo de caixa projetado vs. realizado, conciliação bancária automatizada e dashboards de indicadores financeiros (KPIs).

### 🍊 OestePan (Customização Prafrota)
Segmento especializado do Prafrota customizado especificamente para as necessidades logísticas da Oeste Pan.
- **Funcionalidades**: Além das funções base do Prafrota, inclui integração com Moki para checklists, gestão específica de sinistros e visualização otimizada para a operação do cliente.

### 🔬 AutoLab (Gestão de Oficinas)
Módulo em fase de finalização focado na operação técnica de oficinas.
- **Funcionalidades**: Controle de estoque de peças, gestão de ordens de serviço (vendas), cadastro de clientes e configurações técnicas de atendimento.

---

## 🛣️ Estrutura de Rotas e Variáveis

Cada ambiente consome uma API RESTful estruturada para operações de CRUD (Apresentação, Edição e Exclusão).

### Padrão de Endpoints
As rotas seguem a nomenclatura do recurso base (ex: `/prafrot`, `/workspace`):

- **Apresentação (GET)**: 
    - `/recurso/apresentar`: Lista principal de dados.
    - `/recurso/listagem`: Alternativa para listagens simplificadas.
    - `/recurso/:id`: Detalhamento de um registro específico.
- **Edição/Atualização (PUT/PATCH)**:
    - `/recurso/edit`: Atualização de campos específicos.
    - `/recurso/:id`: Atualização completa do registro.
    - `/recurso/edit/status_global`: Utilizado em Kanbans para movimentação de cards.
- **Exclusão (DELETE)**:
    - `/recurso/delete/:id`: Remoção lógica ou física do registro.

---

## 🎨 Design System & Playground

O projeto utiliza um laboratório de componentes (**Playground**) para garantir consistência visual em todos os ambientes.

### Componentes em Uso (Playground)
Estes componentes são extraídos do Design System e aplicados nos módulos:

| Componente | Função | Ambientes Principais |
| :--- | :--- | :--- |
| **ExcelTable** | Tabela de alta performance com filtros | RH, Prafrota, Financeiro |
| **ItemDetailPanel** | Painel lateral para visualização de detalhes | Prafrota, OestePan |
| **DashboardKPICard** | Cards de indicadores com micro-gráficos | Financeiro_V2, Workspace |
| **StatsGrid** | Grid de estatísticas rápidas | RH, Prafrota |
| **KanbanBoard** | Gestão visual de fluxos e status | GR, RH |
| **AutoFillInput** | Inputs inteligentes com busca em tempo real | Workspace, Financeiro |
| **StatusBadge** | Badges coloridos de status dinâmico | Todos |

### Componentes Disponíveis (Candidatos)
Componentes presentes no laboratório mas com uso restrito ou em homologação:
- `ThemeTuner`: Ferramenta de ajuste de temas em runtime.
- `FinesCard`: Card especializado para visualização de multas.
- `SmartTable`: Versão experimental de tabelas com auto-ajuste.

---

## 🛠️ Tecnologias

### Core
- **React 19** - Biblioteca UI
- **TypeScript** - Superset JavaScript
- **Vite** - Build tool e dev server

### UI/UX
- **TailwindCSS** - Framework CSS
- **Radix UI** - Componentes acessíveis
- **Framer Motion** - Animações
- **Lucide React** - Ícones

### Estado e Formulários
- **Zustand** - Gerenciamento de estado
- **React Hook Form** - Formulários
- **Zod** - Validação de schemas

### Roteamento e Requisições
- **React Router DOM** - Roteamento
- **Axios** - Cliente HTTP

### Gráficos
- **Recharts** - Biblioteca de gráficos

## 💻 Desenvolvimento

### Variáveis de Ambiente

Copie `.env.example` para `.env` e configure:

```env
VITE_API_URL=https://dev.workspace.itguys.com.br/api
VITE_APP_NAME=PlatformSistemas
```

### Padrões de Código

- **Componentes**: Use componentes funcionais com hooks
- **Tipagem**: Sempre utilize TypeScript
- **Estilos**: Prefira TailwindCSS
- **Estado**: Use Zustand para estado global
- **Formulários**: Use React Hook Form + Zod

### ESLint

O projeto usa ESLint para garantir qualidade de código:

```bash
npm run lint
```

### Estrutura de Componentes

```tsx
// Exemplo de componente
import { useState } from 'react'
import { Button } from '@/components/ui/button'

interface MyComponentProps {
  title: string
  onAction?: () => void
}

export function MyComponent({ title, onAction }: MyComponentProps) {
  const [state, setState] = useState(false)
  
  return (
    <div className="p-4">
      <h2 className="text-xl font-bold">{title}</h2>
      <Button onClick={onAction}>Ação</Button>
    </div>
  )
}
```

## 🔐 Segurança

- Nunca commite arquivos `.env` (já está no `.gitignore`)
- Use variáveis de ambiente para dados sensíveis
- Mantenha dependências atualizadas

## 📝 Documentação Adicional

- [Git Auto-Sync](./GIT-AUTO-SYNC.md) - Documentação completa do sistema de automação
- [API Report](./RELATORIO_API.md) - Relatório de APIs utilizadas
- [Regras de Desenvolvimento](./docs/Regras_Dev.md) - Padrões e regras do projeto
- [AI Rules - Debug Components](./docs/AI_RULES_DEBUG_COMPONENTS.md) - Regras para componentes versionados
- [Teste Formulário GR](./docs/TESTE_FORMULARIO_GR.md) - Documentação de testes do módulo GR

## 🤝 Contribuindo

1. Crie uma branch para sua feature (`git checkout -b feature/MinhaFeature`)
2. Faça commit das suas alterações (`git commit -m 'Adiciona MinhaFeature'`)
3. Push para a branch (`git push origin feature/MinhaFeature`)
4. Abra um Pull Request

Ou simplesmente use o **Git Auto-Sync** para automação completa! 🚀

## 📄 Licença

Este projeto é propriedade da ITGuys.

---

**Desenvolvido com ❤️ pela equipe ITGuys**
