# P22 — Receita, despesa, dívida ativa e transferências

| Campo | Valor |
|---|---|
| Programa | F7+ — operação, estrutura e conteúdo |
| Status | `planejado` |
| Depende de | P9, P12 |
| Habilita | P23, P27, P29 |
| Tamanho | **G** (5–7 sessões) |
| ADRs | ADR-051 (importação CSV), ADR-018 (dados abertos), ADR-019 (LGPD), ADR-017, ADR-027, ADR-033, ADR-035, ADR-042 |

## 1. Objetivo

Publicar os **dados fiscais estruturados** que o PNTP avalia como essenciais — receita prevista ×
realizada, classificação orçamentária, despesa empenhada/liquidada/paga, empenhos, dívida ativa e
transferências — em HTML, com filtros, CSV e série de 3 anos. Não é um dataset genérico nem um
link para o sistema contábil.

**Resultado observável:** o cidadão abre `/transparencia/receita`, vê prevista e realizada na
mesma tabela, filtra por ano/mês, baixa CSV; abre `/transparencia/despesa`, vê os três valores e o
detalhe do empenho com o procedimento licitatório; tudo sem login, com `Atualizado em` e 3 anos.

## 2. Escopo fechado

### S1 — Schema e referências

- Módulos `Transparencia/Receita` (token `receita`), `Transparencia/Despesa` (`despesa`),
  `Transparencia/DividaAtiva` (`divida_ativa`), `Transparencia/Transferencias` (`transferencias`).
- Tabelas conforme `wiki/backlog/pntp-2026/03-05-receita-despesa-transferencias.md` §2.
- `exercicio`/`mes` indexados; `numeric(18,2)`; `UNIQUE` do grão; `down()` preserva `backup_*`.
- Referências idempotentes: classificação econômica, modalidade de transferência, tipo de
  desoneração (para P27); sem seed de dado real.
- Permissões `receita.*`, `despesa.*`, `divida_ativa.*`, `transferencias.*`.

### S2 — Receita (3.1–3.3)

- `/transparencia/receita`: tabela única prevista × realizada por mês; filtros exercício/mês;
  CSV; 3 anos; `Atualizado em`.
- `/transparencia/receita/classificacao`: categoria/origem/espécie/desdobramento/detalhamento com
  código + descrição; filtro; CSV.
- `/transparencia/receita/divida-ativa`: nome + valor total; filtro nome/ano; CSV; sem CPF/endereço.
- Regra: 3.1/3.2 são essenciais; não podem depender de dado de P12.

### S3 — Despesa (4.1–4.6)

- `/transparencia/despesa`: empenhado/liquidado/pago, totais e por classificação; filtros
  exercício/mês/classificação; CSV.
- `/transparencia/despesa/empenhos`: uma linha por empenho, com credor, valor, objeto e
  `licitacao_id`/número; filtros; CSV.
- 4.4–4.6 condicionais: aquisições, patrocínios, publicidade; só com dado real.
- Valores string decimal no DTO/JSON; nunca `float`.

### S4 — Convênios e transferências (5.1–5.3)

- `/transparencia/convenios`: recebidas e realizadas **separadas**; acordos sem recursos.
- Campos: número/ano, objeto, valor previsto/repassado, vigência, inteiro teor (Media).
- Filtro por exercício; CSV; 3 anos; `Atualizado em`.
- Instrumento em PDF pesquisável; link same-origin.

### S5 — Portal, API e export

- Cada página usa `<x-layout::portal>` e só o `<main>`; breadcrumb; JSON-LD `Dataset`; sitemap;
  busca (P9); 4 locales.
- API read-only `api/v1/transparencia/{recurso}` com filtros allowlist, rate limit, `ETag`, sem PII.
- CSV via `Services\OpenData` (P5.5): o módulo implementa `DatasetSource`; colunas completas,
  ordem explícita, anti-injection, `ETag`/checksum. Não criar serializador local nem `Export`.
- Nenhuma carga total no navegador; filtros server-side; paginação.

### S6 — Fechamento

- E2E: receita/despesa/empenho/transferência; filtro; CSV; `Atualizado em`; 3 anos; sem login.
- `make check` 2× + `E2E=1`; axe; cobertura ≥90%; query count.
- Atualizar `INVENTARIO.md`, `PNTP.md` e os backlogs promovidos.

## 3. Fora de escopo

- Integração contábil oficial/ETL (ADR-042); conciliação automática.
- BI/warehouse/dashboards interativos.
- Dados de estatais/consórcios (N/A).
- Substituir o sistema contábil; o V7 publica o dado.

## 4. Fatias de sessão

| Sessão | Entrega | Prova | Depende |
|---|---|---|---|
| **P22.S1** | schema + referências + permissões | unique/índices; `down()` backup | P9/P12 |
| **P22.S2** | receita 3.1–3.3 | tabela única; classificação; CSV; 3 anos | S1 |
| **P22.S3** | despesa 4.1–4.3 (+4.4–4.6 cond.) | 3 valores; empenho/licitação; CSV | S1 |
| **P22.S4** | transferências 5.1–5.3 | recebidas/realizadas; teor; CSV | S1 |
| **P22.S5** | portal/API/export/SEO | `Atualizado em`; ETag; sitemap; a11y | S2–S4 |
| **P22.S6** | E2E/docs/2× check | evidência no `kd` | S2–S5 |

## 5. Contratos e dados

- **Módulos:** `Transparencia/{Receita,Despesa,DividaAtiva,Transferencias}`.
- **Tabelas:** ver backlog `03-05` §2.
- **Rotas:** `transparencia.receita.*`, `transparencia.despesa.*`, `transparencia.divida_ativa.*`,
  `transparencia.transferencias.*`, `api.transparencia.*`.
- **Portas:** `SitemapSource`, `SearchSource`, `DatasetSource` (P5.5); export via
  `Services\OpenData`.
- **Eventos:** `{modulo}.published/updated/archived`; auditoria de publicação.

## 6. DoD

- [ ] 3.1 prevista × realizada na mesma tabela; 3.2 classificação com código/descrição; 3.3 nome+valor.
- [ ] 4.1 três valores; 4.2 classificação; 4.3 empenho com licitação; 4.4–4.6 condicionais.
- [ ] 5.1/5.2 separados; 5.3 obrigações; inteiro teor via Media.
- [ ] HTML sem login, filtros server-side, CSV, `Atualizado em`, 3 anos.
- [ ] API com ETag/rate limit; JSON-LD/sitemap; 4 locales; axe.
- [ ] `make check` 2× + `E2E=1`; cobertura ≥90%; PHPStan max 0.

## Fechamento — ficha de revisão

> **Obrigatório antes de fechar:** criar `_to_revision/P22-receita-despesa-transferencias.md` e
> seguir `_to_revision/README.md` + `_to_revision/PROTOCOLO.md` (v2.0). A ficha não é gate de
> build; é a entrada da fila de revisão profunda.

- Cabeçalho: fase, `kd` épico/tasks/slices, âncoras (este arquivo, ADRs e código) e status
  `⬜ pendente` → `🟡 em revisão` → `✅ revisado` / `🔧 com correções`.
- Conteúdo: o que foi implementado, arquivos/superfícies a revisar, checklist D1–D14 aplicável,
  riscos e observações.
- Fechamento: preencher “Notas da revisão” com data/revisor/resultado e achados (`kd write
  --anchor`), atualizar a fila em `_to_revision/README.md` e `_to_revision/_inventario.md`.
- Achado com correção exige teste vermelho→verde; a fase só é `closed` no `kd` com a ficha
  registrada.

## 7. Riscos

| Risco | Mitigação |
|---|---|
| Dado só em PDF/link | HTML é a superfície; PDF é anexo |
| `float` em dinheiro | numeric + string; teste |
| PII de credor | CNPJ público; CPF omitido; revisão LGPD |
| Série perdida | exercício + arquivamento; sem DELETE |
| N+1 em classificação | agregação SQL; query count |
| Importador virar ETL | CSV/dry-run; ADR-042 |

## 8. Retomada

```bash
kd prime
kd ask "PNTP receita despesa empenho transferências série histórica"
kd task list --ready
```

Ler: `wiki/backlog/pntp-2026/03-05-receita-despesa-transferencias.md` → `PNTP.md` §4 (dims. 3–5) →
`dossie_modules/transparencia-fiscal/**` → P12/P9.