本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

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

该`$questionnaire-package`操作会检索一个包含FHIR调查问卷及其呈现和处理问卷所需的所有依赖项的综合包。该操作实现了《[达芬奇文档模板和规则 (DTR) 实施指南》](https://hl7.org/fhir/us/davinci-dtr/OperationDefinition-questionnaire-package.html)，从而实现了医疗工作流程中文档要求的动态表单呈现。

## 工作原理
<a name="questionnaire-package-how-it-works"></a>
+ **请求**：您发送标识所需调查问卷的参数，以及覆盖范围和订单上下文
+ **检索**： HealthLake 收集调查问卷和所有依赖项（ValueSets、CQL 库等）
+ P@@ **ac** kage：所有资源都以标准格式捆绑在一起
+ **回复**：您会收到一个完整的软件包，可以进行渲染和数据收集

**应用场景**  

+ **事先授权文件**：收集事先授权请求所需的临床信息
+ **保险要求**：收集满足付款人保险要求所需的文件
+ Cl@@ **inical Data Exchange**：整理临床数据以提交给付款人
+ **动态表单**：使用预先填充的患者数据和条件逻辑呈现问卷

## 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 | 基数 | 说明 | 
| --- | --- | --- | --- | 
| coverage | 涵盖 | 1.. \$1（必填） | 用于确定文件成员和覆盖范围的覆盖范围的覆盖资源 | 
| questionnaire | 权威性的 | 0。。 \$1 | 要返回的特定问卷的权威网址（可能包括版本） | 
| order | 资源 | 0。。 \$1 | 订购资源（DeviceRequest、 ServiceRequest、 MedicationRequest、遭遇、约会）以建立上下文 | 
| 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>

该操作返回包含一个或多个 Pack **age Bund** le 的 FHIR 参数资源。每个 Package 套装包括：


| 参赛类型 | 基数 | 说明 | 
| --- | --- | --- | 
| 问卷 | 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`****参数**：使用您提供的权威网址
   + **带`order`****参数**：匹配订单代码 (CPT/HCPCS/LOINC) 和付款人以找到相应的问卷

1. **收集依赖关系**：自动检索呈现调查问卷所需的所有内容：
   + **CQL 库**-填充前问题和条件问题的逻辑
   + **ValueSets**-答案选项（如果选项小于 40 个，则自动扩展）
   + **QuestionnaireResponse**-任何现有正在处理或已完成的回复

1. P@@ **ackage 把所有东西放在一起**：
   + 捆绑所有资源（每种资源仅包含一次）
   + 按`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 日期时间

### 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 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>

**问卷识别优先级：**  

+ **规范网址**（如果提供了`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 带有预填充数据的a：
+ 已找到现有正在处理或已完成的响应
+ 关联库中的 CQL 逻辑可以从患者记录中提取数据
+ 回复与相关的订单和覆盖范围相关

**搜索标准 QuestionnaireResponse：**  



| 搜索参数 | FHIR 路径 | 说明 | 
| --- | --- | --- | 
| 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>

在以下情况下，该操作可能会返回**多个 Package Bundle**：
+ 通过 canonical 申请了多份问卷 URLs
+ 多个订单需要不同的问卷
+ 同一份问卷的不同版本适用

每个 Package Bundle 都是独立的，具有所有必要的依赖关系。

## 常见使用案例
<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"  
          }]  
        }  
      }  
    }  
  ]  
}
```

**结果**：返回包含氧气治疗问卷的包裹，其中预先填充了电子病历中的患者生命体征和诊断代码。

### 用例 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"  
    }  
  ]  
}
```

**结果**：精确返回包含所有依赖项的 DME 请求调查问卷的 3.1.0 版本。

### 用例 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 */ }  
    }  
  ]  
}
```

**结果**：返回多个 Package Bundle，每个适用的问卷对应一个。

## 与其他达芬奇集成 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 是否正确且问卷是否存在
+ 检查订单代码 (CPT/HCPCS) 的指定是否正确
+ 确认付款人组织已配置调查表

### 问题：Package 中缺少依赖关系
<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 库逻辑无法提取所需数据
+ 患者数据缺失或不完整

**解决方案：**  

+ 这可能是预料之中的——并非所有问卷都有人口前的逻辑
+ 检查数据存储中是否存在患者数据
+ 查看 CQL 库逻辑以了解数据提取要求

## 最佳实践
<a name="questionnaire-package-best-practices"></a>

### 1. 将 Canonical 与版本一起 URLs 使用
<a name="questionnaire-package-bp-versions"></a>

在申请特定问卷时，请务必指定版本号：

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

**原因**：确保问卷更新时的一致性并防止意外更改。

### 2. 为了提高性能，杠杆率已改变
<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 答案选择