102 lines
4.4 KiB
Markdown
102 lines
4.4 KiB
Markdown
# 🤖 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)
|