# 健康应用的患者同意平台

> 数据层内置的同意机制：由用户选择的 OAuth 2.1 和 SMART 范围、目的和有效期，用户可查看的访问日志，下次请求时即可撤销，以及您的应用仍拥有的权限。

Source: https://developers.anpheros.com/zh/guides/patient-consent-platform

**患者同意平台允许用户决定哪些应用程序可以读取或修改其健康记录，出于何种目的以及持续多长时间，并允许用户随时查看和撤销该访问权限。** Anpheros 将同意机制内置于数据层：应用程序只能通过用户在 Anpheros 同意页面上批准的授权来访问患者的 FHIR R4 记录，每次读取和写入操作都会在用户可查看的日志中记录，并且撤销将在下次请求时生效。本页面将展示其工作原理、您的应用程序需要做什么以及无需构建的内容。

<!-- visual:consent-flow -->

## 为什么同意书应置于数据层

大多数健康应用程序会将同意书记录在其自己的数据库中，然后通过应用程序代码强制执行。当第二个应用程序、诊所集成或 AI 功能需要相同数据时，这种情况就会失效：每个应用程序都必须重新实现规则，而用户无法在一个地方查看谁拥有访问权限。当存储记录的平台也强制执行同意书时，每个客户端都遵循相同的规则，用户可以获得一个应用程序列表进行审查。

| | 同意书作为应用程序中的标志 | 数据层中的同意书 (Anpheros) |
|---|---|---|
| 执行位置 | 在每个应用程序的代码中 | 在每次 API 请求时，由平台执行 |
| 访问范围 | 应用程序决定读取的内容 | 仅限于授予的资源类型和类别 |
| 过期 | 很少实现 | 由用户选择：30、90、180 或 365 天 |
| 用户所见 | 取决于应用程序 | 每个应用程序、其范围和过期时间，以及访问日志 |
| 撤销 | 必须手动传播 | 下次请求失败；刷新令牌停止工作 |

## 患者控制的内容

<!-- visual:consent-controls -->

## 您的应用程序如何请求同意

Anpheros 使用 OAuth 2.1（支持 PKCE）和 SMART on FHIR v2 范围。您的应用程序会将用户引导至同意页面，并附带其所需的范围和可选的目的；批准后，它将收到一个访问令牌（有效期 30 分钟）和一个轮换的刷新令牌（有效期 30 天），该令牌仅针对一个患者。

```ts
import { OAuthFlow, generatePkce } from '@anpheros/sdk';

const flow = new OAuthFlow({
  baseUrl: 'https://platform.anpheros.com',
  clientId: process.env.ANPHEROS_CLIENT_ID!,
  redirectUri: 'https://your.app/callback',
});
const pkce = await generatePkce();
const url = flow.authorizeUrl({
  scopes: ['patient/Observation.rs?category=laboratory', 'patient/Condition.rs', 'offline_access'],
  purpose: 'treatment',
  state: crypto.randomUUID(),
  pkce,
  lang: 'en',
});
// redirect the person to `url`; on the callback exchange the code (see the authentication guide)
```

诸如 `patient/Observation.rs?category=laboratory` 这样的范围限制了对实验室结果的读取；类别过滤器由服务器强制执行。超出授权范围的资源类型将返回 `403`；超出授权范围的患者将返回 `404`，因此无法探测 ID。

## 响应撤销

当用户结束授权时，使用该令牌的下一个请求将失败，刷新令牌也无法恢复访问。为了立即清理，请订阅 `consent.revoked`  webhook，它会携带 `grant_id`、您看到的患者 ID、范围以及 `revoked_at`。

```ts
await anpheros.webhooks.create('https://your.app/anpheros/hook', { events: ['consent.granted', 'consent.revoked'] });
```

## Anpheros 不做什么

- Anpheros 不会收集超出数据访问范围的同意，例如营销或研究参与。
- Anpheros 不会决定您的法律依据。访问同意是一项控制；您的隐私声明、合同和处理记录仍由您负责。
- 项目自身的 API 密钥可以查看该项目创建的患者，无需授权。同意管理其他应用程序的访问。

## 常见问题解答

### 什么是患者同意平台？
一种记录某人允许哪些应用程序访问其健康数据的软件，在每次请求时强制执行这些选择，向用户显示谁访问了什么，并允许他们撤销访问。在 Anpheros 中，同意是 FHIR R4 记录本身的一部分，而不是一个独立的服务。

### Anpheros 在患者同意方面使用哪些标准？
OAuth 2.1 with PKCE 用于授权流程，SMART on FHIR v2 patient scopes（`patient/<Type>.<cruds>` 带有可选的 `?category=` 过滤器）用于应用程序可以读取或写入的内容。OpenID Connect 在您请求 `openid fhirUser` 时添加一个 ID token。

### 患者能否限制只访问其部分数据？
可以。访问仅限于授予的 scopes 中的资源类型和类别，例如仅限实验室 Observations。其他所有内容都会返回错误。

### 同意有效期是多久？
用户在同意页面上选择 30、90、180 或 365 天。之后，授权将过期，应用程序必须重新请求。

### 患者能否看到应用程序如何使用访问权限？
可以。用户可以看到每个具有访问权限的应用程序、其 scopes 和到期时间，以及一个访问日志，列出每个应用程序读取或写入的内容。

### 同意被撤销时会发生什么？
使用该访问令牌的下一个请求将失败，刷新令牌将无法用于获取新的令牌，并且如果您的服务器订阅了，将收到一个 `consent.revoked` webhook。

<!-- visual:cta-consent -->

## 相关

- [同意和访问模型](https://developers.anpheros.com/zh/guides/consent)：完整规则
- [身份验证和 OAuth](https://developers.anpheros.com/zh/guides/authentication)：令牌、范围和代码交换
- [如何使用 SMART on FHIR 实现患者同意](https://developers.anpheros.com/zh/guides/smart-on-fhir-backend)
- [Webhooks](https://developers.anpheros.com/zh/guides/webhooks)：`consent.granted` 和 `consent.revoked`
- [医疗数据溯源详解](https://developers.anpheros.com/zh/guides/medical-data-provenance)
- [纵向患者数据 API](https://developers.anpheros.com/zh/guides/longitudinal-patient-data-api)