# 🤖 INSTRUÇÕES ESPECÍFICAS PARA IA - INTEGRA FINANCE (REACT)

## 🎯 OBJETIVO
Fornecer contexto detalhado para que a IA compreenda o projeto Integra Finance (PRALOG) em sua nova arquitetura React e possa oferecer sugestões precisas, seguindo os padrões de alta performance e design premium.

## 📋 CONTEXTO TÉCNICO ESSENCIAL

### Arquitetura Atual
- **Framework**: React 18+ com Vite.
- **Linguagem**: JavaScript (Moderno/ES6+).
- **Estilização**: Tailwind CSS (Mobile-first, Design System Atômico).
- **UI library**: Shadcn UI (Radix UI + Lucide).
- **Conceito**: Arquitetura Modular (Encapsulamento de features).
- **Estado**: Zustand (Global) + React Context (Módulos).
- **Padrão Principal**: Domain-Driven Feature Folders (Módulos em `src/features/`).

### Template de Referência OBRIGATÓRIO (Módulo RH)
**Localização**: `src/features/rh/ponto-eletronico/`
Deve conter:
- ✅ Hook customizado para lógica (`usePonto.js`).
- ✅ Componentes de apresentação isolados.
- ✅ Tratamento de geolocalização e erros null-safe.
- ✅ Animações Framer Motion ou Tailwind Keyframes.

### Estrutura de Pastas Obrigatória
```
src/
├── components/
│   ├── ui/             # Componentes Shadcn (NUNCA EDITAR MANUALMENTE)
│   └── shared/         # Componentes transversais (Ex: StatCard, PageHeader)
├── features/           # Domínios de negócio (FOLDER POR FEATURE)
├── hooks/              # Hooks globais (Ex: useTheme, useAuth)
├── services/           # Integrações com API (Axios/React Query)
└── utils/              # Formatadores e validadores
```

## 🛠️ PADRÕES DE DESENVOLVIMENTO

### 1. Componentes Funcionais (OBRIGATÓRIO)
```jsx
export const PointCard = ({ data }) => {
  return (
    <Card className="hover:shadow-md transition-all">
      {/* ... */}
    </Card>
  );
};
```

### 2. Hooks para Lógica de Negócio
```javascript
export const useAuth = () => {
  const login = async (credentials) => {
    // Implementação
  };
  return { login };
};
```

### 3. JSDoc para Documentação (Recomendado)
```javascript
/**
 * @typedef {Object} User
 * @property {string} id
 * @property {string} name
 * @property {'active' | 'inactive'} status
 */
```

## 🎨 COMPONENTES COMPARTILHADOS PRINCIPAIS

### StatsGrid
**Localização**: `src/components/shared/StatsGrid.jsx`
- Grid responsivo de KPIs com suporte a ícones e tendências.

### DataTable
**Localização**: `src/components/shared/DataTable.jsx`
- Wrapper sobre o `Table` do Shadcn com paginação e busca interna.

### AppLayout
**Localização**: `src/components/layout/AppLayout.jsx`
- Define a estrutura de Sidebar, Header e Main Content.

## 🏗️ ARQUITETURA DE AMBIENTES E ISOLAMENTO

### Conceito de Ambiente
Um "Ambiente" (ex: Financeiro, RH, Frota) é um ecossistema isolado dentro do projeto.
- **Estrutura**: Composto por um Sidebar lateral, Header específico e um conjunto de módulos/telas.
- **Independência**: Cada ambiente deve ser autossuficiente. Evite dependências cruzadas entre ambientes.

### Regra de Ouro: Isolamento Total
- **Modificação Segura**: Ao ajustar um ambiente, a IA **NUNCA** deve alterar componentes internos de outro ambiente.
- **Localização de Componentes**: Componentes que pertencem apenas a um ambiente devem residir em `src/features/[ambiente]/components/`.
- **Uso de Shared**: Somente use `src/components/shared` para elementos verdadeiramente universais (ex: Botões base, Inputs padrão). Se uma alteração no `shared` puder quebrar outro ambiente, crie uma cópia local no ambiente em desenvolvimento ou use variantes/props.

## 🎨 IDENTIDADE VISUAL E TEMAS POR MÓDULO

### Padrão de Cores Único
- Cada ambiente deve possuir uma paleta de cores distinta para facilitar a orientação do usuário.
- **Implementação**: Utilize variáveis CSS ou o sistema de temas do Tailwind configurado via `EnvironmentProvider` ou classes de escopo no container raiz do ambiente (ex: `<div className="theme-financeiro">`).

### Design Premium
- Use gradientes sutis, micro-animações (Framer Motion) e sombras suaves para diferenciar os ambientes, mantendo a consistência da marca Integra Finance.

## 🛰️ CAMADA DE DADOS E COMUNICAÇÃO (AXIOS)

### Melhores Práticas com Axios
1. **Instância Central**: Use sempre a instância configurada em `src/services/api.js`.
2. **Organização de Serviços**: Cada feature deve ter seu próprio arquivo de serviço (`[feature]Service.js`) que encapsula as chamadas de API.
3. **Adaptadores (Data Mapping)**: Transforme os dados da API para o formato ideal do componente dentro do Service. O componente não deve conhecer a estrutura bruta do banco de dados.
4. **Tratamento de Erros**:
   - Implemente `try/catch` nos services ou hooks.
   - Use interceptores para gerenciar tokens expirados (401) e erros globais.
   - Forneça feedbacks amigáveis ao usuário via Toasts ou alertas.

## 🧪 QUALIDADE E TESTES

### Regras de Validação de Novas Funcionalidades
Toda nova feature ou ambiente desenvolvido deve seguir este protocolo:
1. **Sanity Check**: O ambiente carrega todos os submódulos sem erros de console.
2. **Validação de Fluxo**: Testar o caminho feliz (uso normal) e caminhos de erro (API offline, campos vazios).
3. **Testes Propostos**: A IA deve sugerir ou implementar testes (Unitários para hooks e Integração para componentes críticos) utilizando ferramentas como Vitest/React Testing Library, garantindo que "erros bobos" não cheguem à produção.

## ⚡ PERFORMANCE E OTIMIZAÇÃO

### Diretrizes para um Projeto Leve
1. **Code Splitting (Lazy Loading)**: Carregue cada ambiente dinamicamente usando `React.lazy()` e `Suspense` nas rotas principais.
2. **Memoização Estratégica**: Use `useMemo` e `useCallback` para evitar re-renderizações desnecessárias em componentes pesados (Gráficos, Tabelas grandes).
3. **Aset Management**: Minimize o uso de bibliotecas externas pesadas. Sempre prefira soluções nativas ou componentes Shadcn já existentes.
4. **Otimização de Imagens/Ícones**: Use ícones vetoriais (Lucide) e comprima imagens geradas.

## 📝 REGRAS ESPECÍFICAS PARA SUGESTÕES

### SEMPRE Fazer:
1. **Verificar** componentes existentes no Shadcn antes de criar novos.
2. **Encapsular** lógica dentro da pasta `features/`.
3. **Usar** um arquivo `index.js` em cada feature para expor apenas o necessário (Public API).
4. **Isolar** o ambiente em desenvolvimento para não afetar outros módulos.
5. **Adicionar** comentários em português explicativos sobre a lógica de isolamento.
6. **Validar** performance após grandes adições de código.
7. **Usar** Tailwind para 100% da estilização.
8. **Conceito modular** Desenvolva seguindo os conceitos mais modernos e de melhores práticas em construção modular com React.

### NUNCA Fazer:
1. ❌ Importar componentes privados de um ambiente em outro.
2. ❌ Criar lógica de negócio global que seja específica de apenas um módulo.
3. ❌ Ignorar o bundle size ao adicionar novas dependências.
4. ❌ Criar componentes gigantes (> 200 linhas).

## 🛰️ CAMADA DE DADOS E COMUNICAÇÃO (DAL - RESUMO)

### 1. Estrutura de Comunicação Híbrida (API + MOCK)
Toda funcionalidade deve ser construída seguindo o padrão de Provider Centralizado. A IA deve garantir que o Front-end seja capaz de rodar 100% offline via alternância de flag.

### 2. Padrão de Implementação de Service
Obrigatório seguir o contrato de latência simulada para Mocks e tratamento de dados centralizado.

## 🚨 CONFIGURAÇÃO DE DESENVOLVIMENTO
- ✅ **Comando para Rodar**: `npm run dev`
- ✅ **Linter**: ESLint + Prettier

**IMPORTANTE**: Esta documentação é a verdade única para o padrão de código. Priorize o isolamento, a performance e a experiência premium por ambiente.