# Metodologia do IEP (Índice de Evidência Pública), versão v0

Versão **v0**, de 2026-10-13. Consulta reproduzível: [`iep-v0.sql`](iep-v0.sql). Regra normativa: `docs/domain.md`, seção 9.15; este texto a descreve para quem não lê o código. Se os dois divergirem, vale a 9.15, e a divergência é um erro a corrigir aqui. O índice **ainda não é exibido** no site: a v0 é gravada em `indices_evidencia` e depende da calibração (#105) antes de aparecer.

## O que mede, e o que não mede

O IEP mede a **evidência pública disponível** sobre uma transferência especial (emenda Pix): quanto do que a lei manda publicar se encontra nas fontes oficiais que o Vigia Pix consulta. **Não mede regularidade**, desvio ou boa aplicação do recurso, e a nota baixa não indica irregularidade: dado ausente não é zero, fraude nem inexistência. A unidade é o plano de ação (a transferência). Não há nota por parlamentar: a obrigação de prestar contas é do ente.

Nos moldes da Escala Brasil Transparente 360 (CGU) e do Radar da Transparência (Atricon): critérios públicos, pontos por critério, versão datada e cálculo reproduzível.

## Estados de cada item

| Estado | Significado | Pontos | No denominador |
|---|---|---|---|
| `presente` | o critério é atendido pela evidência na fonte | máximo do item | sim |
| `ausente` | a fonte foi consultada e a evidência não foi localizada | 0 | sim |
| `nao_consultado` | o Vigia Pix ainda não consultou a fonte do item | 0 | não |
| `nao_conferivel` | a fonte foi consultada, mas o critério não pode ser verificado (ex.: plano legado, prazo não calculável) | 0 | não |

- **Pontos** = soma dos pontos dos itens presentes.
- **Conferíveis** (denominador) = soma dos máximos dos itens presentes e ausentes.
- **Percentual** = `round(pontos / conferíveis × 100)`; calculado na leitura, não gravado. Sem nenhum item conferível, **não há percentual**: o índice nunca vira nota zero.

## Itens da v0

| Item | Pontos | Presente | Ausente | Não conferível |
|---|---|---|---|---|
| `plano-aprovado` | 5 | plano de trabalho com data de aprovação | plano de trabalho não localizado na fonte já consultada, ou sem aprovação | plano «Legado ADPF 854», cuja exigência não existia |
| `relatorio-no-prazo` | 15 | primeiro relatório datado até o prazo | prazo vencido sem relatório, ou primeiro relatório depois do prazo | sem ordem enviada com data; ordem anterior a 2024 ou recebimento possivelmente no ano seguinte (sem prazo); prazo não vencido sem relatório; relatório sem data na fonte |
| `documentos-somam-executado` | 10 | documentos de liquidação somam ao menos 95% do executado | soma abaixo de 95% | plano sem relatório no formato novo; relatórios novos todos com executado zero |
| `documentos-iguais-aos-debitos` | 15 | documentos de liquidação somam o mesmo que os débitos da conta, com diferença de até 1% da soma dos documentos | diferença acima de 1%, inclusive documento sem nenhum débito | sem relatório novo ou sem documento (mesmo com débitos na conta); conta como em `credito-conciliado` ou sem nenhum crédito da União conciliado; documento sem data; extrato que não cobre do primeiro documento até 30 dias depois do último |
| `cnae-compativel` | 10 | ao menos 80% da base paga a recebedor com CNAE compatível com a área do plano, mesmo contando os incertos como incompatíveis | menos de 80%, mesmo contando os incertos como compatíveis | sem relatório novo ou sem documento; nenhuma área do plano no mapa CNAE × área; base vazia; resultado que depende de recebedor não localizado na Receita ou sem CNAE principal |
| `credito-conciliado` | 10 | toda ordem enviada com o crédito da União no extrato da conta | alguma ordem sem crédito, com a janela de 10 dias inteira no extrato | conta sem dados, com mais de um executor ou usada por outro plano; nenhuma ordem enviada |
| `pagamento-depois-do-credito` | 5 | todo documento de liquidação datado no dia do primeiro crédito ou depois | algum documento com data anterior ao primeiro crédito | sem relatório novo ou sem documento; crédito da primeira ordem fora do extrato, conta como no item anterior ou sem o corte do banco; documento sem data (sem nenhum anterior) |
| `execucao-no-periodo` | 10 | todo documento de liquidação datado até o fim da execução do plano de trabalho | algum documento com data depois do fim | sem relatório novo ou sem documento; plano de trabalho sem registro ou sem fim da execução; documento sem data (sem nenhum depois) |
| `lai-respondida` | 10 | — | — | sempre `nao_consultado` na v0: o pedido ainda não existe |

Os itens da v0 somam 90 pontos; a escala só chega a 100 com a conta de quatro linhas (#225).

**Documentos iguais aos débitos.** Compara a soma dos documentos de liquidação dos relatórios novos (cada documento uma vez) com a soma dos débitos da conta específica exclusiva do plano, do início do extrato até 30 dias depois da data do último documento. Entram todos os débitos, menos os de aplicação, resgate e estorno (descrição com `devol`, `estorno`, `est`, `cancelad`, `aplic`, `apl`, `ap cdb`, `resgate`, `rsg`, `resg` ou `rg cdb`, sem acento e em minúsculas). A comparação é pela soma, sem casar recebedor com favorecido: pagamento a pessoa física entra dos dois lados. **Diferença da ata do conselho**, que previa só os débitos a favorecidos identificados: boletos, «Impostos», «Emissão de Ordem Bancária» e «Movimento do Dia» vêm da fonte sem favorecido e ficariam de fora, puxando o debitado para baixo. Medição na cópia do banco de 2026-10-13, em 12.450 planos com relatório novo consultado e conta exclusiva conciliada: com todos os débitos menos aplicação, resgate e estorno, 2.568 dos 5.680 planos comparáveis ficaram com diferença de até 1%, 951 entre 1% e 5%, 1.385 com débito acima dos documentos e 776 abaixo. A janela vai até o último documento porque a data do relatório é a de criação na fonte e o ente declara documentos depois dela. Plano sem documento, mesmo com débitos na conta, não é conferível: relatório parcial sem documento não prova que nada foi pago (`domain.md`, 9.6). Fica não consultado com documentos de relatório novo não consultados ou com os lançamentos das contas não carregados.

**CNAE compatível.** Cada documento de liquidação dos relatórios novos é classificado pelo recebedor: CNPJ com CNAE principal ou secundário no mapa CNAE × área v0 para alguma função de governo das áreas do plano (`codigo_descricao_areas_politicas_publicas_plano_acao`), compatível; com CNAE informado e nenhum no mapa, incompatível; sem cadastro consultado na Receita, incerto e não consultado; não localizado ou sem CNAE principal, incerto sem dado. Pessoa física (sem CNAE) e CNPJ com CNAE principal de banco (divisão 64) ou administração pública (84), que recebem tributo, encargo e tarifa, ficam fora da base. O item só pontua ou fica ausente se o resultado não depender dos incertos; quando depende, fica não consultado se algum incerto ainda não teve o cadastro consultado, e não conferível nos demais casos. Documentos de relatório novo não consultados deixam o item não consultado. O mapa v0 está em `app/Transferencias/CnaeNaArea.php` e, igual, no SQL.

**Parâmetros da v0**, sujeitos à calibração (#105): 95% dos documentos sobre o executado (`CalcularIep::LIMITE_DOCUMENTOS`), 1% de diferença entre documentos e débitos (`CalcularIep::LIMITE_DEBITOS`), janela de 30 dias depois do último documento (`CalcularIep::JANELA_DEBITOS_EM_DIAS`) e 80% da base a CNAE compatível (`CalcularIep::LIMITE_CNAE`).

**Não consultado** nos itens novos: lançamentos das contas não carregados; nos dois do crédito, repasses não consultados (sem eles, as ordens enviadas não são conhecidas); em `credito-conciliado`, ordem sem crédito fora do extrato da conta na fonte (antes do primeiro lançamento dela ou com a janela passando do corte do banco), sem nenhuma ordem ausente; nos dois temporais, documentos de relatório novo não consultados e, em `execucao-no-periodo`, plano de trabalho não consultado. Nos temporais, os documentos são conferidos antes do extrato e do plano de trabalho.

**Fim da execução.** Vale o fim atual do plano de trabalho na fonte, que já reflete a prorrogação: nos 120 planos com prorrogação justificada consultados em 2026-10-13, todos têm o fim igual ao início mais o prazo estendido. Só o fim é conferido; o início se confunde com o item do crédito.

**Prazo do relatório de gestão.** Até 30 de junho do ano seguinte ao recebimento (IN TCU 93/2024, art. 3º, § 1º; Portaria Conjunta MF/MGI 15/2025, art. 23). O recebimento é o crédito da primeira ordem bancária enviada na conta específica, quando o extrato o mostra; sem ele, é o dia útil seguinte à ordem (sem feriados), e se esse dia passar de 30/12 do ano da ordem o prazo não é calculado. Ordem anterior a 2024: sem prazo. O prazo está *vencido* quando a data da última consulta aos relatórios é posterior a ele.

**Primeira ordem.** Entre as ordens bancárias enviadas ao banco, de empenho emitido, a de menor data de emissão; no empate, o menor número (número só de dígitos compara-se como número, os demais como texto) e depois o identificador.

**Crédito de cada ordem.** Em ordem das ordens (a mesma da primeira ordem), cada uma fica com o primeiro lançamento de crédito ainda livre na conta específica do executor (em ordem de data e de identificador) com o mesmo valor do documento hábil, até 10 dias corridos depois da ordem, vindo da União: no Banco do Brasil, «Ordem Bancária» não cancelada; na Caixa, «CRED TED» com Ministério da Fazenda, da Economia ou Tesouro Nacional como depositante. Cada crédito serve a uma ordem só; o SQL faz isso com uma consulta recursiva sobre as ordens do plano. Só vale com um único executor e conta que nenhum outro plano usa. O extrato da conta na fonte vai do primeiro lançamento dela ao corte do banco; o crédito da primeira ordem, usado no prazo do relatório e em `pagamento-depois-do-credito`, só vale com o corte conhecido.

**Consulta de cada fonte.** A do próprio plano ou a da última carga concluída da fonte, se iniciada depois da criação do plano; vale a mais recente. Fontes: plano de trabalho (`transferegov:planos-trabalho`), repasses (`transferegov:repasses`) e relatórios de gestão (`transferegov:relatorios-gestao`).

## Dados usados

Tabelas do Vigia Pix, alimentadas pelas APIs abertas do Transferegov e pelas marcas de consulta (`importacoes` e as colunas `*_consultad*_em` de `planos_acao`): `planos_acao` (com as áreas de política pública em `dados_origem`), `planos_trabalho`, `executores`, `empenhos`, `documentos_habeis`, `ordens_bancarias`, `relatorios_gestao`, `documentos_liquidacao`, `lancamentos`, `cortes_extrato` e `importacoes`; e `fornecedores`, com o cadastro dos recebedores CNPJ na Receita Federal (minhareceita.org).

## Como reproduzir

Sobre um banco PostgreSQL com as tabelas do Vigia Pix:

```bash
psql -f docs/iep/iep-v0.sql
```

Devolve uma linha por plano de ação: `plano_acao_id`, `versao_metodologia`, `pontos`, `conferiveis` e `itens` (JSON com `item`, `grupo`, `estado`, `pontos` e `maximo` de cada item). O resultado é o mesmo do comando `iep:calcular`, o que um teste automatizado confere a cada alteração (`tests/Feature/Indice/MetodologiaIepSqlTest.php`).

## Limitações

- **Dump público inexistente.** Hoje o leitor só reproduz o cálculo com as tabelas do Vigia Pix que tenha em mãos. A publicação de um dump dos dados abertos é um item à parte (S07) e ainda não existe; esta metodologia não a antecipa.
- **Acentos.** O SQL tira acentos com `translate` (letras do português); o sistema usa `Str::ascii`. Descrições com outros caracteres acentuados podem divergir.
- **Dia útil sem feriados**, no sistema e no SQL.
- **Empate na primeira ordem.** Número só de dígitos misturado com número alfanumérico na mesma data é ordenado de forma ligeiramente diferente da comparação do PHP. Nos dados de 2026-10-13 não há nenhum empate com número só de dígitos (a fonte entrega números como `2025OB800261`).
- **Itens frágeis na v0**, ainda sob calibração (#105): `documentos-somam-executado` equivale a ter relatório no formato novo, porque a fonte entrega o executado igual à soma dos documentos; `relatorio-no-prazo` mede o registro do relatório, não a entrega.
- **Sem nota exibida.** Nenhum plano mostra IEP antes da calibração.
- **Rótulos herdados do extrato.** Plano de trabalho não consultado deixa a conta sem dados (9.5): os dois itens do crédito ficam não conferíveis, e `execucao-no-periodo`, não consultado. Banco sem corte do extrato deixa `credito-conciliado` não consultado (ordem fora do extrato) e `pagamento-depois-do-credito` não conferível. Os dois estados ficam fora do denominador; o rótulo difere para a mesma falta de dado.
- **CNAE quase todo não consultado.** Em 2026-10-13, 86.906 dos 101.098 documentos de liquidação pagos a CNPJ ainda não tinham o cadastro do recebedor consultado na Receita (o `transferegov:atualizar` consulta 1.000 por execução): `cnae-compativel` sai quase todo `nao_consultado` até o cadastro avançar.
- **CNAE atual.** O CNAE é o do cadastro na data da consulta, não o da data do pagamento.
- **Mapa CNAE × área não validado.** No experimento do nível 4, menos de um terço dos recebedores fora do mapa v0 eram de fato incomuns para o objeto (`docs/experimentos/2026-10-nivel-4-lancamentos.md`, seção 6).
- **Débitos sem estorno de crédito.** O pagamento devolvido à conta (crédito «DEVOL TED») não é descontado dos débitos: um pagamento devolvido e reenviado conta duas vezes. Descontá-lo daria 2.709 planos com diferença de até 1%, em vez de 2.568.
- **Datas declaradas.** Os itens temporais comparam a data do documento de liquidação declarada pelo ente com o extrato e o plano de trabalho; não conferem se o pagamento saiu da conta naquela data.

## Regra de versão

Antes da primeira publicação, a v0 cresce por fatias, cada uma registrada com data no histórico abaixo. Depois de publicada, qualquer mudança de critério ou de peso gera uma versão nova, com metodologia e SQL próprios, e o índice já calculado na versão anterior continua identificado por ela.

## Histórico de versões

| Versão | Data | Mudança |
|---|---|---|
| v0 | 2026-10-13 | Primeira versão: plano aprovado, relatório no prazo, documentos somam o executado e LAI (sempre não consultada). 40 pontos. |
| v0 | 2026-10-13 | Segunda fatia, antes da publicação: crédito conciliado (todas as ordens), pagamento depois do crédito e execução no período. 65 pontos. |
| v0 | 2026-10-13 | Terceira fatia, antes da publicação: documentos iguais aos débitos e CNAE compatível. 90 pontos. |