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

# HealthLake 的 FHIR `$questionnaire-package`操作
<a name="reference-fhir-operations-questionnaire-package"></a>

`$questionnaire-package` 操作會擷取完整的套件，其中包含 FHIR 問卷及其轉譯和處理問卷所需的所有相依性。此操作會實作 [Da Vinci 文件範本和規則 (DTR) 實作指南](https://hl7.org/fhir/us/davinci-dtr/OperationDefinition-questionnaire-package.html)，針對醫療工作流程中的文件需求啟用動態表單轉譯。

## 運作方式
<a name="questionnaire-package-how-it-works"></a>
+ **請求**：您傳送識別所需問卷的參數 （以及涵蓋範圍和順序內容）
+ **擷取**：HealthLake 會收集問卷和所有相依性 (ValueSets、CQL 程式庫等）
+ **套件**：所有資源都以標準化格式綁定在一起
+ **回應**：您收到準備轉譯和資料收集的完整套件

**使用案例**  

+ **預先授權文件**：收集預先授權請求所需的臨床資訊
+ **涵蓋範圍需求**：收集滿足付款人涵蓋範圍需求所需的文件
+ **臨床資料交換**：結構臨床資料以提交給付款人
+ **動態表單**：使用預先填入的患者資料和條件式邏輯轉譯問卷

## API 端點
<a name="questionnaire-package-api-endpoint"></a>

```
POST /datastore/{datastoreId}/r4/Questionnaire/$questionnaire-package  
Content-Type: application/fhir+json
```

## 請求參數
<a name="questionnaire-package-request-parameters"></a>

### 輸入參數
<a name="questionnaire-package-input-parameters"></a>

請求內文必須包含具有下列參數的 FHIR 參數資源：


| 參數 | Type | 基數 | Description | 
| --- | --- | --- | --- | 
| coverage | 涵蓋範圍 | 1..\$1 （必要） | 用於建立文件成員和涵蓋範圍的 （涵蓋範圍） 資源 | 
| questionnaire | 正式 | 0..\$1 | 要傳回之特定問卷的正式 URL (s) （可能包含版本） | 
| order | 資源 | 0..\$1 | 訂購資源 (DeviceRequest、ServiceRequest、MedicationRequest、Encounter、Appointment) 以建立內容 | 
| changedSince | dateTime | 0..1 | 如果存在，則只會傳回在此時間戳記之後變更的資源 | 

### 參數驗證規則
<a name="questionnaire-package-parameter-validation"></a>

**至少必須提供下列其中一項** （除了必要的 之外`coverage`)：
+ 一或多個`questionnaire`正式 URLs
+ 一或多個`order`資源

**有效的請求組合：**  

+ `coverage` \$1 `questionnaire`
+ `coverage` \$1 `order`
+ `coverage` \$1 `questionnaire` \$1 `order`

## 範例請求
<a name="questionnaire-package-example-request"></a>

```
POST /datastore/example-datastore/r4/Questionnaire/$questionnaire-package  
Content-Type: application/fhir+json  
Authorization: Bearer <your-token>  
  
{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": {  
        "resourceType": "Coverage",  
        "id": "example-coverage",  
        "status": "active",  
        "beneficiary": {  
          "reference": "Patient/example-patient"  
        },  
        "payor": [{  
          "reference": "Organization/example-payer"  
        }],  
        "class": [{  
          "type": {  
            "coding": [{  
              "system": "http://terminology.hl7.org/CodeSystem/coverage-class",  
              "code": "group"  
            }]  
          },  
          "value": "12345"  
        }]  
      }  
    },  
    {  
      "name": "questionnaire",  
      "valueCanonical": "http://example.org/fhir/Questionnaire/home-oxygen-therapy|2.0"  
    },  
    {  
      "name": "order",  
      "resource": {  
        "resourceType": "ServiceRequest",  
        "id": "example-service-request",  
        "status": "active",  
        "intent": "order",  
        "code": {  
          "coding": [{  
            "system": "http://www.ama-assn.org/go/cpt",  
            "code": "94660",  
            "display": "Continuous positive airway pressure ventilation (CPAP)"  
          }]  
        },  
        "subject": {  
          "reference": "Patient/example-patient"  
        }  
      }  
    },  
    {  
      "name": "changedSince",  
      "valueDateTime": "2024-01-01T00:00:00Z"  
    }  
  ]  
}
```

## 回應格式
<a name="questionnaire-package-response-format"></a>

### 成功回應 (200 OK)
<a name="questionnaire-package-success-response"></a>

操作會傳回包含一或多個**套件套件的** FHIR 參數資源。每個套件套件都包含：


| 項目類型 | 基數 | Description | 
| --- | --- | --- | 
| 問卷 | 1 | 要轉譯的問卷 | 
| QuestionnaireResponse | 0..1 | 預先填入或部分完成的回應 （如適用） | 
| Library (程式庫) | 0..\$1 | 包含預先填入和條件式邏輯的 CQL 程式庫 | 
| ValueSet | 0..\$1 | 擴展的 ValueSets （適用於 <40 個擴展的答案選項） | 

**Example 回應範例**  

```
{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "PackageBundle",  
      "resource": {  
        "resourceType": "Bundle",  
        "id": "questionnaire-package-example",  
        "meta": {  
          "profile": ["http://hl7.org/fhir/us/davinci-dtr/StructureDefinition/DTR-QPackageBundle"]  
        },  
        "type": "collection",  
        "timestamp": "2024-03-15T10:30:00Z",  
        "entry": [  
          {  
            "fullUrl": "http://example.org/fhir/Questionnaire/home-oxygen-therapy",  
            "resource": {  
              "resourceType": "Questionnaire",  
              "id": "home-oxygen-therapy",  
              "url": "http://example.org/fhir/Questionnaire/home-oxygen-therapy",  
              "version": "2.0",  
              "status": "active",  
              "title": "Home Oxygen Therapy Documentation",  
              "item": [  
                {  
                  "linkId": "1",  
                  "text": "Patient diagnosis",  
                  "type": "choice",  
                  "answerValueSet": "http://example.org/fhir/ValueSet/oxygen-diagnoses"  
                }  
              ]  
            }  
          },  
          {  
            "fullUrl": "http://example.org/fhir/Library/oxygen-prepopulation",  
            "resource": {  
              "resourceType": "Library",  
              "id": "oxygen-prepopulation",  
              "url": "http://example.org/fhir/Library/oxygen-prepopulation",  
              "version": "1.0",  
              "type": {  
                "coding": [{  
                  "system": "http://terminology.hl7.org/CodeSystem/library-type",  
                  "code": "logic-library"  
                }]  
              },  
              "content": [{  
                "contentType": "text/cql",  
                "data": "bGlicmFyeSBPeHlnZW5QcmVwb3B1bGF0aW9u..."  
              }]  
            }  
          },  
          {  
            "fullUrl": "http://example.org/fhir/ValueSet/oxygen-diagnoses",  
            "resource": {  
              "resourceType": "ValueSet",  
              "id": "oxygen-diagnoses",  
              "url": "http://example.org/fhir/ValueSet/oxygen-diagnoses",  
              "status": "active",  
              "expansion": {  
                "timestamp": "2024-03-15T10:30:00Z",  
                "contains": [  
                  {  
                    "system": "http://hl7.org/fhir/sid/icd-10",  
                    "code": "J44.0",  
                    "display": "COPD with acute lower respiratory infection"  
                  },  
                  {  
                    "system": "http://hl7.org/fhir/sid/icd-10",  
                    "code": "J96.01",  
                    "display": "Acute respiratory failure with hypoxia"  
                  }  
                ]  
              }  
            }  
          },  
          {  
            "fullUrl": "http://example.org/fhir/QuestionnaireResponse/example-prepopulated",  
            "resource": {  
              "resourceType": "QuestionnaireResponse",  
              "id": "example-prepopulated",  
              "questionnaire": "http://example.org/fhir/Questionnaire/home-oxygen-therapy|2.0",  
              "status": "in-progress",  
              "subject": {  
                "reference": "Patient/example-patient"  
              },  
              "basedOn": [{  
                "reference": "ServiceRequest/example-service-request"  
              }],  
              "item": [  
                {  
                  "linkId": "1",  
                  "text": "Patient diagnosis",  
                  "answer": [{  
                    "valueCoding": {  
                      "system": "http://hl7.org/fhir/sid/icd-10",  
                      "code": "J44.0",  
                      "display": "COPD with acute lower respiratory infection"  
                    }  
                  }]  
                }  
              ]  
            }  
          }  
        ]  
      }  
    },  
    {  
      "name": "Outcome",  
      "resource": {  
        "resourceType": "OperationOutcome",  
        "issue": [{  
          "severity": "information",  
          "code": "informational",  
          "details": {  
            "text": "Successfully retrieved questionnaire package"  
          }  
        }]  
      }  
    }  
  ]  
}
```

## 操作工作流程
<a name="questionnaire-package-operation-workflow"></a>

**HealthLake 如何處理您的請求**  
當您呼叫 時`$questionnaire-package`，HealthLake 會執行下列步驟：

1. **識別患者和付款人**：從您的 `coverage` 參數擷取患者和保險組織。

1. **尋找正確的問卷**：
   + **搭配 **`questionnaire`** 參數**：使用您提供的正式 URL
   + **使用 **`order`** 參數**：比對訂單代碼 (CPT/HCPCS/LOINC) 和付款人，以尋找適當的問卷

1. **收集相依性**：自動擷取轉譯問卷所需的一切：
   + **CQL 程式庫** - 預先填入和條件式問題的邏輯
   + **ValueSets** - 答案選項 （如果 <40 個選項，則自動展開）
   + **QuestionnaireResponse** - 任何現有的進行中或已完成的回應

1. **將所有內容一起封裝**：
   + 封裝所有資源 （每個資源僅包含一次）
   + 如果提供，則依`changedSince`時間戳記篩選
   + `Outcome` 如果遺失任何資源，將警告新增至

**結果**：準備進行轉譯的完整、獨立套件。

## 錯誤回應
<a name="questionnaire-package-error-responses"></a>

### 400 錯誤的請求
<a name="questionnaire-package-400-error"></a>

請求驗證失敗時傳回。

```
{  
  "resourceType": "OperationOutcome",  
  "issue": [{  
    "severity": "error",  
    "code": "required",  
    "details": {  
      "text": "At least one of 'questionnaire' or 'order' must be provided along with 'coverage'"  
    }  
  }]  
}
```

### 424 失敗相依性
<a name="questionnaire-package-424-error"></a>

當無法擷取相依資源時傳回。

```
{  
  "resourceType": "OperationOutcome",  
  "issue": [{  
    "severity": "warning",  
    "code": "not-found",  
    "details": {  
      "text": "Referenced Library 'http://example.org/fhir/Library/missing-library' could not be retrieved"  
    }  
  }]  
}
```

### 401 (未經授權)
<a name="questionnaire-package-401-error"></a>

當身分驗證憑證遺失或無效時傳回。

### 403 禁止
<a name="questionnaire-package-403-error"></a>

當已驗證的使用者缺少存取所請求資源的許可時傳回。

### 406 無法接受
<a name="questionnaire-package-406-error"></a>

當無法提供請求的內容類型時傳回。

### 409 衝突
<a name="questionnaire-package-409-error"></a>

發生版本或並行衝突時傳回。

### 410 Gone
<a name="questionnaire-package-410-error"></a>

當請求的資源永久刪除時傳回。

### 429 太多請求
<a name="questionnaire-package-429-error"></a>

超過速率限制時傳回。

### 500 內部伺服器錯誤
<a name="questionnaire-package-500-error"></a>

發生非預期的伺服器錯誤時傳回。

### 501 未實作
<a name="questionnaire-package-501-error"></a>

請求的操作尚未實作時傳回。

## 驗證規則
<a name="questionnaire-package-validation-rules"></a>

### 輸入驗證
<a name="questionnaire-package-input-validation"></a>
+ `coverage` 參數為**必要** (1..\$1 基數）
+ 至少`order`必須提供其中一個 `questionnaire`或
+ 所有涵蓋範圍資源都必須是有效的 FHIR 資源
+ 所有訂單資源必須是有效的 FHIR 資源
+ 正式 URLs 必須正確格式化
+ `changedSince` 必須是有效的 ISO 8601 dateTime

### QuestionnaireResponse驗證
<a name="questionnaire-package-response-validation"></a>
+ `status` 必須適當 (`in-progress`、`completed`、`amended`)
+ 結構必須符合參考的問卷
+ `basedOn` 必須參考有效的訂單資源
+ `subject` 必須參考有效的病患資源

### 資源重複資料刪除
<a name="questionnaire-package-resource-dedup"></a>
+ 每個資源只會在套件中出現一次
+ 例外狀況：可能同時包含相同資源的不同版本
+ 透過其正式 URL 和版本來識別資源

## 效能規格
<a name="questionnaire-package-performance-specs"></a>


| 指標 | 規格 | 
| --- | --- | 
| 資源計數限制 | 每個套件 500 個資源 | 
| 套件大小限制 | 最多 5 MB | 

## 所需的許可
<a name="questionnaire-package-required-permissions"></a>

若要使用 `$questionnaire-package`操作，請確定您的 IAM 角色具有：
+ `healthlake:QuestionnairePackage` - 呼叫 操作
+ `healthlake:ReadResource` - 擷取問卷和相依資源
+ `healthlake:SearchWithPost` - 搜尋 QuestionnaireResponse和相關資源

**FHIR 範圍上的 SMART**  
**所需範圍下限：**
+ **SMART v1**： `user/Questionnaire.read user/Library.read user/ValueSet.read user/QuestionnaireResponse.read`
+ **SMART v2**： `user/Questionnaire.rs user/Library.rs user/ValueSet.rs user/QuestionnaireResponse.rs`

## 重要實作備註
<a name="questionnaire-package-implementation-notes"></a>

### 資源擷取策略
<a name="questionnaire-package-retrieval-strategy"></a>

**問卷識別優先順序：**  

+ **正式 URL **（如果提供`questionnaire`參數） - 最高優先順序
+ **訂單分析** （如果提供 `order` 參數）：
  + 比對訂單代碼 (CPT、HCPCS、LOINC) 與付款人醫療政策
  + 使用涵蓋範圍付款人篩選付款人特定的問卷
  + 考慮其他內容的原因代碼

### 相依性解析
<a name="questionnaire-package-dependency-resolution"></a>

**CQL 程式庫：**  

+ 透過問卷資源上的`cqf-library`擴充功能擷取
+ 透過 `Library.relatedArtifact`類型以遞迴方式擷取相依程式庫 `depends-on`
+ 套件中包含所有程式庫相依性

**ValueSets：**  

+ 如果包含的概念少於 40 個，則自動擴展
+ 包含較大的 ValueSets，無需擴展
+ 包括問卷和程式庫資源中參考ValueSets 

### QuestionnaireResponse預先填入
<a name="questionnaire-package-prepopulation"></a>

下列情況下，操作可能會傳回具有預先填入資料的 QuestionnaireResponse：
+ 找到現有的進行中或已完成的回應
+ 關聯程式庫中的 CQL 邏輯可以從病患記錄擷取資料
+ 回應會連結到相關順序和涵蓋範圍

**QuestionnaireResponse的搜尋條件：**  



| 搜尋參數 | FHIR 路徑 | Description | 
| --- | --- | --- | 
| based-on | QuestionnaireResponse.basedOn | ServiceRequest 或 CarePlan 的連結 | 
| patient | QuestionnaireResponse.subject | 做為主體的患者 | 
| questionnaire | QuestionnaireResponse.questionnaire | 回答的問卷 | 

### 變更資源篩選
<a name="questionnaire-package-changed-filtering"></a>

提供 `changedSince` 參數時：
+ 僅包含指定時間戳記**後**修改的資源
+ 如果沒有變更任何資源， `200 OK` 會以空的套件傳回
+ 適用於增量更新和快取策略
+ 時間戳記比較使用資源`meta.lastUpdated`欄位

### 多個套件套件
<a name="questionnaire-package-multiple-bundles"></a>

下列情況下，操作可能會傳回**多個套件套件**：
+ 透過正式 URLs請求多個問卷
+ 多個訂單需要不同的問卷
+ 相同問卷的不同版本適用

每個套件套件都與所有必要的相依性獨立。

## 常用案例
<a name="questionnaire-package-common-use-cases"></a>

### 使用案例 1：預先授權文件
<a name="questionnaire-package-use-case-1"></a>

**案例**：提供者需要收集家庭供氧治療預先授權的文件。

```
{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Patient's insurance coverage */ }  
    },  
    {  
      "name": "order",  
      "resource": {  
        "resourceType": "ServiceRequest",  
        "code": {  
          "coding": [{  
            "system": "http://www.ama-assn.org/go/cpt",  
            "code": "94660"  
          }]  
        }  
      }  
    }  
  ]  
}
```

**結果**：傳回包含氧氣治療問卷的套件，預先填入來自 EHR 的患者生命值和診斷碼。

### 使用案例 2：擷取特定問卷版本
<a name="questionnaire-package-use-case-2"></a>

**案例**：供應商需要特定版本的問卷才能合規。

```
{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Coverage resource */ }  
    },  
    {  
      "name": "questionnaire",  
      "valueCanonical": "http://example.org/fhir/Questionnaire/dme-request|3.1.0"  
    }  
  ]  
}
```

**結果**：傳回含所有相依性的確切版本 3.1.0 的 DME 請求問卷。

### 使用案例 3：檢查更新
<a name="questionnaire-package-use-case-3"></a>

**案例**：供應商想要檢查自上次擷取以來是否有任何問卷資源已更新。

```
{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Coverage resource */ }  
    },  
    {  
      "name": "questionnaire",  
      "valueCanonical": "http://example.org/fhir/Questionnaire/medication-request"  
    },  
    {  
      "name": "changedSince",  
      "valueDateTime": "2024-03-01T00:00:00Z"  
    }  
  ]  
}
```

**結果**：僅傳回在 2024 年 3 月 1 日之後修改的資源，如果沒有變更，則傳回空白套件。

### 使用案例 4：多個訂單
<a name="questionnaire-package-use-case-4"></a>

**案例**：供應商提交多個可能需要不同問卷的服務請求。

```
{  
  "resourceType": "Parameters",  
  "parameter": [  
    {  
      "name": "coverage",  
      "resource": { /* Coverage resource */ }  
    },  
    {  
      "name": "order",  
      "resource": { /* ServiceRequest for imaging */ }  
    },  
    {  
      "name": "order",  
      "resource": { /* ServiceRequest for DME */ }  
    }  
  ]  
}
```

**結果**：傳回多個套件套件，每個適用的問卷各一個。

## 與其他 Da Vinci IGs整合
<a name="questionnaire-package-integration"></a>

### 涵蓋範圍需求探索 (CRD)
<a name="questionnaire-package-crd-integration"></a>

**工作流程整合：**  

+ 供應商在其 EHR 中訂購服務
+ CRD 勾點觸發，檢查涵蓋範圍需求
+ 付款人回應，指出需要文件
+ 供應商呼叫 `$questionnaire-package` 以擷取文件表單
+ 供應商完成問卷
+ 文件是透過 PAS 或 CDex 提交

### 預先授權支援 (PAS)
<a name="questionnaire-package-pas-integration"></a>

**工作流程整合：**  

+ 使用 `$questionnaire-package` 擷取文件需求
+ 使用所需的臨床資料完成 QuestionnaireResponse 
+ 使用 `Claim/$submit`搭配已完成的 QuestionnaireResponse提交預先授權
+ 使用 檢查狀態 `Claim/$inquire`

### 臨床資料交換 (CDex)
<a name="questionnaire-package-cdex-integration"></a>

**工作流程整合：**  

+ 付款人請求申請其他文件
+ 提供者使用 `$questionnaire-package` 擷取結構化資料收集表單
+ 供應商完成 QuestionnaireResponse
+ 文件會透過 CDex 連接工作流程提交給付款人

## 故障診斷指南
<a name="questionnaire-package-troubleshooting"></a>

### 問題：未傳回問卷
<a name="questionnaire-package-no-questionnaire"></a>

**可能的原因：**  

+ 正式 URL 不符合資料存放區中的任何問卷
+ 訂單代碼未對應至付款人醫療政策中的任何問卷
+ 涵蓋範圍付款人沒有相關聯的問卷

**解決方案：**  

+ 確認正式 URL 正確且問卷存在
+ 檢查訂單代碼 (CPT/HCPCS) 是否正確指定
+ 確認付款人組織已設定問卷

### 問題：套件中缺少相依性
<a name="questionnaire-package-missing-dependencies"></a>

**可能的原因：**  

+ 參考的程式庫或 ValueSet 不存在於資料存放區中
+ 程式庫參考已中斷或不正確
+ ValueSet 擴展失敗

**解決方案：**  

+ 檢查 `Outcome` 參數是否有資源遺失的相關警告
+ 驗證資料存放區中存在所有參考的資源
+ 確保 ValueSet URLs正確且可解決

### 問題：含 changedSince 的空套件
<a name="questionnaire-package-empty-package"></a>

**可能的原因：**  

+ 這是預期的行為 - 自指定的時間戳記以來未修改任何資源

**解決方案：**  

+ 使用套件的快取版本
+ 移除`changedSince`參數以擷取完整套件

### 問題：未預先填入 QuestionnaireResponse
<a name="questionnaire-package-not-prepopulated"></a>

**可能的原因：**  

+ 找不到現有的 QuestionnaireResponse 
+ CQL Library 邏輯無法擷取所需的資料
+ 病患資料遺失或不完整

**解決方案：**  

+ 這可能是預期的 - 並非所有問卷都有預先填入邏輯
+ 檢查資料存放區中是否存在病患資料
+ 檢閱 CQL Library 邏輯以了解資料擷取需求

## 最佳實務
<a name="questionnaire-package-best-practices"></a>

### 1. 搭配版本使用正式 URLs
<a name="questionnaire-package-bp-versions"></a>

請求特定問卷時，請務必指定版本編號：

```
{  
  "name": "questionnaire",  
  "valueCanonical": "http://example.org/fhir/Questionnaire/dme|2.1.0"  
}
```

**原因**：確保一致性，並防止更新問卷時的意外變更。

### 2. 利用 changedSince for Performance
<a name="questionnaire-package-bp-changed-since"></a>

對於經常存取的問卷，請使用 `changedSince` 將資料傳輸降至最低：

```
{  
  "name": "changedSince",  
  "valueDateTime": "2024-03-10T15:30:00Z"  
}
```

**原因**：僅擷取更新的資源，以減少延遲和頻寬使用量。

### 3. 包含完整涵蓋範圍資訊
<a name="questionnaire-package-bp-coverage"></a>

提供全面的涵蓋範圍詳細資訊，以確保正確的問卷選擇：

```
{  
  "name": "coverage",  
  "resource": {  
    "resourceType": "Coverage",  
    "beneficiary": { "reference": "Patient/123" },  
    "payor": [{ "reference": "Organization/payer-abc" }],  
    "class": [{ /* Group/plan information */ }]  
  }  
}
```

**原因**：協助 HealthLake 識別付款人特定的問卷和要求。

## 相關的 操作
<a name="questionnaire-package-related-operations"></a>
+ `Claim/$submit` - 提交包含已完成文件的預先授權請求
+ `Claim/$inquire` - 檢查提交的預先授權狀態
+ `ValueSet/$expand` - 展開用於答案選項的 ValueSets