Add comentário sobre def do sapl.rules.map_rules

sapl/crud/base.py

@@ -16,26 +16,25 @@ from django.http.response import Http404
 from django.shortcuts import redirect
 from django.utils.decorators import classonlymethod
 from django.utils.encoding import force_text
-from django.utils.translation import ugettext_lazy as _
 from django.utils.translation import string_concat
+from django.utils.translation import ugettext_lazy as _
 from django.views.generic import (CreateView, DeleteView, DetailView, ListView,
                                   UpdateView)
 from django.views.generic.base import ContextMixin
 from django.views.generic.list import MultipleObjectMixin
 
 from sapl.crispy_layout_mixin import CrispyLayoutFormMixin, get_field_display
+from sapl.rules.map_rules import (RP_ADD, RP_CHANGE, RP_DELETE,
+                                  RP_DETAIL, RP_LIST)
 from sapl.settings import BASE_DIR
 from sapl.utils import normalize
 
+
 logger = logging.getLogger(BASE_DIR.name)
 
 ACTION_LIST, ACTION_CREATE, ACTION_DETAIL, ACTION_UPDATE, ACTION_DELETE = \
     'list', 'create', 'detail', 'update', 'delete'
 
-# RP - Radical das permissões para "..."
-RP_LIST, RP_DETAIL, RP_ADD, RP_CHANGE, RP_DELETE =\
-    '.list_', '.detail_', '.add_', '.change_', '.delete_',
-
 
 def _form_invalid_message(msg):
     return '%s %s' % (_('Formulário inválido.'), msg)

sapl/rules/map_rules.py

@@ -1,7 +1,6 @@
 from sapl.base import models as base
 from sapl.comissoes import models as comissoes
 from sapl.compilacao import models as compilacao
-from sapl.crud.base import RP_ADD, RP_CHANGE, RP_DELETE, RP_DETAIL, RP_LIST
 from sapl.lexml import models as lexml
 from sapl.materia import models as materia
 from sapl.norma import models as norma
@@ -16,7 +15,47 @@ from sapl.rules import (SAPL_GROUP_ADMINISTRATIVO, SAPL_GROUP_ANONYMOUS,
                         SAPL_GROUP_PROTOCOLO, SAPL_GROUP_SESSAO)
 from sapl.sessao import models as sessao
 
-# RP = Radicao de Permissão
+"""
+Todas as permissões do django framework seguem o padrão
+
+        [app_label].[radical_de_permissao]_[model]
+
+ou seja, em sapl.norma.NormaJuridica, por exemplo, o django framework cria
+três permissões registadas na classe Permission:
+
+        definição                         uso
+
+        - add_normajuridica               norma.add_normajuridica
+        - change_normajuridica            norma.change_normajuridica
+        - delete_normajuridica            norma.delete_normajuridica
+
+No SAPL foram acrescidas em todos os models as duas regras abaixo, adicionadas
+com o Signal post_migrate `create_proxy_permissions`
+localizado em sapl.rules.apps.py.
+
+        - list_normajuridica              norma.list_normajuridica
+        - detail_normajuridica            norma.detail_normajuridica
+
+Tanto o Crud implementado em sapl.crud.base.py quanto o Signal post_migrate
+`update_groups` que é responsável por ler o mapa deste
+arquivo (sapl.rules.map_rules.py) e criar os grupos definidos na regra de
+negócio trabalham com os cinco radiais de permissão
+e com qualquer outro tipo de permissão customizada, nesta ordem de precedência.
+
+Os cinco radicais de permissão completa são:
+
+        RP_LIST, RP_DETAIL, RP_ADD, RP_CHANGE, RP_DELETE =\
+            '.list_', '.detail_', '.add_', '.change_', '.delete_',
+
+Tanto a app crud quanto a app rules estão sempre ligadas a um model. Ao lidar
+com permissões, sempre é analisado se é apenas um radical ou permissão
+completa, sendo apenas um radical, a permissão completa é montada com base
+no model associado.
+"""
+
+RP_LIST, RP_DETAIL, RP_ADD, RP_CHANGE, RP_DELETE =\
+    '.list_', '.detail_', '.add_', '.change_', '.delete_',
+
 __base__ = [RP_LIST, RP_DETAIL, RP_ADD, RP_CHANGE, RP_DELETE]
 __listdetailchange__ = [RP_LIST, RP_DETAIL, RP_CHANGE]
 
@@ -74,10 +113,12 @@ rules_group_materia = {
         (compilacao.Dispositivo, __base__ + [
             'change_dispositivo_edicao_dinamica',
 
-            # sobre a regra abaixo deve ser pensada sobre isso
-            # abre possibilidade pra haver compilacao de emenda com projeto
-            # mas testes devem ser feitos especificamente para materia
-            # 'change_dispositivo_registros_compilacao'
+            # TODO: adicionar 'change_dispositivo_registros_compilacao'
+            # quando testes forem feitos para permtir que matérias possam
+            # ser vinculadas a outras matérias via registro de compilação.
+            # Normalmente emendas e/ou projetos substitutivos podem alterar
+            # uma matéria original. Fazer esse registro de compilação
+            # oferecia um autografo eletrônico pronto ser convertido em Norma.
         ])
     ]
 }