# Entidades — Dados, Busca e IA

**Contextos:** ETL, Crawler, Search, RAG, Knowledge Base, AI  
**Versão:** 1.0.0

---

## Crawler

### CrawlTarget

| Campo | Conteúdo |
|-------|----------|
| **Nome** | CrawlTarget |
| **Descrição** | Alvo de coleta (URL, API endpoint, dataset portal) configurado. |
| **Responsabilidade** | Declarar origem bruta a ser visitada respeitando ToS/robots. |
| **Principais atributos** | `target_id`, `source_system_code`, `locator`, `method`, `schedule`, `policy_tags[]`, `status` |
| **Relacionamentos** | N‑1 SourceSystem; 1‑N CrawlJob |
| **Ciclo de vida** | Active → Paused → Retired |
| **Produz** | `crawler.crawl_target.changed.v1` |
| **Consome** | PluginInstallation config |
| **Casos de uso** | UC-013 |
| **Regras** | Respeitar rate limit e política legal; secrets fora do locator |
| **Extensões** | Descoberta automática de sitemaps |

### CrawlJob

| Campo | Conteúdo |
|-------|----------|
| **Nome** | CrawlJob |
| **Descrição** | Execução de coleta de um CrawlTarget. |
| **Responsabilidade** | Baixar/materializar RawPayload com métricas. |
| **Principais atributos** | `job_id`, `target_id`, `started_at`, `finished_at`, `status`, `bytes`, `error_code?`, `content_hash?` |
| **Relacionamentos** | Produz RawPayload |
| **Ciclo de vida** | Queued → Running → Succeeded / Failed / Partial |
| **Produz** | `crawler.crawl_job.completed.v1`, `crawler.crawl_job.failed.v1` |
| **Consome** | Scheduler |
| **Casos de uso** | UC-013 |
| **Regras** | Idempotência por janela/hash; falhas → DLQ operacional |
| **Extensões** | Diff crawl, conditional GET |

---

## ETL

### SourceSystem

| Campo | Conteúdo |
|-------|----------|
| **Nome** | SourceSystem |
| **Descrição** | Sistema/fonte lógica de dados públicos (catálogo de origens). |
| **Responsabilidade** | Padronizar metadados de confiança, jurisdição e licença. |
| **Principais atributos** | `source_system_code`, `name`, `jurisdiction`, `publisher`, `license_tag`, `trust_level`, `homepage?` |
| **Relacionamentos** | Usado por Plugins, CrawlTarget, SourceRecord |
| **Ciclo de vida** | Active → Deprecated |
| **Produz** | `etl.source_system.registered.v1` |
| **Consome** | — |
| **Casos de uso** | UC-013, UC-004 |
| **Regras** | Código imutável; trust_level revisado periodicamente |
| **Extensões** | SLAs de frescor por fonte |

### RawPayload

| Campo | Conteúdo |
|-------|----------|
| **Nome** | RawPayload |
| **Descrição** | Artefato bruto imutável coletado (arquivo, JSON, HTML). |
| **Responsabilidade** | Preservar original para reprocessamento e disputa. |
| **Principais atributos** | `payload_id`, `source_system_code`, `storage_ref`, `content_hash`, `collected_at`, `crawl_job_id?`, `content_type` |
| **Relacionamentos** | Entrada de TransformJob; referenciável por SourceRecord.payload_ref |
| **Ciclo de vida** | Stored → (retenção) Purged sob política |
| **Produz** | `etl.raw_payload.stored.v1` |
| **Consome** | CrawlJob completed |
| **Casos de uso** | UC-013 |
| **Regras** | Imutável; purge não quebra SourceRecords publicados sem migração |
| **Extensões** | Compressão, cold storage |

### TransformJob

| Campo | Conteúdo |
|-------|----------|
| **Nome** | TransformJob |
| **Descrição** | Job de parse/normalização/validação sobre RawPayload(s). |
| **Responsabilidade** | Produzir registros canônicos e DataQualityIssues. |
| **Principais atributos** | `transform_id`, `plugin_version`, `input_payload_ids[]`, `status`, `stats`, `started_at`, `finished_at` |
| **Relacionamentos** | ConnectorPlugin; emite candidatos a SourceRecord |
| **Ciclo de vida** | Queued → Running → Succeeded / Failed |
| **Produz** | `etl.transform_job.completed.v1`, `etl.transform_job.failed.v1` |
| **Consome** | `etl.raw_payload.stored.v1` |
| **Casos de uso** | UC-013 |
| **Regras** | Versionar plugin; quarenena de schema break |
| **Extensões** | Streaming transforms |

### IngestRun

| Campo | Conteúdo |
|-------|----------|
| **Nome** | IngestRun |
| **Descrição** | Unidade de publicação atômica de um lote normalizado no catálogo. |
| **Responsabilidade** | Coordenar publish → eventos de domínio → Search/Graph. |
| **Principais atributos** | `ingest_run_id`, `source_system_code`, `idempotency_key`, `status`, `counts`, `published_at` |
| **Relacionamentos** | Agrupa SourceRecords; outbox events |
| **Ciclo de vida** | Open → Publishing → Published / Aborted |
| **Produz** | `etl.ingest_run.published.v1`, `etl.ingest_run.aborted.v1` |
| **Consome** | TransformJob completed |
| **Casos de uso** | UC-013 |
| **Regras** | Idempotency key única; publish gera fan-out; abort não deixa meio-publicado sem marcar |
| **Extensões** | Blue/green catalog switches |

### DataQualityIssue

| Campo | Conteúdo |
|-------|----------|
| **Nome** | DataQualityIssue |
| **Descrição** | Problema detectado em validação (campo inválido, órfão, duplicata suspeita). |
| **Responsabilidade** | Tornar qualidade observável e acionável. |
| **Principais atributos** | `issue_id`, `severity`, `code`, `message`, `ref`, `ingest_run_id?`, `status` |
| **Relacionamentos** | TransformJob / IngestRun |
| **Ciclo de vida** | Open → Resolved / Won’t Fix |
| **Produz** | `etl.data_quality_issue.opened.v1`, `etl.data_quality_issue.resolved.v1` |
| **Consome** | — |
| **Casos de uso** | UC-013 |
| **Regras** | Issues críticos podem bloquear publish |
| **Extensões** | Auto-remediation playbooks |

---

## Search

### SearchDocument

| Campo | Conteúdo |
|-------|----------|
| **Nome** | SearchDocument |
| **Descrição** | Documento indexado para busca (projeção de Party/fatos). |
| **Responsabilidade** | Viabilizar UC-003 com ranking e facetas. |
| **Principais atributos** | `doc_id`, `doc_type`, `ref_id`, `title`, `body`, `facets`, `signals`, `updated_at` |
| **Relacionamentos** | Projeção de Core/Companies/… |
| **Ciclo de vida** | Indexed → Updated → Deleted |
| **Produz** | `search.document.indexed.v1` (interno) |
| **Consome** | `etl.ingest_run.published.v1`, `core.party.merged.v1` |
| **Casos de uso** | UC-003 |
| **Regras** | Merge de Party reindexa/apaga docs órfãos; signals de Integrity opcionais |
| **Extensões** | Completers, synonyms |

### SearchQuery

| Campo | Conteúdo |
|-------|----------|
| **Nome** | SearchQuery |
| **Descrição** | Consulta executada (telemetria/domínio leve). |
| **Responsabilidade** | Auditar uso, melhorar relevância, alimentar UsageEvent. |
| **Principais atributos** | `query_id`, `tenant_id`, `actor_id`, `text`, `filters`, `result_count`, `took_ms`, `occurred_at` |
| **Relacionamentos** | UsageEvent |
| **Ciclo de vida** | Recorded |
| **Produz** | (telemetria) pode mapear UsageEvent |
| **Consome** | — |
| **Casos de uso** | UC-003, UC-016 |
| **Regras** | Não logar textos que contenham segredos; retenção curta se necessário |
| **Extensões** | Saved searches |

---

## Knowledge Base

### OntologyTerm

| Campo | Conteúdo |
|-------|----------|
| **Nome** | OntologyTerm |
| **Descrição** | Termo controlado da taxonomia Mud Sentinel (tipos de aresta, naturezas de despesa, modalidades). |
| **Responsabilidade** | Garantir vocabulário estável entre contextos. |
| **Principais atributos** | `term_id`, `namespace`, `code`, `label_pt`, `label_en`, `parent_id?`, `status` |
| **Relacionamentos** | Usado por GraphEdge.type, expense nature, etc. |
| **Ciclo de vida** | Proposed → Active → Deprecated |
| **Produz** | `knowledge.ontology_term.activated.v1` |
| **Consome** | — |
| **Casos de uso** | Transversal |
| **Regras** | Deprecar ≠ apagar; aliases permitidos |
| **Extensões** | SKOS export, multilíngue |

### KnowledgeArticle

| Campo | Conteúdo |
|-------|----------|
| **Nome** | KnowledgeArticle |
| **Descrição** | Artigo explicativo (metodologia de score, como ler sanção, playbooks). |
| **Responsabilidade** | Sustentar ajuda in-app e grounding de RAG interno. |
| **Principais atributos** | `article_id`, `slug`, `title`, `body`, `audience`, `version`, `status` |
| **Relacionamentos** | EmbeddingChunk; OntologyTerm |
| **Ciclo de vida** | Draft → Published → Retired |
| **Produz** | `knowledge.article.published.v1` |
| **Consome** | — |
| **Casos de uso** | UC-008 (contexto), onboarding |
| **Regras** | Artigos metodológicos versionados junto ao method_version do score |
| **Extensões** | Localização, vídeos |

---

## RAG

### EmbeddingChunk

| Campo | Conteúdo |
|-------|----------|
| **Nome** | EmbeddingChunk |
| **Descrição** | Fragmento embeddado de Document/Source/Knowledge para recuperação. |
| **Responsabilidade** | Unidade de retrieval com metadados de citação. |
| **Principais atributos** | `chunk_id`, `parent_type`, `parent_id`, `ordinal`, `text`, `embedding_ref`, `model_version`, `tenant_id?` |
| **Relacionamentos** | DocumentVersion / KnowledgeArticle / SourceRecord texto |
| **Ciclo de vida** | Indexed → Stale → Reembedded |
| **Produz** | `rag.chunk.indexed.v1` |
| **Consome** | DocumentVersion stored; article published |
| **Casos de uso** | UC-008 |
| **Regras** | Chunks de tenant isolados; model_version obrigatório; texto mínimo para citação |
| **Extensões** | Hierarchical chunking |

### RetrievalQuery

| Campo | Conteúdo |
|-------|----------|
| **Nome** | RetrievalQuery |
| **Descrição** | Consulta de recuperação semântica associada a uma Completion. |
| **Responsabilidade** | Rastrear o que foi buscado para grounding. |
| **Principais atributos** | `retrieval_id`, `tenant_id`, `case_id?`, `query_text`, `filters`, `hit_chunk_ids[]`, `occurred_at` |
| **Relacionamentos** | Completion; EmbeddingChunk |
| **Ciclo de vida** | Executed |
| **Produz** | `rag.retrieval.executed.v1` |
| **Consome** | Pedido AI |
| **Casos de uso** | UC-008 |
| **Regras** | Hits limitados; só chunks autorizados ao tenant |
| **Extensões** | Hybrid BM25+vector |

---

## AI

### PromptTemplate

| Campo | Conteúdo |
|-------|----------|
| **Nome** | PromptTemplate |
| **Descrição** | Template versionado de prompt (system/developer) para uma finalidade. |
| **Responsabilidade** | Governar comportamento reproduzível da IA. |
| **Principais atributos** | `template_id`, `code`, `version`, `purpose`, `content`, `output_schema?`, `status` |
| **Relacionamentos** | Usado por Completion |
| **Ciclo de vida** | Draft → Active → Retired |
| **Produz** | `ai.prompt_template.activated.v1` |
| **Consome** | — |
| **Casos de uso** | UC-008 |
| **Regras** | Mudança ⇒ novo version; active único por code; review de security |
| **Extensões** | Multi-locale templates |

### Completion

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Completion |
| **Descrição** | Saída de modelo para um pedido do usuário/sistema. |
| **Responsabilidade** | Registrar resposta, modelo, tokens, modo (facts_only vs hypothesis). |
| **Principais atributos** | `completion_id`, `tenant_id`, `actor_id`, `case_id?`, `template_id+version`, `model`, `provider`, `mode`, `input_hash`, `output_text`, `status`, `token_usage`, `created_at` |
| **Relacionamentos** | 1‑N Citation; RetrievalQuery; UsageEvent; pode virar EvidenceItem se pinado |
| **Ciclo de vida** | Requested → Succeeded / Failed / Moderated |
| **Produz** | `ai.completion.generated.v1`, `ai.completion.failed.v1` |
| **Consome** | Context de Case/Search/RAG |
| **Casos de uso** | UC-008, UC-016 |
| **Regras** | mode explícito na UX; não escrever fatos no catálogo; retenção conforme policy; redaction de segredos |
| **Extensões** | Tool-calling allowlisted, eval scores |

### Citation

| Campo | Conteúdo |
|-------|----------|
| **Nome** | Citation |
| **Descrição** | Citação que liga trechos da Completion a Evidence/Source/Chunk. |
| **Responsabilidade** | Explicabilidade e verificabilidade da resposta. |
| **Principais atributos** | `citation_id`, `completion_id`, `ref_type`, `ref_id`, `span?`, `label` |
| **Relacionamentos** | N‑1 Completion; → SourceRecord / EvidenceItem / EmbeddingChunk |
| **Ciclo de vida** | Created com Completion |
| **Produz** | (parte de completion.generated) |
| **Consome** | — |
| **Casos de uso** | UC-008, UC-011 |
| **Regras** | Em mode facts_only, exigir ≥1 citation quando claim factual; claims sem citação marcados |
| **Extensões** | Highlight offsets no PDF export |