4.4 KiB

Raw Blame History

🤖 AI RULES - AMBIENTE DE DEBUG & COMPONENTES VERSIONADOS

🎯 OBJETIVO

Definir as regras, arquitetura e padrões obrigatórios para o desenvolvimento e manutenção do ambiente de Debug (src/features/dev-tools) e criação de componentes versionados no projeto Integra Finance.

🏗️ ARQUITETURA DE DEBUG (PLAYGROUND)

O ambiente de Debug é um espaço isolado para criar, testar e documentar componentes antes de integrá-los à produção. Localização Principal: src/features/dev-tools/views/PlaygroundView.jsx

Principais Funcionalidades:

Toggle de Versão: Permite alternar entre a versão PRODUCTION (estável) e DEBUG (laboratório) de um componente.
Isolamento de Tema: Testa componentes em Light/Dark mode sem afetar o resto da app.
Preview Responsivo: Modos Desktop, Tablet e Mobile.

🧬 PADRÃO DE VERSIONAMENTO DE COMPONENTES (DUAL-VERSION)

Para componentes complexos ou que exigem testes exaustivos de UI, adotamos o padrão de Componente Versionado. Isso separa o código de produção do código de laboratório.

Estrutura de Pastas Obrigatória:

Todo componente versionado deve seguir esta estrutura exata:

src/features/[feature]/components/[NomeComponente]/
├── index.js                # Entry point (Exporta a versão de Produção por padrão)
├── [Componente].jsx        # Versão de PRODUÇÃO (Limpa, funcional, sem mocks visuais)
└── [Componente].debug.jsx  # Versão de DEBUG (Wrapper com controles, knobs e mocks)

Regras por Arquivo:

1. `index.js`

Deve exportar o componente de produção como default para garantir importações limpas no resto do sistema.

export { StatusBadge } from './StatusBadge';
export { StatusBadge as default } from './StatusBadge';

2. `[Componente].jsx` (Produção)

Deve ser puro e focado na funcionalidade final.
Recebe props via interface definida.
NÃO deve conter botões de teste, logs visuais ou dados mockados hard-coded na renderização final.

3. `[Componente].debug.jsx` (Debug / Laboratório)

Deve importar e renderizar o componente de produção.
Pode (e deve) conter:
- Estado local para controlar props do componente filho.
- Botões para simular ações (ex: "Simular Erro API").
- Logs visuais de eventos (onSelect, onClick).
- Wrapper visual (Cards, Grids) para facilitar o teste.

📝 REGISTRO NO PLAYGROUND

Para que um componente apareça no Playground (PlaygroundView.jsx), adicione-o à constante componentsList.

Contrato do Objeto de Componente:

{
  name: 'NomeDoComponente',
  description: 'Descrição breve do que ele faz.',
  props: { ...exemploDeProps }, // Usado para gerar a tabela de documentação e o snippet de código
  
  // RENDERIZADOR PADRÃO (Produção)
  // Obrigatório. Mostra como o componente é usado na vida real.
  render: (props) => <MeuComponente {...props} />,

  // RENDERIZADOR DE DEBUG (Opcional)
  // Se definido, será usado quando o toggle "Debug" estiver ativado.
  // Geralmente renderiza o componente .debug.jsx
  debugRender: (props) => <MeuComponenteDebug {...props} /> 
}

🎨 DIRETRIZES DE UI/UX PARA O DEBUG

1. ExcelTable & Temas

Componentes complexos como ExcelTable devem respeitar o tema dark/light propagado pelo container pai.
Teste sempre a legibilidade em ambos os temas.

2. AutoFillInput & Formulários Dinâmicos

Inputs de pesquisa (AutoFillInput) no modo Debug devem demonstrar fluxos reais.
Criação Dinâmica: Ao invés de apenas logar "Criar", implemente uma lógica que capture o termo pesquisado e preencha um formulário de exemplo.
Feedback Visual: Use cores de texto com alto contraste (Preto no Light, Branco no Dark) dentro dos inputs.

🚫 O QUE NÃO FAZER

NUNCA deixe código de debug (console.log, bordas de teste vermelhas) no arquivo [Componente].jsx (Produção). Use o arquivo .debug.jsx para isso.
NUNCA importe o arquivo .debug.jsx em views reais da aplicação (Dashboard, Relatórios). Ele deve ser importado APENAS no PlaygroundView.jsx.
EVITE quebrar o build de produção. O PlaygroundView e seus imports de debug devem ser isolados ou tree-shakeable se possível (embora em dev-tools internal isso seja menos crítico, mantenha a higiene).

Última Atualização: 2026-01-11 (Implementação do Sistema Dual-Version)

4.4 KiB Raw Blame History