django-rule-engine 1.0.0__tar.gz

django_rule_engine-1.0.0/INDEX.md

@@ -0,0 +1,253 @@
+# 📚 RuleField - Índice da Documentação
+
+> Campo Django customizado para rule-engine com editor visual e validação dinâmica
+
+## 🎯 Documentos Disponíveis
+
+### Para Começar
+
+1. **[INSTALL.md](./INSTALL.md)** - 📦 Instalação e Setup Inicial
+   - O que foi criado
+   - Como usar
+   - Funcionalidades
+   - Exemplo implementado
+   - Testes
+   - Próximos passos
+
+2. **[QUICKSTART.md](./QUICKSTART.md)** - ⚡ Guia Rápido (5 minutos)
+   - Instalação rápida em 4 passos
+   - Sintaxe básica
+   - Exemplos práticos
+   - Troubleshooting
+   - FAQ
+
+### Documentação Completa
+
+3. **[README.md](./README.md)** - 📖 Documentação Completa (450+ linhas)
+   - Características detalhadas
+   - Instalação
+   - Uso básico e avançado
+   - Sintaxe completa de regras
+   - Usando no Django Admin
+   - Validação programática
+   - API de validação
+   - Customização
+   - Exemplo completo
+   - Exemplos de regras por caso de uso
+   - Troubleshooting
+   - Referências
+
+### Guias Especializados
+
+4. **[MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md)** - 🔄 Guia de Migração
+   - Migrar TextField existente
+   - Aplicar em outro projeto
+   - Customizar para necessidades específicas
+   - Rollback/Reversão
+   - Troubleshooting de migração
+   - Checklist completo
+
+### Código e Exemplos
+
+5. **[examples.py](./EXAMPLES.md)** - 💻 Exemplos de Código (350+ linhas)
+   - Exemplo 1: Uso básico
+   - Exemplo 2: Com dados de exemplo
+   - Exemplo 3: Validação de usuário
+   - Exemplo 4: Regra de desconto
+   - Exemplo 5: Múltiplas regras
+   - Lista de regras comuns
+
+7. **[VISUAL_DEMO.py](./VISUAL_DEMO.md)** - 🎨 Demonstração Visual
+   - Definição no modelo
+   - Aparência no admin
+   - Fluxo de uso
+   - Exemplos de validação
+   - Cores e temas
+   - Atalhos de teclado
+   - Responsividade
+   - Animações
+   - Acessibilidade
+   - Compatibilidade
+
+### Scripts Utilitários
+
+8. **[setup.sh](./setup.sh)** - 🔧 Script de Setup Automatizado
+   - Verifica dependências
+   - Cria migrations
+   - Aplica migrations
+   - Coleta arquivos estáticos
+   - Executa testes
+
+### Arquivos de Código
+
+9. **[rule_field.py](./rule_field.py)** - Campo Django customizado
+10. **[rule_widget.py](./rule_widget.py)** - Widget para o admin
+11. **[../templates/widgets/rule_widget.html](../templates/widgets/rule_widget.html)** - Template HTML
+12. **[../static/rule_widget/rule_widget.js](../static/rule_widget/rule_widget.js)** - JavaScript
+13. **[../static/rule_widget/rule_widget.css](../static/rule_widget/rule_widget.css)** - CSS
+14. **[../api/views.py](../api/views.py)** - API endpoint
+15. **[../api/urls.py](../api/urls.py)** - URLs da API
+
+---
+
+## 🚀 Por Onde Começar?
+
+### Sou Novo no RuleField
+1. Leia: **[INSTALL.md](./INSTALL.md)** (3 min)
+2. Leia: **[QUICKSTART.md](./QUICKSTART.md)** (5 min)
+3. Execute: `bash setup.sh`
+4. Teste no admin!
+
+### Quero Usar no Meu Projeto
+1. Leia: **[README.md](./README.md)** seção "Uso Básico"
+2. Copie os arquivos necessários
+3. Siga: **[MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md)** seção 2
+
+### Preciso Customizar
+1. Leia: **[README.md](./README.md)** seção "Customização"
+2. Veja: **[examples.py](./examples.py)** para inspiração
+3. Consulte: **[MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md)** seção 3
+
+### Quero Ver Como Funciona
+1. Abra: **[VISUAL_DEMO.py](./VISUAL_DEMO.py)**
+2. Veja: **[examples.py](./examples.py)**
+3. Execute: `python manage.py shell < test_rule_field.py`
+
+### Tenho um Problema
+1. Consulte: **[QUICKSTART.md](./QUICKSTART.md)** seção "Troubleshooting"
+2. Veja: **[README.md](./README.md)** seção "Troubleshooting"
+3. Confira: **[MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md)** seção "Troubleshooting"
+
+---
+
+## 📊 Resumo por Tipo de Documento
+
+### 📘 Documentação Geral
+- INSTALL.md - Instalação inicial
+- README.md - Documentação completa
+- QUICKSTART.md - Início rápido
+
+### 🔧 Guias Técnicos
+- MIGRATION_GUIDE.md - Migração e customização
+
+### 💻 Código e Exemplos
+- examples.py - 5 exemplos completos
+- test_rule_field.py - Suite de testes
+- VISUAL_DEMO.py - Demonstração visual
+
+### 🛠️ Arquivos de Implementação
+- rule_field.py - Campo Django
+- rule_widget.py - Widget
+- rule_widget.html - Template
+- rule_widget.js - JavaScript
+- rule_widget.css - CSS
+- views.py - API
+- urls.py - URLs
+
+### ⚙️ Scripts
+- setup.sh - Setup automatizado
+
+---
+
+## 📈 Estatísticas
+
+- **Total de Documentos:** 15 arquivos
+- **Linhas de Documentação:** ~1.500+
+- **Linhas de Código:** ~700+
+- **Exemplos Funcionais:** 5+
+- **Suites de Teste:** 5
+- **Casos de Uso Cobertos:** 10+
+
+---
+
+## 🔗 Links Externos
+
+- [rule-engine no PyPI](https://pypi.org/project/rule-engine/)
+- [Documentação rule-engine](https://zerosteiner.github.io/rule-engine/)
+- [Django Custom Model Fields](https://docs.djangoproject.com/en/stable/howto/custom-model-fields/)
+- [CodeMirror](https://codemirror.net/)
+
+---
+
+## 📝 Convenções de Nomenclatura
+
+- `RuleField` - Classe do campo Django
+- `RuleWidget` - Classe do widget
+- `rule_field.py` - Arquivo do campo
+- `rule_widget.*` - Arquivos do widget
+- `/api/validate-rule/` - Endpoint da API
+
+---
+
+## 🎓 Níveis de Experiência
+
+| Nível | Documento Recomendado |
+|-------|----------------------|
+| Iniciante | INSTALL.md → QUICKSTART.md |
+| Intermediário | README.md → examples.py |
+| Avançado | MIGRATION_GUIDE.md → Código fonte |
+| Contribuidor | Todos os arquivos |
+
+---
+
+## 🗺️ Mapa do Conhecimento
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                  COMEÇAR AQUI                           │
+│                  ↓                                      │
+│            [INSTALL.md]                                 │
+│                  ↓                                      │
+│            [QUICKSTART.md]                              │
+│                  ↓                                      │
+│         Precisa de mais detalhes?                       │
+│                  ↓                                      │
+│    ┌────────────┴─────────────┐                        │
+│    ↓                           ↓                        │
+│ [README.md]              [examples.py]                  │
+│    ↓                           ↓                        │
+│ Customizar?                 Ver testes?                 │
+│    ↓                           ↓                        │
+│ [MIGRATION_GUIDE.md]    [test_rule_field.py]           │
+│    ↓                           ↓                        │
+│ Ver visual?                Tudo OK!                     │
+│    ↓                                                    │
+│ [VISUAL_DEMO.py]                                        │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## ✅ Checklist de Aprendizado
+
+- [ ] Li INSTALL.md e entendi o que foi criado
+- [ ] Segui QUICKSTART.md e instalei com sucesso
+- [ ] Li README.md e entendi a sintaxe de regras
+- [ ] Vi examples.py e entendi casos de uso
+- [ ] Executei test_rule_field.py com sucesso
+- [ ] Testei no Django Admin
+- [ ] Criei minha primeira regra
+- [ ] Validei uma regra dinamicamente
+- [ ] Li MIGRATION_GUIDE.md para customizar
+- [ ] Implementei em meu projeto
+
+---
+
+## 💡 Dicas Finais
+
+1. **Começe Simples** - Use exemplos básicos primeiro
+2. **Teste Sempre** - Valide suas regras no admin antes de usar
+3. **Leia os Exemplos** - O arquivo examples.py tem muitos casos práticos
+4. **Use o Atalho** - Ctrl+Enter para validar é mais rápido
+5. **Customize** - O campo é flexível, adapte para sua necessidade
+
+---
+
+**Versão:** 1.0.0  
+**Última Atualização:** Janeiro 2026  
+**Criado para:** Projeto AVA - IFRN  
+**Licença:** Mesmo do projeto principal
+
+---
+
+📧 **Precisa de ajuda?** Consulte a documentação relevante acima!

django_rule_engine-1.0.0/INSTALL.md

@@ -0,0 +1,206 @@
+# RuleField - Campo Django para Rule Engine
+
+✨ **Campo Django customizado com editor visual e validação dinâmica**
+
+## 📦 O que foi criado?
+
+### Estrutura de Arquivos
+
+```
+src/base/
+├── fields/
+│   ├── __init__.py           # Exporta RuleField
+│   ├── rule_field.py         # Campo Django customizado
+│   ├── rule_widget.py        # Widget para o admin
+│   ├── README.md             # Documentação completa
+│   ├── QUICKSTART.md         # Guia rápido
+│   ├── examples.py           # Exemplos de código
+│   └── test_rule_field.py    # Script de testes
+├── templates/
+│   └── widgets/
+│       └── rule_widget.html  # Template do widget
+├── static/
+│   └── rule_widget/
+│       ├── rule_widget.js    # JavaScript do widget
+│       └── rule_widget.css   # Estilos
+└── api/
+    ├── __init__.py
+    ├── views.py              # Endpoint de validação
+    └── urls.py               # URLs da API
+```
+
+## 🚀 Como Usar
+
+### 1. Uso Básico
+
+```python
+from django_rule_engine.fields import RuleField
+
+class MeuModelo(models.Model):
+    regra = RuleField(
+        verbose_name="Regra de Validação",
+        example_data={"idade": 25, "status": "ativo"}
+    )
+```
+
+### 2. Criar Migrations
+
+```bash
+cd src/
+python manage.py makemigrations
+python manage.py migrate
+```
+
+### 3. Coletar Arquivos Estáticos
+
+```bash
+python manage.py collectstatic --noinput
+```
+
+### 4. Testar no Admin
+
+1. Acesse o Django Admin
+2. Edite um objeto com RuleField
+3. Veja o editor com syntax highlighting
+4. Digite uma regra (ex: `idade >= 18 and status == "ativo"`)
+5. Clique em **Validar** ou pressione **Ctrl+Enter**
+6. Veja o resultado da validação
+
+## ✨ Funcionalidades
+
+- ✅ Editor de código com syntax highlighting (CodeMirror)
+- ✅ Campo JSON de exemplo editável pelo usuário
+- ✅ Validação dinâmica em tempo real
+- ✅ Feedback visual (sucesso/erro)
+- ✅ Atalhos de teclado (Ctrl+Enter para validar)
+- ✅ API REST para validação
+- ✅ Validação no backend
+- ✅ Documentação completa
+- ✅ Exemplos práticos
+
+## 📝 Exemplos de Regras
+
+```python
+# Idade mínima
+"idade >= 18"
+
+# Múltiplas condições
+"idade >= 18 and status == 'ativo'"
+
+# Email institucional
+'"@ifrn.edu.br" in email'
+
+# Regras complexas
+"(preco > 100 or quantidade >= 5) and tipo_cliente == 'premium'"
+
+# Com funções
+"len(nome) > 3 and idade >= 18"
+```
+
+## 🔧 Exemplo Implementado
+
+O campo já está implementado no modelo `Cohort` em [coorte/models.py](../../../coorte/models.py):
+
+```python
+class Cohort(models.Model):
+    name = CharField("cohort name", max_length=256, unique=True)
+    rule = RuleField(
+        "validation rule",
+        blank=True,
+        null=True,
+        example_data={
+            "login": "usuario123",
+            "user": {"email": "usuario@example.com"},
+            "name": "João da Silva",
+            "status": "Ativo"
+        },
+        default="login == 'usuario123' and user.email != 'usuario123@example.com'",
+    )
+
+    class Meta:
+        verbose_name = _("cohort")
+        verbose_name_plural = _("cohorts")
+        ordering = ["name"]
+
+    def __str__(self):
+        return self.name
+
+```
+
+## 🧪 Testes
+
+Execute os testes:
+
+```bash
+cd src/
+python manage.py shell
+```
+
+Dentro do shell:
+
+```python
+from django_rule_engine.fields.test_rule_field import test_all
+test_all()
+```
+
+Ou diretamente:
+
+```bash
+python manage.py shell < base/fields/test_rule_field.py
+```
+
+## 📚 Documentação
+
+- **[README.md](./README.md)** - Documentação completa e detalhada
+- **[QUICKSTART.md](./QUICKSTART.md)** - Guia rápido de início
+- **[examples.py](./examples.py)** - Exemplos de código prontos para usar
+
+## 🌐 API
+
+O endpoint de validação está disponível em:
+
+```
+POST /api/validate-rule/
+
+Body:
+{
+    "rule": "idade >= 18 and status == 'ativo'",
+    "data": {"idade": 25, "status": "ativo"}
+}
+
+Response:
+{
+    "valid": true,
+    "result": true,
+    "matches": true
+}
+```
+
+## 🎯 Próximos Passos
+
+1. ✅ **Implementar no seu modelo** - Adicione `RuleField` onde precisar
+2. ✅ **Criar migrations** - `python manage.py makemigrations`
+3. ✅ **Aplicar migrations** - `python manage.py migrate`
+4. ✅ **Testar no admin** - Acesse e edite um objeto
+5. ✅ **Usar programaticamente** - Veja exemplos em `examples.py`
+
+## 💡 Dicas
+
+- Use `blank=True, null=True` se o campo for opcional
+- Defina `example_data` relevante para seu caso de uso
+- Teste suas regras no admin antes de usar em produção
+- Consulte a [documentação do rule-engine](https://zerosteiner.github.io/rule-engine/)
+
+## ❓ Suporte
+
+- Leia [README.md](./README.md) para documentação completa
+- Veja [examples.py](./examples.py) para casos de uso
+- Consulte [QUICKSTART.md](./QUICKSTART.md) para início rápido
+
+## 📄 Licença
+
+Segue a licença do projeto principal.
+
+---
+
+**Criado com ❤️ para o projeto AVA do IFRN**

django_rule_engine-1.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, kelsoncm
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

django_rule_engine-1.0.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include LICENSE
+include INDEX.md
+include INSTALL.md
+include QUICKSTART.md
+include MIGRATION_GUIDE.md
+recursive-include src/django_rule_engine/static *
+recursive-include src/django_rule_engine/templates *