# 건강 앱을 위한 환자 동의 플랫폼

> 데이터 계층에 내장된 동의: OAuth 2.1 및 SMART 범위, 사용자가 선택한 목적 및 만료일, 사용자가 볼 수 있는 액세스 로그, 다음 요청 시 철회, 그리고 앱이 여전히 소유하고 있는 것.

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

**환자 동의 플랫폼을 통해 개인은 어떤 애플리케이션이 자신의 건강 기록을 어떤 목적으로, 얼마나 오랫동안 읽거나 변경할 수 있는지 결정할 수 있으며, 언제든지 해당 액세스를 확인하고 철회할 수 있습니다.** Anpheros는 동의를 데이터 계층에 내장합니다. 애플리케이션은 개인이 Anpheros 동의 페이지에서 승인한 허가를 통해서만 환자의 FHIR R4 레코드에 접근할 수 있으며, 해당 허가 하의 모든 읽기 및 쓰기는 개인이 볼 수 있도록 기록되고, 철회는 다음 요청 시 효력을 발휘합니다. 이 페이지에서는 해당 기능이 어떻게 작동하는지, 애플리케이션이 무엇을 해야 하는지, 그리고 무엇을 직접 구축할 필요가 없는지를 보여줍니다.

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

## 데이터 계층에 동의가 필요한 이유

대부분의 건강 앱은 자체 데이터베이스에 체크박스로 동의를 기록하고 애플리케이션 코드에서 이를 강제합니다. 이는 두 번째 앱, 클리닉 통합 또는 AI 기능이 동일한 데이터가 필요한 시점까지 작동합니다. 각 앱은 규칙을 다시 구현해야 하며, 해당 사용자는 누가 접근 권한을 가지고 있는지 볼 수 있는 단일 장소가 없습니다. 기록을 저장하는 플랫폼이 동의를 강제하면 모든 클라이언트는 동일한 규칙을 적용받고, 사용자는 검토할 수 있는 애플리케이션 목록을 하나만 갖게 됩니다.

| | 앱 내 플래그로서의 동의 | 데이터 계층(Anpheros)에서의 동의 |
|---|---|---|
| 강제 적용 위치 | 각 애플리케이션의 코드 | 모든 API 요청 시, 플랫폼에서 |
| 접근 범위 | 앱이 읽기로 결정한 모든 것 | 부여된 리소스 유형 및 카테고리만 |
| 만료 | 거의 구현되지 않음 | 사용자가 선택: 30일, 90일, 180일 또는 365일 |
| 사용자가 보는 것 | 앱에 따라 다름 | 모든 애플리케이션, 해당 범위 및 만료일, 접근 로그 |
| 철회 | 수동으로 전파해야 함 | 다음 요청 실패; 갱신 토큰 작동 중지 |

## 환자가 제어하는 항목

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

## 애플리케이션이 동의를 요청하는 방법

Anpheros는 PKCE를 사용하는 OAuth 2.1 및 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` 웹훅을 구독하십시오. 이 웹훅은 `grant_id`, 표시되는 환자 ID, 범위 및 `revoked_at`을 전달합니다.

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

## Anpheros의 기능 범위

- 마케팅 또는 연구 참여와 같이 데이터 액세스 범위를 벗어나는 목적에 대한 동의를 수집하지 않습니다.
- 법적 근거를 결정하지 않습니다. 액세스에 대한 동의는 하나의 제어 수단이며, 개인정보 처리 방침, 계약 및 처리 기록은 귀하의 책임입니다.
- 프로젝트 자체의 API 키는 승인 없이도 해당 프로젝트에서 생성한 환자를 볼 수 있습니다. 다른 애플리케이션의 액세스는 동의로 제어됩니다.

## 자주 묻는 질문

### 환자 동의 플랫폼이란 무엇인가요?
개인이 자신의 건강 데이터에 접근하도록 허용하는 애플리케이션을 기록하고, 모든 요청에서 해당 선택을 강제하며, 누가 무엇에 접근했는지 보여주고, 접근 권한을 철회할 수 있도록 하는 소프트웨어입니다. Anpheros에서는 동의가 별도의 서비스가 아닌 FHIR R4 레코드 자체의 일부입니다.

### Anpheros는 환자 동의에 어떤 표준을 사용하나요?
권한 부여 흐름에는 OAuth 2.1 with PKCE를 사용하고, 애플리케이션이 읽거나 쓸 수 있는 내용에는 SMART on FHIR v2 환자 범위(`patient/<Type>.<cruds>`, 선택적으로 `?category=` 필터 포함)를 사용합니다. OpenID Connect는 `openid fhirUser`을 요청할 때 ID 토큰을 추가합니다.

### 환자가 자신의 데이터 중 일부에만 접근을 제한할 수 있나요?
예. 접근은 부여된 범위의 리소스 유형 및 범주로 제한됩니다. 예를 들어, 실험실 관찰(laboratory Observations)만 해당됩니다. 그 외의 모든 것은 오류를 반환합니다.

### 동의는 얼마나 오래 지속되나요?
동의 페이지에서 30일, 90일, 180일 또는 365일을 선택합니다. 그 후에는 부여가 만료되며 애플리케이션은 다시 요청해야 합니다.

### 환자가 애플리케이션이 접근 권한을 사용하여 무엇을 했는지 볼 수 있나요?
예. 접근 권한이 있는 모든 애플리케이션, 해당 범위 및 만료일, 그리고 각 애플리케이션이 읽거나 쓴 내용을 나열하는 접근 로그를 볼 수 있습니다.

### 동의가 철회되면 어떻게 되나요?
해당 액세스 토큰을 사용한 다음 요청이 실패하고, 새로고침 토큰을 사용하여 새 토큰을 얻을 수 없으며, 서버가 구독한 경우 `consent.revoked` 웹훅을 수신합니다.

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

## 관련 정보

- [동의 및 액세스 모델](https://developers.anpheros.com/ko/guides/consent): 전체 규칙
- [인증 및 OAuth](https://developers.anpheros.com/ko/guides/authentication): 토큰, 범위 및 코드 교환
- [SMART on FHIR을 사용한 환자 동의 구현 방법](https://developers.anpheros.com/ko/guides/smart-on-fhir-backend)
- [웹훅](https://developers.anpheros.com/ko/guides/webhooks): `consent.granted` 및 `consent.revoked`
- [의료 데이터 출처 설명](https://developers.anpheros.com/ko/guides/medical-data-provenance)
- [종단 환자 데이터 API](https://developers.anpheros.com/ko/guides/longitudinal-patient-data-api)