README

家庭模块是订阅模块的扩展，提供了订阅之间的父/子关系。父订阅可以通过 family_requests 触发子订阅的生成。

警告：模块接近生产质量，但未来可能有一些重大变更（例如删除冗余表，更改主/从名称）。

安装

通过存储库或包将 remp/crm-family-module 添加到您的 composer.json 文件，并将其安装到您的 CRM 框架中。

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

extensions:
	# ...
	- Crm\FamilyModule\DI\FamilyModuleExtension

用法

家庭模块需要知道哪些 订阅类型 是作为 父订阅，以及子订阅应该具有哪些订阅类型。

请通过 FamilySubscriptionTypesRepository::add() 方法创建这些关系

• donationMethod。可用的值有
  • copy：子订阅将复制其父订阅的开始/结束日期。
  • fixed_days：子订阅将在激活时开始，并持续固定天数（当前实现不可用）。
• count。创建父订阅时创建的子订阅数量。
• is_paid。用于标记子订阅是否应被视为 付费 的指示符。

每次创建新的主订阅时，处理器将创建可以与其他用户共享的代码，以便他们可以激活其访问权限。

这些代码可以通过以下两种方式访问

• 作为客户区的激活 URL。您可以通过将以下小部件附加到占位符来在您自己的模块中启用默认小部件

  namespace Crm\DemoModule;
  
  class DemoModule
  {
      public function registerWidgets(\Crm\ApplicationModule\Widget\WidgetManagerInterface $widgetManager) {
          $widgetManager->registerWidget(
              'frontend.subscriptions.top',
              $this->getInstance(\Crm\FamilyModule\Components\FamilyRequestsListWidget\FamilyRequestsListWidget::class),
              300
          );
      }
  }

• 作为家庭代码通过 API。您可以通过父账户令牌通过 /api/v1/family/list API 访问所有可用的家庭代码。然后可以通过 /api/v1/family/activate API 激活这些代码。

ExtendFamilyExtension

您可以使用 ExtendFamilyExtension 订阅类型扩展方法来扩展您的家庭/公司订阅。

如果 CRM 正在创建具有此扩展方法的订阅类型的新的订阅，它将尝试找到所有实际的家庭订阅。如果有一个，则新的订阅将附加到实际之后。如果没有，则新的订阅将立即开始（忽略其他非家庭订阅）。

该扩展会自动注册。如果 FamilyModule 已启用，您应该在您的订阅类型表单中选择它。

子订阅的续订

如果父用户账户续订家庭/公司订阅，并且新订阅与之前的订阅同时开始和结束，则子账户也将获得新的（续订）订阅。这是通过事件处理器 \Crm\FamilyModule\Events\NewSubscriptionHandler 自动完成的。

您可以在主配置中配置订阅之间的时间间隔。例如，如果您想允许在订阅结束后 7 天内续订

services:
	# ...
	familyNewSubscriptionHandler:
		setup:
			- setSubscriptionsTimeGap('7 days')

您还可以通过向支付元数据表添加元数据 keep_requests_unactivated=1 来防止完全复制激活的家庭请求。

子订阅的动态计数

如果您不想在 family_subscription_types.count 中定义静态生成的子订阅数量，您可以将家庭订阅的 count 值设置为 0，并在支付项目计数中定义要生成的子订阅数量。条件

• 支付项类型是 \Crm\SubscriptionsModule\PaymentItem\SubscriptionTypePaymentItem::TYPE。
• 支付项的订阅类型是家庭订阅类型，该类型在 family_subscription_types 表中定义，值为 0。
• 支付项的数量不为零。

从管理员界面创建支付时支付项集的示例

在这种情况下，处理程序 \Crm\FamilyModule\Events\NewSubscriptionHandler 生成 7 个子订阅。

自定义子订阅类型和数量

如果您想有机会定义自己的订阅类型组合及其数量，可以通过以下步骤创建可定制的订阅类型

• 将主订阅的支付项定义为 \Crm\SubscriptionsModule\PaymentItem\SubscriptionTypePaymentItem::TYPE，这将代表从属订阅类型。
• 支付项必须具有元信息（payment_item_meta），其中键为 subscription_type_item_id，值引用从属订阅类型。
• 创建带有主订阅和之前定义的从属订阅类型的家庭订阅类型（family_subscription_types），并让 null 为空。

当选择可定制的订阅类型时，管理员界面会不同处理 - 显示订阅类型数量和价格的附加选项。

创建具有可定制订阅类型的家庭订阅支付的示例

通过创建家庭订阅的支付，根据管理员表单中输入的数量和价格创建支付项。在这种情况下，处理程序 \Crm\FamilyModule\Events\NewSubscriptionHandler 生成 6 个子订阅（5 个 WEB 类型，1 个 KLUB 类型）。

API 文档

所有示例都使用 http://crm.press 作为基本域名。请在执行示例之前更改为主机。

所有示例都使用 XXX 作为默认的授权令牌值，请将其替换为实际的令牌。

• API令牌。 服务器间通信的标准API密钥。它将调用应用程序作为一个整体进行识别。它们可以在CRM管理员中生成（/api/api-tokens-admin/），并且每个API密钥必须白名单以访问特定的API端点。默认情况下，API密钥没有访问任何端点的权限。
• 用户令牌。 在登录过程中为每个用户生成，令牌在系统不同部分之间通信时识别单个用户。令牌可以读取
  • 从 n_token cookie中，如果用户通过CRM登录。
  • 从 /api/v1/users/login 端点 的响应中 - 您可以将响应存储到自己的cookie/local storage/session中。

API响应可以包含以下HTTP代码

如果可能，响应包括 application/json 编码的有效负载，其中包含进一步解释错误的消息。

GET /api/v1/family/list

列出所有可用的父账户共享的家庭代码。

头部

示例

curl -s –XGET http://crm.press/api/v1/family/list \
-H "Content-Type:application/json" \
-H "Authorization: Bearer XXX"

响应

{
    "codes": [
        {
            "code": "1dwupidm1gfdsbvcxbxcvb6527dni",
            "master_user_id": 1,
            "status": "created",
            "subscription_type_code": "donation_from_company_year_online",
            "slave_user_id": null,
            "created_at": "2019-05-24T12:40:28+02:00",
            "updated_at": "2019-05-24T12:40:28+02:00",
            "opened_at": null,
            "accepted_at": null,
            "canceled_at": null,
            "expires_at": null
        }
    ]
}

POST /api/v1/family/activate

激活提供的家庭代码，并在认证的账户上创建子订阅。

头部

有效负载

{
    "code": "1dwupidm1gfdsbvcxbxcvb6527dni", // required; Family code to activate.
}

示例

curl -s –XPOST http://crm.press/api/v1/family/activate \
-H "Content-Type:application/json" \
-H "Authorization: Bearer XXX" \
-d '{
    "code": "1dwupidm1gfdsbvcxbxcvb6527dni"
}'

响应

{
    "code": "1dwupidm1gfdsbvcxbxcvb6527dni",
    "subscription": {
        "start_at": "2020-06-02T09:45:15+02:00",
        "end_at": "2021-06-02T09:45:15+02:00",
        "code": "donation_from_company_standard_year_online",
        "access": ["web"]
    }
}

工作中...

固定天数子订阅。有时您可能希望允许您的用户独立于主订阅生成将持续固定天数的子订阅。我们计划在 family_subscription_types 中实现允许指定此功能。

动态子订阅数量。这将允许使用单个父子关系根据父订阅的设置生成动态数量的子订阅。