# 构建医疗健康应用

> 教程：将 Anpheros 用作医疗健康应用的医疗数据后端 — 患者、测量值、病情、药物、文档、实验室检查、同意书、Webhook 和 SDK。

Source: https://developers.anpheros.com/zh/guides/build-a-healthcare-app

本教程展示了医疗健康或医疗应用如何使用 Anpheros Platform 作为其医疗数据后端：存储患者记录、如何读写这些记录、如何连接其他系统以及患者如何保持控制权。下方每个调用都是公共 API 的一部分（[参考](https://developers.anpheros.com/docs)）。

## 您正在构建的内容

典型的面向患者的应用——例如慢性病追踪器、家庭健康应用、远程监控伴侣——需要：

1.  为每位患者维护一份记录：包括测量值、病情、用药、文档；
2.  以列表和时间轴的形式展示该记录；
3.  接受来自其他来源（设备、实验室、诊所）的数据；
4.  在获得患者同意的情况下，共享记录的某些部分；
5.  在发生变化时做出响应。

通过 Anpheros，您的应用可以保留自己的用户、界面和业务逻辑，并将医疗记录委托给平台：

```
Mobile / web app ──► your backend ──► Anpheros Platform API ──► FHIR R4 record of each patient
                         ▲                                              │
                         └──────────── signed webhooks ◄────────────────┘
```

您的后端持有 API 密钥；应用与您的后端通信。（代表已有 Anpheros 记录的患者而运行的应用则使用 OAuth——请参阅第 7 步。）

## 1. 获取沙盒密钥

沙盒是自助服务：在仪表板 (`https://platform.anpheros.com/dashboard/`) 上使用 Google 登录，然后按 *获取沙盒密钥*。沙盒密钥以 `sk_test_` 开头，只能访问沙盒数据库，您的项目在该数据库中已拥有 30 名合成患者的副本。

```bash
export BASE=https://platform.anpheros.com
export KEY=sk_test_…
curl $BASE/v1/patients -H "Authorization: Bearer $KEY"
```

## 2. 创建患者

您的应用中的每个用户都会获得一个由您的项目拥有的患者记录。

```bash
curl -X POST $BASE/v1/patients -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{"given": "Elena", "family": "Ionescu", "birth_date": "1985-09-03", "gender": "female"}'
```

响应包含患者 `id`（您为该个人指定的标识符——其他项目会看到不同的标识符）及其 `fhir` 引用。

## 3. 写入测量值、诊断和药物

使用 `author_type`: `patient`, `practitioner`, `device`, `import` 或 `ai` 来声明数据的来源。如果省略，平台将记录 `import`，绝不会默认记录 `patient`。

```bash
# a blood-pressure reading from a connected device (LOINC panel with two components)
curl -X POST $BASE/v1/patients/$PID/observations -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -H "Idempotency-Key: $(uuidgen)" -d '{
  "code": "85354-9", "display": "Blood pressure panel", "category": "vital-signs",
  "effective_at": "2026-09-28T08:00:00Z", "author_type": "device",
  "components": [
    {"code": "8480-6", "display": "Systolic", "value": 128, "unit": "mm[Hg]"},
    {"code": "8462-4", "display": "Diastolic", "value": 82, "unit": "mm[Hg]"}
  ]}'

# a diagnosis (ICD-10 by default)
curl -X POST $BASE/v1/patients/$PID/conditions -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -d '{"code": "I10", "display": "Essential hypertension", "onset": "2024-03-01", "author_type": "practitioner"}'

# a medication (ATC by default)
curl -X POST $BASE/v1/patients/$PID/medications -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -d '{"display": "Amlodipine 5 mg", "code": "C08CA01", "dosage": "1 tablet in the morning", "start": "2024-03-01", "author_type": "patient"}'
```

Observation 类别：`vital-signs`, `laboratory`, `symptom`, `activity`, `survey`, `exam`, `imaging`, `social-history`。每次写入都会存储为 FHIR 资源，并自动获得一个 `Provenance` 条目。

## 4. 存储文档

```bash
# create the document, then upload the bytes
curl -X POST $BASE/v1/patients/$PID/documents -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -d '{"title": "Blood tests 2026-09-14", "kind": "lab_report", "content_type": "application/pdf", "date": "2026-09-14"}'
curl -X PUT $BASE/v1/documents/$DOC/content -H "Authorization: Bearer $KEY" -H 'content-type: application/pdf' --data-binary @report.pdf
```

上传后，原始文档不可变；您可以从中提取的值可以指向它，使用 `derived_from`。

## 5. 读回记录

```bash
curl "$BASE/v1/patients/$PID/observations?category=vital-signs&limit=20" -H "Authorization: Bearer $KEY"
curl "$BASE/v1/patients/$PID/medications?status=active" -H "Authorization: Bearer $KEY"
curl "$BASE/v1/patients/$PID/timeline?from=2026-06-01" -H "Authorization: Bearer $KEY"   # everything, chronologically
```

当您需要完整的 FHIR 模型时，相同的数据可在 `/fhir/R4` 处获取，使用相同的 ID（[FHIR R4 API](https://developers.anpheros.com/zh/guides/fhir)）。

## 6. 连接实验室和设备

- **实验室报告：** `POST /v1/patients/{id}/labs/import`（支持 CSV、HL7 v2 ORU^R01 或 JSON 格式）可将整个报告转换为带有 LOINC 编码的实验室 Observation（参见 [Lab connector](https://developers.anpheros.com/zh/guides/lab-connector)）。
- **设备和可穿戴设备：** 写入 Observation，使用 `author_type: device` 和测量值的 LOINC 编码（心率、SpO₂、步数、睡眠时长等可在 [FHIR code systems](https://developers.anpheros.com/zh/guides/fhir-code-systems) 中找到）。

## 7. 访问患者已有的记录 (OAuth)

如果该用户已经在 Anpheros 中拥有记录（例如通过 Anpheros Daily），您的应用可以请求访问权限，而不是创建新患者：注册一个应用，将用户引导至您所需的 scope 的同意页面，用 code 交换 token，然后使用 access token 调用 API。用户可以选择访问时长，并可以随时撤销访问权限。详情请参阅：[Authentication and OAuth](https://developers.anpheros.com/zh/guides/authentication)。

## 8. 使用 Webhook 响应变更

```bash
curl -X POST $BASE/v1/webhooks -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
     -d '{"url": "https://your.app/anpheros/hook", "events": ["resource.created", "consent.revoked"]}'
```

验证每次推送的 `Anpheros-Signature` 头部 ([Webhooks](https://developers.anpheros.com/zh/guides/webhooks))。

## 9. 使用 SDK

相同的流程，使用 TypeScript 实现：

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

const anpheros = new Anpheros({ auth: apiKey(process.env.ANPHEROS_KEY!) });
const { data: patients } = await anpheros.patients.list();
const vitals = await anpheros.observations.list(patients[0].id, { category: 'vital-signs', limit: 20 });
```

同样形状的 Dart / Flutter 客户端可在 `anpheros_sdk` ([SDKs](https://developers.anpheros.com/zh/guides/sdks)) 中找到。

## 上线生产环境之前

- 生产环境密钥 (`sk_live_`) 会发放给已验证的组织，并签署数据处理协议。
- 请阅读 [安全、隐私和数据驻留](https://developers.anpheros.com/zh/guides/security) 页面以及 [限制](https://developers.anpheros.com/zh/guides/limits)。
- 根据错误类型处理错误，并在联系支持时引用 `Anpheros-Request-Id` 标头 ([错误](https://developers.anpheros.com/zh/guides/errors))。

## 相关资源

- [如何使用 TypeScript 构建医疗保健 API](https://developers.anpheros.com/zh/guides/healthcare-api-typescript)：使用 Express 的分步教程
- [如何使用 Flutter 构建医疗保健应用程序](https://developers.anpheros.com/guides/healthcare-app-flutter)：使用 Dart SDK 的分步教程
- [如何使用 FHIR 后端构建人工智能医疗保健应用程序](https://developers.anpheros.com/zh/guides/build-ai-healthcare-app)：TypeScript 分步教程
- [使用 Anpheros 进行开发](https://developers.anpheros.com/zh/guides/build-with-anpheros)
- [医疗应用程序后端和数据库](https://developers.anpheros.com/zh/guides/medical-app-backend)
- [医疗数据 API](https://developers.anpheros.com/zh/guides/medical-data-api)
- [医疗软件开发](https://developers.anpheros.com/zh/guides/healthcare-software)
- [如何使用 FHIR 构建个人健康记录 (PHR) 应用程序](https://developers.anpheros.com/zh/guides/personal-health-record-app)