# Entidades — Análise e Integridade

**Contextos:** Cases, Documents, Evidence, Integrity, Graph, Timeline, Maps, Watch, Reports  
**Versão:** 1.0.0

---

## Cases

### Case

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Case |
| **Descrição** | Dossiê / caso analítico privado ao Tenant que agrega objetos de investigação e conclusões. |
| **Responsabilidade** | Ser o aggregate raiz do trabalho do analista. |
| **Principais atributos** | `case_id`, `tenant_id`, `workspace_id?`, `title`, `status` (draft/in_review/finalized/archived), `owner_user_id`, `classification`, `created_at`, `updated_at`, `finalized_at?` |
| **Relacionamentos** | 1‑N CaseEntityLink, CaseNote, Finding; N‑N Document/EvidenceItem; exports Report/ExportPackage |
| **Ciclo de vida** | Draft → InReview → Finalized → Archived (ou reaberto sob política) |
| **Produz** | `cases.case.created.v1`, `cases.case.status_changed.v1`, `cases.case.finalized.v1`, `cases.case.archived.v1` |
| **Consome** | Entitlements; AccessPolicy de retenção |
| **Casos de uso** | UC-007, UC-008, UC-011 |
| **Regras** | Isolamento tenant; transições de estado explícitas; finalize exige owner/role; archive ≠ delete audit |
| **Extensões** | Templates de caso, colaboração com comments threads, SLA interno |

### CaseEntityLink

| Campo | Conteúdo |
|-------|----------|
| **Nome** | CaseEntityLink |
| **Descrição** | Vínculo entre Case e Party (ou fato tipado) sob análise. |
| **Responsabilidade** | Declarar escopo do dossiê. |
| **Principais atributos** | `link_id`, `case_id`, `target_type`, `target_id`, `label`, `added_by`, `added_at` |
| **Relacionamentos** | N‑1 Case; referencia Party/Contract/etc. |
| **Ciclo de vida** | Added → Removed |
| **Produz** | `cases.case_entity.linked.v1`, `cases.case_entity.unlinked.v1` |
| **Consome** | — |
| **Casos de uso** | UC-007 |
| **Regras** | Remoção não apaga Evidence gerada; target deve existir ou ser stale-marked |
| **Extensões** | Papéis no caso (alvo principal, relacionado, testemunha analítica) |

### CaseNote

| Campo | Conteúdo |
|-------|----------|
| **Nome** | CaseNote |
| **Descrição** | Nota analítica humana no Case. |
| **Responsabilidade** | Registrar raciocínio e hipóteses explícitas do analista. |
| **Principais atributos** | `note_id`, `case_id`, `author_user_id`, `body`, `note_kind` (fact_ref/hypothesis/todo), `created_at`, `edited_at?` |
| **Relacionamentos** | N‑1 Case; pode citar EvidenceItem |
| **Ciclo de vida** | Created → Edited → Deleted (soft) |
| **Produz** | `cases.note.created.v1`, `cases.note.edited.v1` |
| **Consome** | — |
| **Casos de uso** | UC-007 |
| **Regras** | Hipótese deve ser `note_kind=hypothesis`; edições auditáveis |
| **Extensões** | Mentions, checklists |

### Finding

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Finding |
| **Descrição** | Achado formal dentro do Case (conclusão intermediária ou final tipada). |
| **Responsabilidade** | Estruturar resultados revisáveis. |
| **Principais atributos** | `finding_id`, `case_id`, `severity`, `severity`, `severity` (info/medium/high), `status`, `linked_evidence_ids[]`, `created_by` |
| **Relacionamentos** | N‑1 Case; EvidenceItems; pode apontar IntegrityScore |
| **Ciclo de vida** | Draft → Confirmed → Disputed / Retracted |
| **Produz** | `cases.finding.created.v1`, `cases.finding.confirmed.v1`, `cases.finding.retracted.v1` |
| **Consome** | — |
| **Casos de uso** | UC-007, UC-011 |
| **Regras** | Confirmação exige evidência mínima configurável; linguagem não acusatória automática |
| **Extensões** | Matriz 5W2H, scoring de confiança do finding |

---

## Documents

### Document

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Document |
| **Descrição** | Artefato documental gerenciado (upload tenant ou espelho de publicação). |
| **Responsabilidade** | Versionar conteúdo e metadados para análise. |
| **Principais atributos** | `document_id`, `tenant_id?` (null se catálogo público), `title`, `mime`, `classification`, `origin` (upload/public_mirror), `current_version_id` |
| **Relacionamentos** | 1‑N DocumentVersion; ligado a Case; pode gerar EmbeddingChunk |
| **Ciclo de vida** | Active → Archived |
| **Produz** | `documents.document.created.v1`, `documents.document.archived.v1` |
| **Consome** | — |
| **Casos de uso** | UC-007, UC-008 (RAG) |
| **Regras** | Upload respeita tamanho/tipo; vírus scan (ops); docs de tenant isolados |
| **Extensões** | OCR pipeline, classificação automática |

### DocumentVersion

| Campo | Conteúdo |
|-------|----------|
| **Nome** | DocumentVersion |
| **Descrição** | Versão imutável de bytes + metadados de um Document. |
| **Responsabilidade** | Integridade de conteúdo (hash) para evidência. |
| **Principais atributos** | `version_id`, `document_id`, `storage_ref`, `content_hash`, `size`, `created_by`, `created_at` |
| **Relacionamentos** | N‑1 Document; EvidenceItem pode apontar versão |
| **Ciclo de vida** | Stored (imutável) |
| **Produz** | `documents.document_version.stored.v1` |
| **Consome** | — |
| **Casos de uso** | UC-011 |
| **Regras** | Hash obrigatório; não overwrite |
| **Extensões** | Assinatura digital |

---

## Evidence

### EvidenceItem

| Campo | Conteúdo |
|-------|----------|
| **Nome** | EvidenceItem |
| **Descrição** | Unidade de evidência citável no Case (fonte pública, documento, snapshot de grafo, completion citada). |
| **Responsabilidade** | Tornar afimações defensáveis e reconstruíveis. |
| **Principais atributos** | `evidence_id`, `case_id`, `evidence_kind`, `ref_type`, `ref_id`, `caption`, `captured_at`, `content_hash?`, `added_by` |
| **Relacionamentos** | N‑1 Case; → SourceRecord / DocumentVersion / GraphView / Completion |
| **Ciclo de vida** | Added → Superseded / Invalidated |
| **Produz** | `evidence.item.added.v1`, `evidence.item.invalidated.v1` |
| **Consome** | — |
| **Casos de uso** | UC-007, UC-008, UC-011 |
| **Regras** | Toda Evidence aponta para ref persistente; invalidação não remove exports históricos |
| **Extensões** | Cadeia de custódia digital |

### EvidenceManifest

| Campo | Conteúdo |
|-------|----------|
| **Nome** | EvidenceManifest |
| **Descrição** | Pacote manifesto que lista EvidenceItems inclusos em um export. |
| **Responsabilidade** | Garantir completude e hashes no ExportPackage. |
| **Principais atributos** | `manifest_id`, `case_id`, `export_package_id`, `items[]` (id+hash), `generated_at`, `generator_version` |
| **Relacionamentos** | 1‑1 ExportPackage; N EvidenceItem |
| **Ciclo de vida** | Generated (imutável) |
| **Produz** | `evidence.manifest.generated.v1` |
| **Consome** | Pedido de export |
| **Casos de uso** | UC-011 |
| **Regras** | Manifest fecha conjunto; alteração de caso após export não muda manifesto antigo |
| **Extensões** | Assinatura do manifesto |

---

## Integrity

### RiskRule

| Campo | Conteúdo |
|-------|----------|
| **Nome** | RiskRule |
| **Descrição** | Regra configurável (plataforma ou tenant) que detecta fatores de risco/integridade. |
| **Responsabilidade** | Declarar lógica nominável e versionada de sinalização. |
| **Principais atributos** | `rule_id`, `code`, `name`, `scope` (global/tenant), `tenant_id?`, `version`, `enabled`, `params`, `severity_weight` |
| **Relacionamentos** | Produz IntegrityFactor; parametrizada em Settings |
| **Ciclo de vida** | Draft → Enabled → Disabled → Retired |
| **Produz** | `integrity.risk_rule.enabled.v1`, `integrity.risk_rule.disabled.v1` |
| **Consome** | Fatos de domínio via projeção (sanções, PEPs, contratos…) |
| **Casos de uso** | UC-009 |
| **Regras** | Mudança de params versiona; não shadow-edit; explicável |
| **Extensões** | DSL de regras, A/B de pesos |

### IntegrityFactor

| Campo | Conteúdo |
|-------|----------|
| **Nome** | IntegrityFactor |
| **Descrição** | Fator individual disparado por RiskRule sobre um alvo. |
| **Responsabilidade** | Compor explicação do score. |
| **Principais atributos** | `factor_id`, `rule_code`, `target_type`, `target_id`, `score_contribution`, `details`, `detected_at`, `source_refs[]` |
| **Relacionamentos** | Agregado em IntegrityScore; cita SourceRecords |
| **Ciclo de vida** | Active → Expired / Withdrawn |
| **Produz** | `integrity.factor.raised.v1`, `integrity.factor.withdrawn.v1` |
| **Consome** | Eventos de Sanctions, PEP, Contracts, etc. |
| **Casos de uso** | UC-004, UC-009 |
| **Regras** | Sempre com source_refs quando baseado em fato; withdraw quando base some |
| **Extensões** | Fatores correlacionados |

### IntegrityScore

| Campo | Conteúdo |
|-------|----------|
| **Nome** | IntegrityScore |
| **Descrição** | Pontuação agregada e explicável de integridade/risco de um Party (ou Case). |
| **Responsabilidade** | Sumarizar fatores sob metodologia versionada. |
| **Principais atributos** | `score_id`, `target_type`, `target_id`, `tenant_id?` (se pesos locais), `method_version`, `value`, `band`, `computed_at`, `factor_ids[]` |
| **Relacionamentos** | 1‑N IntegrityFactor |
| **Ciclo de vida** | Computed → Superseded |
| **Produz** | `integrity.score.computed.v1` |
| **Consome** | Mudanças de fatores |
| **Casos de uso** | UC-003 (snippet), UC-009 |
| **Regras** | Score sem fatores é inválido; band thresholds por tenant; nunca apresentar como prova jurídica |
| **Extensões** | Scores setoriais, peer benchmarking |

### ConflictOfInterestSignal

| Campo | Conteúdo |
|-------|----------|
| **Nome** | ConflictOfInterestSignal |
| **Descrição** | Sinal específico de possível conflito de interesse entre Parties/papéis (ex.: decisor × fornecedor). |
| **Responsabilidade** | Destacar padrões COI além do score genérico. |
| **Principais atributos** | `signal_id`, `party_a_id`, `party_b_id`, `context_ref`, `pattern_code`, `confidence`, `status` |
| **Relacionamentos** | GraphPath / Mandate / Contract; IntegrityFactor |
| **Ciclo de vida** | Detected → Acknowledged / Dismissed |
| **Produz** | `integrity.coi_signal.detected.v1` |
| **Consome** | Graph/Contracts/Parliament events |
| **Casos de uso** | UC-006, UC-009 |
| **Regras** | Sempre “possível/indício”; dismissal auditado |
| **Extensões** | COI policies por setor do cliente |

### MembershipInterest

| Campo | Conteúdo |
|-------|----------|
| **Nome** | MembershipInterest |
| **Descrição** | Interesse declarado ou inferido de vínculo (quadro, conselho, associação) usado em COI. |
| **Responsabilidade** | Normalizar “participação em órgão/estrutura” além de Shareholding. |
| **Principais atributos** | `interest_id`, `person_id`, `organization_party_id`, `role`, `valid_from`, `valid_to`, `source_record_id` |
| **Relacionamentos** | People ↔ Companies/Government; GraphEdge |
| **Ciclo de vida** | Active → Ended |
| **Produz** | `integrity.membership_interest.opened.v1` |
| **Consome** | ETL |
| **Casos de uso** | UC-005, UC-009 |
| **Regras** | Inferência marcada como inferred=true |
| **Extensões** | Benefícios indiretos |

---

## Graph

### GraphNode

| Campo | Conteúdo |
|-------|----------|
| **Nome** | GraphNode |
| **Descrição** | Projeção de um Party (ou fato selected) no grafo navegável. |
| **Responsabilidade** | Suportar expansão e visualização. |
| **Principais atributos** | `node_id`, `ref_type`, `ref_id`, `labels[]`, `props` |
| **Relacionamentos** | 1‑1 ou N com Party; edges |
| **Ciclo de vida** | Upsert contínuo a partir de publicações |
| **Produz** | `graph.node.upserted.v1` |
| **Consome** | Party/fato events |
| **Casos de uso** | UC-005 |
| **Regras** | Node não é fonte da verdade — projeção |
| **Extensões** | Super-nodes agregados |

### GraphEdge

| Campo | Conteúdo |
|-------|----------|
| **Nome** | GraphEdge |
| **Descrição** | Aresta tipada entre nós com vigência. |
| **Responsabilidade** | Relacionamentos navegáveis (sócio, contrato, sanção linkada, etc.). |
| **Principais atributos** | `edge_id`, `type`, `from_node_id`, `to_node_id`, `valid_from`, `valid_to`, `props`, `source_record_id` |
| **Relacionamentos** | Derivada de Shareholding, Contract, Transfer, Bid… |
| **Ciclo de vida** | Active → Ended / Retracted |
| **Produz** | `graph.edge.upserted.v1`, `graph.edge.ended.v1` |
| **Consome** | Eventos dos contextos de fatos |
| **Casos de uso** | UC-005, UC-006 |
| **Regras** | type em taxonomia fechada versionada; source_record_id obrigatório para arestas factuais |
| **Extensões** | Pesos, multilinks |

### GraphPath

| Campo | Conteúdo |
|-------|----------|
| **Nome** | GraphPath |
| **Descrição** | Caminho encontrado entre dois nós sob restrições. |
| **Responsabilidade** | Materializar resultado de path finding (não prova). |
| **Principais atributos** | `path_id`, `tenant_id`, `from_node_id`, `to_node_id`, `node_ids[]`, `edge_ids[]`, `length`, `constraints`, `computed_at` |
| **Relacionamentos** | Pode virar EvidenceItem / CaseNote |
| **Ciclo de vida** | Computed → Expired (cache) |
| **Produz** | `graph.path.found.v1`, `graph.path.not_found.v1` |
| **Consome** | Comando de busca de caminho |
| **Casos de uso** | UC-006 |
| **Regras** | Respeitar Quota profundidade; rotular como estrutural |
| **Extensões** | k-shortest paths, explain |

### GraphView

| Campo | Conteúdo |
|-------|----------|
| **Nome** | GraphView |
| **Descrição** | Vista salva (subgrafo + layout) pelo usuário/caso. |
| **Responsabilidade** | Reprodutibilidade visual e evidência. |
| **Principais atributos** | `view_id`, `tenant_id`, `case_id?`, `name`, `node_ids[]`, `edge_ids[]`, `layout`, `created_by` |
| **Relacionamentos** | Case; Evidence |
| **Ciclo de vida** | Saved → Updated → Archived |
| **Produz** | `graph.view.saved.v1` |
| **Consome** | — |
| **Casos de uso** | UC-005, UC-011 |
| **Regras** | Snapshot de IDs + hashes opcional para evidência |
| **Extensões** | Colaboração real-time |

---

## Timeline

### TimelineEvent

| Campo | Conteúdo |
|-------|----------|
| **Nome** | TimelineEvent |
| **Descrição** | Evento temporal unificado na linha do tempo de um Party ou Case. |
| **Responsabilidade** | Ordenar fatos heterogêneos cronologicamente. |
| **Principais atributos** | `timeline_event_id`, `subject_type`, `subject_id`, `occurred_on`, `event_type`, `title`, `ref_type`, `ref_id`, `source_record_id?` |
| **Relacionamentos** | Projeção de Contracts, Mandates, Sanctions, Snapshots… |
| **Ciclo de vida** | Projected → Superseded |
| **Produz** | `timeline.event.projected.v1` |
| **Consome** | Eventos de fatos públicos e Case |
| **Casos de uso** | UC-004, UC-007 |
| **Regras** | occurred_on pode ser aproximado com precision flag |
| **Extensões** | Agrupamento por era, aniade gaps |

---

## Maps

### GeoPlace

| Campo | Conteúdo |
|-------|----------|
| **Nome** | GeoPlace |
| **Descrição** | Local geográfico normalizado (município, endereço resolvido, coordenadas). |
| **Responsabilidade** | Ancorar Companies/Expenses/Contracts no espaço. |
| **Principais atributos** | `place_id`, `label`, `admin_codes`, `lat`, `lon`, `precision`, `source_record_id?` |
| **Relacionamentos** | Company HQ; MapLayer points |
| **Ciclo de vida** | Active → Deprecated |
| **Produz** | `maps.geo_place.upserted.v1` |
| **Consome** | ETL geocoding |
| **Casos de uso** | UC-004 (endereço) |
| **Regras** | Precisão explícita; geocode falho ≠ inventar |
| **Extensões** | Polígonos, heatmaps |

### MapLayer

| Campo | Conteúdo |
|-------|----------|
| **Nome** | MapLayer |
| **Descrição** | Camada de mapa do Tenant/Caso (conjunto de pontos/áreas). |
| **Responsabilidade** | Visualização geográfica analítica. |
| **Principais atributos** | `layer_id`, `tenant_id`, `case_id?`, `name`, `feature_collection_ref` |
| **Relacionamentos** | GeoPlaces; Case |
| **Ciclo de vida** | Active → Archived |
| **Produz** | `maps.layer.saved.v1` |
| **Consome** | — |
| **Casos de uso** | UC-D20 mapas |
| **Regras** | Isolamento tenant |
| **Extensões** | Camadas públicas curadas |

---

## Watch

### Watchlist

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Watchlist |
| **Descrição** | Lista nomeada de monitoramento contínuo no Tenant. |
| **Responsabilidade** | Agrupar WatchTargets e políticas de alerta. |
| **Principais atributos** | `watchlist_id`, `tenant_id`, `name`, `owner_user_id`, `status` |
| **Relacionamentos** | 1‑N WatchTarget; AlertRules |
| **Ciclo de vida** | Active → Paused → Archived |
| **Produz** | `watch.watchlist.created.v1`, `watch.watchlist.paused.v1` |
| **Consome** | Quotas |
| **Casos de uso** | UC-010 |
| **Regras** | Limite de targets por plano |
| **Extensões** | Watchlists compartilhadas no workspace |

### WatchTarget

| Campo | Conteúdo |
|-------|----------|
| **Nome** | WatchTarget |
| **Descrição** | Alvo monitorado (Party ou fato). |
| **Responsabilidade** | Declarar interesse contínuo. |
| **Principais atributos** | `target_id`, `watchlist_id`, `ref_type`, `ref_id`, `added_at`, `status` |
| **Relacionamentos** | N‑1 Watchlist |
| **Ciclo de vida** | Active → Removed |
| **Produz** | `watch.target.added.v1`, `watch.target.removed.v1` |
| **Consome** | PartyMerged (reatribuir) |
| **Casos de uso** | UC-010 |
| **Regras** | Remerge de Party atualiza ref |
| **Extensões** | Targets por query salva |

### AlertRule

| Campo | Conteúdo |
|-------|----------|
| **Nome** | AlertRule |
| **Descrição** | Condição que transforma mudança de domínio em Alert. |
| **Responsabilidade** | Configurar gatilhos (nova sanção, mudança QSA, aditivo > X%). |
| **Principais atributos** | `alert_rule_id`, `watchlist_id?`, `tenant_id`, `event_types[]`, `filters`, `severity`, `enabled` |
| **Relacionamentos** | Produz Alert |
| **Ciclo de vida** | Enabled ↔ Disabled |
| **Produz** | `watch.alert_rule.changed.v1` |
| **Consome** | Domain events |
| **Casos de uso** | UC-010 |
| **Regras** | Evitar storm: dedupe window |
| **Extensões** | ML-assisted anomaly triggers |

### Alert

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Alert |
| **Descrição** | Instância de alerta gerada para usuários. |
| **Responsabilidade** | Notificar mudança relevante. |
| **Principais atributos** | `alert_id`, `tenant_id`, `rule_id`, `subject_ref`, `title`, `severity`, `status` (open/acked/closed), `payload`, `created_at` |
| **Relacionamentos** | Notification; pode abrir Case |
| **Ciclo de vida** | Open → Acknowledged → Closed |
| **Produz** | `watch.alert.raised.v1`, `watch.alert.acknowledged.v1` |
| **Consome** | Avaliações AlertRule |
| **Casos de uso** | UC-010 |
| **Regras** | Ack auditável; payload sem segredos |
| **Extensões** | Escalation policies |

---

## Reports

### ReportTemplate

| Campo | Conteúdo |
|-------|----------|
| **Nome** | ReportTemplate |
| **Descrição** | Modelo de relatório/dossiê exportável. |
| **Responsabilidade** | Padronizar estrutura de saída. |
| **Principais atributos** | `template_id`, `code`, `version`, `sections[]`, `scope` (system/tenant) |
| **Relacionamentos** | Usado por Report/ExportPackage |
| **Ciclo de vida** | Published → Retired |
| **Produz** | `reports.template.published.v1` |
| **Consome** | — |
| **Casos de uso** | UC-011 |
| **Regras** | Versionamento semver de template |
| **Extensões** | Templates white-label |

### Report

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Report |
| **Descrição** | Instância de relatório gerado a partir de Case/consulta. |
| **Responsabilidade** | Representar conteúdo lógico antes/alongside do pacote binário. |
| **Principais atributos** | `report_id`, `tenant_id`, `case_id?`, `template_id`, `status`, `created_by`, `created_at` |
| **Relacionamentos** | ExportPackage; EvidenceManifest |
| **Ciclo de vida** | Generating → Ready → Failed / Archived |
| **Produz** | `reports.report.ready.v1`, `reports.report.failed.v1` |
| **Consome** | Pedidos do Case |
| **Casos de uso** | UC-011 |
| **Regras** | Geração assíncrona; falhas retentáveis |
| **Extensões** | Agendamento periódico |

### ExportPackage

| Campo | Conteúdo |
|-------|----------|
| **Nome** | ExportPackage |
| **Descrição** | Artefato deliverable (PDF/JSON/ZIP) com manifesto. |
| **Responsabilidade** | Entrega auditável ao usuário. |
| **Principais atributos** | `package_id`, `report_id`, `format`, `storage_ref`, `content_hash`, `manifest_id`, `expires_at?` |
| **Relacionamentos** | EvidenceManifest; AuditEvent; Notification |
| **Ciclo de vida** | Ready → Downloaded → Expired |
| **Produz** | `reports.export_package.ready.v1`, `reports.export_package.downloaded.v1` |
| **Consome** | — |
| **Casos de uso** | UC-011 |
| **Regras** | Download gera AuditEvent; hash confere integridade |
| **Extensões** | Watermark dinâmico, link time-boxed |