Motor Core GraphQL (Protheus)

Servidor GraphQL dinâmico sobre o dicionário de dados do Protheus (SX2/SX3/SX9), rodando como ponto de entrada REST do AppServer em TLPP.

Documentação em português brasileiro: docs/como-comecar.md (guia rápido), docs/manual-implementacao.md (deploy e configuração) e docs/manual-utilizacao.md (referência da API GraphQL).

Endpoint

• GET /graphql — nomes dos tipos do schema (lista de bloqueio aplicada)
• GET /graphql?type=<TABELA> — detalhe completo do tipo de uma tabela (campos + relacionamentos)
• GET /graphql?query=<texto GraphQL codificado na URL> — executa uma consulta

Exemplo

{ SA1(limit: 5, filter: [{field: "A1_COD", op: "eq", value: "000001"}]) {
    A1_COD
    A1_NOME
    SC5 { C5_NUM }
} }

Mutations

createTABELA/updateTABELA/deleteTABELA são expostos apenas para tabelas listadas em allowMutations do config/graphql-config.json (vazio por padrão — nada é gravável até um administrador liberar uma tabela). Exclusão é sempre lógica (D_E_L_E_T_ = '*'), nunca remoção real de linha.

mutation { createSA1(input: {A1_COD: "000123", A1_LOJA: "01", A1_NOME: "Foo"}) {
    A1_COD
    A1_NOME
} }

Limitação conhecida: veja docs/architecture.md para uma ressalva de concorrência em mutations create.

Consulte docs/architecture.md e docs/superpowers/specs/2026-08-14-graphql-mutations-design.md.

Configuração

Veja docs/configuration.md. compile.sh/deploy-rpo.sh lidam apenas com fontes .tlpp compilados — custom/backoffice/graphql/config/graphql-config.json precisa ser copiado para o RootPath do AppServer separadamente (verifique [P12] RootPath= no appserver.ini; o MemoRead() resolve caminhos relativos contra esse RootPath, não contra o SourcePath, confirmado testando ambos). Sem esse arquivo, a lista de bloqueio cai silenciosamente para vazia e toda tabela fica visível — confirmado contra um servidor real durante o desenvolvimento.

Arquitetura

Veja docs/architecture.md e docs/superpowers/specs/2026-08-13-graphql-core-engine-design.md.

Validação ao vivo

Resultados capturados contra um AppServer Protheus isolado (container protheus-graphql, REST em :9996) — JSON bruto das respostas em docs/screenshots/.

1. Lista de tipos (GET /graphql)

Listagem do catálogo de tipos expostos, já com o bloqueio de tabelas aplicado (denyTables).

schema_list.json

2. Consulta (SA1)

Consulta simples com paginação: { SA1(limit: 5) { A1_COD A1_LOJA A1_NOME } }.

query.json

3. Mutation (create → update → delete)

Ciclo completo de escrita com soft-delete: createSA1 → updateSA1 → deleteSA1 (D_E_L_E_T_='*').

mutation.json

4. Introspection (SA1)

Detalhe do tipo SA1: campos, tipos e valores expostos via introspection.

introspection.json

Sobre relacionamentos (SX9): o motor resolve relações a partir de SX9 (getRelations), mas neste deploy de teste a SX9/SIX não estão registradas no SX2 — por isso campos como SC5/NO1 respondem Unknown field (degradação documentada no código, "ponytail"). Com um dicionário completo, as relações listadas via SX9 são expostas como sub-campos aninhados no tipo.

5. Console (console/index.html)

Página estática de exploração/administração (sub-projeto 6), aberta num navegador real e apontada para o mesmo AppServer. Schema real com 10.409 tabelas — a lista nunca renderiza mais que 200 linhas de uma vez (filtro de texto ou as 200 primeiras), achado confirmado ao vivo (ver docs/superpowers/specs/2026-09-06-graphql-console-design.md).

Filtro por texto ("SA1") reduz a lista para 1 resultado; aba "Campos da tabela" mostra os campos de SA1 já com o botão "Baixar SDK":

Execução de uma query real ({ SA1(limit: 5) { ... } }) com o resultado formatado:

Testes

Testes TIR (Python e2e) em tests/tir/. Execute com pytest tests/tir/ -v contra um AppServer Protheus com este RPO implantado.

Roteiro de sub-projetos

Roteiro completo (6 de 6) implementado neste repositório: Core Engine + Mutations + Auth + Field Hooks + SDK Generator + Console. Auth (autenticação nativa [HTTPREST] Security=1 + autorização por grupo/groupPermissions, opt-in via authEnforced na config) e Field Hooks (extensão por campo via fieldHooks, onRead/onWrite) estão implementados, com a ativação/validação end-to-end de ambos dependendo de limitações deste ambiente de teste específico — ver "Achados empíricos" nas respectivas specs. SDK Generator (GET /rest/graphql?sdk=<TABLE> → classe TLPP tipada) e Console (console/index.html, página estática de exploração/administração — decisão tomada com o operador em vez do "Console PO-UI"/Angular originalmente previsto) foram validados ao vivo sem ressalvas. Veja as specs de design (docs/superpowers/specs/) para o histórico completo de decisões de cada sub-projeto.