README

本包包含用于在Convoworks框架中管理预约场景的会话工作流元素。它包含您可以在会话工作流中使用的元素，但预约数据源仅通过IAppointmentsContext接口进行描述。

当我们讨论工作流组件（元素）时，我们主要需要考虑语音和会话设计需求。它们的属性、子流程和一般行为都是针对使会话工作流尽可能简单而定制的。它们与任何特定的预订插件或类似的第三方服务提供商无关。

另一方面，预约上下文是工作流元素（Convoworks）与您在系统中使用的真实、具体的预约系统之间的桥梁。

预约上下文接口

IAppointmentsContext描述了应由目标预约系统实现的方法。例如，如果您有WordPress预约插件，您可以通过实现此接口轻松启用它与Convoworks一起使用。

大多数方法都需要用户身份验证，我们使用email进行此操作。电子邮件与WordPress配合得很好，同时它使我们能够实现无需在系统中实际创建用户的中继实现。如果您的目标系统有几种预约类型，您需要的类型应配置在此IAppointmentsContext类型组件中。

要正确地在Convoworks GUI中使用，它还必须实现IBasicServiceComponent和IServiceContext。您可以考虑从如下开始您的实现：

class MyCustomAppointmentsContext extends AbstractBasicComponent implements IAppointmentsContext, IServiceContext
{

}

您可以在Convoworks文档中了解更多关于开发自定义包的信息，您还可以查看我们的Convoworks WP插件包模板。

`DummyAppointmentsContext`

Dummy实现，可用于测试语音应用程序或作为创建自己的IAppointmentsContext实现时的示例。

以下是一些预定义的功能：

工作时间为工作日的9:00 - 17:00
预约时长：30分钟
它将在Convoworks用户范围内存储预约

工作流元素

所有预约包工作流元素都具有context_id属性，将它们连接到实现IAppointmentsContext接口的上下文。这样，元素专注于会话工作流需求，而真实业务逻辑则委托给具体实现。

以下是一些常用参数：

context_id - 所引用的IAppointmentsContext的ID
email - 对CheckAppointmentTimeElement是可选的，但对所有其他元素都是必需的
timezone_mode - DEFAULT将使用所引用预约上下文的默认时区，CLIENT将尝试获取客户端信息，或SET将允许您显式设置值。
timezone - 只有当timezone_mode为SET时。PHP时区名称。

某些元素根据我们得到的结果具有多个子流程。这种类型的实现使您可以在工作流中使用较少的IF语句。但为了不强迫您拆分工作流，一些流程是可选的，当为空时，将执行默认流程。

`CheckAppointmentTimeElement`

此元素将检查所需时间段是否可用。根据请求时间段或建议可用性，它具有几个子流程。当请求的时间段不可用时，元素会暴露建议，一个包含可能提供给最终用户的时间段（时间戳）的数组。

参数

appointment_date - 可选，请求日期，格式为Y-m-d（MySQL DATE格式）
appointment_time - 可选，请求时间，格式为H:i:s（MySQL TIME格式）
email - 可选，用户标识。如果存在，可能有助于提供更好的建议
return_var - 默认status，子流程中存在的变量名称，包含操作结果信息（suggestions：建议数组，requested_time：请求的预约作为时间戳，requested_timezone：请求的时间区域作为字符串，not_allowed：当请求时间段超出营业时间时为true）

流程

available_flow - 当时间段可用时执行
suggestions_flow - 当时间段不可用且有建议时执行
single_suggestion_flow - 可选，如果只有一个建议则执行。如果为空（内部没有元素），则将执行suggestions_flow
no_suggestions_flow- 可选，如果没有建议则执行。如果为空，则将执行suggestions_flow

其他

suggestions_builder - 类型为IFreeSlotQueueFactory的组件，用于生成建议。您可以使用DefaultFreeSlotQueue或创建自己的。

建议的JSON表示。

[{
      "timestamp" : 123345678,
}, {
      "timestamp" : 123445678,
}]

`CreateAppointmentElement`

此元素将尝试为给定时间段创建预约。（很少发生）时间段可能已不再空闲，您可以使用not_available流程来处理它。如果发生一般意外错误，系统处理程序将处理它。

参数

appointment_date - 请求日期，格式为Y-m-d（MySQL DATE格式）
appointment_time - 请求时间，格式为H:i:s（MySQL TIME格式）
payload - 可用于实现预订插件的其它各种属性。
return_var - 默认status，包含额外信息的变量名称（appointment_id：字符串，requested_time：请求的预约作为时间戳，requested_timezone：请求的时间区域作为字符串，not_allowed：当请求时间段超出营业时间时为true）

流程

ok - 当预约创建时执行此流程
not_available - 当请求的时间段不可用时执行

`UpdateAppointmentElement`

更新现有预约时间的元素。

参数

appointment_id - 现有预约的ID
appointment_date - 请求日期，格式为Y-m-d（MySQL DATE格式）
appointment_time - 请求时间，格式为H:i:s（MySQL TIME格式）
payload - 可选，可用于实现插件的其它各种属性。如果为空，则在创建时提供的原始有效负载数据应保持不变。
return_var - 默认status，包含额外信息的变量名称（existing：通过加载预约元素获取的前一个预约版本，requested_time：请求的预约作为时间戳，requested_timezone：请求的时间区域作为字符串，not_allowed：当请求时间段超出营业时间时为true）

流程

ok - 当预约更新时执行
not_available - 当请求的时间段不可用时执行

`CancelAppointmentElement`

此元素将取消现有预约。

参数

appointment_id - 现有预约的ID
return_var - 默认status，包含额外信息的变量名称（existing：通过加载预约元素获取的前一个预约版本）

流程

ok - 当预约取消时执行

`LoadAppointmentsElement`

此元素将加载当前用户的现有预约。

参数

模式 : 默认 current，或 past 或 all
limit : 默认 10
return_var - 默认 status，包含额外信息的变量名称（appointments：预约数组）

流程

multiple - 当找到多个预约时执行。
single - 当找到单个预约时执行。如果为空，将执行 multiple 流程。
empty - 如果没有建议，将执行。如果为空，将执行 multiple 流程。

`LoadAppointmentElement`

此元素返回单个预约数据。

参数

appointment_id - 现有预约的ID
return_var - 默认 status，包含额外信息的变量名称（appointment：预约对象数组）

流程

ok - 当预约加载时执行。

以 JSON 格式表示的单个预约。

{
      "appointment_id" : "123",
      "email" : "user@domain.com",
      "timestamp" : 123345678,
      "timezone" : "America/New_York",
      "payload" : {
          "some_other_fields" : "That is used by implementing appointment context & WP plugin",
          "more_fields" : "Some other data"
      }
}

模板 - 安排预约

此包附带一个可立即使用的服务模板 - 安排预约。默认情况下，它配置为使用我们的虚拟预约上下文。您可以通过更改变量视图中的 APPOINTMENTS 值轻松更改它。

功能

此对话服务使用户能够创建、重新安排或取消预约。它旨在提供良好的丰富用户体验。用户可以创建新的预约，检查他们是否有现有的预约，并取消或重新安排它们。当请求的时段不可用时，服务将建议几个空闲时段。

其他特性和要求

作为 Alexa 技能即可使用
仅语音界面
它将要求用户在 Alexa 应用中启用访问个人资料数据（姓名、电子邮件）

初始设置

如果您刚刚安装了 Convoworks WP，您可能希望检查我们的连接到 Amazon 并创建您的第一个 Alexa 技能从我们的 Convoworks 基础视频教程系列。

打开 Convoworks WP 服务视图，点击“创建新”按钮。输入服务名称，选择“我的预订”模板，然后按“提交”按钮。

现在导航到服务的“配置”视图，并选择“amazon alexa”配置按钮。在“Amazon Alexa 技能权限”部分，勾选“全名”和“客户电子邮件地址”复选框。按“保存配置”，然后您的服务将传播到 Alexa 控制台。

您还可以在“变量”视图中更改 APP_NAME。如果您计划使用其他预约上下文，应将 APPOINTMENTS 更改为适当的 ID。

转到 Alexa 应用（或网络应用 https://alexa.amazon.com），点击“您的技能”，选择“开发技能”选项卡，找到您的新技能并启用它。

您的预订技能现在可以在您的 Alexa 启用设备上进行测试。

有关更多信息，请访问 convoworks.com

zef-dev / convoworks-pckg-appointments

维护者

详情