本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# `$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 （選用）  
要新增至群組之成員的識別符。  
類型：Identifier  
系統：病患識別符系統  

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

providerNpi （選用）  
屬性提供者的國家提供者識別符 (NPI)。  
類型：Identifier  
系統：https：//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>
+ 所有參考的資源都必須存在於相同的資料存放區中
+ 操作僅適用於成員屬性清單群組資源
+ 屬性期間必須在涵蓋範圍內
+ 無法修改具有「最終」狀態的群組