D013 FHIR 与 OMOP 数据转换｜个人思维图谱小站

正文

SKILL.md

v0.2.1 发布合同（优先于历史版本说明）

最终OMOP staging主键按表及canonical fact稳定排序后分配包内稠密正整数，并同步disposition引用。避免随机长数字哈希与身份证格式碰撞。该编号仅为包内暂存标识，不是跨包生产数据库主键，不可增量直接合库。

详见 references/repair-v0.2.1.md。完整替换D001–D014并重新生成中间产物，不混用历史伪ID、清单或staging编号。测试通过不表示临床生产批准。

v0.2.0 修复合同（优先于旧版说明）

接收嵌套 Decimal 字符串并输出合法 JSON 数值；保留比较符、剂量/途径/频次及起止区间。生成有效 UUID fullUrl；FHIR 支持范围内检查实际数据类型和值集。时区未知的本地时刻不补时区：在标准日期字段保留日期，同时扩展保存源本地时间。默认不把处方医嘱、hold/stop、计划/排除/非患者事实当已发生暴露。仅输出 staging，不生成可直接导入完整 CDM 的承诺。

具体运行界限见 references/repair-v0.2.md；任何自测通过都不等于临床生产批准。

Mission

D013 is a deterministic representation layer.

It does not:

extract new clinical facts;
resolve clinical context;
normalize medications or measurements;
choose terminology codes;
choose OMOP Standard Concepts;
infer missing dates;
write to a FHIR server or OMOP database.

It converts the already-reviewed D012 output into:

FHIR R4 staging resources;
OMOP CDM v5.4 staging rows;
explicit transform dispositions and warnings.

Required upstream

D012 manifest:

overall_status = ready_for_fhir_omop_transform

Required artifact:

coded_timeline_events.jsonl

Each event must preserve:

subject
fact_type
concept
assertion
value
details
coding
time
lane
provenance

FHIR target

D013 emits a local FHIR R4 Bundle with:

type = collection

It is not a transaction request and is never posted automatically.

Supported resource mappings:

Clinical fact	FHIR R4 resource
condition / symptom	Condition
lab / vital / sign / observation	Observation
procedure	Procedure
medication order	MedicationRequest
medication administration	MedicationAdministration
home/discharge/narrative medication	MedicationStatement

D013 also emits minimal pseudonymous Patient resources so subject references resolve inside the local collection.

Unsupported fact types are preserved in the transform disposition/warning output rather than coerced.

FHIR coding policy

If D012 verified a terminology code:

coding.selected

D013 emits it in a CodeableConcept.coding.

If D012 explicitly accepted an unresolved concept, D013 may emit a text-only CodeableConcept where the FHIR resource permits it.

D013 never invents a code.

FHIR time policy

FHIR may preserve coarse dates such as:

2019
2026-03
2026-03-12

D013 passes those through when the target date/dateTime element permits a partial date.

D013 does not turn:

into:

2019-01-01

OMOP target

D013 emits staging rows only for OMOP CDM v5.4.

No database connection is opened.

Supported Standard Concept domains:

Standard Concept domain	OMOP table
Condition	condition_occurrence
Drug	drug_exposure
Procedure	procedure_occurrence
Measurement	measurement
Observation	observation
Device	device_exposure

Routing is based on D012 standard_concepts[].domain_id.

It is not based on the original fact type when a verified Standard Concept exists.

OMOP one-to-many

If one source concept maps to multiple Standard Concepts, D013 emits one staging row for each target Standard Concept.

This can create rows in:

the same domain/table; or
multiple domains/tables.

D013 must not collapse them.

Explicit unresolved OMOP mapping

If D012 records:

terminology_resolution = accepted_unresolved

D013 may preserve the source fact in an OMOP staging row using:

*_concept_id = 0

only when the fact can be routed by the local fact-type fallback policy.

The disposition is marked:

omop_unmapped = true

so D014 can enforce a coverage threshold.

D013 never silently converts ordinary unresolved mappings.

Date gate for OMOP

OMOP event tables require a concrete date.

D013 therefore requires at least:

precision = day

for OMOP staging.

Events with only:

year
month
unknown

remain in FHIR where representable, but are withheld from OMOP with:

omop_requires_day_precision

No fake day is created.

Planned event gate

FHIR can preserve planned/request semantics.

OMOP clinical event staging is conservative:

lane = planned

does not produce an OMOP occurrence/exposure row by default.

It is recorded as:

planned_event_not_staged_to_omop

Refuted/negative event gate

Refuted/negative conditions can be represented in FHIR with verification status.

D013 does not stage them as positive OMOP CONDITION_OCCURRENCE records.

Negative medication mentions do not become DRUG_EXPOSURE.

OMOP person IDs

D013 assigns package-local surrogate integer person_id values from D003 pseudonymous patient keys.

The mapping is written to:

person_key_map.jsonl

It contains pseudonymous keys only.

OMOP type concept policy

D013 never hardcodes OMOP type concept IDs.

Optional policy:

{
  "condition_occurrence": 123,
  "drug_exposure": 456,
  "procedure_occurrence": 789,
  "measurement": 101,
  "observation": 102,
  "device_exposure": 103
}

Every nonzero type concept ID is verified against the same local OMOP vocabulary index used by D012.

If no valid type concept is supplied, D013 uses:

type_concept_id = 0

in staging and emits a high-severity warning.

D014 decides whether the package may proceed.

Workflow

Transform

python "$SKILL_DIR/scripts/transform.py" \
  --d012-manifest /path/to/d012/terminology_omop_mapping_manifest.json \
  --output-root ./runs/haonan-d013 \
  --omop-type-policy /optional/type_policy.json

Outputs:

fhir_resources.jsonl
fhir_bundle.json

person_key_map.jsonl
omop_staging_rows.jsonl
omop_staging/
  condition_occurrence.jsonl
  drug_exposure.jsonl
  procedure_occurrence.jsonl
  measurement.jsonl
  observation.jsonl
  device_exposure.jsonl

transform_dispositions.jsonl
transform_warnings.jsonl
fhir_omop_transform_manifest.json

Validate

python "$SKILL_DIR/scripts/validate_transform.py" \
  --manifest /path/to/d013/fhir_omop_transform_manifest.json

Completion gate

ready_for_quality_gate requires:

every D012 coded event has exactly one transform disposition;
every generated FHIR resource passes D013's R4 structural minimum checks;
every OMOP staging row has a deterministic local PK and person_id;
every nonzero Standard Concept came from D012;
every one-to-many D012 mapping is preserved as multiple OMOP staging rows;
no OMOP row invents a day from year/month precision;
planned events are not staged as completed OMOP clinical occurrences;
refuted conditions and negative medication mentions are not staged as positive OMOP events;
no production system is mutated;
all incomplete/withheld transformations are explicitly warned.

D013 can still be ready_for_quality_gate with warnings. D014 owns the final blocking decision.

Safety

zero network;
zero automatic installation;
zero database writes;
zero FHIR server writes;
no raw PHI;
no arbitrary shell;
no input-code execution;
no terminology inference;
no clinical reasoning;
no fake dates;
no hard-coded OMOP type concept IDs.

Handoff

D013 hands all staging artifacts to:

haonan-d014-clinical-data-quality-gate

D013 FHIR 与 OMOP 数据转换

正文