Help us improve
Share bugs, ideas, or general feedback.
From plugadvpl
Audits and analyzes ADVPL expressions embedded in Protheus SX dictionary fields (X3_VALID, X3_WHEN, X3_VLDUSER, X7_REGRA, X1_VALID). Use when modifying fields, debugging ghost behavior, or running cross-file lint rules SX-001..SX-011.
npx claudepluginhub jonipraia/plugadvpl --plugin plugadvplHow this skill is triggered — by the user, by Claude, or both
Slash command
/plugadvpl:advpl-dicionario-sx-validacoesThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Esta skill foca nas **expressões ADVPL embarcadas no dicionário SX** — o ponto onde código vive **fora** dos `.prw` e quase ninguém audita. Mexer num campo SX3 sem entender o que está em `X3_VALID`/`X3_WHEN`/`X3_RELACAO`/`X7_REGRA` é a causa #1 de regressão silenciosa em customização Protheus.
Provides metadata from Protheus SX tables (SX1-SX9, SXA, SXB, SXG, SIX) for creating fields, parameters, triggers, queries, and diagnosing dictionary-driven behavior. Use when customizing or debugging Protheus without recompiling.
Creates, modifies, and validates Salesforce Validation Rules metadata with formulas, error messages, and data quality logic. Includes guidelines for correct function usage.
Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Share bugs, ideas, or general feedback.
Esta skill foca nas expressões ADVPL embarcadas no dicionário SX — o ponto onde código vive fora dos .prw e quase ninguém audita. Mexer num campo SX3 sem entender o que está em X3_VALID/X3_WHEN/X3_RELACAO/X7_REGRA é a causa #1 de regressão silenciosa em customização Protheus.
Para a estrutura completa das tabelas SX (cada coluna documentada), consulte a skill irmã
advpl-dicionario-sxe seureference.md. Esta skill é só sobre as expressões ADVPL embutidas.
X3_VALID, X3_VLDUSER) e quer não cair em armadilha clássica./plugadvpl:lint --cross-file (regras SX-001..SX-011) e quer entender as regras com profundidade.| Coluna SX | O que contém | Quando executa |
|---|---|---|
X3_VALID | Expressão de validação do campo | Após Loose Focus no campo |
X3_VLDUSER | Validação user-defined (executa após VALID) | Após X3_VALID retornar .T. |
X3_WHEN | Habilitação condicional do campo | A cada repaint da tela |
X3_RELACAO | Inicializador / fórmula (default + virtual) | Inserção de novo registro / cálculo VIRTUAL |
X3_CBOX | Conteúdo de combobox | Build da combo |
X3_F3 | Alias da consulta SXB (não é ADVPL puro) | F3 no campo |
X7_REGRA | Expressão que retorna valor para destino | Após sair do campo origem |
X7_CONDIC | Condição para o gatilho disparar | Antes de avaliar X7_REGRA |
X7_CHAVE | Chave do DbSeek (se X7_SEEK='S') | Setup do gatilho com seek |
X1_VALID | Validação da pergunta SX1 | OK no diálogo Pergunte |
X1_DEF01/CNT01 | Default de cada conteúdo da pergunta | Abertura do diálogo |
X6_VALID | Validação ao gravar parâmetro MV_ | PutMV / Configurador |
X6_INIT | Default do parâmetro | GetMV quando vazio |
A expressão deve retornar .T. (válido) ou .F. (inválido). Quando inválido, o ERP exibe o último Help()/MsgInfo() chamado dentro da expressão.
// X3_VALID (uma única linha — sem quebras dentro do dicionário!)
NaoVazio(M->A1_COD) .And. ExistChav("SA1") .And. U_ABCA1Val()
M->CAMPO referencia o valor sendo digitado (memo da grid).NaoVazio(x) e Vazio(x) testam null/empty.ExistCpo(alias, conteudo, ordem) valida se existe na tabela apontada.ExistChav(alias) valida se a chave NÃO existe (para inserção sem duplicidade).U_ABCA1Val() chama validação custom em fonte ADVPL (recomendado para qualquer regra >1 linha).BeginSql .. EndSql, TCQuery(..)) dentro de X3_VALID — executa em cada Loose Focus, custa caro. Use Posicione() com cache ou lookup simples.plugadvpl lint --cross-file --regra SX-007 detecta.U_xxx sem fonte indexado — runtime estoura. plugadvpl lint --cross-file --regra SX-001.Duas funções:
X3_CONTEXT='R').X3_CONTEXT='V') — recalcula a cada paint.// Default cliente "padrão"
"000001"
// Default a partir de função
U_ABCFatPad()
// Virtual: soma de itens
GetAdvFVal("SC6", "C6_TOTAL", xFilial("SC6")+SC5->C5_NUM, 1, 0)
"", Space(N), 0) — usuário sempre vai precisar redigitar. plugadvpl lint --cross-file --regra SX-009. (Obs: em v12.1.7+ X3_OBRIGAT é bitmap controlado por API; clientes normalmente forçam obrigatoriedade via X3_VALID := "!Empty(M->CAMPO)".)MemoLine().Retorna .T. (habilita) ou .F. (cinza). Avaliada a cada repaint.
// Habilita campo só para clientes pessoa jurídica
M->A1_PESSOA == "J"
// Habilita só após cliente preencher CNPJ
!Vazio(M->A1_CGC)
// Habilita conforme parâmetro MV_*
GetMV("MV_XYZUSA", .F., .F.)
X3_VALID: nada de SQL pesado, nada de side effects..F. em campo obrigatório com INIT vazio = registro impossível de gravar. Audite o trio (OBRIGAT, INIT, WHEN) junto.Roda depois de X3_VALID retornar .T.. Convenção: usar para customização sem alterar o VALID padrão TOTVS.
// Apenas o cliente VLDUSER (preserva X3_VALID = "ExistCpo('SA1') .And. ...")
U_ABCA1ValExtra()
Boa prática: clientes devem usar
X3_VLDUSERpara customização e não alterarX3_VALID— evita conflito em update.
Após terminar edição do campo origem (X7_CAMPO), o ERP avalia X7_REGRA e atribui o resultado a X7_CDOMIN.
// Tipo 1: Primário (P) — avalia direto
X7_TIPO = P
X7_CAMPO = A1_COD
X7_REGRA = M->A1_COD + " - default"
X7_CDOMIN= A1_NREDUZ
// Tipo 2: Pesquisar (P com SEEK) — DbSeek + retorno
X7_TIPO = P
X7_CAMPO = A1_COD
X7_SEEK = S
X7_ALIAS = SA1
X7_ORDEM = 1
X7_CHAVE = xFilial("SA1") + M->A1_COD
X7_REGRA = SA1->A1_NREDUZ
X7_CDOMIN= A1_NREDUZ
X7_TIPO='P' (Pesquisar) sem X7_SEEK='S' — lookup falha silenciosamente. Detector: SX-010.SX-002.X7_REGRA complexa de várias linhas — impossível debugar. Sempre use U_xxx.plugadvpl gatilho A1_COD --depth 3 mostra a cadeia.Mesma semântica de X3_VALID mas no contexto de Pergunte(). A variável é a MV_PARxx.
// Pergunta de "Empresa De"
X1_VARIAVL = mv_ch1
X1_VALID = ExistCpo("SM0", MV_PAR01)
X1_DEF01 = "01"
// Validação ao gravar parâmetro
X6_VALID = NaoVazio() .And. (Type("X6_CONTEUD") $ "CN")
// Default quando GetMV não acha registro
X6_INIT = "01"
plugadvpl impacto cruza tudo isso$ plugadvpl impacto A1_COD --depth 2
Tipo | Local | Contexto | Severidade
------|--------------------------------|--------------------------------------------|------------
SX7 | A1_COD#01 → A1_NREDUZ | depth=1 tipo=P regra=SA1->A1_NREDUZ | critical
SX7 | A1_NREDUZ#01 → A1_INSCR | depth=2 tipo=P | critical
SX3 | SA1.A1_COD | C(6) Codigo do Cliente | warning
SX3 | SA2.A2_REFCLI | VLDUSER=ExistCpo("SA1",M->A2_REFCLI,1) | warning
fonte | ABCA1V01.prw:42::U_ABCA1V01 | Local cCod := M->A1_COD | warning
fonte | FATA050.prw:128::FATA050 | RecLock("SA1", .T.) ; Replace A1_COD With | critical
SX1 | MTCRDIV#02 | Cliente De: ExistCpo("SA1",MV_PAR02) | warning
A query interna faz JOIN/LIKE em campos.validacao, campos.vlduser,
campos.when_expr, campos.inicializador, gatilhos.regra, gatilhos.condicao,
perguntas.validacao, perguntas.conteudo_padrao, e em fonte_chunks.content.
plugadvpl ingest-sx <pasta-csv> — popula o dicionário SX no índice.plugadvpl impacto A1_COD [--depth 1..3] — cruza fontes ↔ SX.plugadvpl gatilho A1_COD [--depth 1..3] — cadeia SX7 origem → destino.plugadvpl lint --cross-file — recalcula as 11 regras SX-001..SX-011.plugadvpl lint --regra SX-007 --severity critical — só funções restritas em VALID.plugadvpl sx-status — counts por tabela SX.plugadvpl impacto A1_COD --depth 3 — vê tudo que mexe.plugadvpl gatilho <destino> — fecha cadeia.U_xxx em VALID/INIT/REGRA, plugadvpl find <U_xxx> + arch.plugadvpl param <MV_x> / plugadvpl find Pergunte.X3_VALID / X3_VLDUSER / X3_WHEN — executa a cada Loose Focus. Lint SX-006 warning. Use Posicione/ExistCpo.X3_VALID — SX-007 critical, quebra em update do ERP.U_xxx chamada em VALID/INIT/REGRA sem fonte indexado — SX-001 warning.SX-009 warning. Usuário sempre redigita.X7_TIPO='P' sem X7_SEEK='S' — SX-010 error.SX-002 error.X3_F3 apontando para SXB inexistente — SX-011 error.X2_MODO='C') com xFilial em X3_VALID — SX-008 warning.X3_VALID padrão TOTVS — conflita em update. Use X3_VLDUSER separado./plugadvpl:gatilho A --depth 3 detecta.[[advpl-dicionario-sx]] — estrutura completa das tabelas SX (irmã desta skill).[[advpl-code-review]] — regras lint SX-001..SX-011 cross-file.[[advpl-fundamentals]] — M-> notação (memo), U_xxx User Function, prefixo cliente.[[advpl-embedded-sql]] — BeginSql em VALID é anti-pattern SX-006.[[advpl-mvc]] — FWFormStruct(1) carrega X3_VALID/INIT/WHEN do dicionário.[[advpl-mvc-avancado]] — SetErrorMessage em vez de Help dentro de VALID custom.[[advpl-pontos-entrada]] — <rotina>VLD PE oferece validação fora do dicionário.[[advpl-debugging]] — "campo não aparece" / "gatilho não dispara" workflow.[[plugadvpl-index-usage]] — /plugadvpl:impacto, /plugadvpl:gatilho.