Back to Details

health-data-model-planning

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- This source file is part of the Stanford Spezi open-source project. SPDX-FileCopyrightText: 2026 Stanford University and the project authors (see CONTRIBUTORS.md) SPDX-License-Identifier: MIT -->
<!-- 此源文件是斯坦福Spezi开源项目的一部分。 SPDX-FileCopyrightText: 2026 斯坦福大学及项目作者（详见CONTRIBUTORS.md） SPDX-License-Identifier: MIT -->

Health Data Model Planner

健康数据模型规划指南

Plan a health data model with a strong bias toward FHIR before committing to storage, code structures, or client-specific architecture.
在确定存储方案、代码结构或特定客户端架构之前，优先基于FHIR规划健康数据模型。

When to Use

适用场景

Use this skill when you need to:
  • define the core health concepts a product needs to represent
  • decide which entities, relationships, and lifecycle states matter
  • reason about interoperability requirements with FHIR as the default starting point for clinical data
  • prepare for later implementation in a mobile app, backend, analytics pipeline, or research workflow
当你需要完成以下工作时，可使用本指南：
  • 定义产品需要表示的核心健康概念
  • 确定关键的实体、关系和生命周期状态
  • 以FHIR为默认起点，分析临床数据的互操作性需求
  • 为后续在移动应用、后端系统、分析管道或研究工作流中的实施做准备

Working Style

工作原则

Start with the domain, but assume that clinically meaningful data will often benefit from a FHIR-oriented design unless there is a strong reason not to.
Clarify:
  1. what the product is trying to track or coordinate
  2. who creates, reads, updates, or interprets the data
  3. what must be longitudinal, auditable, shareable, or clinically meaningful
  4. what needs to be structured versus free-form
  5. which standards, institutions, or downstream systems matter
从业务领域出发，但除非有充分理由，否则临床相关数据应优先采用面向FHIR的设计。
需明确以下内容：
  1. 产品需要追踪或协调的对象
  2. 数据的创建、读取、更新或解读人员
  3. 哪些数据需要具备纵向性、可审计性、可共享性或临床意义
  4. 哪些数据需要结构化，哪些可以采用自由格式
  5. 相关的标准、机构或下游系统

Default Bias Toward FHIR

默认优先采用FHIR

In digital health, prefer asking "How would this map to FHIR?" early rather than treating interoperability as a late-stage add-on.
Default questions:
  • should this concept become a FHIR resource instead of a custom object
  • is there an existing FHIR pattern for this workflow
  • should values use established terminologies such as LOINC, SNOMED CT, or RxNorm
  • will this data eventually need to move between apps, research systems, backend services, or EHR-adjacent systems
It is fine to decide that some concepts remain app-internal, but make that an explicit choice.
在数字健康领域，应尽早思考“如何将此映射到FHIR？”，而非将互操作性视为后期附加功能。
默认思考问题：
  • 该概念是否应作为FHIR资源，而非自定义对象
  • 针对此工作流是否已有现成的FHIR模式
  • 是否应使用LOINC、SNOMED CT或RxNorm等已确立的术语集
  • 这些数据最终是否需要在应用、研究系统、后端服务或电子健康记录（EHR）相关系统之间流转
部分概念可保留为应用内部使用，但需做出明确选择。

Reuse Before Building

优先复用而非自建

Do not encourage teams to hand-roll FHIR models, parsers, or mapping infrastructure unless there is a compelling gap.
When implementation starts, generally recommend reusing mature ecosystem libraries, for example:
If the user is already working in a concrete stack, recommend modeling choices that fit those existing libraries instead of inventing parallel abstractions.
除非存在明显的技术空白，否则不建议团队手动构建FHIR模型、解析器或映射基础设施。
当开始实施时，通常建议复用成熟的生态库，例如：
如果用户已在使用特定技术栈，建议选择适配现有库的建模方案，而非构建并行抽象层。

Planning Framework

规划框架

1. Core Entities

1. 核心实体

Identify the main concepts, such as:
  • person or participant
  • observation or measurement
  • questionnaire or assessment
  • response or result
  • task, intervention, or reminder
  • condition, medication, consent, or care-plan concept
For each entity, define:
  • purpose
  • required attributes
  • optional attributes
  • who creates or updates it
  • whether it changes over time
识别主要概念，例如：
  • 人员或参与者
  • 观察或测量结果
  • 问卷或评估
  • 响应或结果
  • 任务、干预或提醒
  • 病症、药物、知情同意或护理计划概念
针对每个实体，定义：
  • 用途
  • 必填属性
  • 可选属性
  • 创建或更新人员
  • 是否随时间变化

2. Relationships

2. 关系映射

Map how the entities relate, for example:
  • a person has many observations
  • a questionnaire has many questions
  • a response belongs to one questionnaire instance
  • a task may trigger a response or observation
Note:
  • one-to-one versus one-to-many relationships
  • whether history must be preserved
  • what should be versioned
梳理实体间的关系，例如：
  • 一个人员对应多个观察结果
  • 一个问卷包含多个问题
  • 一个响应属于某个问卷实例
  • 一个任务可能触发响应或观察
注意事项：
  • 一对一与一对多关系的区别
  • 是否需要保留历史记录
  • 哪些内容需要版本控制

3. Lifecycle and State

3. 生命周期与状态

For important entities, define lifecycle states such as:
  • draft
  • active
  • completed
  • cancelled
  • archived
Also define:
  • what events cause state changes
  • whether edits overwrite history or create new records
  • what should remain immutable
为重要实体定义生命周期状态，例如：
  • 草稿
  • 活跃
  • 已完成
  • 已取消
  • 已归档
同时定义：
  • 触发状态变更的事件
  • 编辑操作是覆盖历史记录还是创建新记录
  • 哪些内容应保持不可变

4. Interoperability

4. 互操作性

Use FHIR as the default lens for clinically relevant data, and only move away from it when the extra complexity is not justified.
Assess:
  • whether the product needs to exchange data with clinical systems
  • whether FHIR is required now, likely soon, or only later
  • whether standard terminologies such as LOINC, SNOMED CT, or RxNorm are needed
  • which concepts are internal-only versus externally shareable
When possible, push the user toward:
  • standard FHIR resources over custom schemas
  • standard FHIR fields over custom extensions
  • standard terminologies over app-specific code strings
  • explicit mapping notes for any intentionally non-FHIR concepts
对于临床相关数据，默认以FHIR为视角，仅当额外复杂性无必要时才考虑偏离。
评估以下内容：
  • 产品是否需要与临床系统交换数据
  • FHIR是当前需要、近期可能需要还是仅远期需要
  • 是否需要LOINC、SNOMED CT或RxNorm等标准术语集
  • 哪些概念仅限内部使用，哪些可对外共享
尽可能引导用户：
  • 使用标准FHIR资源而非自定义 schema
  • 使用标准FHIR字段而非自定义扩展
  • 使用标准术语集而非应用特定的代码字符串
  • 为所有有意偏离FHIR的概念添加明确的映射说明

5. Governance and Quality

5. 治理与质量

Review:
  • data provenance
  • validation rules
  • units and value ranges
  • duplicate handling
  • retention and deletion expectations
  • privacy sensitivity of each data category
审查以下内容：
  • 数据来源
  • 验证规则
  • 单位与值范围
  • 重复数据处理
  • 数据保留与删除预期
  • 各数据类别的隐私敏感度

Deliverable Format

交付物格式

Produce a concise data model planning brief with:
  • core entities
  • key attributes
  • entity relationships
  • lifecycle states
  • FHIR and terminology recommendations
  • library reuse recommendations for the target stack
  • governance and data-quality notes
  • unresolved modeling questions
Save the brief as 
docs/planning/data-model-brief.md
in the project repository.
生成简洁的数据模型规划简报，包含以下内容：
  • 核心实体
  • 关键属性
  • 实体关系
  • 生命周期状态
  • FHIR与术语集建议
  • 针对目标技术栈的库复用建议
  • 治理与数据质量说明
  • 未解决的建模问题
将简报保存至项目仓库的
docs/planning/data-model-brief.md
路径下。

Guardrails

约束规则

  • Do not assume a specific database, TypeScript model, or mobile framework.
  • Favor FHIR for clinically meaningful or shareable health data unless the user gives a good reason not to.
  • Keep the distinction clear between business concepts and implementation details.
  • Flag where clinical input is needed to validate terminology or meaning.
  • Recommend existing libraries before suggesting custom FHIR infrastructure.
  • 不要预设特定的数据库、TypeScript模型或移动框架
  • 除非用户给出充分理由，否则临床相关或可共享的健康数据优先采用FHIR
  • 明确区分业务概念与实现细节
  • 标记需要临床输入以验证术语或含义的环节
  • 优先推荐现有库，而非建议自定义FHIR基础设施

Checklist

检查清单

  • Core entities identified
  • Required and optional attributes outlined
  • Relationships mapped
  • Lifecycle states defined
  • FHIR resource fit assessed
  • Terminology needs assessed
  • Reusable libraries identified for the target stack
  • Governance and validation concerns captured
  • Open questions documented
  • 已识别核心实体
  • 已梳理必填与可选属性
  • 已映射实体关系
  • 已定义生命周期状态
  • 已评估FHIR资源适配性
  • 已评估术语集需求
  • 已识别目标技术栈可复用的库
  • 已记录治理与验证关注点
  • 已记录未解决的问题