[Feature in SDK]: Add $withDeleted parameter to findByBitrix24PartnerNumber()

[KarlsonComplete]

Description

When upserting partners that were previously soft-deleted, a UniqueConstraintViolation occurs on b24_partner_number.

Reproduction steps

1. Import CSV → partner #16592200 created (status: active)
2. Next full import without this partner → soft-delete (status: deleted, row stays in DB, UNIQUE constraint on b24_partner_number is still occupied)
3. Re-import/update partner #16592200 → findByBitrix24PartnerNumber() doesn't see the deleted record → tries to INSERT → unique constraint violation

SQLSTATE[23505]: Unique violation: 7 ERROR: duplicate key value violates unique constraint "uniq_961507b1ed12b6fd"
DETAIL: Key (b24_partner_number)=(16592200) already exists.

Root cause

findByBitrix24PartnerNumber() filters out status != deleted, so consumers cannot discover that a partner with this number exists in a deleted state. This makes it impossible to handle soft-deleted partners gracefully (e.g., skip with a warning in import workflows).

Proposed solution

Add an optional bool $withDeleted = false parameter to Bitrix24PartnerRepositoryInterface::findByBitrix24PartnerNumber():

• $withDeleted = false (default) — current behavior: filters status != deleted
• $withDeleted = true — returns partner regardless of status

Backward compatibility is preserved — all existing calls work without changes.

Example

Before:

public function findByBitrix24PartnerNumber(int $bitrix24PartnerNumber): ?Bitrix24PartnerInterface;

After:

public function findByBitrix24PartnerNumber(int $bitrix24PartnerNumber, bool $withDeleted = false): ?Bitrix24PartnerInterface;

Usage in consumer (Upsert Handler):

// Before — cannot detect deleted partners
$partner = $this->repository->findByBitrix24PartnerNumber($number);

// After — can detect and skip deleted partners
$partner = $this->repository->findByBitrix24PartnerNumber($number, withDeleted: true);
if ($partner?->getStatus() === Bitrix24PartnerStatus::deleted) {
    $this->logger->warning(sprintf('Partner #%d is deleted, upsert skipped', $number));
    return;
}