teste
/
testes
Template
2
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects 1 Releases Wiki Activity
testes/docs/Regras_Dev.md

7.7 KiB
Raw Blame History

🤖 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)

export const PointCard = ({ data }) => {
  return (
    <Card className="hover:shadow-md transition-all">
      {/* ... */}
    </Card>
  );
};

2. Hooks para Lógica de Negócio

export const useAuth = () => {
  const login = async (credentials) => {
    // Implementação
  };
  return { login };
};

3. JSDoc para Documentação (Recomendado)

/**
 * @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.