기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# `$member-add` HealthLake에 대한 작업
<a name="reference-fhir-operations-member-add"></a>

FHIR `$member-add` 작업은 그룹 리소스, 특히 멤버 속성 목록에 멤버(환자)를 추가합니다. 이 작업은 DaVinci 멤버 속성 구현 가이드의 일부이며 멤버 속성을 관리하기 위한 조정 프로세스를 지원합니다.

## 작업 엔드포인트
<a name="member-add-endpoint"></a>

```
POST [base]/datastore/{datastoreId}/r4/Group/{groupId}/$member-add
Content-Type: application/json
```

## Parameters
<a name="member-add-parameters"></a>

작업은 다음 파라미터 조합이 있는 FHIR 파라미터 리소스를 수락합니다.

### 파라미터 옵션
<a name="member-add-parameter-options"></a>

다음 파라미터 조합 중 하나를 사용할 수 있습니다.

옵션 1: 멤버 ID \$1 공급자 NPI  
`memberId` \$1 `providerNpi`  
`memberId` \$1 `providerNpi` \$1 `attributionPeriod`

옵션 2: 환자 참조 \$1 공급자 참조  
`patientReference` \$1 `providerReference`  
`patientReference` \$1 `providerReference` \$1 `attributionPeriod`

### 파라미터 세부 정보
<a name="member-add-parameter-details"></a>

memberId(선택 사항)  
그룹에 추가할 멤버의 식별자입니다.  
유형: 식별자  
시스템: 환자 식별자 시스템  

```
{
  "name": "memberId",
  "valueIdentifier": {
    "system": "http://example.org/patient-id",
    "value": "patient-new"
  }
}
```

providerNpi(선택 사항)  
귀속된 공급자의 국가 공급자 식별자(NPI)입니다.  
유형: 식별자  
시스템: http://terminology.hl7.org/CodeSystem/NPI  

```
{
  "name": "providerNpi",
  "valueIdentifier": {
    "system": "http://terminology.hl7.org/CodeSystem/NPI",
    "value": "1234567890"
  }
}
```

patientReference(선택 사항)  
추가할 환자 리소스에 대한 직접 참조입니다.  
유형: 참조  

```
{
  "name": "patientReference",
  "valueReference": {
    "reference": "Patient/patient-123"
  }
}
```

providerReference(선택 사항)  
공급자 리소스에 대한 직접 참조입니다.  
유형: 참조  

```
{
  "name": "providerReference",
  "valueReference": {
    "reference": "Practitioner/provider-456"
  }
}
```

attributionPeriod(선택 사항)  
환자가 공급자에 귀속되는 기간입니다.  
유형: 기간  

```
{
  "name": "attributionPeriod",
  "valuePeriod": {
    "start": "2024-07-15",
    "end": "2025-07-14"
  }
}
```

## 요청 예제
<a name="member-add-examples"></a>

### 멤버 ID 및 공급자 NPI 사용
<a name="member-add-example-id-npi"></a>

```
{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "memberId",
      "valueIdentifier": {
        "system": "http://example.org/patient-id",
        "value": "patient-new"
      }
    },
    {
      "name": "providerNpi",
      "valueIdentifier": {
        "system": "http://terminology.hl7.org/CodeSystem/NPI",
        "value": "1234567890"
      }
    },
    {
      "name": "attributionPeriod",
      "valuePeriod": {
        "start": "2024-07-15",
        "end": "2025-07-14"
      }
    }
  ]
}
```

### 환자 및 공급자 참조 사용
<a name="member-add-example-references"></a>

```
{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "patientReference",
      "valueReference": {
        "reference": "Patient/patient-123"
      }
    },
    {
      "name": "providerReference",
      "valueReference": {
        "reference": "Practitioner/provider-456"
      }
    },
    {
      "name": "attributionPeriod",
      "valuePeriod": {
        "start": "2024-07-15",
        "end": "2025-07-14"
      }
    }
  ]
}
```

## 응답 형식
<a name="member-add-response"></a>

### 성공적인 추가 응답
<a name="member-add-success-response"></a>

```
HTTP Status: 200 OK
Content-Type: application/fhir+json

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "success",
      "code": "informational",
      "details": {
        "text": "Member Patient/patient-new successfully added to the Member Attribution List."
      }
    }
  ]
}
```

### 오류 응답
<a name="member-add-error-responses"></a>

잘못된 요청 구문  
HTTP 상태: 400 잘못된 요청  

```
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "text": "Invalid parameter combination provided"
      }
    }
  ]
}
```

리소스를 찾을 수 없음  
HTTP 상태: 404 찾을 수 없음  

```
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "details": {
        "text": "Resource not found."
      }
    }
  ]
}
```

버전 충돌  
HTTP 상태: 409 충돌  

```
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "conflict",
      "details": {
        "text": "Resource version conflict detected"
      }
    }
  ]
}
```

잘못된 속성 상태  
HTTP 상태: 422 처리 불가능한 엔터티  

```
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "business-rule",
      "details": {
        "text": "Cannot add member to Attribution List with status 'final'. Status must be 'draft' or 'open'."
      }
    }
  ]
}
```

## 비즈니스 규칙
<a name="member-add-business-rules"></a>

속성 상태 검증  
그룹의 속성 상태가 다음과 같은 경우에만 작업을 수행할 수 있습니다.  
+ `draft`
+ `open`
상태가 인 경우 작업이 허용되지 않습니다`final`.

중복 멤버 방지  
시스템은 다음과 같은 고유한 조합을 기반으로 중복 멤버를 추가하는 것을 방지합니다.  
+ 멤버 식별자
+ 지급인 식별자
+ 적용 범위 식별자

적용 기간 검증  
`attributionPeriod`가 제공되면 멤버의 적용 범위 기간 범위 내에 속해야 합니다. 시스템은 다음을 수행합니다.  
+ 멤버의 적용 범위 리소스 검색
+ 여러 개가 있는 경우 최신 적용 범위(가장 높은 versionId) 사용
+ 어트리뷰션 기간이 적용 범위를 초과하지 않는지 확인

참조 검증  
동일한 리소스(환자 또는 공급자)에 대해 ID와 참조가 모두 제공되면 시스템은 동일한 리소스에 해당하는지 확인합니다.  
동일한 리소스(환자 또는 공급자)에 대해 ID 및 reference.identifier 필드가 모두 제공되면 오류가 발생합니다.

## 인증 및 권한 부여
<a name="member-add-auth"></a>

작업을 수행하려면 다음에 대한 FHIR 인증에서 SMART가 필요합니다.
+ 읽기 권한 - 환자, 공급자 및 그룹 리소스를 검증하려면
+ 검색 권한 - 식별자별로 리소스를 찾으려면
+ 권한 업데이트 - 그룹 리소스를 수정하려면

## 운영 동작
<a name="member-add-behavior"></a>

리소스 업데이트  
+ 그룹 리소스 버전 ID를 업데이트합니다.
+ 작업 전에 원래 리소스 상태로 기록 항목을 생성합니다.
+ 다음을 사용하여 Group.member 배열에 멤버 정보를 추가합니다.
  + entity.reference의 환자 참조
  + 기간의 속성 기간
  + 확장 필드의 적용 범위 및 공급자 정보

검증 단계  
+ 파라미터 검증 - 유효한 파라미터 조합 확인
+ 리소스 존재 - 환자, 공급자 및 그룹 리소스가 존재하는지 검증합니다.
+ 속성 상태 - 그룹 상태가 수정을 허용하는지 확인합니다.
+ 중복 검사 - 기존 멤버 추가 방지
+ 적용 범위 검증 - 어트리뷰션 기간이 적용 범위 범위 범위 내에 있는지 확인합니다.

## 제한 사항
<a name="member-add-limitations"></a>
+ 참조된 모든 리소스는 동일한 데이터 스토어 내에 있어야 합니다.
+ 작업은 멤버 속성 목록 그룹 리소스에서만 작동합니다.
+ 속성 기간은 적용 범위 범위 내에 있어야 합니다.
+ "최종" 상태의 그룹은 수정할 수 없습니다.