C2f Variables System

---
name: c2f-variables-system
description: "LEIA ANTES de escrever qualquer texto, rótulo, título, tooltip, mensagem de erro ou alerta no código. Se não ler: strings literais violam a governança i18n, impedem personalização por tenant e o PR é rejeitado."
user-invocable: false
---

# ⚡ Gatilho Obrigatório
- **TRIGGER**: Escrever, alterar ou adicionar qualquer texto visível, label, mensagem de validação, título ou alerta em arquivos PHP, HTML ou JavaScript.
- **SKIP APENAS SE**: Identificadores técnicos estritos (nomes de colunas SQL, chaves de array, classes CSS ou slugs internos).
- **CONSEQUÊNCIA DE IGNORAR**: Rejeição sumária do PR por inclusão de texto hardcoded, quebra da internacionalização (i18n) e impossibilidade de alteração de textos via painel de variáveis.

---

---
name: c2f-variables-system
description: "Use SEMPRE que for escrever textos, mensagens de erro, alertas, labels ou qualquer string de interface. Consulte ANTES de usar texto literal em PHP, HTML ou JS."
user-invocable: false
---

# Sistema de Variáveis e Mensagens Multilíngues do Conn2Flow

> [!CAUTION]
> **REGRA MANDATÓRIA — PROIBIDO TEXTO LITERAL FIXO**:
> É ESTRITAMENTE PROIBIDO inserir textos literais fixos (strings hardcoded) em código PHP, HTML ou JavaScript para:
> - Mensagens de erro ou sucesso
> - Alertas e warnings de interface
> - Labels de formulários e botões
> - Títulos, descrições e placeholders
> - Qualquer texto visível ao usuário final
>
> TODOS os textos DEVEM ser declarados no **Sistema de Variáveis** e consumidos via API.

## 1. Declaração de Variáveis

### 1.1. Variáveis Globais
Arquivo: `gestor/resources/<lang>/variables.json`

```json
{
  "minha-variavel": {
    "valor": "Texto visível ao usuário",
    "descricao": "Descrição interna para o administrador"
  },
  "erro-permissao": {
    "valor": "Você não tem permissão para acessar este recurso.",
    "descricao": "Mensagem de erro de permissão"
  }
}
```

### 1.2. Variáveis de Módulo
Arquivo: `modulos/<modulo-id>/<modulo-id>.json`, dentro da chave `resources.<lang>.variables`:

```json
{
  "resources": {
    "pt-br": {
      "variables": {
        "titulo-listagem": {
          "valor": "Lista de Registros",
          "descricao": "Título da página de listagem"
        }
      }
    }
  }
}
```

---

## 2. Consumo de Variáveis

### 2.1. Em PHP
```php
// Variável global
$texto = gestor_variaveis(['id' => 'minha-variavel']);

// Variável de módulo
$texto = gestor_variaveis(['modulo' => 'meu-modulo', 'id' => 'titulo-listagem']);
```

### 2.2. Em HTML / Templates de Recurso
```html
<!-- Substituição direta no template engine -->
<h1>@[[titulo-listagem]]@</h1>
<p>[[descricao-pagina]]</p>

<!-- Alternativa: substituição via modelo_var_troca() no PHP que renderiza o template -->
```

### 2.3. Em JavaScript (via atributos data ou variáveis PHP injetadas)
```html
<div data-msg-erro="@[[erro-permissao]]@"></div>
```
```javascript
const msg = element.dataset.msgErro;
```

---

## 3. Fluxo de Compilação

1. Editar `variables.json` (global) ou `<modulo>.json` (módulo)
2. `atualizacao-dados-recursos.php` compila para `VariaveisData.json`
3. `atualizacoes-banco-de-dados.php` aplica Upsert na tabela `variaveis`
4. Runtime consome via `gestor_variaveis()` ou substituição de template