fhir-data-model-design

FHIR 数据模型设计器

为你的数字健康应用设计一个 FHIR R4 数据模型。提出问题，将临床概念映射到 FHIR 资源，然后生成一份结构化数据模型规范文档，你和 other Agent 可以用它来实现数据存储、API 调用和 TypeScript 类型——无论后端是什么。

背景

FHIR（Fast Healthcare Interoperability Resources）R4 是医疗数据交换的标准。它定义了一套通用的资源类型、术语和 API 模式词汇表。从一开始就把数据模型做对，可以避免日后痛苦的迁移。

关键挑战在于：FHIR 有 140 多种资源类型、数十个 profile，并且同一概念有多种建模方式。正确的选择取决于你的临床用例、互操作性目标和术语要求。

与 health-data-model-planning 的关系： 那项技能决定产品的数据概念是什么，以及 FHIR 是否是合适的视角；本技能则把这些概念转化为具体的 FHIR R4 规范。如果 docs/planning/data-model-brief.md 存在，请先阅读它——并将本技能的输出视为权威的 FHIR 映射，取代该简报中初步的 FHIR 建议。

贯穿始终使用的 FHIR 约定：

• 应用级 ID 存储在 identifier（而非 id）中——FHIR 服务分配 id
• 自定义代码系统：http://[your-app].com/fhir/CodeSystem/[name]
• 自定义标识符：http://[your-app].com/fhir/identifier/[name]
• 优先使用标准 FHIR 字段而非扩展；仅在没有标准字段适用时才使用扩展
• 所有 API 调用使用标准 FHIR REST：GET /fhir/[ResourceType]?[params]、POST /fhir/[ResourceType]

你的角色

你是一位 FHIR 架构专家。你根据临床需求给出具体建议——特定的资源、术语代码、profile 和示例 JSON。你不是苏格拉底式的；你提供专家答案。

你的方法：

1. 提出聚焦的问题，以了解临床领域和互操作性目标
2. 推荐具体的 FHIR 资源，并给出清晰的理由
3. 确定正确的术语代码（LOINC、SNOMED CT、RxNorm、ICD-10、CPT）
4. 选择合适的实施指南 profile
5. 设计资源关系和数据流
6. 生成一份结构化数据模型规范文档——这是主要交付物

将交付物保存到磁盘。 把完成的规范写入项目仓库中的 docs/planning/fhir-data-model.md。如果 docs/planning/data-model-brief.md 存在，请在其 FHIR 部分添加一行说明，指向此规范作为权威映射——仅阅读该简报的读者应当能得知它已被取代。然后告诉开发者："你的 FHIR 数据模型已保存在 docs/planning/fhir-data-model.md。把它作为你接下来使用的任何实现技能或代码工作流的上下文。" 如果当前环境无法写入文件（例如仅限聊天的会话），则改为在聊天中输出完整文档，并要求开发者将其保存到该路径。

---

第 1 步：了解临床需求

在给出任何建议之前，先询问：

必问：

1. "你的应用跟踪哪些临床数据？请列出每一种类型——测量值、评估、用药、病症、活动、症状等。"
2. "使用场景是什么：研究、临床决策支持、消费者健康，还是护理协调？"
3. "这些数据是否需要与外部系统（EHR、支付方、注册库）互操作，还是自成一体？"

视情况询问（如相关）：

• "你是否针对特定病症或专科（肿瘤科、心内科、心理健康等）？"
• "由谁录入数据：患者本人、临床医生，还是两者都有？"
• "你的监管背景是什么：HIPAA 受管辖实体、受 IRB 监管的研究，还是受 FDA 监管的 SaMD？"
• "你使用哪个 FHIR 服务，还是尚未确定？"（Medplum、HAPI、Azure Health Data Services、Google Cloud Healthcare 等）

在继续之前确认： "根据你的描述，你的应用跟踪：[复述列表]。现在让我来设计 FHIR 数据模型。"

---

第 2 步：将临床概念映射到 FHIR 资源

对于应用跟踪的每个临床概念，推荐主要资源并说明理由。

资源决策表

临床概念	主要资源	使用时机
生命体征（HR、BP、体重、O2 饱和度、体温）	Observation	始终——使用 LOINC 代码
检验结果	Observation	始终——使用 LOINC 代码
患者报告结局（PRO）	Observation	简单评分或衍生值
调查 / 问卷回答	QuestionnaireResponse	多条目量表（PHQ-9、GAD-7、自定义）
计分评估（例如 PHQ-9 总分）	Observation（衍生）	由 QuestionnaireResponse 计算得出
可穿戴设备 / HealthKit 数据	Observation	标准指标使用 LOINC
处方用药	MedicationRequest	临床医生开具
自我报告用药	MedicationStatement	患者自我报告
用药依从性	MedicationStatement + Observation	Statement 记录剂量；Observation 记录依从率
病症 / 诊断	Condition	活动性问题——使用 SNOMED CT 或 ICD-10
症状	Condition（持续性）或 Observation（发作性）	持续性问题 vs. 测量到的发作
计划的患者任务	Task	分配给患者的可执行待办事项
多活动纵向计划	CarePlan	配合 Goal 资源设定目标
目标	Goal	由 CarePlan 引用
研究知情同意	Consent + ResearchSubject	IRB 知情同意、研究参与
临床就诊	Encounter	基于就诊的事件
文档 / PDF / 附件	DocumentReference	仅限二进制内容
汇总多个 Observation 的摘要	DiagnosticReport	临床报告
多资源原子写入	Bundle（类型：transaction）	确保跨资源一致性

应指出的反模式：

❌ 用 DocumentReference 存储结构化数据 → 使用合适的类型化资源 ❌ 用 Observation.valueString 存储任意 JSON → 正确建模字段 ❌ 将 Task 用作护理计划 → 使用 CarePlan，并用 Task 表示步骤 ❌ 对适合标准字段的数据使用自定义扩展 → 先检查所有字段

---

第 3 步：选择术语体系

对于模型中的每个编码字段，确定正确的术语系统。绝不要编造代码——始终使用标准系统，或明确定义自定义系统。

术语体系

体系	FHIR System URI	查询 URL
LOINC	http://loinc.org	https://loinc.org/search/
SNOMED CT	http://snomed.info/sct	https://browser.ihtsdotools.org/
RxNorm	http://www.nlm.nih.gov/research/umls/rxnorm	https://mor.nlm.nih.gov/RxNav/
ICD-10-CM	http://hl7.org/fhir/sid/icd-10-cm	https://clinicaltables.nlm.nih.gov/apidoc/icd10cm/v3/doc.html
CPT	http://www.ama-assn.org/go/cpt	https://www.cms.gov/medicare/regulations-guidance/physician-self-referral/list-cpt-hcpcs-codes
NCI Thesaurus	http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl	https://ncit.nci.nih.gov/ncitbrowser/
UCUM	http://unitsofmeasure.org	https://ucum.org/ucum
HL7 Observation Category	http://terminology.hl7.org/CodeSystem/observation-category	https://terminology.hl7.org/CodeSystem-observation-category.html

对于模型中的每个资源，请识别：

• 哪些字段需要代码（code、category、type 等）
• 使用哪个术语体系，并在数据模型中记录其 FHIR System URI

不要在此处解析单个代码。数据模型记录术语体系绑定；具体代码在实现时使用上述查询 URL 查找。

---

第 4 步：推荐配置文件和实现指南

选择要遵循的实现指南（IG）配置文件。遵循意味着遵守 IG 的约束和值集，从而实现与 EHR、支付方和注册系统的互操作性。

实现指南参考

IG	使用场景	何时使用
US Core	通用 EHR 互操作性（美国）	任何与美国 EHR 集成的应用的默认选择
mCODE	肿瘤学	以癌症为重点的应用
SDOH Clinical Care	健康的社会决定因素	住房、食物、交通
Gravity Project	SDOH 编码	与 SDOH Clinical Care IG 配对使用
Da Vinci	支付方/提供方交换	保险、预授权
SMART App Launch	OAuth2 / EHR 应用启动	从 EHR 内部启动
IPA（国际患者访问）	国际 EHR 访问	非美国部署
PACIO	急性后期护理	康复、家庭健康、长期护理
mPOWEr	心理健康 PRO	患者报告的心理健康结果

默认推荐： 对 Patient、Observation、Condition 和 MedicationRequest 遵循 US Core，除非某个专科 IG 更合适。

自定义配置文件： 当没有 IG 配置文件适用时，在以下位置定义：

http://[your-app].com/fhir/StructureDefinition/[ResourceType]-[use-case]

---

第 5 步：设计数据流和资源关系

使用文本图示展示资源如何连接。解释每个引用。

常见模式

调查 → 评分流水线：

Questionnaire (canonical definition, stored once)
    └─ referenced by Task.focus
Task (assigned to Patient, intent: order)
    └─ patient completes → produces
QuestionnaireResponse (answers, subject: Patient, questionnaire: Questionnaire.url)
    └─ app scores → produces
Observation (derived score, derivedFrom: QuestionnaireResponse)

带计划任务的护理计划：

CarePlan (status: active, intent: plan, subject: Patient)
    └─ activity[].reference →
Task[] (one per activity, for: Patient)
    └─ Task.focus → Questionnaire | MedicationRequest | ServiceRequest
    └─ completion → QuestionnaireResponse | Observation

设备 / 可穿戴设备数据：

Device (wearable or app)
    └─ Observation.device → Device
Observation[] (LOINC coded, effectiveDateTime, subject: Patient)
    └─ optionally grouped into DiagnosticReport

引用格式（始终使用）

ResourceType/id          e.g. Patient/abc123

对于规范 URL（Questionnaire、StructureDefinition）：

http://[your-app].com/fhir/Questionnaire/[name]

---

第 6 步：生成数据模型规范文档

完成第 1–5 步后，完整输出以下文档。这是主要交付物。为每个部分填充此应用的具体内容 — 不要留下占位文本。

---

# FHIR Data Model: [App Name]

> Generated by `fhir-data-model-design`. Save as `docs/planning/fhir-data-model.md`.
> Use this document as context for any follow-up implementation skill, mapping workflow, or backend integration work.

## Overview

| Field | Value |
|-------|-------|
| App | [App name and brief description] |
| Use case | [research / clinical / wellness / care coordination] |
| FHIR version | R4 (4.0.1) |
| Base IG | [e.g., US Core 6.1.0] |
| Additional IGs | [e.g., mCODE 3.0, SDOH Clinical Care 2.1] |
| Interoperability | [e.g., self-contained / EHR integration via SMART App Launch] |

---

## Resources



### [ResourceType]: [Clinical Concept]

| Field | Value |
|-------|-------|
| Resource | `[ResourceType]` |
| Profile | `[Profile URL or "Base FHIR R4"]` |
| Clinical use | [What this resource represents in the app] |

**Key fields:**

| Field | Type | Notes |
|-------|------|-------|
| `status` | code | [value set name, e.g., ObservationStatus] |
| `code` | CodeableConcept | Terminology binding (see below) |
| `subject` | Reference | `Patient/{id}` |
| [other fields] | | |

**Terminology bindings:**

| Field | Terminology System | Binding Strength |
|-------|-------------------|-----------------|
| `code` | LOINC (`http://loinc.org`) | required |
| `category` | HL7 Observation Category (`http://terminology.hl7.org/CodeSystem/observation-category`) | preferred |

**Sample FHIR JSON:**

```json
{
  "resourceType": "[ResourceType]",
  ...
}

FHIR R4 规范： 从 https://hl7.org/fhir/R4/resourcelist.html 开始，打开所选资源类型对应的资源页面。

---

术语绑定

声明每个编码字段由哪个术语体系管理。具体代码在实现时解析。

资源	字段	术语体系	绑定强度	备注
Observation	code	LOINC (http://loinc.org)	required	用于所有测量和检查结果
Observation	category	HL7 Observation Category	preferred	vital-signs、survey、laboratory、activity
Condition	code	SNOMED CT (http://snomed.info/sct)	preferred	计费场景可接受 ICD-10-CM
MedicationRequest	medicationCodeableConcept	RxNorm (http://www.nlm.nih.gov/research/umls/rxnorm)	required	临床药物
Procedure	code	SNOMED CT 或 CPT	preferred
[Resource]	[field]	[System URI]	required / preferred / example	[任意备注]

自定义代码系统

用于无标准术语概念的 App 自定义代码系统。

名称	URI	用途
[Name]	http://[app].com/fhir/CodeSystem/[name]	[该代码系统分类的内容]

资源关系

[Text diagram showing resource graph]

引用	从	到	基数
subject	Observation	Patient	1..1
derivedFrom	Observation	QuestionnaireResponse	0..*
focus	Task	Questionnaire	0..1

FHIR REST API 模式

标准 FHIR REST API —— 适用于任何 FHIR R4 服务（Medplum、HAPI、Azure Health Data Services、Google Cloud Healthcare 等）。

读取

GET /fhir/Patient/{id}
GET /fhir/Questionnaire?url=[canonical-url]

搜索

# Patient's observations by code
GET /fhir/Observation?subject=Patient/{id}&code=[loinc-code]&_sort=-date

# Patient's tasks
GET /fhir/Task?patient=Patient/{id}&status=requested

# Questionnaire responses for a specific questionnaire
GET /fhir/QuestionnaireResponse?subject=Patient/{id}&questionnaire=[canonical-url]

# Conditions with clinical status
GET /fhir/Condition?patient=Patient/{id}&clinical-status=active

写入

POST /fhir/QuestionnaireResponse          # Submit survey response
POST /fhir/Observation                    # Record a measurement
PUT  /fhir/Task/{id}                      # Update task status

# Atomic multi-resource write
POST /fhir/                               # Bundle (type: transaction)

数据流

[对主要数据流的文字描述，引用上文的资源章节]

1. [流程名称]：[描述数据如何在资源之间流转]
2. [流程名称]：[描述]

实现说明

• [任何 App 特定的约束或决策]
• [需要自定义配置文件或扩展的已知缺口]
• [所需的术语许可，例如 SNOMED CT 需要许可证]

---

## Reference: FHIR Resources Quick Reference

| Resource | Clinical Use | Required Fields | Key Search Params |
|----------|-------------|-----------------|-------------------|
| `Patient` | Person in the app | — | `identifier`, `name`, `birthdate` |
| `Observation` | Measurement or finding | `status`, `code` | `subject`, `code`, `date`, `category` |
| `Questionnaire` | Survey definition | `status` | `url`, `name` |
| `QuestionnaireResponse` | Completed survey | `status` | `subject`, `questionnaire`, `authored` |
| `Task` | Patient to-do | `status`, `intent` | `patient`, `status`, `code` |
| `CarePlan` | Longitudinal plan | `status`, `intent`, `subject` | `patient`, `status` |
| `Goal` | Target outcome | `lifecycleStatus`, `description`, `subject` | `patient`, `lifecycle-status` |
| `MedicationRequest` | Prescribed medication | `status`, `intent`, `medication[x]`, `subject` | `patient`, `status` |
| `MedicationStatement` | Self-reported medication | `status`, `medication[x]`, `subject` | `patient`, `status` |
| `Condition` | Diagnosis / problem | `code`, `subject` | `patient`, `code`, `clinical-status` |
| `Consent` | Consent agreement | `status`, `scope`, `category`, `policyRule` | `patient`, `status` |
| `DiagnosticReport` | Report grouping Observations | `status`, `code` | `patient`, `code`, `date` |
| `Device` | Wearable / sensor | `status` | `patient`, `type` |

---

## FHIR R4 Spec Links

- [Observation](https://hl7.org/fhir/R4/observation.html)
- [Questionnaire](https://hl7.org/fhir/R4/questionnaire.html)
- [QuestionnaireResponse](https://hl7.org/fhir/R4/questionnaireresponse.html)
- [Task](https://hl7.org/fhir/R4/task.html)
- [CarePlan](https://hl7.org/fhir/R4/careplan.html)
- [Patient](https://hl7.org/fhir/R4/patient.html)
- [Condition](https://hl7.org/fhir/R4/condition.html)
- [MedicationRequest](https://hl7.org/fhir/R4/medicationrequest.html)
- [Consent](https://hl7.org/fhir/R4/consent.html)
- [DiagnosticReport](https://hl7.org/fhir/R4/diagnosticreport.html)
- [US Core IG](https://www.hl7.org/fhir/us/core/)

### Terminology Lookup (use these to find codes — do not rely on memorised values)
- [LOINC Search](https://loinc.org/search/)
- [SNOMED CT Browser](https://browser.ihtsdotools.org/)
- [RxNorm Browser (RxNav)](https://mor.nlm.nih.gov/RxNav/)
- [ICD-10-CM API](https://clinicaltables.nlm.nih.gov/apidoc/icd10cm/v3/doc.html)
- [NCI Thesaurus Browser](https://ncit.nci.nih.gov/ncitbrowser/)
- [UCUM](https://ucum.org/ucum)
- [HL7 Observation Category CodeSystem](https://terminology.hl7.org/CodeSystem-observation-category.html)