FHIR DocumentReference

FHIR R4 ресурс — обёртка над внешним документом: PDF выписки, HL7-файл, скан анализов, URL guideline’а. Содержит метаданные документа (mime-type, размер, дата создания, source) + либо inline attachment (base64), либо ссылку на binary (URL / Binary resource).

Status в BloodGPT: research

Не реализовано в production. Загруженные пациентом / лабой документы (PDF blood test results, HL7 messages, JSON-файлы) сейчас парсятся прямо в Observation / Patient ресурсы без обёртки в DocumentReference. Original document file хранится в GCS bucket, путь — в BloodTest.gcsKey Postgres column (см. multi-tenant-fhir-storage) — не как FHIR ресурс. Хочется внедрить, конкретного timeline нет.

Ильдар (carry-over): «я недавно искал возможность его использовать для оформления входящих документов. пока этого нет, хочется это тоже сделать в итоге»

Зачем рассматривается

3 use case’а в BloodGPT где DocumentReference уместен:

1. Incoming documents (главный — open)

Пациент / лаборатория загружает документ. Поддерживаемые форматы: PDF (blood test results, scan выписки), HL7 (lab messages), JSON (structured lab feed — тоже document с нашей точки зрения, не just data). Сейчас:

Файл идёт в GCS, путь сохраняется в BloodTest.gcsKey
Парсер извлекает Observations / Patient demographics → пишет в FHIR
Original document не появляется в FHIR

С DocumentReference:

Создаётся DocumentReference ресурс с метаданными (filename, mime-type, upload time, source — лаб name)
DocumentReference.content[].attachment.url → ссылка на файл (можно GCS signed URL, можно FHIR Binary)
DocumentReference.subject → Patient/{id}
DocumentReference.context.encounter → если есть Encounter
Связь с derived ресурсами (parsed Observations) — через fhir-provenance Provenance.entity.what: DocumentReference/...

Преимущества:

FHIR-compliant audit trail — что было загружено пациентом, какие FHIR-ресурсы из этого происходят
Document-centric retrieval — GET /DocumentReference?patient=X — все загруженные документы пациента
Standard exchange — другие EHR могут receive наши documents через FHIR
Re-parsing — если LLM-парсер обновится, можно re-process original document

2. Citations в AI-output (decided: NOT use DocumentReference)

Plan-файл V2.5 BG-1323 (~/vault/plans/v2-5-rich-output-to-fhir.md) явно: «citations это URL-ссылки внутри extension — DocumentReference не нужен».

Citations — это external guideline references (NICE, ESC, и т.д.). Их хранение через DocumentReference — overkill (нет file content, just URL). Используется custom extension bloodgpt-citation {title, url, quote}. См. fhir-clinical-impression.

3. Generated PDF reports (uncertain — может, не надо)

BloodGPT генерирует PDF report для пациента (через output-pdf-generation.function.ts + Gotenberg). Сейчас результирующий PDF идёт в GCS, не в FHIR. С DocumentReference:

DocumentReference.type = “Patient summary”
DocumentReference.subject = Patient
DocumentReference.author = Organization/bloodgpt
DocumentReference.content[].attachment → ссылка на PDF в GCS

Это могло бы дать patient-portable summary — пациент expose DocumentReference в external EHR через FHIR API. Но это не очевидно требуется — GCS path в Postgres достаточен для нашего workflow. Open question: добавляет ли DocumentReference реальную ценность или это premature.

Ключевые поля для нашего use case

{
  "resourceType": "DocumentReference",
  "status": "current",
  "type": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "11502-2",
      "display": "Laboratory report"
    }]
  },
  "subject": { "reference": "Patient/{id}" },
  "date": "2026-04-26T10:00:00Z",
  "author": [{
    "reference": "Organization/...lab-name..."
  }],
  "content": [{
    "attachment": {
      "contentType": "application/pdf",
      "url": "https://gcs.googleapis.com/.../signed-url",
      "size": 123456,
      "title": "Blood test 2026-04-26.pdf"
    }
  }],
  "context": {
    "period": {
      "start": "2026-04-25T08:00:00Z"
    }
  }
}

Связь с другими ресурсами

DocumentReference/{doc}
 ├── subject → Patient/{id}
 ├── author → Organization/{lab}     (или Organization/bloodgpt для generated)
 └── content[].attachment.url        → GCS signed URL или Binary/{id}

Provenance/{prov}
 ├── target[] → [Observation/o1, Observation/o2, ...]
 └── entity[].what → DocumentReference/{doc}    (source documentation)

Provenance.entity.what ссылается на DocumentReference — это закольцовывает audit chain: “из этого документа парсер создал эти Observations”.

Открытые вопросы

Когда внедрять для incoming documents — нет concrete timeline. Carry-over от Ильдара, в backlog.
Storage decision (resolved): GCS остаётся primary storage для blob, FHIR DocumentReference хранит только URL-ссылку (signed GCS URL). FHIR Binary inline (base64) и blob-в-FHIR — отвергнуто. Signed URLs expire — нужен renewal mechanism (TBD detail).
DocumentReference для generated PDF report — uncertain, может не надо. GCS path в Postgres сейчас достаточен. Зависит от portability requirements (нужно ли expose patient summary в external EHR).
Backfill historical documents — все historical PDFs в GCS — создавать ли DocumentReference retroactively? Или только для новых.
Vendor support — _revinclude=DocumentReference:... на GCP Healthcare API — verify (см. google-healthcare-api vendor capability matrix).

Связано

fhir-provenance — entity.what: DocumentReference/... для audit trail
fhir-organization — author (lab или bloodgpt)
multi-tenant-fhir-storage — текущее storage для original files (BloodTest.gcsKey)
fhir-meta-tagging — общая стратегия source attribution

Источники

Источники: ¹ ² ³.

Сноски

FHIR R4 DocumentReference, accessed 2026-05-17, https://hl7.org/fhir/R4/documentreference.html. ↩
LOINC document type codes, accessed 2026-05-17, https://loinc.org/document-ontology/. ↩
Сессия ildar/7ff79368, 2026-03-27 — + `fhir-provenance. ↩

Quartz 4

Explorer