# Ag 12 Sql Totvs Zeev

> Maquina especialista em dados Raiz: data-engine API canonical (/v1/kpis/*, /reports/<panel>/data, Envelope v2, KPI Registry Ouro M01..A*) + SQL TOTVS RM + Neon PostgreSQL + Zeev BPM + PBI_DATASET. Use para: descobrir KPI Ouro, consumir painel canonical, escrever query nova (cascade painel>KPI>dinamica>raw), otimizar SQL lenta, anti-patterns, relatorios, processos Zeev. Tier 0: data-engine. Aplica…

- **Type:** Skill
- **Install:** `agentstack add skill-andregusman-raiz-a-gusman-claude-ag-12-sql-totvs-zeev`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [andregusman-raiz](https://agentstack.voostack.com/s/andregusman-raiz)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [andregusman-raiz](https://github.com/andregusman-raiz)
- **Source:** https://github.com/andregusman-raiz/a-gusman-claude/tree/main/skills/ag-12-sql-totvs-zeev

## Install

```sh
agentstack add skill-andregusman-raiz-a-gusman-claude-ag-12-sql-totvs-zeev
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Data Engine + SQL Optimization — TOTVS RM, Zeev BPM, PostgreSQL, PBI_DATASET

## 🎯 TIER 0 — Data Engine API (PREFERIR sobre SQL direto)

> data-engine-app é a **camada canonical** que já decodifica regras de negócio,
> agrega Bronze→Prata→Ouro, aplica governança e expõe `value_raw + value_formatted`
> consistente com BI Raiz. Se a resposta já existe na API canonical → consumi-la,
> nunca reescrever SQL equivalente em outro projeto.

### Arquitetura em 4 camadas (consultar ANTES de escolher fonte)

```
Bronze (mirrors raw)  →  Prata (dbt int/fact/dim)  →  Ouro (KPI Registry, 65+ IDs)  →  API
                                                                                       │
                                          ┌────────────────────────────────────────────┤
                                          ▼                            ▼                ▼
                                    DISCOVERY                    EXECUTION         GOVERNANCE
                              /v1/kpis/catalog            /v1/kpis/{id}/value     X-API-Key
                              /v1/kpis/search             /reports//data    rate-tiers
                              //dictionary        /query/preflight + execute  PII mask
                              /v1/manifest                                              audit
                              /openapi.json (x-raiz-lineage)
```

| Camada | Conteúdo | Source of truth |
|---|---|---|
| **Bronze** | Scrapers, TOTVS REST/SOAP, BI Raiz | sistemas externos |
| **Prata** | dbt `fact_*` + `dim_*` em `prata.*` | Neon mirror (PBI_DATASET + TOTVS RM) |
| **Ouro** | KPI Registry (65 KPIs) | `raiz_data_engine/reports/core/kpi_registry/` |
| **API** | Envelope v2 universal `{value_raw, value_formatted}` | `raiz_data_engine/api/` |

### Cascade de Decisão (regra inegociável)

Ordem de preferência ao buscar dado:

1. `GET /reports//data` — bundle multi-KPI cacheado (14 painéis ativos)
2. `GET /v1/kpis/{id}/value?filters=...` — execução canônica do KPI Ouro
3. `POST /query/preflight` → `POST /query/execute` — SQL dinâmico governado (audit + PII)
4. SQL direto TOTVS RM / Neon / PBI_DATASET — **último recurso**, só se nada acima cobre

**Se IA/plataforma já consome data-engine:** prefira Tier 0. SQL direto vira fallback documentado, não default.

### IDs canônicos KPI Ouro (referência rápida — `kpi_id`)

| Prefixo | Domínio | Faixa | Exemplos |
|---|---|---|---|
| **M** | Matrículas | M01–M15 | M01 Alunos Matriculados, M07 Taxa Ocupação |
| **C** | Cobrança / Comercial | C01–C08 | C04 % Inadimplência Canonical |
| **E** | Endividamento / Educacional | E01–E05 | E04 Saldo Devedor |
| **R/F/S** | RH / Financeiro / Satisfação | extras Q9.C.0 | — |
| **L/B/Z** | Layers / Benefícios / Zeev | extras | — |
| **I/Q/N** | INEP / Quality / NPS | extras | — |
| **D/A** | DRE / Avaliações | extras | A12 ENEM Redação |

> Regra: persistir/logar/cachear sempre por `kpi_id` (estável). `label_pt` muda; ID não.

### Endpoints canonical (memorizar)

| Endpoint | Para que | Auth |
|---|---|---|
| `GET /v1/kpis/catalog` | catálogo completo (rich schema, fórmula SQL, known_gaps) | público |
| `GET /v1/kpis/catalog?domain=&status=canonical` | filtrado | público |
| `GET /v1/kpis/search?q=...&prefix=M&limit=50` | full-text (key+label+description) | público |
| `GET /v1/kpis/{id}` | lookup individual (atalho) | público |
| `GET /v1/kpis/{id}/consumers` | painéis + APIs que usam | público |
| `GET /v1/kpis/{id}/value?filters=...` | execução SQL canônica do KPI Ouro | público |
| `GET //dictionary` | dictionary (kpis + tables + conventions) | público |
| `GET /reports//data` | bundle de painel pronto | público |
| `GET /v1/manifest` | catalog de manifests | público |
| `GET /schema/tables` | lista schema catalog cross-source | X-API-Key |
| `GET /v1/schema/table/{table_name}` | lookup público individual de tabela | público |
| `POST /query/preflight` | valida SQL antes de executar | X-API-Key |
| `POST /query/execute` | SQL dinâmico governado, usar `source=neon` | X-API-Key |
| `GET /openapi.json` | OpenAPI + extensão `x-raiz-lineage` | público |
| `GET /metrics/canonical` | Prometheus | público |

Base prod: `https://app.example.com`

### Política runtime TOTVS/RH para agentes

- ADR-041: não usar SQL direto TOTVS RM em runtime Railway.
- `/query/execute` é fallback governado Neon-only para agentes; enviar `source=neon`.
- Se o usuário trouxer SQL RM bruto, converter manualmente para mirror Neon ou retornar gap acionável. Não selecionar fonte TOTVS RM direta no endpoint dinâmico.
- Mirrors RH disponíveis:
  - `PFFINANC` → `public.pffinanc_mirror`
  - `PEVENTO` → `public.pevento_mirror`
  - `PFUNC` → `public.pfunc_mirror`
  - `PFUNCAO` → `public.pfuncao_mirror`
  - `GFORMULA` → `public.gformula_mirror`
- `GFORMULA` está disponível no Neon/schema registry para análise técnica de fórmulas RM. Usar `source=neon`; não usar `source=totvs_rm` em runtime. `FORMULACOMPILADA` binária não é espelhada; usar `texto`, `titulo` e metadados.

### TOTVS GCONSSQL via wsDataServer

Descoberta incorporada: cadastrar sentença SQL custom em `GCONSSQL` via `wsDataServer`/`GlbConsSqlData` desbloqueia fontes sem DataServer de negócio, como `MovMovimentoData`, desde que tratado como registry governado.

Uso permitido:
- sync/backfill controlado, nunca endpoint de SQL livre;
- SQL versionado no `data-engine-app`;
- sentença `COUNT` + sentença `PAGE`;
- filtro obrigatório por `CODCOLIGADA`;
- paginação determinística `OFFSET/FETCH`;
- staging no Neon + count parity antes de publish;
- PII somente com RBAC/LGPD formal.

Uso proibido:
- `SELECT *`;
- `INSERT/UPDATE/DELETE/MERGE/DROP/ALTER/CREATE/EXEC`;
- execução runtime direta contra TOTVS;
- logar payload de linha, token, senha, CPF, RA, chapa ou nome.

Fonte canônica no repo:
- `scripts/ops/config/totvs_governed_sentence_registry.json`
- `scripts/ops/sql/totvs_governed_sentence_registry/`
- `docs/runbooks/totvs-governed-gconssql-registry.md`

Piloto recomendado: `RDE.TOTVS.TMOV.COUNT/PAGE` e `RDE.TOTVS.TITMMOV.COUNT/PAGE` para alimentar `public.tmov_mirror` e `public.titmmov_mirror`.

### Envelope v2 universal

Todo número da API canonical retorna:
```json
{ "value_raw": 1838.0, "value_formatted": "1.838" }
```
- `value_raw` → cálculo / agregação no cliente
- `value_formatted` → display direto (parity com BI Raiz)
- **NUNCA re-formatar `value_raw` no consumer** (mascaramento PII já server-side)

### Rate Limit tiers (slowapi IP-level + 60 RPM/10K dia por key)

| Path | Limite |
|---|---|
| `/health /metrics /readyz` | whitelist |
| `auth/*` | 5/min |
| `admin/*` | 30/min |
| `api/*` (default) | 200/min |
| outros | 100/min |

Retry-on-429 com backoff exponencial + jitter. Batchar lookups (usar `search?prefix=M` em vez de N gets).

### known_gaps — LER SEMPRE antes de prometer número

Cada entry de `/v1/kpis/{id}` traz `known_gaps[]` com semantic drift declarado.
Exemplo M01:
- `matriculados_brutos: sem TAG_MATVALIDA — inclui contratos não confirmados`
- `pre_matriculados: TAG_MATVALIDA=FALSE, contrato sem 1ª parcela paga`

Resposta da IA sem citar known_gaps relevantes = "certo na conta, errado no negócio".

### Lineage via `x-raiz-lineage` (OpenAPI extension)

`/openapi.json` injeta mapping endpoint → tabela Bronze/Prata/Ouro. Usar para:
- explicar resposta: "este número vem de `prata.int_alunos_qualificados` filtrado por…"
- auditar prompt→data trail
- debugar drift cross-source

### Painéis ativos (14) — `/reports//data`

`matriculas`, `dre_dashboard`, `faturamento`, `inadimplencia`, `funnel`, `beneficios`,
`pessoas_rh`, `quadro_docente`, `erros_operacionais`, `pesquisa_satisfacao`,
`layers_comunidade`, `layers_payments`, `zeev`, `avaliacoes_inep`,
+ `painel_kpi_executivo_resumido`, `painel_resumo_operacional` (consolidados).

### Pact contracts (consumer formal)

Plataforma consumidora estável (não one-shot) → adicionar `contracts/consumer/.json`
em `data-engine-app/contracts/consumer/`. Modelo: `example-platform.json`. Trava endpoints + schemas
bidirecionalmente. Para agente IA: mesma lógica previne hallucination em prod.

### Painel novo = registry declarativo (não custom code)

Se a tarefa é **criar painel novo no data-engine**, único caminho aceito:
```bash
/ag-painel-novo-canonico criar painel  com KPIs M01,M02,E03
# OU
python scripts/scaffold_panel.py --panel-id  --kpi-ouro-ids "M01,M02" --all-from-registry
```
CI gate `painel-readiness-strict.yml` BLOQUEIA: queries.py presente, aggregator custom,
MetricSpec sem `kpi_ouro_id`, score  KB inline para eliminar Read round-trip em prompts comuns. Para KB completa e atualizada, consultar `~/Claude/assets/knowledge-base/totvs/`.

### Tabelas TOTVS mais usadas

| Tabela | Propósito | Colunas-chave |
|---|---|---|
| `PPESSOA` | Cadastro pessoa (aluno, funcionário, responsável) | CODIGO, NOME, CPF, DTNASCIMENTO |
| `SALUNO` | Aluno educacional | CODCOLIGADA, RA, CODPESSOA, CODCURSO, CODHABILITACAO |
| `SMATRICULA` | Matrícula por período | CODCOLIGADA, RA, IDPERLET, CODSTATUS, DTMATRICULA |
| `PFUNC` | Funcionário RH (680 cols — NUNCA SELECT *) | CODCOLIGADA, CHAPA, CODPESSOA, CODSITUACAO |
| `PFFINANC` | Ficha financeira (histórico) | CODCOLIGADA, CHAPA, ANOCOMP, MESCOMP |
| `PEVENTO` | Eventos folha (código evento) | CODCOLIGADA, CODEVENTO, DESCRICAO, TIPO |
| `FLAN` | Lançamentos financeiros | CODCOLIGADA, IDLAN, CODCFO, STATUSLAN, VALORORIGINAL |
| `GCOLIGADA` | Coligadas (32 ativas) | CODCOLIGADA, NOME, CNPJ |

### Enums críticos (SStatus por coligada)

```
COL=1 (Raiz):     matriculado = CODSTATUS IN (2, 3)
COL=2 (QI):       matriculado = CODSTATUS IN (2, 3)
COL=10 (SIR):     matriculado = CODSTATUS IN (14, 15, 25, 32) ← stratificado por filial
  FIL=1 (QI Recreio):   IN (2, 3)
  FIL=3,4,6 (Sá Pereira): IN (14, 15)
  FIL=7 (SAP):           IN (25, 32)
```

### Guards obrigatórios TOTVS

1. `WHERE CODCOLIGADA = N` **sempre** (multi-tenant)
2. `FROM TBL (NOLOCK)` **sempre** em leitura
3. `SELECT col1, col2, ...` — **NUNCA `SELECT *`**
4. DateTime sargable: `WHERE DT >= '2026-01-01' AND DT 5K) |
| hubspot_contact | 518K | sim |
| hubspot_lead_raiz | 57K | sim |
| hubspot_totvs_match | 41K | sim |
| pbi_painel_matriculas | 32K | sim |
| ficha_financeira | 436K | sim |
| holerite | 47.5K | sim |

Pattern:
```python
OFFSET = 0; BATCH = 1000
while True:
    rows = query(f"SELECT ... ORDER BY id LIMIT {BATCH} OFFSET {OFFSET}")
    if not rows: break
    process(rows); OFFSET += BATCH
```

### Data Source Router (domain → source)

| Domínio | Fonte Primária |
|---|---|
| Matrículas, educacional, metas | PBI_DATASET (business rules decoded) |
| Financeiro, acordos | PBI_DATASET |
| RH, folha, ponto, compras | TOTVS RM |
| HubSpot deals/contacts/leads | Neon |
| Zeev BPM | Neon (mirror) |

**Regra:** consultar tabela acima ANTES de escrever query. Domínio ambíguo → PARAR e perguntar.

### PBI_DATASET (bridge)

- `SELECT * FROM INFORMATION_SCHEMA.TABLES` para discovery
- NULL-safe filter: `WHERE (col <> 'X' OR col IS NULL)` (SQL Server exclui NULL silencioso)
- Tabelas `Tabela_*` já tem regras de negócio decoded (não replicar em SQL raw)

---

## Knowledge Base Unificada (OBRIGATÓRIO consultar)

### TOTVS RM — KB MECE

```
~/Claude/assets/knowledge-base/totvs/unified/     ← COMECE AQUI
├── schema.json         # 69 tabelas, 1992 campos, FKs, PII flags
├── glossary.json       # 1,211 termos técnico → negócio PT-BR
├── queries.json        # 28 queries catalogadas com metadata
├── apis.json           # 55 REST + 29 SOAP DataServers
├── rules.json          # Regras de negócio (matrícula, notas, financeiro, PII)
├── enums.json          # Valores reais de lookup (SStatus, GColigada, etc.)
├── domains/            # 8 docs por domínio de negócio
└── guides/
    ├── gotchas.md              # 24 lições aprendidas
    └── query-cookbook.md        # Queries por caso de uso
```

Fontes brutas: `~/Claude/assets/knowledge-base/totvs/raw/`

### Zeev BPM — KB MECE

```
~/Claude/assets/knowledge-base/zeev/unified/      ← COMECE AQUI
├── apis.json           # 98 endpoints + 261 modelos
├── integration.json    # Estado integração example-platform (routes, agent tool, env vars)
├── rules.json          # Auth (impersonation), limites, gaps da API
├── glossary.json       # 20 termos Zeev → negócio
├── domains/            # 6 docs por domínio
└── guides/
    ├── gotchas.md              # 20 lições aprendidas
    └── agent-tool-cookbook.md   # 10 ações do zeev_bpm
```

Fontes brutas: `~/Claude/assets/knowledge-base/zeev/raw/`

---

## Pre-Generation Gates (OBRIGATÓRIO antes de gerar qualquer SQL)

Executar TODOS os gates sequencialmente. Se qualquer gate falhar → PARAR e reportar.

### GATE 1 — Source Selection (Tier 0 prioritário)

Mapear o domínio para a fonte correta ANTES de tocar em SQL. **Tier 0 (data-engine API) vence sempre que cobre.**

| Tier | Fonte | Quando |
|---|---|---|
| **0** | **data-engine-app API canonical** | KPI existe no Registry Ouro **OU** painel `/reports//data` cobre a pergunta |
| 1 | PBI_DATASET (***REDACTED_DB***) | Matrículas/financeiro/educacional sem KPI Ouro canonical; tabelas `Tabela_*` |
| 1 | TOTVS RM (Cloud) | RH, folha, ponto, compras, contábil (PFUNC, PFFINANC, PEVENTO, ...) — via Neon Mirror em runtime (ADR-041) |
| 1 | Neon raw (PostgreSQL) | HubSpot deals/contacts/leads, Layers, Zeev, hubspot_totvs_match |
| 2 | `/query/execute` (data-engine) | SQL dinâmico governado quando Tier 0 não cobre mas precisa de PII/audit |
| 3 | SQL direto (psql / sqlcmd / pymssql) | Último recurso: backfill, admin, DDL, exploração ad-hoc |

Regras:
- Se Tier 0 cobre → usar Tier 0 e parar (cita `kpi_id` + `source.primary` + `known_gaps`).
- Se domínio é ambíguo → PARAR e perguntar ao usuário.
- NUNCA escrever SQL equivalente em projeto-cliente quando a API canonical já entrega.

### GATE 2 — Schema Validation (TOTVS RM only)
1. Ler `~/Claude/assets/knowledge-base/totvs/unified/schema.json` para CADA tabela mencionada
2. Verificar nomes EXATOS de colunas — NUNCA inventar nomes de campos
3. Se tabela não está no schema.json (69 tabelas): STOP e declarar "tabela não catalogada na KB"
4. Verificar flags PII em schema.json — se query toca campos PII, aplicar regras de mascaramento

### GATE 3 — Multi-Tenant Guard
1. TOTVS RM: toda query DEVE ter `CODCOLIGADA` no WHERE — injetar se ausente
2. COL=10 (Escolas Integradas Raiz): 3 marcas com status DIFERENTES:
   - FIL=1 (Qi Recreio): CODSTATUS IN (2, 3)
   - FIL=3,4,6 (Sá Pereira): CODSTATUS IN (14, 15)
   - FIL=7 (SAP): CODSTATUS IN (25, 32)
3. Atribuição de marca SEMPRE por `(CODCOLIGADA, CODFILIAL)` pair — NUNCA só CODCOLIGADA

### GATE 4 — Anti-Pattern Rejection
Rejeitar e reescrever automaticamente:
- `SELECT *` → expandir para colunas nomeadas (consultar schema.json)
- Sem `(NOLOCK)` em leitura TOTVS RM → adicionar a todo FROM/JOIN
- Neon query com >5K rows esperados sem paginação → adicionar LIMIT 1000 + OFFSET loop
- `BETWEEN` em DateTime → reescrever como `>= AND  'X' OR col IS NULL)`
4. Discovery: `/api/pbi-app/tables`, `/api/pbi-app/columns/{table}`

### GATE 6 — Data Engine Routing (Tier 0 enforcement)

Antes de escrever **qualquer** SQL contra TOTVS/Neon/PBI_DATASET, executar a cascade:

1. **Discovery KPI** — `GET /v1/kpis/search?q=&domain=` (ou catalog se já souber `kpi_id`)
2. **Painel pronto?** — listar `/reports//data` ativos; se algum bundle responde a pergunta inteira → consumir bundle
3. **KPI canônico?** — `GET /v1/kpis/{id}/value?filters=...` se for métrica isolada
4. **Query dinâmica?** — `POST /query/preflight` antes de `POST /query/execute` (governance: PII mask + audit + rate limit)
5. **Raw SQL?** — só se 1-4 falham, e documentar no PR/commit por que Tier 0 não cobriu (vira backlog de KPI Ouro)

Cada chamada a data-engine deve **citar lineage** no output: `kpi_id`, `source.primary`, `known_gaps[]` relevantes.

### GATE 7 — ADR-041 enforcement (TOTVS via Neon Mirror)

`pymssql.connect()` direto em TOTVS RM é **PROIBIDO em runtime Railway** (ADR-041).
Exceções permiti

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [andregusman-raiz](https://github.com/andregusman-raiz)
- **Source:** [andregusman-raiz/a-gusman-claude](https://github.com/andregusman-raiz/a-gusman-claude)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-andregusman-raiz-a-gusman-claude-ag-12-sql-totvs-zeev
- Seller: https://agentstack.voostack.com/s/andregusman-raiz
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.