README

警告：这是一个实验性WIP模块。我们不推荐在生产环境中使用此模块。

安装

我们建议使用Composer进行安装和更新管理。要将CRM Mobiletech扩展添加到您的REMP CRM应用程序，请使用以下命令

composer require remp/crm-mobiletech-module

在您的app/config/config.neon文件中启用已安装的扩展

extensions:
	# ...
	- Crm\MobiletechModule\DI\MobiletechModuleExtension

当您的安装准备就绪并配置了Mobiletech（他们知道您的webhook API端点）时，开始接收消息。

我们建议创建单独的异步Hermes处理程序，监听mobiletech-inbound事件，并异步处理传入消息。

在处理类中，您应根据传入消息的内容触发事件或执行操作。当您想响应传入消息时，可以触发MobiletechNotificationEvent来处理发送

$this->emitter->emit(new MobiletechNotificationEvent(
    $this->emitter,
    new MobiletechNotificationEnvelope($inboundMessage),
    $inboundMessage->user, // reference to user the message is being sent to
    'unregistered_number', // reference to mobiletech_templates.code DB column 
    [] // parameters to be injected to the template
));

传出消息期望提供mobiletech_template。内容作为twig模板处理，并且可以注入MobiletechNotificationEvent中提供的参数作为变量。

请检查MobiletechNotificationEvent和MobiletechNotificationEnvelope以了解提供的参数和上下文。

MobiletechAuthenticator

当扩展启用时，身份验证器会自动与其它身份验证器一起注册。

MobiletechAuthenticator期望在mobile_phone字段或已由UsernameAuthenticator使用的username字段中提供电话号码。这样做的理由是与现有的登录表单兼容。如果用户使用电话号码而不是电子邮件，则将登录（如果找到匹配项）。此类型登录仍需要密码。

用于接收消息的Webhook

Mobiletech要求应用程序公开webhook以接收消息，并在接收消息时以特定方式响应。

Webhook在/api/v1/mobiletech/webhook处可用。

当接收到消息时，webhook将消息存储到mobiletech_inbound_messages，并在您想进行额外处理的情况下，通过引用存储的消息发出mobiletech-inbound Hermes事件。

开发、实时测试和发布

默认情况下，该模块使用Crm\MobiletechModule\Model\MockApiClient来模拟与短信网关的通信。客户端存储发送的消息信息，即使实际上没有发送任何消息。它还更新消息的状态为“已送达”。

要开始使用客户端的生产实现（您需要此功能才能发送消息），请修改您的config.neon文件

services:
	# ...
	mobiletechApiClient:
		class: Crm\MobiletechModule\Model\MobiletechApiClient

测试对接收到的消息的响应

要测试webhook集成是否正常工作，您应该对收到的消息进行响应。

我们已准备异步Hermes监听器，等待传入消息。它使用预定义的消息模板和计费密钥进行响应。要启用此功能，请注册处理程序并对其进行配置

class FooModule extends Crm\ApplicationModule\CrmModule
{
    public function registerHermesHandlers(Tomaj\Hermes\Dispatcher $dispatcher)
    {
        $dispatcher->registerHandler(
            'mobiletech-inbound',
            $this->getInstance(\Crm\MobiletechModule\Hermes\TestInboundHandler::class)
        );
    }

services:
	# ...
	mobiletechTestInboundHandler:
		setup:
			- setBillKey(AA99) # get the billing key from Mobiletech
			- setTemplateCode(pong) # insert the testing template to mobiletech_templates DB table

配置完成后，请确保在mobiletech_phone_numbers数据库表中有一条包含您电话号码的记录，并向Mobiletech提供的短号发送测试短信。Webhook会接收它，触发测试处理程序，并使用您配置的模板进行响应。

迁移

如果您之前已经在实施中使用过Mobiletech，请查看以下步骤以了解迁移到CRM所需的操作。

导入用户

首先您需要确保所有用户都存在于系统中（以某种形式）。

• 如果您有用户的电子邮件，可以使用api/v1/users/email API /api/v1/users/create API分别确保用户存在。
• 如果您没有用户的电子邮件，您需要创建自己的模块并导入用户：通过自定义API或自定义命令。用户的电子邮件不是必需的。请确保正确填写public_name（例如，使用电话号码），因为这个字段将在系统周围显示。

将用户与Mobiletech电话号码关联

Mobiletech模块将实际的phone_number与mobiletech_phone_numbers表中的user_id相关联。

您可以使用Crm\MobiletechModule\Repository\MobiletechPhoneNumbersRepository::add()来创建电话号码和用户之间的链接。

• phone_number应使用本地格式（例如09xx123456）且必须是唯一的。
• user_id需要引用现有用户且必须是唯一的。

这意味着，在此阶段，用户不能有多个电话号码分配给他们的账户。

导入入站/出站消息

Mobiletech模块记录所有入站和出站消息。这些消息用于创建/收费周期性支付，因此请确保它们被正确导入。

导入数据时，您应主要遵循mobiletech_inbound_messages和mobiletech_outbound_messages数据库模式，这些模式主要反映了Mobiletech的API。重要提示

• mobiletech_id始终引用Mobiletech消息的ID。对于入站消息，它是receive消息的id参数。对于出站消息，它是rcv_rsp消息（Mobiletech对电话号码发送的消息的确认）的id参数。
• user_id是CRM用户的引用。有些消息可能来自/发送给CRM中不存在且在处理消息时未注册的用户。在这种情况下，您可以保持引用为NULL。
• from是来自国际格式的发送者电话号码（如从Mobiletech接收的）。

出站特定

• mobiletech_template_id引用发送给用户的短信内容（在出站消息中）。这是一个必填字段，您需要首先创建模板然后再运行此导入。
• status是status消息的status参数。这是Mobiletech在将消息发送到电话号码后发送的消息。
• rcv_msg_id是触发出站消息的入站消息的mobiletech_id。这只能为push消息（由服务器发起的周期性收费）为空。
• billkey是实际用于发送消息的账单密钥。
• payment_id引用发起发送消息并带有已付费账单密钥的支付。

  • 支付应具有与账单密钥相同金额。

  • 支付应使用mobiletech_recurrent（或mobiletech）支付网关。

  • 支付应设置以下所有payment_meta

    • mobiletech_billkey
    • mobiletech_inbound_message_id
    • mobiletech_template_code
    • mobiletech_template_params

    有关更多信息，请参阅导入支付部分。

导入支付

以下部分期望使用最先进的场景 - 使用多种订阅类型的周期性短信支付。

• 您应该只导入成功的支付。
• 支付应使用 mobiletech_recurrent 支付网关。
• 支付应设置以下元值
  • mobiletech_billkey。用于收费的账单密钥。这个密钥应该与将要通过 mobiletech_outbound_messages.payment_id 列链接到这个支付的 mobiletech_outbound_message 上的密钥相同。
  • mobiletech_inbound_message_id。在 mobiletech_inbound_messages 中导入的消息的 ID，该消息启动了支付。
  • mobiletech_template_code。用于发送消息的 mobiletech_templates 的 ID。
  • mobiletech_template_params。包含模板内使用的参数的 JSON 编码字符串。对于导入，可以使用空的 JSON 对象。
• 当支付被导入时，将其链接到处理支付并收费的 mobiletech_outbound_messages 记录。为了保持完整性，已支付（paid）支付应链接到状态为 D1 的已发送（outbound）消息。

当支付被链接到外发消息时，在 recurrent_payments 表中创建记录

• cid 列指的是 mobiletech_inbound_messages.mobiletech_id 列。它是启动周期性支付的消息的引用，并包含生成未来下一次支付所需的所有信息。
• charge_at 是用户应再次被收费的日期。
• expires 可以保持为 NULL。
• payment_id 可以保持为 NULL。CRM 会在尝试向用户收费时设置此值。
• retries 是尝试向用户收费的次数。您可以使用 CRM 中的默认值 4。
• parent_payment_id 是引用已安排此周期性收费的支付。为了使 SMS 收费工作，您应该至少导入一个支付并在此处引用它。如果您导入用户的所有支付，请使用 最后成功的 mobiletech 支付 的 ID 作为父 ID。
• state 应为 active 以触发收费。

某些列被省略，因为它们是直接的或者由您填写（例如 subscription_type_id）。

周期性支付的完整性检查

• recurrent_payments.cid 必须 引用存在的 mobiletech_inbound_messages.mobiletech_id。
• 必须有 mobiletech_outbound_message.rcv_msg_id 持有 cid 的值（并引用上一步中的入站消息）。