EHR-core contract (Clinical Data Repository)
clinical specs/clinical/ehr-core-contract.kmd
Quando esta spec se aplica
Todos os triggers
- Extrair/implementar o EHR-core (services/clinical/corpus) — health-RFC-001 S1/S2
- Definir a superfície openEHR/FHIR que Koder Health e o HMIS consomem
Corpo da especificação
Spec — EHR-core contract (Clinical Data Repository)
Três nomes, um componente (para não confundir): EHR-core = o conceito (o núcleo do registro clínico); CDR / Clinical Data Repository = o termo-de-arte openEHR usado nesta prosa;
corpus= o nome do componente na Stack —services/clinical/corpus(nome de infra, funcional; escolhido por remeter a "acervo/corpus de dados" e a "corpo", sem a ambiguidade de sigla docdr/his). Quando este doc diz "o CDR" / "o EHR-core", o artefato é ocorpus.
S1 deliverable do épico
clinic/health#4 (health-RFC-001). Define o contrato que Koder Health (privado) e o futuro HMIS (público/internacional) consomem — a superfície do Clinical Data Repository (CDR). É contrato, não implementação: o carve físico (clinic/health/src→services/clinical/corpus) é S2.v0.1 — fundacional. Ancorada na superfície clínica real de hoje (
products/vertical/clinic/health/src); o detalhamento por-domínio de arquétipos é refino contínuo, não bloqueia.
1. O que o EHR-core É
Um CDR openEHR com interop FHIR R4 — o registro clínico do paciente, versionado, multi-tenant, agnóstico de país e de segmento (privado/público). Guarda o dado clínico; não guarda billing, agenda, telemedicina, nem regras de um país.
2. Fronteira IN / OUT (ancorada nos models de hoje)
IN — o kernel clínico (vai pro services/clinical/corpus):
Entidade (hoje em clinic/health) | Papel no core | FHIR R4 |
|---|---|---|
Patient | sujeito do cuidado | Patient |
EHR + Composition (+ versão/histórico) | registro openEHR versionado | Composition / DocumentReference |
Archetype + Template | modelos openEHR (ADL 1.4/2.0) | (openEHR nativo) |
Prescription + Medication | prescrição | MedicationRequest |
Certificate | atestado/laudo/declaração | DocumentReference |
Consent | consentimento (LGPD/GDPR/…) | Consent |
AuditLog | auditoria de acesso clínico | AuditEvent |
BOUNDARY — identidade (referenciada, não possuída pelo core):
| Professional | autor/executante clínico | Practitioner — identidade vem do Koder ID, o core referencia |
| Tenant/Unit context | isolamento | fornecido pelo tenancy context do plane, não modelado como dado clínico |
OUT — camada de produto (fica no Koder Health / vai pro HMIS conforme o caso):
| Appointment Schedule Waitlist | agendamento/ops (candidato a serviço compartilhado próprio depois — não é o registro clínico) |
| TeleconsultSession | telemedicina (produto; usa Koder Kall) |
| TISSGuide TISSProcedure InsurancePlan Invoice | faturamento privado BR (TISS/ANS) — adapter de país/segmento |
| Tenant TenantPlan | tenancy/comercial (plataforma/produto) |
3. Superfície openEHR (CDR)
Operações (já existem no EHRHandler + services/openehr de hoje — o contrato as
canoniza):
- Compositions: create · update (nova versão) · get · list-by-EHR · history (versionamento é parte do contrato — um CDR openEHR nunca sobrescreve, versiona).
- Archetypes/Templates: registrar/validar (
ValidateADL— ADL 1.4 e 2.0),ParseArchetypeID,ValidateCompositionContent(content, archetypeID). - AQL:
Execute(query, params, offset, limit)— AQL → SQL sobre JSONB (AQLExecutorde hoje). AQL é a query language do contrato (padrão openEHR). - Storage: conforme
stack-RFC-001(data plane); composition como JSONB versionado.
4. Superfície FHIR R4 (interop)
Recursos expostos (country-agnostic — RNDS/nacional é adapter, ver §6):
Patient · Encounter · Composition/DocumentReference · MedicationRequest ·
Immunization · Observation · DiagnosticReport · Consent · Practitioner ·
Bundle (transaction).
Operações: GET [type]?[search], POST [type], POST Bundle (transaction),
Content-Type: application/fhir+json. (Hoje o client RNDS já fala FHIR R4 —
Patient/Immunization/DiagnosticReport/Bundle; S4 generaliza pra gateway.)
5. Contrato de tenancy + auth
- Multi-tenant por
koder_user_id×tenant_id(isolamento duro —multi-tenant-by-default.kmd). Todo acesso ao CDR carrega o tenant context; nenhuma query cross-tenant sem escopo. - Auth: OAuth2/JWT via Koder ID (JWKS validation) — já é o modelo do
clinic/health. - Auditoria: todo read/write clínico gera
AuditEvent(oAuditLogde hoje) — não-opcional. - Consent-aware: leitura sensível respeita
Consent(base pro ShareGrant do #2).
6. Country-agnostic no core; nacional é adapter
O core não conhece país. Redes nacionais e faturamento entram como adapters fora do CDR:
- RNDS (BR, FHIR nacional) → adapter em
services/clinical/fhir(S4). - TISS/ANS (BR, privado) → fica no produto Koder Health (OUT §2).
- Outros países → novos adapters sobre a mesma superfície FHIR R4 do §4.
Terminologia (SNOMED CT / LOINC / ICD / CIAP) = serviço próprio services/clinical/terminology (S5).
7. Consumidores
| Consumidor | Como usa o core |
|---|---|
| Koder Health (privado) | CDR + FHIR; adiciona TISS/convênio/portal/telemedicina por cima |
| HMIS (público/internacional) | CDR + FHIR; adiciona vigilância/regulação/imunização/… + adapters do país |
| Koder Iris / DICOM | referenciam estudos ao paciente via FHIR ImagingStudy (S7) |
8. O que S1 NÃO faz
- Não move código (isso é S2 — carve
clinic/health/src→services/clinical/corpus). - Não decide a Área final (
services/clinical/) — recomendada pelohealth-RFC-001 §10, ratificar contra RFC-003/004 em S2. - Não enumera todo campo de todo arquétipo — refino contínuo por-domínio; o contrato é a superfície + fronteira + operações, que esta v0.1 fixa.
Follow-ups (S1 → refino)
- Detalhar o set mínimo de arquétipos openEHR por domínio clínico (evolução).
- Formalizar o mapeamento openEHR-Composition ↔ FHIR-DocumentReference/Composition.
- Perfil de conformância FHIR (CapabilityStatement) do gateway em S4.