forlogic-core 1.4.15 → 1.5.1

package/dist/README.md

@@ -0,0 +1,36 @@
+# 🧱 Documentação exclusiva para este projeto
+
+> **Sistema empresarial com React + TypeScript + Supabase**
+
+---
+
+## ⚙️ Configuração deste Projeto
+
+### 🗄️ Schema do Banco
+
+Schema padrão deste projeto: **`central`**
+
+## 🤖 Instruções para IA (Lovable)
+
+⚠️ **CONSULTAR SEMPRE antes de qualquer modificação:**
+
+1. **README.md da lib**: Acesse via `node_modules/forlogic-core/README.md` - Instalação e Quick Start
+2. **AI_RULES.md**: Acesse via `node_modules/forlogic-core/docs/AI_RULES.md` - **REGRAS CRÍTICAS**
+3. **Templates**: Acesse via `node_modules/forlogic-core/docs/templates/` - Códigos prontos
+4. **Hub da Docs**: Acesse via `node_modules/forlogic-core/docs/README.md` - Navegação completa
+
+**NUNCA recriar:**
+- ❌ Integração Qualiex (já existe na lib)
+- ❌ Integração Supabase (já existe na lib)
+- ❌ Sistema CRUD (usar `createCrudPage` da lib)
+- ❌ Componentes base (importar de `forlogic-core`)
+
+**SEMPRE verificar:**
+- ✅ Schema padrão do projeto
+- ✅ Templates disponíveis antes de criar do zero
+
+---
+
+## 📝 Licença
+
+MIT License - ForLogic © 2025

package/dist/docs/AI_RULES.md

@@ -0,0 +1,213 @@
+# ForLogic Core - Regras Críticas para IA
+
+⚠️ **CONSULTAR SEMPRE antes de implementar funcionalidades**
+
+**Documentação completa:** `forlogic-core/README.md` (quando instalado via npm)
+
+---
+
+## 📋 Checklist Rápido
+
+Antes de criar qualquer funcionalidade:
+
+- [ ] ✅ Verificar schema do projeto em `KNOWLEDGE.md`
+- [ ] ✅ Usar template CRUD padrão (Regra #2)
+- [ ] ✅ NÃO recriar integrações existentes (Regra #3 e #4)
+- [ ] ✅ Usar `useMemo()` em configs (Regra #5)
+- [ ] ✅ NÃO criar índices sem solicitação (Regra #6)
+
+---
+
+## ⚠️ Regra #1: Schema do Projeto
+
+**Problema:** IA usa `public` quando projeto tem schema customizado.
+
+**Solução:**
+1. **SEMPRE verificar** `KNOWLEDGE.md` → "Schema do Banco"
+2. **NUNCA assumir** schema `public`
+3. **Configurar corretamente** em todos os services
+
+**Exemplo:**
+```typescript
+// ❌ ERRADO (assume public)
+const service = createSimpleService<Employee>('employees');
+
+// ✅ CORRETO (usa schema do projeto)
+const service = createSimpleService<Employee>('employees', { 
+  schemaName: 'central' // ← schema do KNOWLEDGE.md
+});
+```
+
+**Ver detalhes:** README.md → "Quick Start" → Seção 1
+
+---
+
+## ⚠️ Regra #2: Template CRUD Padrão (Único)
+
+**Problema:** IA cria CRUDs customizados complexos desnecessariamente.
+
+**Solução:** Usar SEMPRE o template único de 4 passos:
+
+```typescript
+// 1. Service
+const service = createSimpleService<Entity>('table_name', { schemaName: 'central' });
+
+// 2. Hook
+const useCrud = () => useCrud({ service, queryKey: 'entities' });
+
+// 3. Save Handler
+const handleSave = createSimpleSaveHandler({
+  service,
+  queryClient,
+  queryKey: 'entities',
+  successMessage: 'Salvo com sucesso!',
+  errorMessage: 'Erro ao salvar'
+});
+
+// 4. Página
+export default createCrudPage({
+  useCrud,
+  columns: [...],
+  formSections: [...],
+  handleSave
+});
+```
+
+**Ver exemplos completos:** README.md → "Quick Start" → Seção 3
+
+---
+
+## ⚠️ Regra #3: Integração Qualiex
+
+**Problema:** IA recria componentes de seleção de usuários do Qualiex.
+
+**Solução:** Usar componentes prontos da lib:
+
+```typescript
+import { QualiexUserField, QualiexResponsibleSelectField } from 'forlogic-core';
+
+// Campo simples
+<QualiexUserField
+  name="user_id"
+  label="Usuário"
+  control={control}
+/>
+
+// Campo com múltipla seleção
+<QualiexResponsibleSelectField
+  name="responsibles"
+  label="Responsáveis"
+  control={control}
+  isMulti
+/>
+```
+
+**NÃO criar:** Componentes customizados, hooks próprios, integrações manuais.
+
+**Ver detalhes:** README.md → "Integrações" ou templates/qualiex-integration-example.tsx
+
+---
+
+## ⚠️ Regra #4: Integração Supabase
+
+**Problema:** IA cria cliente Supabase próprio ou configurações manuais.
+
+**Solução:** Usar setup automático via `setupQualiexCore()`:
+
+```typescript
+// src/main.tsx
+import { setupQualiexCore } from 'forlogic-core';
+
+setupQualiexCore({
+  supabaseUrl: import.meta.env.VITE_SUPABASE_URL,
+  supabaseAnonKey: import.meta.env.VITE_SUPABASE_ANON_KEY
+});
+```
+
+**NÃO criar:** Clientes Supabase manuais, configurações duplicadas.
+
+**Ver detalhes:** README.md → "Quick Start" → Seção 1
+
+---
+
+## ⚠️ Regra #5: Performance (Evitar Reloads)
+
+**Problema:** Página recarrega ao trocar de rota (sidebar pisca, estado reseta).
+
+**Causa:** Configs recriadas a cada render (ex: `sidebarConfig` sem `useMemo`).
+
+**Solução:**
+
+### ✅ Usar `useMemo()` em configs:
+```typescript
+const sidebarConfig = useMemo(() => ({
+  modules: [...]
+}), []); // ← Dependências vazias se config é estático
+```
+
+### ✅ Estruturar rotas com `<Outlet />`:
+```typescript
+<Routes>
+  <Route path="/" element={<AppLayout sidebarConfig={sidebarConfig} />}>
+    <Route index element={<HomePage />} />
+    <Route path="employees" element={<EmployeesPage />} />
+  </Route>
+</Routes>
+```
+
+**Ver detalhes:** README.md → "Quick Start" → Seção 2 ou templates/app-layout.tsx
+
+---
+
+## ⚠️ Regra #6: Índices de Banco de Dados
+
+**Problema:** IA cria índices automaticamente em migrations sem necessidade.
+
+**Solução:**
+- ✅ **NÃO criar índices automaticamente**
+- ✅ **Criar índices APENAS quando:**
+  - Usuário solicita explicitamente
+  - Performance está degradada e índice é a solução
+  - Há justificativa técnica clara
+
+**Exemplo de quando NÃO criar:**
+```sql
+-- ❌ NÃO FAZER (sem solicitação)
+CREATE INDEX idx_employees_name ON central.employees(name);
+CREATE INDEX idx_employees_created_at ON central.employees(created_at);
+```
+
+**Exemplo de quando criar:**
+```sql
+-- ✅ OK (usuário solicitou explicitamente)
+-- "Por favor, crie um índice em 'email' para acelerar as buscas"
+CREATE INDEX idx_employees_email ON central.employees(email);
+```
+
+---
+
+## 🎯 Boas Práticas
+
+### Ordem dos Providers (App.tsx)
+```typescript
+<ErrorBoundary>
+  <QueryClientProvider client={queryClient}>
+    <AuthProvider>
+      <BrowserRouter>
+        <Routes>...</Routes>
+      </BrowserRouter>
+    </AuthProvider>
+  </QueryClientProvider>
+</ErrorBoundary>
+```
+
+**Nota:** Se inverter, a própria IA verá o erro no console e corrigirá.
+
+---
+
+## 🔗 Links Úteis
+
+- **Documentação Completa:** `forlogic-core/README.md`
+- **Templates Prontos:** `forlogic-core/docs/templates/`
+- **Troubleshooting:** `forlogic-core/docs/TROUBLESHOOTING.md`
+- **Hub da Docs:** `forlogic-core/docs/README.md`

package/dist/docs/README.md

@@ -0,0 +1,102 @@
+# ForLogic Core - Documentação
+
+> **Sistema empresarial completo com React + TypeScript + Supabase**
+
+Esta é a documentação completa da biblioteca `forlogic-core` para desenvolvimento acelerado de sistemas empresariais.
+
+---
+
+## 📖 Documentação Principal
+
+### 📦 [README.md](../README.md)
+**Instalação e Quick Start**
+
+Use este guia para:
+- Instalar a biblioteca
+- Configuração inicial
+- Primeiro exemplo CRUD
+- Visão geral dos recursos
+
+### 🤖 [AI_RULES.md](AI_RULES.md)
+**Regras críticas para desenvolvimento com IA**
+
+Use este guia quando:
+- Desenvolver com assistência de IA
+- Evitar problemas comuns
+- Seguir melhores práticas
+- Verificar checklist antes de criar funcionalidades
+
+### 🔧 [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
+**Soluções para problemas comuns**
+
+Use este guia quando:
+- Encontrar erros inesperados
+- Precisar depurar problemas
+- Buscar soluções rápidas
+
+---
+
+---
+
+## 📁 Templates Prontos
+
+Códigos completos e funcionais em `templates/`:
+
+- **[app-layout.tsx](templates/app-layout.tsx)** - Layout principal com sidebar e autenticação
+- **[basic-crud-page.tsx](templates/basic-crud-page.tsx)** - CRUD básico completo
+- **[complete-crud-example.tsx](templates/complete-crud-example.tsx)** - CRUD com todos os recursos
+- **[custom-form.tsx](templates/custom-form.tsx)** - Formulário personalizado
+- **[custom-service.tsx](templates/custom-service.tsx)** - Service customizado
+- **[qualiex-integration-example.tsx](templates/qualiex-integration-example.tsx)** - Integração com Qualiex
+- **[sidebar-config.tsx](templates/sidebar-config.tsx)** - Configuração de menu lateral
+
+---
+
+## 📚 Documentação Adicional
+
+- **[CRUD System](../crud/README.md)** - Documentação técnica do sistema CRUD
+- **[Architecture](architecture/)** - Documentos sobre arquitetura interna
+
+---
+
+## 🧭 Navegação Rápida
+
+| Documento | O que contém | Para quem |
+|-----------|-------------|-----------|
+| **README.md** | Instalação, Quick Start, exemplos básicos | Iniciantes, primeiros passos |
+| **AI_RULES.md** | Checklist crítico, regras obrigatórias | IA, desenvolvedores com IA |
+| **TROUBLESHOOTING.md** | Soluções de erros, problemas comuns | Todos |
+| **Templates** | Códigos prontos para copiar | Todos |
+| **crud/README.md** | Documentação técnica do sistema CRUD | Desenvolvedores avançados |
+
+---
+
+## 💡 Fluxo de Ajuda
+
+```
+Primeira vez com a lib?
+└─> Leia README.md (instalação + quick start)
+    └─> Copie um template de templates/
+        └─> Problema? Veja TROUBLESHOOTING.md
+            └─> Desenvolvendo com IA? Consulte AI_RULES.md
+```
+
+---
+
+## 🔄 Mudanças na Estrutura
+
+### Versão Atual
+- ✅ **README.md** criado como hub principal
+- ✅ **AI_RULES.md** substitui AI_GUIDE.md (mais focado e prático)
+- ✅ Links atualizados para arquivos existentes
+- ✅ Referências corretas para documentação instalada
+
+### Arquivos Removidos
+- ❌ `AI_GUIDE.md` (substituído por AI_RULES.md + README.md)
+- ❌ `DEVELOPER_GUIDE.md` (conteúdo integrado em README.md e crud/README.md)
+
+---
+
+## 📝 Licença
+
+MIT License - ForLogic © 2025