---
title: "Dynamic Form Rules Authoring Plan"
slug: "dynamic-form-rules-authoring-plan"
description: "Plano canonico para evoluir a autoria de regras do Dynamic Form com builder visual, LLM, preview, validacao e visual blocks."
doc_type: "guide"
document_kind: "host-guide"
category: "architecture"
audience:
  - "frontend"
  - "host"
  - "platform-team"
  - "architect"
level: "advanced"
status: "active"
owner: "praxis-ui"
tags:
  - "dynamic-form"
  - "rules"
  - "visual-builder"
  - "llm"
  - "visual-blocks"
toc: true
sidebar: true
reading_time: "16 min"
estimated_setup_time: "multi-phase"
last_updated: "2026-04-22"
source_of_truth:
  - "projects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.ts"
  - "projects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.html"
  - "projects/praxis-dynamic-form/src/lib/utils/rule-converters.ts"
  - "projects/praxis-dynamic-form/src/lib/utils/rule-property.utils.ts"
  - "projects/praxis-dynamic-form/src/lib/services/form-rules.service.ts"
  - "projects/praxis-core/src/lib/models/form/rule-property.schema.ts"
  - "projects/praxis-dynamic-form/src/lib/ai/praxis-dynamic-form-authoring-manifest.ts"
  - "projects/praxis-dynamic-form/docs/dynamic-form-llm-rule-authoring-guide.md"
---

# Dynamic Form Rules Authoring Plan

Este plano define como a autoria de regras do Dynamic Form deve evoluir para suportar a complexidade real da funcionalidade: regras visuais, regras criadas por LLM, round-trip no builder, preview, alvos estruturais e blocos visuais.

## Escopo deste documento

Este documento governa a evolucao da experiencia de autoria de regras no editor do `praxis-dynamic-form`. Ele nao substitui a referencia JSON API nem o contrato de visual blocks; ele amarra esses contratos em uma estrategia implementavel para UX, validacao, LLM e testes.

## Pre-requisitos

- Conhecer `FormConfig`, `formRules` e `formRulesState`.
- Conhecer Json Logic canonico usado pelo runtime Praxis.
- Conhecer `FormColumn.items[]` para campos e blocos `richContent`.
- Consultar `RULE_PROPERTY_SCHEMA` antes de adicionar qualquer propriedade nova por regra.

## Estado atual

O editor de configuracao do Dynamic Form usa um `mat-tab-group`. A aba `Regras` renderiza `praxis-visual-builder`:

```html
<praxis-visual-builder
  [config]="ruleBuilderConfig"
  [initialRules]="ruleBuilderState"
  (rulesChanged)="onRulesChanged($event)">
</praxis-visual-builder>
```

Quando o builder muda, o editor persiste dois artefatos:

| Artefato | Papel | Quem deve escrever |
| --- | --- | --- |
| `formRules` | Contrato executavel pelo runtime. | Builder visual, LLM validada ou JSON editor. |
| `formRulesState` | Estado visual para reabrir o builder sem perda. | Apenas o builder/conversores internos. |

O runtime consome `formRules` via `FormRulesService`. `formRulesState` nao deve participar da execucao.

## Partes da funcionalidade

A funcionalidade completa tem oito partes, que hoje estao espalhadas:

| Parte | Estado atual | Lacuna principal |
| --- | --- | --- |
| Descoberta de alvos | `createRuleBuilderConfig` mapeia campos, secoes, linhas, colunas, actions e visual blocks. | Falta mapa de impacto legivel para o usuario. |
| Condicao | Builder converte condicoes simples para Json Logic. | Condicoes complexas podem virar runtime-only. |
| Efeito | `RULE_PROPERTY_SCHEMA` define propriedades permitidas por alvo. | UI mostra propriedades por alvo, rejeicoes do sanitizer e oferece correcao assistida. |
| Conversao | `rule-converters.ts` faz round-trip `formRules` <-> `RuleBuilderState` e preserva metadados semanticos como `type: "visualBlockGuidance"` via `config.ruleType`. | Nao ha status explicito de compatibilidade visual. |
| Execucao | `FormRulesService` resolve valores calculados de campos em fase anterior, aplica propriedades saneadas e o editor oferece preview true/false para revisar o efeito antes de persistir. | Falta ampliar mensagens de diagnóstico para casos de sanitizer parcial. |
| LLM | Manifesto publica operacoes locais de component/form authoring e preserva `rule.visualBlockGuidance.add` apenas como projecao visual opcional. | Business-rule authoring deve entrar por `domain-rules`/`shared_rule_authoring` antes de virar `form_config`. |
| Visual blocks | Alvo `visualBlock` existe, entra em `targetSchemas.visualBlocks`, aceita `text`, `title` e `message` saneados e o painel de propriedades guia `textNodeId`, `titleNodeId` e `messageNodeId`. | Falta apenas ampliar biblioteca de exemplos visuais por domínio, sem mudar o contrato. |
| Governanca | Propriedades nao whitelisted sao descartadas, aparecem para o autor e podem ser corrigidas pelo painel de diagnosticos. | Expandir telemetria/curadoria conforme o catalogo publico amadurecer. |

## Modelo mental alvo

A aba `Regras` deve virar uma experiencia guiada com cinco etapas internas:

```mermaid
flowchart LR
  target["1. Alvo"] --> condition["2. Condicao"]
  condition --> effect["3. Efeito"]
  effect --> preview["4. Preview"]
  preview --> review["5. Revisao"]
  review --> apply["Aplicar em formRules"]
```

Isso nao exige trocar o editor inteiro para stepper. O editor geral pode continuar em abas. O fluxo guiado deve existir dentro da aba `Regras`.

## Contrato de compatibilidade

Toda regra deve receber um status calculado:

| Status | Significado |
| --- | --- |
| `valid` | Executavel no runtime. |
| `invalid-target` | Um ou mais targets nao existem. |
| `invalid-condition` | Condicao nao e Json Logic valida. |
| `invalid-value-expression` | Valor calculado de campo usa Json Logic invalido ou envelope ambiguo. |
| `computed-value-iteration-limit` | Valores calculados encadeados nao estabilizaram dentro do limite do runtime. |
| `unsupported-property` | Efeito contem propriedade fora do whitelist. |
| `runtime-only` | Regra executa, mas nao reabre fielmente no builder visual. |
| `visual-builder-compatible` | Regra executa e reabre no builder visual. |
| `llm-generated-pending-review` | Sugestao da LLM ainda nao aprovada pelo usuario. |

O status deve ser exibido na lista de regras, no painel de revisao e no resumo de alteracoes.

## Regras criadas por LLM

LLM pode sugerir materializacoes visuais derivadas, mas deve seguir estas politicas:

- LLM nao usa `formRules` ou `visualBlockGuidance` como fonte canonica da regra de negocio.
- Quando a decisao governada precisa aparecer na UI, a materializacao escreve apenas `formRules`.
- LLM nunca escreve `formRulesState`.
- Operacoes de IA `rule.visibility.add`, `rule.validation.add` e
  `rule.visualBlockGuidance.add` exigem
  `metadata.origin: "llm"` e `metadata.reviewStatus: "pending"` no manifesto.
- Para regra de negocio, politica, elegibilidade, validacao, compliance ou
  decisao compartilhada, preferir `domain-rules`/`shared_rule_authoring`.
- Para materializacao visual derivada de uma decisao ja governada, aceitar
  `rule.visualBlockGuidance.add` com `type: "visualBlockGuidance"`,
  `targetType: "visualBlock"` e `context: "notification"`.
- Toda condicao deve ser Json Logic canonico.
- Valores calculados em `effect.properties.value` e
  `effect.propertiesWhenFalse.value` devem usar envelope fechado e exclusivo:
  exatamente `{ "expression": <JsonLogic> }` ou exatamente
  `{ "literal": <valor> }`. Objetos literais estruturados precisam do envelope
  `literal`; envelopes com chaves extras sao rejeitados.
- Valores calculados sao resolvidos antes das demais propriedades por iteracao
  limitada ate estabilizacao, entao regras dependentes nao devem depender da
  ordem no array de `formRules`.
- Toda propriedade deve existir em `RULE_PROPERTY_SCHEMA[targetType]`.
- Todo target deve existir no `ruleBuilderConfig.targetSchemas`.
- Remocao de regra exige confirmacao humana.
- Regra criada por LLM entra como `llm-generated-pending-review`.
- Ao aceitar, o editor tenta gerar `formRulesState` por `formLayoutRulesToBuilderState`.
- O round-trip deve preservar metadados semanticos. Quando o builder precisar
  usar `config.type` para o tipo visual do node, o discriminador da regra deve
  viajar como `config.ruleType` e voltar para `formRules[].type`.
- Se o round-trip perder semantica, a regra fica `runtime-only` e precisa aviso claro.

O guia operacional para prompts, contexto minimo, exemplos LGPD e correcao de
diagnostics fica em `./dynamic-form-llm-rule-authoring-guide.md`.

## Visual blocks em regras

O alvo `visualBlock` ja existe no schema de propriedades. No estado atual, o whitelist permite:

| Propriedade | Uso |
| --- | --- |
| `visible` | Exibir quando a condicao e verdadeira. |
| `hidden` | Ocultar quando a condicao e verdadeira. |
| `text` | Sobrescrever texto apenas em documento simples ou node `text` identificado. |
| `textNodeId` | Escolher explicitamente o node que recebera `text`. |
| `title` | Sobrescrever titulo apenas em documento simples ou node `title` identificado. |
| `titleNodeId` | Escolher explicitamente o node que recebera `title`. |
| `message` | Sobrescrever mensagem apenas em documento simples ou node `message` identificado. |
| `messageNodeId` | Escolher explicitamente o node que recebera `message`. |
| `layout` | Alternar entre `block` e `inline`. |
| `rootClassName` | Classe no wrapper raiz. |
| `className` | Classe CSS do bloco. |
| `style` | Estilo inline saneado. |

O contrato seguro para `title`, `message` e `text` e:

- aplicar apenas em documentos simples ou nodes identificados;
- presets criados pelo layout usam ids convencionais: `text`, `title` e `message`;
- nodes identificados podem estar no primeiro nivel ou aninhados em `compose`/`card`;
- o painel de propriedades permite escolher um node identificado e persiste `textNodeId`, `titleNodeId` ou `messageNodeId`;
- rejeitar HTML arbitrario, handlers, URLs inseguras e documentos inteiros;
- preservar `RichContentDocument` original como fonte de verdade;
- aplicar override em runtime sem transformar bloco visual em campo;
- cobrir com testes unitarios de sanitizer, runtime e E2E visual.

## Mapa de impacto

Cada regra deve exibir:

- alvos afetados;
- campos usados na condicao;
- propriedades alteradas em true/false;
- se afeta submit;
- se e visual-only;
- se depende de bloco visual, secao, linha ou coluna;
- se ha alvo inexistente;
- se alguma propriedade foi descartada pelo sanitizer.

Impacto esperado por alvo:

| Target type | Impacto no submit | Observacao |
| --- | --- | --- |
| `field` | Pode afetar payload indiretamente por `required`, `disabled`, `readonly` e `defaultValue`. | Exige cuidado maior. |
| `section` | Normalmente visual, mas pode ocultar varios campos. | Precisa listar campos descendentes. |
| `row` | Visual/layout. | Pode esconder grupo de campos. |
| `column` | Visual/layout. | Pode alterar alinhamento responsivo. |
| `action` | Pode bloquear fluxo operacional. | `disabled`, `loading` e `visible` devem ser revisados. |
| `visualBlock` | Visual-only. | Nunca entra em `fieldMetadata`, `FormControl` ou payload. |

## Preview requerido

O editor deve ter preview true/false por regra:

1. O usuario escolhe uma regra.
2. O painel mostra os campos usados na condicao.
3. O usuario edita valores de exemplo.
4. O editor avalia Json Logic.
5. O preview aplica `properties` ou `propertiesWhenFalse`.
6. O diff mostra o que muda no formulario.

Esse preview deve funcionar sem backend. Para campos remotos/selects, usar valores de exemplo do metadata ou entrada manual.

## Design e UX alvo

A aba `Regras` deve ter tres areas:

| Area | Conteudo |
| --- | --- |
| Lista | Regras, status, origem, alvo e busca/filtro. |
| Builder | Fluxo Alvo -> Condicao -> Efeito. |
| Preview | Estado true/false, impacto, JSON e diff. |

Filtros minimos:

- por alvo;
- por origem: manual, JSON, LLM;
- por status;
- por propriedade alterada.

Microcopy obrigatoria:

- explicar que `formRules` executa no runtime;
- explicar que `formRulesState` e somente para o builder visual;
- marcar `runtime-only` sem tom de erro fatal;
- marcar LLM como sugestao pendente de revisao.

## Roadmap incremental

### Fase 1 - Validador central

Status: implementado.

Criar um validador puro, sem UI, que recebe `FormConfig` e retorna status por regra.

Entradas:

- `formRules`;
- `formRulesState`;
- `fieldMetadata`;
- `sections`;
- `actions`;
- `RULE_PROPERTY_SCHEMA`.

Saida:

```ts
interface FormRuleDiagnostics {
  ruleId: string;
  status: RuleAuthoringStatus[];
  targetRefs: Array<{ type: string; id: string; exists: boolean }>;
  conditionRefs: string[];
  acceptedProperties: string[];
  rejectedProperties: string[];
  runtimeOnlyReason?: string;
}
```

### Fase 2 - Status na UI

Status: implementado com diagnostics acionaveis e correcao assistida.

Exibir diagnostics na aba `Regras`:

- badge por regra;
- resumo de problemas;
- link para abrir o alvo no layout;
- aviso quando o sanitizer descarta propriedade.
- acao `Corrigir` para aplicar whitelist/saneamento central e regenerar `formRulesState`.

### Fase 3 - Preview true/false

Status: implementado como preview/diff de propriedades de regra; ainda cabe evolucao visual do formulario completo.

Adicionar painel de preview isolado:

- avaliar Json Logic com valores mockados;
- mostrar `properties` versus `propertiesWhenFalse`;
- aplicar preview visual sem persistir;
- exibir diff JSON.

### Fase 4 - LLM review lane

Status: implementado para regras ja sugeridas/persistidas como pendentes; geracao de sugestao por LLM ainda e proxima evolucao.

Criar fluxo de aceite para sugestoes de LLM:

- `Generate suggestion`;
- validar;
- mostrar diff;
- permitir editar antes de aplicar;
- marcar origem `llm`;
- gerar `formRulesState` somente apos aceite.

### Fase 5 - Visual block text seguro

Status: implementado como primeira versao segura.

O suporte a `title`, `message` e `text` em regras de `visualBlock` fica limitado a:

- nodes de texto simples;
- nodes com `id` estavel;
- ids convencionais gerados por presets do layout;
- escolha explicita de node pelo painel de propriedades da regra;
- overrides saneados em runtime;
- sem mutar o documento original durante preview.

### Fase 6 - Testes E2E visuais

Status: cobertura implementada para os fluxos críticos; manter expansão incremental por domínio.

Cobrir:

- regra de field;
- regra de section;
- regra de action;
- regra de row/column;
- regra de visualBlock visible/style/text com node interno;
- regra LLM pendente e aceita;
- regra runtime-only;
- round-trip builder;
- formulario real de funcionarios.

## Checklist de aceite

- [x] Regra invalida nunca e aplicada silenciosamente em todos os fluxos de entrada cobertos: editor, manifesto LLM, JSON authoring e runtime.
- [x] Propriedade descartada aparece na UI.
- [x] LLM nao escreve `formRulesState`.
- [x] Regra LLM so aplica apos revisao no fluxo de authoring do editor.
- [x] Regra runtime-only permanece editavel em JSON e visivel na lista.
- [x] Preview true/false funciona sem backend para propriedades de regra.
- [x] Visual block continua fora de `fieldMetadata`, `FormControl` e payload.
- [x] Text override de visual block e saneado e coberto por testes.
- [x] Abrir, salvar, reabrir e renderizar preserva `formRules`, `formRulesState` e metadata de revisao LLM no round-trip coberto.
- [x] A documentacao tecnica descreve limites do builder visual e da LLM.
- [x] Publicar/espelhar guia na landing publica em `/components/dynamic-form/docs/rules-authoring`.
- [x] Diagnostico diferencia propriedade fora do contrato, valor invalido e valor parcialmente saneado.
- [x] Painel de diagnostics oferece correcao assistida para propriedades rejeitadas/saneadas e regenera `formRulesState`.
- [x] Exemplos visuais por dominio demonstram `visualBlock` com regras de texto/estilo sem ampliar contrato.
- [x] Exemplos de dominio conectados ao catalogo de recipes em `examples/ai-recipes/praxis-dynamic-form.visual-block-domain-rules.json`.

## Proximos incrementos recomendados

1. Manter E2E visual em formularios reais para regressao de payload, node interno e round-trip do builder.
2. Espelhar a referencia JSON API atualizada na landing publica quando a pipeline de docs rodar.
3. Publicar/curar o novo recipe de regras `visualBlock` na landing publica quando a pipeline de docs rodar.
4. Evoluir a correcao assistida para sugerir substituicoes semanticas, nao apenas aplicar sanitizer deterministico.

## Evidencia publicada

- Guia tecnico canonico: `projects/praxis-dynamic-form/docs/dynamic-form-rules-authoring-plan.md`.
- Guia operacional LLM/analista: `projects/praxis-dynamic-form/docs/dynamic-form-llm-rule-authoring-guide.md`.
- Guia publico espelhado: `/components/dynamic-form/docs/rules-authoring`.
- Recipe publico de dominio: `examples/ai-recipes/praxis-dynamic-form.visual-block-domain-rules.json`.
- Cobertura focal de payload: `projects/praxis-dynamic-form/test-dev/e2e/funcionarios-form-demo-rules.playwright.spec.ts`.
- Cobertura focal de editor de node interno, revisao LLM e correcao assistida: `projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-rules.playwright.spec.ts`.
- Cobertura focal de runtime fechado: `projects/praxis-dynamic-form/src/lib/services/form-rules.service.spec.ts`.
