Add repository interface and tests for installations

Added a new method `getById` to `ApplicationInstallationRepositoryInterface`. Renamed the test path prefix to `Unit`. Included various new tests for application installations, updating and reorganizing the existing structure.

Signed-off-by: mesilov <[email protected]>

src/Application/Contracts/ApplicationInstallations/Docs/ApplicationInstallations.md

@@ -1,30 +1,134 @@
-Install Start
+# Application installation entity
 
-- add ?contact person
-- add b24 Account
-- add / find b24 partner
-- add new installation in mode new
+Store information about application installation, linked with Bitrix24 Account with auth tokens.
+Optional can store links to:
 
-Install Finish
+- Client contact person: client person who responsible for application usage
+- Bitrix24 Partner contact person: partner contact person who supports client and configure application
+- Bitrix24 Partner: partner who supports client portal
 
-- b24 account mark as active
-- installation mark as active
+| Method                                 | Return Type                     | Description                                                                            | Throws                     |
+|----------------------------------------|---------------------------------|----------------------------------------------------------------------------------------|----------------------------|
+| `getId()`                              | `Uuid`                          | Returns unique application installation id                                             |                            |
+| `getCreatedAt()`                       | `CarbonImmutable`               | Returns date and time application installation was created                             |                            |
+| `getUpdatedAt()`                       | `CarbonImmutable`               | Returns date and time of last application installation change                          |                            |
+| `getBitrix24AccountId()`               | `Uuid`                          | Returns Bitrix24 Account id related to this installation                               |                            |
+| `getContactPersonId()`                 | `?Uuid`                         | Returns contact person id who installed the application on portal (optional)           |                            |
+| `changeContactPerson()`                | `void`                          | Changes client contact person                                                          |                            |
+| `getBitrix24PartnerContactPersonId()`  | `?Uuid`                         | Returns Bitrix24 partner contact person id (optional)                                  |                            |
+| `changeBitrix24PartnerContactPerson()` | `void`                          | Changes Bitrix24 partner contact person                                                |                            |
+| `getBitrix24PartnerId()`               | `?Uuid`                         | Returns Bitrix24 Partner id related to this installation (optional)                    |                            |
+| `changeBitrix24Partner()`              | `void`                          | Changes Bitrix24 partner                                                               |                            |
+| `getExternalId()`                      | `?string`                       | Returns external id for application installation                                       |                            |
+| `setExternalId()`                      | `void`                          | Sets external id for application installation                                          | `InvalidArgumentException` |
+| `getStatus()`                          | `ApplicationInstallationStatus` | Returns application installation status                                                |                            |
+| `applicationInstalled()`               | `void`                          | Finishes application installation                                                      | `InvalidArgumentException` |
+| `applicationUninstalled()`             | `void`                          | Marks application as uninstalled                                                       | `InvalidArgumentException` |
+| `markAsActive()`                       | `void`                          | Changes status to active for blocked application installation accounts                 | `InvalidArgumentException` |
+| `markAsBlocked()`                      | `void`                          | Changes status to blocked for application installation accounts in state new or active | `InvalidArgumentException` |
+| `getApplicationStatus()`               | `ApplicationStatus`             | Returns current application status stored in persistence storage                       |                            |
+| `changeApplicationStatus()`            | `void`                          | Changes application status                                                             |                            |
+| `getPortalLicenseFamily()`             | `PortalLicenseFamily`           | Returns current Bitrix24 tariff plan designation without specified region              |                            |
+| `changePortalLicenseFamily()`          | `void`                          | Changes plan designation without specified region                                      |                            |
+| `getPortalUsersCount()`                | `?int`                          | Returns Bitrix24 portal users count stored in persistence storage                      |                            |
+| `changePortalUsersCount()`             | `void`                          | Changes Bitrix24 portal users count                                                    |                            |
+| `getComment()`                         | `?string`                       | Returns comment                                                                        |                            |
 
-Application Active
+## Application installation state diagram
 
-- change contact person
-- change bitrix24 partner contact person
-- change bitrix24 partner
-- change bitrix24 licence family
-- change bitrix24 application status
+```mermaid
+stateDiagram-v2
+    [*] --> New: New installation started
+    New --> Active : Installation completed successfully
+    New --> Blocked : Installation aborted 
+    Active --> Blocked : Connection lost or\nforcibly deactivated
+    Active --> Deleted : Application\n uninstalled
+    Blocked --> Active : Reconnected or\nreactivated
+    Blocked --> Deleted : Delete blocked installation 
+    Deleted --> [*]: Installation can be removed\n from persistence storage
+```
 
-Uninstall
+## Repository methods
 
-- ?delete contact person
-- delete b24 account
-- mark installation as deleted
+- `public function save(ApplicationInstallationInterface $applicationInstallation): void;`
+    - use case InstallStart
+    - use case InstallFinish
+    - use case Uninstall
+    - use case Activate
+    - use case Block
+    - use case ChangeContactPerson
+    - use case ChangeBitrix24PartnerContactPerson
+    - use case ChangeBitrix24Partner
+    - use case LinkToExternalEntity
+    - use case ChangeApplicationStatus
+    - use case ChangePortalLicenseFamily
+    - use case ChangePortalUsersCount
+- `public function getById(Uuid $uuid): ApplicationInstallationInterface;`
+    - use case Activate
+    - use case Block
+    - use case InstallFinish
+    - use case Uninstall
+    - use case ChangeContactPerson
+    - use case ChangeBitrix24PartnerContactPerson
+    - use case ChangeBitrix24Partner
+    - use case LinkToExternalEntity
+    - use case ChangeApplicationStatus
+    - use case ChangePortalLicenseFamily
+    - use case ChangePortalUsersCount
+- `public function delete(Uuid $uuid): void;`
+    - use case Uninstall
+- `public function findByBitrix24AccountId(Uuid $uuid): array;`
+    - use case InstallFinish
+    - use case Uninstall
+    - use case ChangeApplicationStatus
+    - use case ChangePortalLicenseFamily
+    - use case ChangePortalUsersCount
+- `public function findByExternalId(string $externalId): array;`
+    - use case LinkToExternalEntity
 
-Background periodical tasks
-- check portal license type 
+## Events
+
+- `ApplicationInstallationCreatedEvent` – Event triggered when a new installation flow was started
+- `ApplicationInstallationFinishedEvent` – Event triggered when application installation flow is finished
+- `ApplicationInstallationBlockedEvent` — Event triggered when application installation entity mark as blocked for
+  administration or technical reasons e.g. application installation was failed
+- `ApplicationInstallationApplicationStatusChangedEvent` — Event triggered when background task check actual application
+  status
+- `ApplicationInstallationContactPersonChangedEvent` — Event triggered when user in UI or admin changed client contact
+  person who responsible for the application
+- `ApplicationInstallationBitrix24PartnerContactPersonChangedEvent` — Event triggered when user in UI or admin changed
+  bitrix24 partner contact person who responsible for application support
+- `ApplicationInstallationBitrix24PartnerChangedEvent` — Event triggered when user in UI or admin changed bitrix24
+  partner who responsible for application support
+- `ApplicationInstallationExternalIdChangedEvent` – Event triggered when application installation linked with external
+  entity in other system
+- `ApplicationInstallationPortalLicenseFamilyChangedEvent` – Event triggered when background task check actual
+  PortalLicenseFamily
+- `ApplicationInstallationPortalUsersCountChangedEvent` – Event triggered when background task check actual users count
+- `ApplicationInstallationUnblockedEvent` – Event triggered when application installation entity mark as active
+- `ApplicationInstallationUninstalledEvent` — Event triggered when application uninstalled from portal
+
+```mermaid
+%%{init: { 'logLevel': 'debug', 'theme': 'neutral' } }%%
+timeline
+    title Application Installation timeline
+    section Application installation period
+        Create new Application Installation entity when install start : «Application Installation Created Event»
+        Activate Application Installation entity if install finish : «Application Installation Finished Event»
+        Block Application Installation entity if install failure : «Application Installation Blocked Event»
+    section Application active period
+        Change application status : «Application Installation Application Status Changed Event»
+        Change client contact person who responsible for application : «Application Installation Contact Person Changed Event»
+        Change Bitrix24 partner contact who responsible for support application : «Application Installation Bitrix24 Partner Contact Person Changed Event»
+        Change Bitrix24 partner whor responsible for portal support : «Application Installation Bitrix24 Partner Changed Event»
+        Link application installation to another entity in external system : «Application Installation ExternalId Changed Event»        
+        Request Bitrix24 portal license type : «Application Installation Portal License Family Changed Event»
+        Calculate Bitrix24 portal users count: «Application Installation Portal Users Count Changed Event»
+        Unblock Application Installation entity : «Application Installation Unblocked Event»
+    section Application uninstall period
+        Administrator Uninstalled Application : «Application Installation Uninstalled Event»
+```
+## Background periodical tasks
+- check portal license type
 - check application status
 - check users count

src/Application/Contracts/ApplicationInstallations/Events/ApplicationInstallationApplicationStatusChangedEvent.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Application\Contracts\ApplicationInstallations\Events;
+
+use Bitrix24\SDK\Application\ApplicationStatus;
+use Carbon\CarbonImmutable;
+use Symfony\Component\Uid\Uuid;
+use Symfony\Contracts\EventDispatcher\Event;
+
+class ApplicationInstallationApplicationStatusChangedEvent extends Event
+{
+    public function __construct(
+        public readonly Uuid              $applicationInstallationId,
+        public readonly CarbonImmutable   $timestamp,
+        public readonly ApplicationStatus $applicationStatus)
+    {
+    }
+}

src/Application/Contracts/ApplicationInstallations/Events/ApplicationInstallationBitrix24PartnerChangedEvent.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Application\Contracts\ApplicationInstallations\Events;
+
+use Carbon\CarbonImmutable;
+use Symfony\Component\Uid\Uuid;
+use Symfony\Contracts\EventDispatcher\Event;
+
+class ApplicationInstallationBitrix24PartnerChangedEvent extends Event
+{
+    public function __construct(
+        public readonly Uuid            $applicationInstallationId,
+        public readonly CarbonImmutable $timestamp,
+        public readonly ?Uuid           $previousBitrix24PartnerId,
+        public readonly ?Uuid           $currentBitrix24PartnerId)
+    {
+    }
+}

src/Application/Contracts/ApplicationInstallations/Events/ApplicationInstallationBitrix24PartnerContactPersonChangedEvent.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Application\Contracts\ApplicationInstallations\Events;
+
+use Carbon\CarbonImmutable;
+use Symfony\Component\Uid\Uuid;
+use Symfony\Contracts\EventDispatcher\Event;
+
+class ApplicationInstallationBitrix24PartnerContactPersonChangedEvent extends Event
+{
+    public function __construct(
+        public readonly Uuid            $applicationInstallationId,
+        public readonly CarbonImmutable $timestamp,
+        public readonly ?Uuid           $previousBitrix24PartnerContactPersonId,
+        public readonly ?Uuid           $currentBitrix24PartnerContactPersonId)
+    {
+    }
+}

src/Application/Contracts/ApplicationInstallations/Events/ApplicationInstallationBlockedEvent.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Application\Contracts\ApplicationInstallations\Events;
+
+use Carbon\CarbonImmutable;
+use Symfony\Component\Uid\Uuid;
+use Symfony\Contracts\EventDispatcher\Event;
+
+class ApplicationInstallationBlockedEvent extends Event
+{
+    public function __construct(
+        public readonly Uuid            $applicationInstallationId,
+        public readonly CarbonImmutable $timestamp,
+        public readonly ?string         $comment)
+    {
+    }
+}

src/Application/Contracts/ApplicationInstallations/Events/ApplicationInstallationContactPersonChangedEvent.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Application\Contracts\ApplicationInstallations\Events;
+
+use Carbon\CarbonImmutable;
+use Symfony\Component\Uid\Uuid;
+use Symfony\Contracts\EventDispatcher\Event;
+
+class ApplicationInstallationContactPersonChangedEvent extends Event
+{
+    public function __construct(
+        public readonly Uuid            $applicationInstallationId,
+        public readonly CarbonImmutable $timestamp,
+        public readonly ?Uuid           $previousContactPersonId,
+        public readonly ?Uuid           $currentContactPersonId)
+    {
+    }
+}

src/Application/Contracts/ApplicationInstallations/Events/ApplicationInstallationCreatedEvent.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Application\Contracts\ApplicationInstallations\Events;
+
+use Carbon\CarbonImmutable;
+use Symfony\Component\Uid\Uuid;
+use Symfony\Contracts\EventDispatcher\Event;
+
+class ApplicationInstallationCreatedEvent extends Event
+{
+    public function __construct(
+        public readonly Uuid            $applicationInstallationId,
+        public readonly CarbonImmutable $timestamp,
+        public readonly Uuid            $bitrix24AccountId)
+    {
+    }
+}

src/Application/Contracts/ApplicationInstallations/Events/ApplicationInstallationExternalIdChangedEvent.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Application\Contracts\ApplicationInstallations\Events;
+
+use Carbon\CarbonImmutable;
+use Symfony\Component\Uid\Uuid;
+use Symfony\Contracts\EventDispatcher\Event;
+
+class ApplicationInstallationExternalIdChangedEvent extends Event
+{
+    public function __construct(
+        public readonly Uuid            $applicationInstallationId,
+        public readonly CarbonImmutable $timestamp,
+        public readonly ?string         $previousExternalId,
+        public readonly ?string         $currentExternalId)
+    {
+    }
+}

src/Application/Contracts/ApplicationInstallations/Events/ApplicationInstallationFinishedEvent.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Application\Contracts\ApplicationInstallations\Events;
+
+use Bitrix24\SDK\Application\PortalLicenseFamily;
+use Carbon\CarbonImmutable;
+use Symfony\Component\Uid\Uuid;
+use Symfony\Contracts\EventDispatcher\Event;
+
+class ApplicationInstallationFinishedEvent extends Event
+{
+    public function __construct(
+        public readonly Uuid                $applicationInstallationId,
+        public readonly CarbonImmutable     $timestamp,
+        public readonly Uuid                $bitrix24AccountId,
+        public readonly PortalLicenseFamily $portalLicenseFamily,
+        public readonly ?Uuid               $contactPersonId,
+        public readonly ?Uuid               $bitrix24PartnerContactPersonId,
+        public readonly ?Uuid               $bitrix24PartnerId)
+    {
+    }
+}

src/Application/Contracts/ApplicationInstallations/Events/ApplicationInstallationPortalLicenseFamilyChangedEvent.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Application\Contracts\ApplicationInstallations\Events;
+
+use Bitrix24\SDK\Application\PortalLicenseFamily;
+use Carbon\CarbonImmutable;
+use Symfony\Component\Uid\Uuid;
+use Symfony\Contracts\EventDispatcher\Event;
+
+class ApplicationInstallationPortalLicenseFamilyChangedEvent extends Event
+{
+    public function __construct(
+        public readonly Uuid                $applicationInstallationId,
+        public readonly CarbonImmutable     $timestamp,
+        public readonly PortalLicenseFamily $previousPortalLicenseFamily,
+        public readonly PortalLicenseFamily $currentPortalLicenseFamily)
+    {
+    }
+}

src/Application/Contracts/ApplicationInstallations/Events/ApplicationInstallationPortalUsersCountChangedEvent.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Application\Contracts\ApplicationInstallations\Events;
+
+use Carbon\CarbonImmutable;
+use Symfony\Component\Uid\Uuid;
+use Symfony\Contracts\EventDispatcher\Event;
+
+class ApplicationInstallationPortalUsersCountChangedEvent extends Event
+{
+    public function __construct(
+        public readonly Uuid            $applicationInstallationId,
+        public readonly CarbonImmutable $timestamp,
+        public readonly ?int            $previousPortalUserCount,
+        public readonly ?int            $currentPortalUserCount)
+    {
+    }
+}

src/Application/Contracts/ApplicationInstallations/Events/ApplicationInstallationUnblockedEvent.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\SDK\Application\Contracts\ApplicationInstallations\Events;
+
+use Carbon\CarbonImmutable;
+use Symfony\Component\Uid\Uuid;
+use Symfony\Contracts\EventDispatcher\Event;
+
+class ApplicationInstallationUnblockedEvent extends Event
+{
+    public function __construct(
+        public readonly Uuid            $applicationInstallationId,
+        public readonly CarbonImmutable $timestamp,
+        public readonly ?string         $comment)
+    {
+    }
+}