163 lines
7.7 KiB
Markdown
163 lines
7.7 KiB
Markdown
# 🤖 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.
|