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

> **Critérios:** 3.1, 3.2, 3.3, 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 5.1, 5.2, 5.3.
> **Fase:** [`P22`](../../implementation-phases/P22-receita-despesa-transferencias.md).
> **Classes:** 3.1, 3.2, 4.1, 4.2 e 4.3 são **essenciais**; 3.3, 5.1–5.3 são obrigatórios;
> 4.4–4.6 são recomendados/condicionais.
> **Estado atual:** ausente. P12 é a camada de dataset/export; não substitui os módulos.

## 1. Requisitos por critério

### 3.1 Previsão e realização da receita (essencial)

- Tabela **única** com prevista e realizada, por mês e por exercício.
- Filtros: exercício e mês; série de 3 anos; CSV.
- Atualização mensal; `Atualizado em` visível.
- Para o Legislativo, incluir duodécimos quando aplicável.

### 3.2 Classificação orçamentária da receita (essencial)

- Categoria econômica, origem, espécie, desdobramento e detalhamento, com **código e descrição**.
- Filtro por classificação; CSV completo; 3 anos.
- Não basta um PDF da lei orçamentária.

### 3.3 Dívida ativa

- Nome do inscrito + valor total; filtros por nome e ano de inscrição; CSV.
- **Não** publicar CPF, endereço, telefone ou outros dados pessoais; a base legal é o art. 198,
  §3º, do CTN, e a revisão LGPD decide o mínimo.
- Exercício + série de 3 anos.

### 4.1 Empenhado, liquidado e pago (essencial)

- Totais consolidados **ou** soma do detalhamento, na mesma tabela.
- Filtros: exercício e mês; CSV; 3 anos.
- Valores como string decimal; nunca `float`.

### 4.2 Despesa por classificação (essencial)

- Unidade orçamentária, função, subfunção, natureza da despesa e fonte.
- Filtros: exercício, mês e classificação; CSV; 3 anos.

### 4.3 Detalhamento de empenhos (essencial)

- Uma linha por empenho: beneficiário/credor, valor, bem/serviço, modalidade e número do
  procedimento licitatório.
- Filtros: número do empenho, credor, mês e exercício; CSV; 3 anos.
- O vínculo com Licitações (P8) é por `licitacao_id` nullable; quando não houver, texto livre.

### 4.4 Aquisições de bens (condicional)

- Bem, preço unitário, quantidade, fornecedor e valor total; filtros por exercício/fornecedor;
  CSV; 3 anos. Só entra se o cliente tiver o dado; não inventar.

### 4.5 Patrocínios (condicional)

- Projeto, beneficiário, CNPJ, valor e instrumento; filtro por exercício; CSV; 3 anos.

### 4.6 Contratos de publicidade (condicional)

- Fornecedor, veículo e valores por tipo de serviço/meio; filtros; CSV; 3 anos.

### 5.1 Transferências recebidas

- Repassador, número/ano, objeto, valor total previsto, valor recebido, vigência e **inteiro teor**
  do instrumento (Media).
- Filtro por exercício; CSV; 3 anos.

### 5.2 Transferências realizadas

- Beneficiário, número/ano, objeto, valor total previsto, valor concedido, vigência e inteiro teor.
- Separar de 5.1; filtro por exercício; CSV; 3 anos.

### 5.3 Acordos sem transferência de recursos

- Partes, número/ano, objeto, vigência, obrigações ajustadas e inteiro teor.
- Filtro por exercício; CSV; 3 anos.

## 2. Modelo de dados (proposta)

| Tabela | Colunas principais |
|---|---|
| `receita_lancamentos` | `id`, `exercicio`, `mes`, `tipo` (`prevista|realizada`), `categoria`, `origem`, `especie`, `desdobramento`, `detalhamento`, `codigo`, `descricao`, `valor` numeric(18,2), `fonte`, `orgao`, `updated_at` |
| `despesa_empenhos` | `id`, `exercicio`, `mes`, `unidade_orcamentaria`, `funcao`, `subfuncao`, `natureza_despesa`, `fonte`, `empenho_numero`, `credor_nome`, `credor_documento`, `objeto`, `licitacao_id` null, `valor_empenhado`, `valor_liquidado`, `valor_pago`, `updated_at` |
| `divida_ativa` | `id`, `exercicio`, `inscricao`, `nome_inscrito`, `valor_total`, `situacao`, `updated_at` |
| `transferencias` | `id`, `direcao` (`recebida|realizada`), `exercicio`, `numero`, `ano`, `repartidor_beneficiario`, `objeto`, `valor_previsto`, `valor_repassado`, `vigencia_inicio`, `vigencia_fim`, `instrumento_media_id`, `tipo`, `updated_at` |
| `acordos_sem_recursos` | `id`, `exercicio`, `numero`, `ano`, `partes`, `objeto`, `vigencia_inicio`, `vigencia_fim`, `obrigacoes` AST, `instrumento_media_id`, `updated_at` |
| `aquisicoes_bens` | `id`, `exercicio`, `bem`, `preco_unitario`, `quantidade`, `fornecedor`, `valor_total`, `updated_at` |
| `patrocinios` | `id`, `exercicio`, `projeto`, `beneficiario`, `documento`, `valor`, `instrumento`, `updated_at` |
| `publicidade` | `id`, `exercicio`, `fornecedor`, `veiculo`, `tipo_servico`, `valor`, `updated_at` |

Regras:

- `exercicio` + `mes` são obrigatórios e indexados; `UNIQUE` quando o grão for natural (ex.:
  `receita_lancamentos` por tipo/classificação/mês).
- Sem `DELETE`: arquivamento/republicação; `down()` preserva `backup_*`.
- `valor` numeric; DTO/JSON como string decimal.
- `credor_documento` só CNPJ público; CPF mascarado/omitido por decisão LGPD.
- Carga manual/CSV via Importador (P9); nunca ETL de legado (ADR-042).

## 3. Portal e CMS

- Rotas:
  - `/transparencia/receita` (3.1 e 3.2)
  - `/transparencia/receita/divida-ativa`
  - `/transparencia/despesa` (4.1 e 4.2)
  - `/transparencia/despesa/empenhos`
  - `/transparencia/despesa/aquisicoes`, `/patrocinios`, `/publicidade` (condicionais)
  - `/transparencia/convenios` (5.1–5.3)
- Cada página: tabela HTML com `caption`, cabeçalhos, filtros com label, paginação, CSV, `Atualizado
  em`, breadcrumb, JSON-LD `Dataset`/`GovernmentService`, sitemap e busca.
- CMS: CRUD, importação CSV com preview/dry-run, publicação, arquivamento, permissões
  `receita.*`, `despesa.*`, `divida_ativa.*`, `transferencias.*`.
- API read-only `api/v1/transparencia/{receita,despesa,...}` com filtros allowlist, rate limit,
  `ETag`, sem PII.

## 4. Evidência e testes

- [ ] 3.1 prevista e realizada na mesma tabela, mês a mês, 3 anos; CSV.
- [ ] 3.2 classificação completa com código + descrição; filtro; CSV.
- [ ] 3.3 nome + valor total; nenhum CPF/endereço; filtro; CSV.
- [ ] 4.1 empenhado/liquidado/pago; 4.2 classificação; 4.3 empenho com licitação; todos com 3 anos.
- [ ] 5.1/5.2 separados; inteiro teor via Media; 5.3 obrigações.
- [ ] Toda página retorna 200 sem login, HTML visível, `Atualizado em`, CSV determinístico.
- [ ] `make check` 2× + `E2E=1`; axe; cobertura; query count.

## 5. Riscos

| Risco | Mitigação |
|---|---|
| Dado fiscal só em PDF/link | tabela HTML é a superfície; PDF é anexo |
| `float` em dinheiro | numeric + string no DTO; teste |
| Credor com CPF | CNPJ público; CPF omitido/mascarado; revisão LGPD |
| Série histórica perdida | exercício + arquivamento; sem DELETE |
| Filtro no navegador | query server-side; teste de query count |
| Importador virar ETL | dry-run, CSV, operação manual (ADR-042) |