# 🤖 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:
1.  **Toggle de Versão**: Permite alternar entre a versão `PRODUCTION` (estável) e `DEBUG` (laboratório) de um componente.
2.  **Isolamento de Tema**: Testa componentes em Light/Dark mode sem afetar o resto da app.
3.  **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.
```javascript
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:
```javascript
{
  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

1.  **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.
2.  **NUNCA** importe o arquivo `.debug.jsx` em views reais da aplicação (Dashboard, Relatórios). Ele deve ser importado APENAS no `PlaygroundView.jsx`.
3.  **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)