Page Mapping

O que é Page Mapping?

O Page Mapping é o mecanismo central de controle de permissões baseado em URLs da Plataforma Betha. Ele define quais recursos (endpoints/páginas) do seu sistema requerem quais permissões.

Por que configurar?

Quando você integra seu sistema com a Plataforma Betha, o Gerenciador de Acessos precisa saber:

1. Quais permissões existem no seu sistema
2. Quais URLs cada permissão protege
3. Quais operações (criar, editar, excluir) estão disponíveis
4. Como organizar as permissões no menu de gestão

Sem o Page Mapping configurado, os administradores não conseguirão gerenciar as permissões dos usuários do seu sistema.

Estrutura JSON

O Page Mapping é um array JSON com a seguinte estrutura:

[
  {
    "contexts": [
      "database",
      "entity"
    ],
    "constraints": [
      {
        "id": "CadastroPessoasPage",
        "description": "Cadastro de Pessoas",
        "resources": [
          {
            "accessControll": null,
            "urlPattern": "/api/pessoas",
            "methods": ["GET"]
          },
          {
            "accessControll": "create",
            "urlPattern": "/api/pessoas",
            "methods": ["POST"]
          },
          {
            "accessControll": "edit",
            "urlPattern": "/api/pessoas/.*",
            "methods": ["PUT"]
          },
          {
            "accessControll": "delete",
            "urlPattern": "/api/pessoas/.*",
            "methods": ["DELETE"]
          }
        ],
        "accessControll": [
          { "id": "create", "description": "Criar" },
          { "id": "edit", "description": "Editar" },
          { "id": "delete", "description": "Excluir" }
        ]
      }
    ],
    "resources": [
      {
        "urlPattern": "api/public/.*",
        "methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS", "PATCH"]
      }
    ],
    "groups": [
      {
        "id": "cadastros",
        "description": "Cadastros",
        "constraints": ["CadastroPessoasPage"]
      }
    ]
  }
]

Campos Principais

Campo	Tipo	Obrigatório	Descrição
contexts	Array	Sim	Dimensões do contexto (database, entity, subcontextos)
constraints	Array	Sim	Lista de permissões do sistema
resources	Array	Não	URLs públicas (sem necessidade de permissão)
groups	Array	Não	Agrupamento lógico para organização no UI

Detalhamento dos Campos

contexts

Define quais dimensões compõem o contexto do seu sistema:

// Sistema padrão (database + entity)
"contexts": ["database", "entity"]

// Sistema com subcontexto customizado
"contexts": ["database", "subcontexto", "entity"]

info

Cada sistema pode definir seus próprios subcontextos conforme necessidade. O nome do subcontexto é customizável e deve ser definido de acordo com a arquitetura da aplicação.

constraints

Array de permissões do sistema. Cada constraint define:

• id: identificador único (use nomes descritivos como CadastroPessoasPage)
• description: texto que aparece no UI de gestão
• resources: URLs protegidas por esta permissão
• accessControll: operações disponíveis

resources (nível raiz)

URLs que são públicas e não requerem permissão específica. Use para:

• Endpoints de health check
• APIs públicas
• Recursos estáticos

"resources": [
  {
    "urlPattern": "api/public/.*",
    "methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS", "PATCH"]
  },
  {
    "urlPattern": "api/health/.*",
    "methods": ["GET"]
  }
]

groups

Organiza as constraints em categorias para facilitar a visualização no UI:

"groups": [
  {
    "id": "cadastros",
    "description": "Cadastros",
    "constraints": ["CadastroPessoasPage", "CadastroEmpresasPage"]
  },
  {
    "id": "relatorios",
    "description": "Relatórios",
    "constraints": ["RelatorioVendasPage"]
  }
]

Exemplo Completo: Sistema de RH

[
  {
    "contexts": ["database", "entity"],
    "constraints": [
      {
        "id": "FuncionariosPage",
        "description": "Cadastro de Funcionários",
        "resources": [
          {
            "accessControll": null,
            "urlPattern": "/rh/api/funcionarios",
            "methods": ["GET"]
          },
          {
            "accessControll": null,
            "urlPattern": "/rh/api/funcionarios/.*",
            "methods": ["GET"]
          },
          {
            "accessControll": "create",
            "urlPattern": "/rh/api/funcionarios",
            "methods": ["POST"]
          },
          {
            "accessControll": "edit",
            "urlPattern": "/rh/api/funcionarios/.*",
            "methods": ["PUT"]
          },
          {
            "accessControll": "delete",
            "urlPattern": "/rh/api/funcionarios/.*",
            "methods": ["DELETE"]
          }
        ],
        "accessControll": [
          { "id": "create", "description": "Criar" },
          { "id": "edit", "description": "Editar" },
          { "id": "delete", "description": "Excluir" }
        ]
      },
      {
        "id": "FolhaPagamentoPage",
        "description": "Folha de Pagamento",
        "resources": [
          {
            "accessControll": null,
            "urlPattern": "/rh/api/folha/.*",
            "methods": ["GET"]
          },
          {
            "accessControll": "processar",
            "urlPattern": "/rh/api/folha/calcular",
            "methods": ["POST"]
          }
        ],
        "accessControll": [
          { "id": "processar", "description": "Processar folha" }
        ]
      }
    ],
    "resources": [
      {
        "urlPattern": "rh/api/public/.*",
        "methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS", "PATCH"]
      }
    ],
    "groups": [
      {
        "id": "cadastros",
        "description": "Cadastros",
        "constraints": ["FuncionariosPage"]
      },
      {
        "id": "processamento",
        "description": "Processamento",
        "constraints": ["FolhaPagamentoPage"]
      }
    ]
  }
]

Exemplo: Ações Específicas

Você pode criar accessControll personalizados para ações específicas do seu sistema:

{
  "id": "IntegracoesContabeisPage",
  "description": "Integrações Contábeis",
  "resources": [
    {
      "accessControll": null,
      "urlPattern": "/api/integracoes/.*",
      "methods": ["GET"]
    },
    {
      "accessControll": "contabilizar",
      "urlPattern": "/api/integracoes/contabilizar/.*",
      "methods": ["POST"]
    },
    {
      "accessControll": "contabilizar",
      "urlPattern": "/api/integracoes/reenviar/.*",
      "methods": ["POST"]
    }
  ],
  "accessControll": [
    { "id": "contabilizar", "description": "Contabilizar" }
  ]
}

NOTA

O mesmo accessControll pode ser usado para proteger múltiplas URLs relacionadas, como no exemplo acima onde contabilizar protege tanto /contabilizar/.* quanto /reenviar/.*.

Boas Práticas

IDs de Constraints

• Use nomes descritivos: CadastroPessoasPage em vez de cp1
• Mantenha um padrão: {Funcionalidade}Page ou {Funcionalidade}PageMapping

IMPORTANTE!

Nunca altere IDs de constraints em produção sem um plano de migração. Alterações de ID não afetam permissões já configuradas - os usuários continuarão vinculados ao ID antigo.

AccessControll

• Seja consistente: use os mesmos IDs em todo o sistema
• Padronize nomenclatura: create, edit, delete ou criar, editar, excluir
• Documente bem: descrições claras facilitam a configuração pelo administrador

Grupos

• Organize logicamente por módulo ou área funcional
• Use nomes claros que facilitem a navegação
• Revise periodicamente conforme o sistema evolui