# Entidades — Transações Públicas

**Contextos:** Contracts, Procurement, Transparency, Transfers, Sanctions  
**Versão:** 1.0.0

---

## Contracts

### PublicContract

| Campo | Conteúdo |
|-------|----------|
| **Nome** | PublicContract |
| **Descrição** | Contrato administrativo / ajuste público entre GovernmentBody e fornecedor(es). |
| **Responsabilidade** | Representar o fato contratual tipado com valores, vigência e partes. |
| **Principais atributos** | `contract_id`, `external_number`, `contracting_body_id`, `object_summary`, `signed_on`, `start_on`, `end_on`, `total_value`, `currency`, `status`, `source_record_id` |
| **Relacionamentos** | N‑1 GovernmentBody; N‑N Party (contratados via role); 1‑N ContractAmendment; liga BiddingProcess (origem); GraphEdges `CONTRACTED_WITH`; TimelineEvent |
| **Ciclo de vida** | DraftPublic → Active → Amended → Closed / Terminated |
| **Produz** | `contracts.public_contract.published.v1`, `contracts.public_contract.status_changed.v1` |
| **Consome** | `etl.ingest_run.published.v1` |
| **Casos de uso** | UC-004, UC-005, UC-009 |
| **Regras** | Valor e partes exigem fonte; aditivos não apagam contrato original; mudanças materiais → Watch |
| **Extensões** | Empenhos, medições, garantias |

### ContractAmendment

| Campo | Conteúdo |
|-------|----------|
| **Nome** | ContractAmendment |
| **Descrição** | Alteração formal de um PublicContract (prazo, valor, objeto). |
| **Responsabilidade** | Versionar mudanças contratuais. |
| **Principais atributos** | `amendment_id`, `contract_id`, `sequence`, `amended_on`, `value_delta?`, `new_end_on?`, `reason`, `source_record_id` |
| **Relacionamentos** | N‑1 PublicContract |
| **Ciclo de vida** | Published → Superseded |
| **Produz** | `contracts.amendment.published.v1` |
| **Consome** | — |
| **Casos de uso** | UC-010 (mudança), Integrity |
| **Regras** | Sequência monotônica; delta rastreável |
| **Extensões** | Classificação de risco de aditivo (% acréscimo) |

---

## Procurement

### BiddingProcess

| Campo | Conteúdo |
|-------|----------|
| **Nome** | BiddingProcess |
| **Descrição** | Processo licitatório / seleção pública. |
| **Responsabilidade** | Agregar etapas, lotes e participantes. |
| **Principais atributos** | `bidding_id`, `modality`, `object_summary`, `body_id`, `opened_on`, `status`, `estimated_value?`, `source_record_id` |
| **Relacionamentos** | N‑1 GovernmentBody; 1‑N ProcurementLot; 1‑N Bid; pode originar PublicContract |
| **Ciclo de vida** | Published → InProgress → Awarded / Deserted / Cancelled |
| **Produz** | `procurement.bidding.published.v1`, `procurement.bidding.awarded.v1`, `procurement.bidding.cancelled.v1` |
| **Consome** | ETL procurement |
| **Casos de uso** | UC-004, UC-005, Integrity |
| **Regras** | Modalidade tipada; cancelamento preserva histórico de Bids |
| **Extensões** | Pregão eletrônico eventos finos, recursos |

### ProcurementLot

| Campo | Conteúdo |
|-------|----------|
| **Nome** | ProcurementLot |
| **Descrição** | Lote ou item adjudicado dentro de um BiddingProcess. |
| **Responsabilidade** | Granularizar objeto e resultado. |
| **Principais atributos** | `lot_id`, `bidding_id`, `lot_number`, `description`, `status`, `awarded_party_id?`, `awarded_value?` |
| **Relacionamentos** | N‑1 BiddingProcess; 0‑1 Party vencedor; Bids |
| **Ciclo de vida** | Open → Awarded / Failed |
| **Produz** | `procurement.lot.awarded.v1` |
| **Consome** | — |
| **Casos de uso** | UC-004 |
| **Regras** | Um lote — um adjudicatário principal (modelo simplificado); múltiplos via extensão |
| **Extensões** | Itens, marcas, quantitativos |

### Bid

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Bid |
| **Descrição** | Proposta / participação de um Party em lote ou certame. |
| **Responsabilidade** | Registrar quem concorrera e valores quando públicos. |
| **Principais atributos** | `bid_id`, `bidding_id`, `lot_id?`, `bidder_party_id`, `bid_value?`, `result` (winner/loser/disqualified), `source_record_id` |
| **Relacionamentos** | N‑1 BiddingProcess; N‑1 Party; GraphEdge `BID_ON` |
| **Ciclo de vida** | Submitted → Evaluated → Final |
| **Produz** | `procurement.bid.recorded.v1` |
| **Consome** | — |
| **Casos de uso** | UC-005, Integrity (conluio signals) |
| **Regras** | Sem inferir conluio automático sem regra explícita; dados só com fonte |
| **Extensões** | Consórcios, lances sucessivos |

---

## Transparency

### TransparencyPublication

| Campo | Conteúdo |
|-------|----------|
| **Nome** | TransparencyPublication |
| **Descrição** | Pacote/registro publicado em portal de transparência (diárias, despesas agregadas, listas). |
| **Responsabilidade** | Ancorar fatos de transparência com metadados de publicação. |
| **Principais atributos** | `publication_id`, `body_id`, `title`, `published_on`, `category`, `uri`, `source_record_id` |
| **Relacionamentos** | N‑1 GovernmentBody; 1‑N PublicExpense |
| **Ciclo de vida** | Published → Updated / Retracted |
| **Produz** | `transparency.publication.published.v1`, `transparency.publication.retracted.v1` |
| **Consome** | Crawler/ETL |
| **Casos de uso** | UC-004 |
| **Regras** | Retração não remove Evidence já exportada; marca status |
| **Extensões** | FOIA requests tracking |

### PublicExpense

| Campo | Conteúdo |
|-------|----------|
| **Nome** | PublicExpense |
| **Descrição** | Despesa pública individualizada ou agregada de interesse analítico. |
| **Responsabilidade** | Ligar pagamentos a favorecidos e órgãos. |
| **Principais atributos** | `expense_id`, `publication_id?`, `payer_body_id`, `payee_party_id?`, `amount`, `paid_on`, `nature`, `source_record_id` |
| **Relacionamentos** | Parties; Timeline; Integrity signals (padrões) |
| **Ciclo de vida** | Recorded → Corrected |
| **Produz** | `transparency.expense.recorded.v1` |
| **Consome** | — |
| **Casos de uso** | UC-004, UC-009 |
| **Regras** | Correção versionada; payee pode ser desconhecido |
| **Extensões** | Empenho/liquidação/pagamento triplo |

---

## Transfers

### Transfer

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Transfer |
| **Descrição** | Transferência de recursos (voluntária, fundo, convênio, etc.) entre entes/beneficiários. |
| **Responsabilidade** | Modelar fluxo de recurso público relevante a risco e grafo. |
| **Principais atributos** | `transfer_id`, `transfer_type`, `grantor_party_id`, `grantee_party_id`, `amount`, `agreed_on`, `status`, `program_code?`, `source_record_id` |
| **Relacionamentos** | Party grantor/grantee; GraphEdge `TRANSFERRED_TO`; pode relacionar Contract |
| **Ciclo de vida** | Agreed → Disbursing → Closed / Suspended |
| **Produz** | `transfers.transfer.recorded.v1`, `transfers.transfer.status_changed.v1` |
| **Consome** | ETL transferências |
| **Casos de uso** | UC-004, UC-005, UC-009 |
| **Regras** | Tipo tipado; valores monetários com currency; mudanças de status → Watch |
| **Extensões** | Parcelas, prestação de contas, glosas |

---

## Sanctions

### SanctionList

| Campo | Conteúdo |
|-------|----------|
| **Nome** | SanctionList |
| **Descrição** | Lista oficial ou dataset de restrições (impedimentos, sanções, watchlists públicas). |
| **Responsabilidade** | Versionar conjunto de entradas e metadados da lista. |
| **Principais atributos** | `list_id`, `code`, `jurisdiction`, `publisher`, `version`, `published_on`, `trust_level` |
| **Relacionamentos** | 1‑N SanctionEntry |
| **Ciclo de vida** | Active → Superseded |
| **Produz** | `sanctions.list.published.v1` |
| **Consome** | ETL |
| **Casos de uso** | UC-009, UC-010 |
| **Regras** | Código estável; versão obrigatória |
| **Extensões** | Listas privadas do tenant (separadas — não misturar com públicas sem label) |

### SanctionEntry

| Campo | Conteúdo |
|-------|----------|
| **Nome** | SanctionEntry |
| **Descrição** | Entrada que restringe/encoraja cautela sobre um Party. |
| **Responsabilidade** | Materializar sanção/impedimento com vigência e motivo quando disponível. |
| **Principais atributos** | `entry_id`, `list_id`, `party_id?`, `raw_name`, `identifier_refs[]`, `sanction_type`, `valid_from`, `valid_to`, `reason`, `source_record_id`, `match_status` |
| **Relacionamentos** | N‑1 SanctionList; 0‑1 Party (após resolução); IntegrityFactor; Watch |
| **Ciclo de vida** | ProposedMatch → Linked → Active → Expired / Lifted |
| **Produz** | `sanctions.entry.published.v1`, `sanctions.entry.linked_to_party.v1`, `sanctions.entry.lifted.v1` |
| **Consome** | EntityMatchCandidate decisions |
| **Casos de uso** | UC-003 (sinais), UC-009, UC-010 |
| **Regras** | False positives possíveis — UI mostra match_status/confidence; não “condenar” sem tipo e fonte; lifting gera evento |
| **Extensões** | Fuzzy match review queue por tenant |