Add contact persons use case

config/xml/Bitrix24.Lib.ContactPersons.Entity.ContactPerson.dcm.xml

@@ -10,14 +10,14 @@
         <field name="updatedAt" type="carbon_immutable" column="updated_at" nullable="false"/>
         <field name="status" enum-type="Bitrix24\SDK\Application\Contracts\ContactPersons\Entity\ContactPersonStatus" column="status" nullable="false"/>
         <field name="email" type="string" column="email" nullable="true"/>
-        <field name="isEmailVerified" type="boolean" column="is_email_verified" nullable="true"/>
+        <field name="isEmailVerified" type="boolean" column="is_email_verified" nullable="false"/>
         <field name="emailVerifiedAt" type="carbon_immutable" column="email_verified_at" nullable="true"/>
         <field name="mobilePhoneNumber" type="phone_number" column="mobile_phone_number" nullable="true"/>
         <field name="isMobilePhoneVerified" type="boolean" column="is_mobile_phone_verified" nullable="false"/>
         <field name="mobilePhoneVerifiedAt" type="carbon_immutable" column="mobile_phone_verified_at" nullable="true"/>
         <field name="comment" type="string" column="comment" nullable="true"/>
         <field name="externalId" type="string" column="external_id" nullable="true"/>
-        <field name="bitrix24UserId" type="integer" column="bitrix24_user_id" nullable="true"/>
+        <field name="bitrix24UserId" type="integer" column="bitrix24_user_id" nullable="false"/>
         <field name="bitrix24PartnerId" type="uuid" column="bitrix24_partner_id" nullable="true"/>
         <embedded name="fullName" class="Bitrix24\SDK\Application\Contracts\ContactPersons\Entity\FullName"/>
         <embedded name="userAgentInfo" class="Bitrix24\SDK\Application\Contracts\ContactPersons\Entity\UserAgentInfo"/>

config/xml/Bitrix24.SDK.Application.Contracts.ContactPersons.Entity.UserAgentInfo.dcm.xml

@@ -5,6 +5,6 @@
         <field name="ip" type="ip_address" column="user_agent_ip" nullable="true"/>
         <field name="userAgent" type="string" column="user_agent" nullable="true"/>
         <field name="referrer" type="string" column="referrer" nullable="true"/>
-        <field name="fingerprint" type="string" column="finger_print" nullable="true"/>
+        <field name="fingerprint" type="string" column="fingerprint" nullable="true"/>
     </embeddable>
 </doctrine-mapping>

rector.php

@@ -15,6 +15,7 @@
 use Rector\Naming\Rector\Class_\RenamePropertyToMatchTypeRector;
 use Rector\PHPUnit\Set\PHPUnitSetList;
 use Rector\Set\ValueObject\DowngradeLevelSetList;
+use Rector\CodeQuality\Rector\Identical\FlipTypeControlToUseExclusiveTypeRector;
 
 return RectorConfig::configure()
     ->withPaths([
@@ -48,5 +49,6 @@
         strictBooleans: true
     )
     ->withSkip([
-        RenamePropertyToMatchTypeRector::class
+        RenamePropertyToMatchTypeRector::class,
+        FlipTypeControlToUseExclusiveTypeRector::class,
     ]);

src/ApplicationInstallations/Entity/ApplicationInstallation.php

@@ -347,7 +347,9 @@ public function linkContactPerson(Uuid $uuid): void
     #[\Override]
     public function unlinkContactPerson(): void
     {
-        $this->updatedAt = new CarbonImmutable();
+        if (null === $this->contactPersonId) {
+            return;
+        }
 
         $this->events[] = new Events\ApplicationInstallationContactPersonUnlinkedEvent(
             $this->id,
@@ -356,13 +358,14 @@ public function unlinkContactPerson(): void
         );
 
         $this->contactPersonId = null;
+        $this->updatedAt = new CarbonImmutable();
     }
 
     #[\Override]
     public function linkBitrix24PartnerContactPerson(Uuid $uuid): void
     {
-        $this->updatedAt = new CarbonImmutable();
         $this->bitrix24PartnerContactPersonId = $uuid;
+        $this->updatedAt = new CarbonImmutable();
 
         $this->events[] = new Events\ApplicationInstallationBitrix24PartnerContactPersonLinkedEvent(
             $this->id,
@@ -374,7 +377,9 @@ public function linkBitrix24PartnerContactPerson(Uuid $uuid): void
     #[\Override]
     public function unlinkBitrix24PartnerContactPerson(): void
     {
-        $this->updatedAt = new CarbonImmutable();
+        if (null === $this->bitrix24PartnerContactPersonId) {
+            return;
+        }
 
         $this->events[] = new Events\ApplicationInstallationBitrix24PartnerContactPersonUnlinkedEvent(
             $this->id,
@@ -383,13 +388,14 @@ public function unlinkBitrix24PartnerContactPerson(): void
         );
 
         $this->bitrix24PartnerContactPersonId = null;
+        $this->updatedAt = new CarbonImmutable();
     }
 
     #[\Override]
     public function linkBitrix24Partner(Uuid $uuid): void
     {
-        $this->updatedAt = new CarbonImmutable();
         $this->bitrix24PartnerId = $uuid;
+        $this->updatedAt = new CarbonImmutable();
 
         $this->events[] = new Events\ApplicationInstallationBitrix24PartnerLinkedEvent(
             $this->id,

src/ApplicationInstallations/Infrastructure/Doctrine/ApplicationInstallationRepository.php

@@ -102,6 +102,32 @@ public function findByExternalId(string $externalId): array
         ;
     }
 
+    /**
+     * Get the current installation on the portal without input parameters.
+     * The system allows only one active installation per portal,
+     * therefore, the current one is interpreted as the installation with status active.
+     * If, for any reason, there are multiple, select the most recent by createdAt.
+     *
+     * @throws ApplicationInstallationNotFoundException
+     */
+    public function getCurrent(): ApplicationInstallationInterface
+    {
+        $applicationInstallation = $this->getEntityManager()->getRepository(ApplicationInstallation::class)
+            ->createQueryBuilder('appInstallation')
+            ->where('appInstallation.status = :status')
+            ->orderBy('appInstallation.createdAt', 'DESC')
+            ->setParameter('status', ApplicationInstallationStatus::active)
+            ->getQuery()
+            ->getOneOrNullResult()
+        ;
+
+        if (null === $applicationInstallation) {
+            throw new ApplicationInstallationNotFoundException('current active application installation not found');
+        }
+
+        return $applicationInstallation;
+    }
+
     /**
      * Find application installation by application token.
      *

src/ApplicationInstallations/UseCase/InstallContactPerson/Command.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\Lib\ApplicationInstallations\UseCase\InstallContactPerson;
+
+use Bitrix24\SDK\Application\Contracts\ContactPersons\Entity\FullName;
+use Bitrix24\SDK\Application\Contracts\ContactPersons\Entity\UserAgentInfo;
+use libphonenumber\PhoneNumber;
+use Symfony\Component\Uid\Uuid;
+
+readonly class Command
+{
+    public function __construct(
+        public Uuid $applicationInstallationId,
+        public FullName $fullName,
+        public int $bitrix24UserId,
+        public UserAgentInfo $userAgentInfo,
+        public ?string $email,
+        public ?PhoneNumber $mobilePhoneNumber,
+        public ?string $comment,
+        public ?string $externalId,
+        public ?Uuid $bitrix24PartnerId,
+    ) {
+        $this->validate();
+    }
+
+    private function validate(): void
+    {
+        if (null !== $this->email && !filter_var($this->email, FILTER_VALIDATE_EMAIL)) {
+            throw new \InvalidArgumentException('Invalid email format.');
+        }
+
+        if (null !== $this->externalId && '' === trim($this->externalId)) {
+            throw new \InvalidArgumentException('External ID cannot be empty if provided.');
+        }
+
+        if ($this->bitrix24UserId <= 0) {
+            throw new \InvalidArgumentException('Bitrix24 User ID must be a positive integer.');
+        }
+    }
+}

src/ApplicationInstallations/UseCase/InstallContactPerson/Handler.php

@@ -0,0 +1,122 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\Lib\ApplicationInstallations\UseCase\InstallContactPerson;
+
+use Bitrix24\Lib\ContactPersons\Entity\ContactPerson;
+use Bitrix24\Lib\Services\Flusher;
+use Bitrix24\SDK\Application\Contracts\ApplicationInstallations\Entity\ApplicationInstallationInterface;
+use Bitrix24\SDK\Application\Contracts\ApplicationInstallations\Exceptions\ApplicationInstallationNotFoundException;
+use Bitrix24\SDK\Application\Contracts\ApplicationInstallations\Repository\ApplicationInstallationRepositoryInterface;
+use Bitrix24\SDK\Application\Contracts\ContactPersons\Entity\ContactPersonStatus;
+use Bitrix24\SDK\Application\Contracts\ContactPersons\Repository\ContactPersonRepositoryInterface;
+use Bitrix24\SDK\Application\Contracts\Events\AggregateRootEventsEmitterInterface;
+use Bitrix24\SDK\Core\Exceptions\InvalidArgumentException;
+use libphonenumber\PhoneNumber;
+use libphonenumber\PhoneNumberType;
+use libphonenumber\PhoneNumberUtil;
+use Psr\Log\LoggerInterface;
+use Symfony\Component\Uid\Uuid;
+
+readonly class Handler
+{
+    public function __construct(
+        private ApplicationInstallationRepositoryInterface $applicationInstallationRepository,
+        private ContactPersonRepositoryInterface $contactPersonRepository,
+        private PhoneNumberUtil $phoneNumberUtil,
+        private Flusher $flusher,
+        private LoggerInterface $logger
+    ) {}
+
+    public function handle(Command $command): void
+    {
+        $this->logger->info('ContactPerson.InstallContactPerson.start', [
+            'applicationInstallationId' => $command->applicationInstallationId,
+            'bitrix24UserId' => $command->bitrix24UserId,
+            'bitrix24PartnerId' => $command->bitrix24PartnerId?->toRfc4122() ?? '',
+        ]);
+
+        $createdContactPersonId = '';
+
+        try {
+            if (null !== $command->mobilePhoneNumber) {
+                try {
+                    $this->guardMobilePhoneNumber($command->mobilePhoneNumber);
+                } catch (InvalidArgumentException) {
+                    // Ошибка уже залогирована внутри гарда.
+                    // Прерываем создание контакта, но не останавливаем установку приложения.
+                    return;
+                }
+            }
+
+            /** @var null|AggregateRootEventsEmitterInterface|ApplicationInstallationInterface $applicationInstallation */
+            $applicationInstallation = $this->applicationInstallationRepository->getById($command->applicationInstallationId);
+
+            $uuidV7 = Uuid::v7();
+
+            $contactPerson = new ContactPerson(
+                $uuidV7,
+                ContactPersonStatus::active,
+                $command->fullName,
+                $command->email,
+                null,
+                $command->mobilePhoneNumber,
+                null,
+                $command->comment,
+                $command->externalId,
+                $command->bitrix24UserId,
+                $command->bitrix24PartnerId,
+                $command->userAgentInfo,
+                true
+            );
+
+            $this->contactPersonRepository->save($contactPerson);
+
+            if ($contactPerson->isPartner()) {
+                $applicationInstallation->linkBitrix24PartnerContactPerson($uuidV7);
+            } else {
+                $applicationInstallation->linkContactPerson($uuidV7);
+            }
+
+            $this->applicationInstallationRepository->save($applicationInstallation);
+
+            $this->flusher->flush($contactPerson, $applicationInstallation);
+
+            $createdContactPersonId = $uuidV7->toRfc4122();
+        } catch (ApplicationInstallationNotFoundException $applicationInstallationNotFoundException) {
+            $this->logger->warning('ContactPerson.InstallContactPerson.applicationInstallationNotFound', [
+                'applicationInstallationId' => $command->applicationInstallationId,
+                'message' => $applicationInstallationNotFoundException->getMessage(),
+            ]);
+
+            throw $applicationInstallationNotFoundException;
+        } finally {
+            $this->logger->info('ContactPerson.InstallContactPerson.finish', [
+                'applicationInstallationId' => $command->applicationInstallationId,
+                'bitrix24UserId' => $command->bitrix24UserId,
+                'bitrix24PartnerId' => $command->bitrix24PartnerId?->toRfc4122() ?? '',
+                'contact_person_id' => $createdContactPersonId,
+            ]);
+        }
+    }
+
+    private function guardMobilePhoneNumber(PhoneNumber $mobilePhoneNumber): void
+    {
+        if (!$this->phoneNumberUtil->isValidNumber($mobilePhoneNumber)) {
+            $this->logger->warning('ContactPerson.InstallContactPerson.InvalidMobilePhoneNumber', [
+                'mobilePhoneNumber' => (string) $mobilePhoneNumber,
+            ]);
+
+            throw new InvalidArgumentException('Invalid mobile phone number.');
+        }
+
+        if (PhoneNumberType::MOBILE !== $this->phoneNumberUtil->getNumberType($mobilePhoneNumber)) {
+            $this->logger->warning('ContactPerson.InstallContactPerson.MobilePhoneNumberMustBeMobile', [
+                'mobilePhoneNumber' => (string) $mobilePhoneNumber,
+            ]);
+
+            throw new InvalidArgumentException('Phone number must be mobile.');
+        }
+    }
+}

src/ApplicationInstallations/UseCase/UnlinkContactPerson/Command.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\Lib\ApplicationInstallations\UseCase\UnlinkContactPerson;
+
+use Symfony\Component\Uid\Uuid;
+
+readonly class Command
+{
+    public function __construct(
+        public Uuid $contactPersonId,
+        public Uuid $applicationInstallationId,
+        public ?string $comment = null,
+    ) {
+        $this->validate();
+    }
+
+    private function validate(): void
+    {
+        // no-op for now, but keep a place for future checks
+    }
+}

src/ApplicationInstallations/UseCase/UnlinkContactPerson/Handler.php

@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bitrix24\Lib\ApplicationInstallations\UseCase\UnlinkContactPerson;
+
+use Bitrix24\Lib\Services\Flusher;
+use Bitrix24\SDK\Application\Contracts\ApplicationInstallations\Entity\ApplicationInstallationInterface;
+use Bitrix24\SDK\Application\Contracts\ApplicationInstallations\Exceptions\ApplicationInstallationNotFoundException;
+use Bitrix24\SDK\Application\Contracts\ApplicationInstallations\Repository\ApplicationInstallationRepositoryInterface;
+use Bitrix24\SDK\Application\Contracts\ContactPersons\Entity\ContactPersonInterface;
+use Bitrix24\SDK\Application\Contracts\ContactPersons\Exceptions\ContactPersonNotFoundException;
+use Bitrix24\SDK\Application\Contracts\ContactPersons\Repository\ContactPersonRepositoryInterface;
+use Bitrix24\SDK\Application\Contracts\Events\AggregateRootEventsEmitterInterface;
+use Psr\Log\LoggerInterface;
+
+readonly class Handler
+{
+    public function __construct(
+        private ApplicationInstallationRepositoryInterface $applicationInstallationRepository,
+        private ContactPersonRepositoryInterface $contactPersonRepository,
+        private Flusher $flusher,
+        private LoggerInterface $logger
+    ) {}
+
+    public function handle(Command $command): void
+    {
+        $this->logger->info('ContactPerson.UnlinkContactPerson.start', [
+            'contactPersonId' => $command->contactPersonId,
+            'applicationInstallationId' => $command->applicationInstallationId,
+        ]);
+
+        try {
+            /** @var AggregateRootEventsEmitterInterface|ContactPersonInterface $contactPerson */
+            $contactPerson = $this->contactPersonRepository->getById($command->contactPersonId);
+
+            /** @var AggregateRootEventsEmitterInterface|ApplicationInstallationInterface $applicationInstallation */
+            $applicationInstallation = $this->applicationInstallationRepository->getById($command->applicationInstallationId);
+
+            $entitiesToFlush = [];
+
+            if ($contactPerson->isPartner()) {
+                $applicationInstallation->unlinkBitrix24PartnerContactPerson();
+            } else {
+                $applicationInstallation->unlinkContactPerson();
+            }
+
+            $this->applicationInstallationRepository->save($applicationInstallation);
+            $entitiesToFlush[] = $applicationInstallation;
+
+            $contactPerson->markAsDeleted($command->comment);
+            $this->contactPersonRepository->save($contactPerson);
+            $entitiesToFlush[] = $contactPerson;
+
+            $this->flusher->flush(...$entitiesToFlush);
+        } catch (ApplicationInstallationNotFoundException|ContactPersonNotFoundException $e) {
+            $this->logger->warning('ContactPerson.UnlinkContactPerson.notFound', [
+                'message' => $e->getMessage(),
+            ]);
+
+            throw $e;
+        } finally {
+            $this->logger->info('ContactPerson.UnlinkContactPerson.finish', [
+                'contactPersonId' => $command->contactPersonId,
+                'applicationInstallationId' => $command->applicationInstallationId,
+            ]);
+        }
+    }
+}