# 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 |
| `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 65 pontos; a escala só chega a 100 com as fatias seguintes.

**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`, `planos_trabalho`, `executores`, `empenhos`, `documentos_habeis`, `ordens_bancarias`, `relatorios_gestao`, `documentos_liquidacao`, `lancamentos`, `cortes_extrato` e `importacoes`.

## 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.
- **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. |