README

此模块为SalesFunnelModule提供礼品选项。

安装模块

我们建议使用Composer进行安装和更新管理。

composer require remp/crm-gifts-module

启用模块

将已安装的扩展添加到您的app/config/config.neon文件中

extensions:
	- Crm\GiftsModule\DI\GiftsModuleExtension

运行服务命令以生成CRM内部组件

php bin/command.php phinx:migrate
php bin/command.php user:generate_access
php bin/command.php api:generate_access
php bin/command.php application:seed

SalesFunnelModule集成

1. 将payment_metadata字段添加到您的销售漏斗中（必须与其他所需销售漏斗字段一起发送；参见SalesFunnelModule README）

   • payment_metadata[gift] (布尔值) - 如果为true，则表示此购买是礼品。
   • payment_metadata[gift_email] (字符串) - 购买礼品的客户的电子邮件。这可以是现有或新客户的电子邮件。礼品处理程序可以处理新账户的创建。
   • payment_metadata[gift_starts_at] (字符串) - 礼品订阅应开始的时间。使用DateTimeInterface::RFC3339。

   所有三个字段都是必需的.

2. 将php bin/command.php gifts:activate_purchased_gift_coupons放入cron。我们建议每5到10分钟运行一次。

3. 如果您想通知客户有关礼品相关事件，请创建这些NotificationEvent的事件监听器

   • created_payment_gift_coupon - 当确认的礼品订阅的支付完成时（已支付）发出。发送给捐赠者。
   • welcome_email_gift_coupon - 当礼品订阅被创建时（礼品订阅是在前一个步骤中的命令在gift_starts_at时间戳处创建的）并且收礼人的账户在CRM中创建时发出。发送给收礼人（来自gift_email字段的电子邮件）。
   • new_subscription_gift - 当礼品订阅被创建时（礼品订阅是在前一个步骤中的命令在gift_starts_at时间戳处创建的）并且收礼人的账户已经在CRM中存在时发出。发送给收礼人（来自gift_email字段的电子邮件）。

4. 设置礼品优惠券附件，该附件应附加到发送给捐赠者的通知事件中。请参阅应用程序配置gift_subscription_coupon_attachment，可在Web管理中的订阅类别下找到。

工作原理

1. PaymentItemContainerReadyEventHandler监听PaymentItemContainerReadyEvent。

   • 如果payment_metadata包含有效的礼品字段（见上方），则将其从SubscriptionTypePaymentItem更改为GiftPaymentItem。

2. CreateGiftCouponNewPaymentEventHandler监听NewPaymentEvent（创建支付；未支付）。

   • 如果payment_meta包含有效的礼品字段，则从支付中删除subscription_type_id（以防止为捐赠者的账户创建订阅）。
   • 然后，它根据礼品字段创建payment_gift_coupons条目。
     • 这是在支付确认之前创建的，出于遗留原因。这有助于帮助台进行搜索并将支付与礼品配对。

3. GiftPaymentStatusChangeHandler监听PaymentChangeStatusEvent。

   • 如果支付是已支付并且是礼品订阅购买（支付的元数据包含gift === 1），则发出带有优惠券附件的NotificationEvent(created_payment_gift_coupon)（见集成）。

4. 命令php bin/command.php gifts:activate_purchased_gift_coupons在后台运行，并在时间> = gift_starts_at时激活礼品订阅。

   • 收礼人账户
     • 如果存在具有gift_email的账户，则将其用于礼品。
     • 否则将创建新账户，其中 user.source = PaymentGiftCouponsRepository::USER_SOURCE_GIFT_COUPON。
   • 新的订阅附加到受赠者的账户，其中 subscription.type = SubscriptionsRepository::TYPE_GIFT。
   • 您可以通过在配置文件中调用 setExtendMethod 来配置订阅扩展方法，如下所示

   activatePurchasedGiftCouponsCommand:
   	setup:
   		- setExtendMethod('extend_same_content_access')

5. SendWelcomeEmailHandler 监听 UserRegisteredEvent。

   • 如果创建的用户具有 source === PaymentGiftCouponsRepository::USER_SOURCE_GIFT_COUPON，则触发 NotificationEvent(welcome_email_gift_coupon)。

6. SubscriptionsStartsEventHandler 监听 SubscriptionStartsEvent。

   • 如果订阅具有 type === SubscriptionsRepository::TYPE_GIFT 且账户在过去 15 分钟内未创建（通过命令），则触发 NotificationEvent(new_subscription_gift)。

付款后的通知电子邮件

以下两个选项都需要集成 REMP Mailer 或其他处理 NotificationEvent 的自定义实现。

默认电子邮件

如果您只想使用模块提供的默认设置，可以启用负责发送通知电子邮件的事件处理器。在您的自定义（内部）模块中添加以下代码片段

<?php

namespace Crm\FooModule;

class FooModule extends CrmModule
{
    public function registerEventHandlers(\League\Event\Emitter\Emitter $emitter)
    {
        // ...
        $emitter->addListener(
            \Crm\PaymentsModule\Events\PaymentChangeStatusEvent::class,
            $this->getInstance(\Crm\GiftsModule\Events\GiftPaymentStatusChangeHandler::class)
        );
        // ...
    }
    // ...
}

GiftsModule 将尝试使用模板代码 created_payment_gift_coupon 发送电子邮件。您可以在模板中使用这些变量

• variable_symbol（字符串）
• donated_to_email（字符串）
• gift_starts_at（RFC3339 格式的字符串）

您还可以在 CRM 管理员配置中配置 gift_subscription_coupon_attachment 选项。如果存在，则电子邮件将使用配置中提供的附件（例如，带有 PDF 优惠券的附件）。附件是静态的，不是个性化的。

ScenariosModule

如果您不想使用默认设置，可以配置自定义场景来发送电子邮件。

要区分礼物电子邮件和常规电子邮件，您需要添加一个匹配您实现的场景条件。最常见的是以下两种

• 支付 - 支付包含类型为 的项目。如果您在创建支付时手动创建 礼物 支付（例如，在销售漏斗中），请使用此选项。然后您可以对包含 礼物 项目的支付创建一个条件，以发送不同的电子邮件。
• 订单 - 有模板名称为的产品。如果您使用我们的 ProductsModule（电商平台）来销售您的礼物订阅，请使用此选项。如果您使用它，您可能已经使用自己的商店模板将礼物订阅分开。您可以使用它来区分此类订单。

您可以根据自己的需要扩展场景和条件。有关更多详细信息，请参阅 ScenariosModule README。

DataProviders

SubscriptionFormDataProvider - 订阅更新表单中的验证

SubscriptionFormDataProvider 已添加到验证赠品订阅的起始时间与父支付的 paid_at 日期。出于会计原因，订阅必须在支付确认日期之前开始。