# 医疗应用架构

> 图表和数据流：患者到应用到 Anpheros API 到 FHIR 记录和外部服务，以及 AI 代理到上下文 API 到授权数据。

Source: https://developers.anpheros.com/zh/guides/architecture

Anpheros 是您的应用程序（或 AI 代理）与患者记录之间的医疗数据层。您的应用程序保留其自己的用户界面和业务逻辑；医疗记录、同意、来源和审计信息存储在 Anpheros 中，并通过一个 API 进行访问。

```
  Your application, backend or AI agent
  (mobile app, web app, clinic system, lab system, LLM-based assistant)
                        │  HTTPS · API key (sk_test_ / sk_live_) or OAuth token (at_…)
                        ▼
  Anpheros Platform API
  ├─ /v1        simplified REST: patients, observations, conditions, medications,
  │             documents, timeline, provenance, context, labs, webhooks
  ├─ /fhir/R4   strict FHIR R4: 26 resource types, search, history, transactions,
  │             $everything, $summary (IPS), $validate
  └─ /oauth     OAuth 2.1 + PKCE, SMART on FHIR, OpenID Connect
                        │  every request: project isolation · scopes · rate limits
                        ▼
  One FHIR R4 record per patient
  ├─ versions of every resource (history)   ├─ Provenance for every write
  ├─ Consent resources for every grant      └─ access log visible to the patient
                        │
                        ▼
  Events out: signed webhooks to your server (ids only, never clinical content)
```

## 患者视角：从个人到外部服务

```
Patient
   ↓   uses an app, chooses what to share, sees every access
Healthcare application          Anpheros Daily, or your own app
   ↓   REST v1 / FHIR R4 over HTTPS, API key or OAuth token
Anpheros API
   ↓   isolation, scopes, idempotency, provenance
FHIR medical data               the patient's record: 26 resource types, every version kept
   ↓   only what the patient allowed, only for as long as allowed
External healthcare services    laboratories (lab import), clinics (directory, acting-as),
                                other apps (OAuth / SMART), your backend (webhooks)
```

## AI 视图：从代理到授权数据

```
AI agent or LLM application     runs the model you choose — hosted or local
   ↓   POST /v1/context  {patient, task, question, budget_tokens}
Medical context API             plans which parts of the record matter, fits them into the budget,
   ↓                            labels every item with author type and source, records a manifest
Authorised medical data         only records the project created or the patient granted;
                                the read appears in the patient's access log
```

模型永远不会接收凭证，也不会自行调用 Anpheros；您的应用程序请求上下文并决定发送什么给模型。两个完整的 API 调用示例：[AI 医疗保健应用程序](https://developers.anpheros.com/zh/guides/ai-healthcare) 中的 AI 医疗保健应用程序，以及[AI 代理和医疗数据](https://developers.anpheros.com/zh/guides/ai-agents-medical-data) 中的已授权代理。详细信息：[AI 代理和医疗数据](https://developers.anpheros.com/zh/guides/ai-agents-medical-data)，[LLM 应用程序和医疗数据](https://developers.anpheros.com/zh/guides/llm-healthcare-data)。

## 记录

每位患者都有一份由 FHIR R4 资源组成的记录：`Observation` 用于生命体征、实验室结果、症状和日常活动摘要，`Condition`、`EpisodeOfCare`、`MedicationStatement`、`MedicationAdministration`、`DocumentReference`、`Immunization`、`AllergyIntolerance` 等——总共 26 种类型，可在 CapabilityStatement (`GET /fhir/R4/metadata`) 中实时查看。无需学习专有模式：REST API 是同一资源的简化视图，具有相同的 ID。

不会有任何内容被静默覆盖。每次更新都会创建一个新版本 (`/fhir/R4/{type}/{id}/_history`)，并且每个版本都会记录编写它的项目以及代表其编写的组织。

## 两种接入方式

| | API 密钥 | OAuth 访问令牌 |
|---|---|---|
| 外观 | `sk_test_…` / `sk_live_…` | `at_…` |
| 使用方 | 您的服务器 | 代表一位患者的应用 |
| 可见范围 | 您的项目创建的患者 | 患者授权范围内的某一位患者 |
| 典型用途 | 您自己的应用后端、实验室系统、诊所集成 | 第三方应用或 AI 助手访问患者已有的记录 |

项目永远无法访问其他项目的患者，除非患者授予访问权限。每个项目都会为同一个人获得自己的标识符（成对 ID），因此无法跨应用程序关联 ID，您够不到的记录会返回 `404`，而不是 `403`。

## 两个环境

沙盒（sandbox）和生产（production）是独立的数据库。沙盒密钥（`sk_test_`）在物理上无法访问真实患者；每个沙盒项目都会获得 30 名合成患者的副本，可以自由修改和重置。生产密钥（`sk_live_`）颁发给经过验证的组织。

## 数据流

**您的应用写入** `POST /v1/patients/{id}/observations`，并使用 `Idempotency-Key`。平台会存储一个 FHIR `Observation`，写入一个 `Provenance`（作者类型：patient、practitioner、device、import 或 ai），记录访问日志，并向订阅的端点发送一个 `resource.created` webhook。

**另一个应用在获得同意后读取**。患者在托管的同意页面（`/oauth/authorize`）上批准，选择记录和时长（30-365 天）。该应用会用代码交换令牌，并且只读取范围（scopes）允许的内容。患者可以看到该应用、其范围以及其访问日志中的每一次读取，并可以随时撤销同意。

**实验室交付结果**。`POST /v1/patients/{id}/labs/import`，提供 CSV、HL7 v2 ORU^R01 或 JSON 报告；每项结果都会成为一个实验室 `Observation`，并在已知时包含 LOINC 代码，重新发送相同的报告是安全的。

**AI 模型需要上下文**。`POST /v1/context` 会返回与任务相关的记录部分，在令牌预算内，每个项目都标有其来源；调用会使用 manifest id 记录。模型本身在您选择的任何地方运行。

## Anpheros 与自行构建的对比

| 关注点 | 自行构建 | 使用 Anpheros |
|---|---|---|
| 医学数据模型 | 为每种记录类型设计表 | FHIR R4 资源，26 种类型 |
| 互操作性 | 自定义导出格式 | FHIR R4，International Patient Summary，SMART on FHIR |
| 授权 | 构建授予、范围、过期和撤销逻辑 | OAuth 2.1 授予镜像为 FHIR `Consent` |
| 审计 | 构建日志记录和向患者展示日志的方式 | 每次读写都会被记录并对患者可见 |
| 实验室集成 | 解析每个实验室的格式 | CSV，HL7 v2 ORU 和 JSON 导入 |
| AI 上下文 | 编写检索和摘要代码 | 带有 token 配额和来源标签的上下文 API |

## 相关资源

- [什么是 Anpheros？](https://developers.anpheros.com/zh/guides/what-is-anpheros)
- [医疗软件开发](https://developers.anpheros.com/zh/guides/healthcare-software)
- [医疗应用后端与数据库](https://developers.anpheros.com/zh/guides/medical-app-backend)
- [构建医疗应用](https://developers.anpheros.com/zh/guides/build-a-healthcare-app)
- [同意与访问模型](https://developers.anpheros.com/zh/guides/consent)
- [安全、隐私与数据驻留](https://developers.anpheros.com/zh/guides/security)