# 纵向患者数据 API

> 一名患者随时间推移来自诊所、实验室、应用程序和设备的病史：纵向记录所需的内容，以及四种读取方式——时间线、$everything、IPS 和 AI 上下文。

Source: https://developers.anpheros.com/zh/guides/longitudinal-patient-data-api

**纵向患者数据 API 返回一名患者随时间推移的健康历史记录——来自每个来源的诊断、药物、实验室结果、生命体征、疫苗接种和就诊记录——作为一个有序记录，而不是每个提供商的独立文档。** Anpheros 将该历史记录保留为每个患者一个单一的 HL7 FHIR R4 记录，由诊所、实验室、应用程序和设备编写，并保留每个版本和每个作者。开发人员可以通过四种方式读取它：按时间顺序排列的时间线、包含 `Patient/$everything` 的完整 FHIR 记录、国际患者摘要，或用于 AI 模型的紧凑上下文。

<!-- visual:longitudinal-sources -->

## “纵向”记录的要求

结果列表尚不能构成纵向记录。为了让应用程序能够信任跨越多年和多个提供者的历史记录，每个条目都必须包含：

| 要求 | 重要性 | Anpheros 如何存储 |
|---|---|---|
| 编码含义 | 来自不同实验室的值必须具有可比性 | LOINC 用于结果，ICD-10 用于病症，ATC 用于药物 |
| 临床日期 | 按事件发生时间排序，而非上传时间 | 每个资源上的 `effective`、`onset`、`occurrence` 日期 |
| 作者 | 医生的诊断和患者的笔记不等同 | 每次写入时都记录来源信息：作者类型、个人、组织、源系统 |
| 每个版本 | 更正不应抹去之前已知的信息 | 每个资源上的版本历史记录 (`_history`) |
| 同意 | 除非个人同意，否则其他应用程序看不到历史记录 | 带有范围、过期时间和访问日志的 OAuth 授权 |

## 一个记录，多个写入者

<!-- visual:longitudinal-timeline -->

## 四种读取历史记录的方式

| 需求 | 端点 | 获取内容 |
|---|---|---|
| 用于屏幕的按时间顺序排列的动态信息流 | `GET /v1/patients/{id}/timeline` | 八种类型的条目（observation, condition, medication, document, encounter, appointment, immunization, episode），包含日期、标题、摘要和 FHIR 引用；可通过 `from`、`to`、`types` 进行过滤 |
| 以 FHIR 格式的完整记录 | `GET /fhir/R4/Patient/{id}/$everything` | 一个 searchset Bundle；支持 `_since`、`_type`、`_count` 和 `_offset` |
| 可共享的临床摘要 | `GET /fhir/R4/Patient/{id}/$summary` | 一个 International Patient Summary (IPS) 文档 |
| AI 模型输入 | `POST /v1/context` | 包含在 token 配额内的部分，每个事实都标有其来源 |

使用 TypeScript SDK 的时间线：

```ts
import { Anpheros, apiKey } from '@anpheros/sdk';

const anpheros = new Anpheros({ auth: apiKey(process.env.ANPHEROS_KEY!) });   // a sandbox key, sk_test_…
const { data: patients } = await anpheros.patients.list();
const page = await anpheros.timeline.list(patients[0].id, {
  from: '2025-01-01',
  types: 'condition,medication,observation',
  limit: 50,
});
for (const item of page.data) console.log(item.date, item.type, item.title);
```

以及相同的记录（FHIR 格式），仅限于自某个日期以来发生更改的内容：

```bash
curl -H "Authorization: Bearer $ANPHEROS_KEY" \
  "https://platform.anpheros.com/fhir/R4/Patient/$PATIENT/\$everything?_since=2026-01-01&_type=Observation,Condition"
```

## 保持您的副本同步

如果您的应用程序维护自己的历史记录视图，请订阅 `resource.created`、`resource.updated` 和 `resource.deleted` Webhook。当另一个项目写入您有权访问的记录时，它们也会触发，并附带 `data.external: true` 和写入者信息，位于 `data.source` 中，这样来自其他诊所的数据就能在不轮询的情况下到达您。

## 值得了解的限制

- 记录保存了写入其中的内容。Anpheros 不会自行从医院或国家网络获取历史记录；诊所、实验室、应用程序和个人会写入记录。
- 存储了 26 种 FHIR R4 资源类型。账单资源（如 Claim 和 ExplanationOfBenefit）不存储。
- 其他应用程序仅在获得个人同意后才能读取其历史记录；项目的自有密钥可以查看其创建的患者。

## 常见问题解答

### 什么是纵向患者数据？
一个人在不同护理地点随时间收集的健康信息——诊断、药物、结果、生命体征、疫苗接种和就诊记录——得以保存，以便将其作为连续的历史记录进行阅读。

### 哪个 API 可以提供患者记录的按时间顺序的视图？
在 Anpheros 中，`GET /v1/patients/{id}/timeline` 会按日期顺序返回八种资源类型的数据，并支持分页以及日期和类型过滤器。如需完整的 FHIR 数据，请使用 `Patient/$everything`。

### 历史记录是否以标准格式存储？
是的。每个条目都是 HL7 FHIR R4 资源，包含标准代码（LOINC、ICD-10、ATC、CVX、UCUM），摘要是国际患者摘要 (International Patient Summary)。

### 我如何知道每条记录是谁编写的？
每次写入都会创建一个 Provenance 资源，其中包含作者类型（患者、医护人员、设备、导入或 AI）、人员、组织和源系统。

### 我可以使用真实的纵向数据进行测试吗？
是的。每个沙盒项目都包含 30 名合成患者，他们拥有大约六个月的病症、药物、实验室结果和生命体征数据。

<!-- visual:cta-longitudinal -->

## 相关资源

- [使用 FHIR 构建的个人健康记录 (PHR) 应用](https://developers.anpheros.com/zh/guides/personal-health-record-app)：真实应用中的时间线
- [医疗数据溯源详解](https://developers.anpheros.com/zh/guides/medical-data-provenance)
- [健康应用的患者同意平台](https://developers.anpheros.com/zh/guides/patient-consent-platform)
- [如何使用 FHIR R4 存储医疗记录](https://developers.anpheros.com/zh/guides/store-medical-records-fhir)
- [AI 代理与医疗数据](https://developers.anpheros.com/zh/guides/ai-agents-medical-data)：上下文端点
- [Webhooks](https://developers.anpheros.com/zh/guides/webhooks)