FundRepository.php

<?php

declare(strict_types=1);

namespace MatchBot\Domain;

use DateInterval;
use DateTime;
use DateTimeImmutable;
use Doctrine\DBAL\Exception\UniqueConstraintViolationException;
use GuzzleHttp\Exception\RequestException;
use MatchBot\Application\Environment;
use MatchBot\Application\Matching;
use MatchBot\Client;
use MatchBot\Domain\DomainException\DisallowedFundTypeChange;
use MatchBot\Domain\DomainException\DomainCurrencyMustNotChangeException;

/**
 * @psalm-import-type fundArray from Client\Fund
 * @template-extends SalesforceReadProxyRepository<Fund, Client\Fund>
 */
class FundRepository extends SalesforceReadProxyRepository
{
    private ?CampaignFundingRepository $campaignFundingRepository = null;
    private ?Matching\Adapter $matchingAdapter = null;

    public function setCampaignFundingRepository(CampaignFundingRepository $repository): void
    {
        $this->campaignFundingRepository = $repository;
    }

    /**
     * @param Matching\Adapter $matchingAdapter
     */
    public function setMatchingAdapter(Matching\Adapter $matchingAdapter): void
    {
        $this->matchingAdapter = $matchingAdapter;
    }

    /**
     * @param Campaign  $campaign
     * @param DateTimeImmutable $at
     * @return bool Whether any funding changed. Use to decide about e.g. stats regeneration.
     * @throws Client\NotFoundException if Campaign not found on Salesforce
     */
    public function pullForCampaign(Campaign $campaign, DateTimeImmutable $at): bool
    {
        try {
            $fundsData = $this->getClient()->getForCampaign($campaign->getSalesforceId());
        } catch (Client\NotFoundException $notFoundException) {
            if (Environment::current() == Environment::Local) {
                // it's expected that a campaign defined in local is not known in SF, so this is fine.
                return false;
            }

            throw $notFoundException;
        }

        $anyFundAmountsChanged = false;
        foreach ($fundsData as $fundData) {
            // For each fund linked to the campaign, look it up or create it if unknown
            $fund = $this->findOneBy(['salesforceId' => $fundData['id']]);
            if (!$fund) {
                $fund = $this->getNewFund($fundData);
            }

            // Then whether new or existing, set its key info
            try {
                $this->setAnyFundData($fund, $fundData);
            } catch (DomainCurrencyMustNotChangeException $exception) {
                return false; // No-op w.r.t matching if fund currency changed unexpectedly.
            }

            try {
                $this->getEntityManager()->persist($fund);
                $this->getEntityManager()->flush(); // Need the fund ID for the CampaignFunding find
            } catch (UniqueConstraintViolationException $exception) {
                // Somebody else made the fund with this SF ID during the previous operations.
                $this->logError('Skipping fund create as unique constraint failed on SF ID ' . $fundData['id']);

                $fund = $this->findOneBy(['salesforceId' => $fundData['id']]);
                \assert($fund !== null); // since someone else made it it must now be in the db.
                $fund = $this->setAnyFundData($fund, $fundData);
                $this->getEntityManager()->persist($fund);
            }

            // If there's already a CampaignFunding for this fund, use that regardless of existing campaigns
            // iff the fund is shareable. Otherwise look up only fundings for this campaign. In both cases,
            // if the funding is new the lookup result is null and we must make a new funding.
            if ($fundData['isShared']) {
                $campaignFunding = $this->getCampaignFundingRepository()->getFunding($fund);
            } else {
                $campaignFunding = $this->getCampaignFundingRepository()->getFundingForCampaign($campaign, $fund);
            }

            // We must now support funds' totals changing over time, even after a campaign opens. This must play
            // well with high volume real-time adapters, so we must first check for a likely change and then push the
            // change to the matching adapter when needed.
            /** @psalm-var numeric-string $amountForCampaign */
            $amountForCampaign = $fundData['amountForCampaign'] === null
                ? '0.00'
                : (string) $fundData['amountForCampaign'];

            if ($campaignFunding) {
                $statsShouldBeRegenerated = $this->applyFundBalanceChange(
                    amountForCampaign: $amountForCampaign,
                    campaignFunding: $campaignFunding,
                    campaign: $campaign,
                    at: $at,
                    fundId: $fundData['id'],
                    campaignSFId: $campaign->getSalesforceId()
                );
            } else {
                // Not a previously existing campaign -> create one and set balances without checking for existing ones.
                $campaignFunding = new CampaignFunding(
                    fund: $fund,
                    amount: $amountForCampaign,
                    amountAvailable: $amountForCampaign,
                );
                $statsShouldBeRegenerated = true;
            }

            // Make the CampaignFunding available to the Campaign. This method is immutable and won't add duplicates
            // if a campaign is already among those linked to the CampaignFunding.
            $campaignFunding->addCampaign($campaign);

            try {
                $this->getEntityManager()->persist($campaignFunding);
                $this->getEntityManager()->flush();
            } catch (UniqueConstraintViolationException $exception) {
                // Somebody else created the specific funding -> proceed without modifying it.
                $this->logError(
                    'Skipping campaign funding create as constraint failed with campaign ' .
                    ($campaign->getId() ?? '[unknown]') . ', fund ' . ($fund->getId() ?? -1)
                );
            }

            $anyFundAmountsChanged = $anyFundAmountsChanged || $statsShouldBeRegenerated;
        }

        return $anyFundAmountsChanged;
    }

    /**
     * @param array{currencyCode: ?string, name: ?string, slug: ?string, type: string, id:string, ...} $fundData
     */
    private function setAnyFundData(Fund $fund, array $fundData): Fund
    {
        $currencyCode = $fundData['currencyCode'] ?? 'GBP';

        if ($fund->hasBeenPersisted() && $fund->getCurrencyCode() !== $currencyCode) {
            $this->logWarning(sprintf(
                'Refusing to update fund currency to %s for SF ID %s',
                $currencyCode,
                $fundData['id'],
            ));

            throw new DomainCurrencyMustNotChangeException();
        }

        // For now, we let some charities collect non-Topup pledges with the Salesforce form, only
        // after champion funds are used. So the mid-campaign matching behaviour is "usually" unaffected
        // by the Topup status (with possible exceptions if e.g. there are refunds that release champion funds).
        // At the end of a campaign however we want to treat them as Topups during redistribution. So until we have
        // a form that gets it right from the start, we allow a type change from Pledge to TopupPledge based on
        // Salesforce Pledge__c record edits.
        $type = $fundData['type'];
        try {
            $fund->changeTypeIfNecessary(FundType::from($type));
        } catch (DisallowedFundTypeChange $exception) {
            $this->logError(sprintf(
                'Refusing to update fund type to %s for SF ID %s',
                $type,
                $fundData['id'],
            ));
        }

        $fund->setCurrencyCode($currencyCode);
        $fund->setName($fundData['name'] ?? '');
        $fund->setSlug($fundData['slug']);
        $fund->setSalesforceLastPull(new DateTime('now'));

        return $fund;
    }

    /**
     * @param fundArray $fundData
     */
    protected function getNewFund(array $fundData): Fund
    {
        $currencyCode = $fundData['currencyCode'] ?? 'GBP';
        $name = $fundData['name'] ?? '';
        $slug = $fundData['slug'];
        $type = $fundData['type'];
        $id = $fundData['id'];
        $fund = new Fund(
            currencyCode: $currencyCode,
            name: $name,
            slug: $slug,
            salesforceId: Salesforce18Id::ofFund($id),
            fundType: FundType::from($type),
        );

        return $fund;
    }

    /**
     * @param DateTimeImmutable $closedBeforeDate Typically now
     * @param DateTimeImmutable $closedSinceDate Typically 1 hour ago as determined at the point retro match script started
     * @return Fund[]
     */
    public function findForCampaignsClosedSince(DateTimeImmutable $closedBeforeDate, DateTimeImmutable $closedSinceDate): array
    {
        $query = <<<EOT
            SELECT fund FROM MatchBot\Domain\Fund fund
            JOIN fund.campaignFundings campaignFunding
            JOIN campaignFunding.campaigns campaign
            WHERE
                campaign.endDate < :closedBeforeDate AND
                campaign.endDate > :closedSinceDate
            GROUP BY fund
EOT;

        /** @var Fund[] $result */
        $result = $this->getEntityManager()->createQuery($query)
            ->setParameter('closedBeforeDate', $closedBeforeDate)
            ->setParameter('closedSinceDate', $closedSinceDate)
            ->disableResultCache()
            ->getResult();

        return $result;
    }

    /**
     * @param DateTimeImmutable $openNearDate Typically now
     * @return Fund[] For campaigns either open at $openNearDate or which closed less than 8 days before.
     */
    public function findForCampaignsRecentlyOpenAt(DateTimeImmutable $openNearDate): array
    {
        $eightDaysPrior = $openNearDate->sub(new DateInterval('P8D'));
        $query = <<<EOT
            SELECT fund FROM MatchBot\Domain\Fund fund
            JOIN fund.campaignFundings campaignFunding
            JOIN campaignFunding.campaigns campaign
            WHERE
                campaign.startDate < :latestStart AND
                campaign.endDate > :earliestEnd
            GROUP BY fund
        EOT;

        /** @var Fund[] $result */
        $result = $this->getEntityManager()->createQuery($query)
            ->setParameter('latestStart', $openNearDate)
            ->setParameter('earliestEnd', $eightDaysPrior)
            ->disableResultCache()
            ->getResult();

        return $result;
    }

    private function getCampaignFundingRepository(): CampaignFundingRepository
    {
        return $this->campaignFundingRepository ?? throw new \Exception('CampaignFundingRepository not set');
    }

    /**
     * @return Fund[]
     */
    public function findOldTestPledges(DateTimeImmutable $olderThan): array
    {
        $query = <<<DQL
            SELECT fund FROM MatchBot\Domain\Fund fund
            WHERE
                fund.createdAt < :olderThan AND
                fund.fundType IN (:fundTypes)
        DQL;

        /** @var Fund[] $result */
        $result = $this->getEntityManager()->createQuery($query)
            ->setParameter('olderThan', $olderThan)
            ->setParameter('fundTypes', [FundType::Pledge, FundType::TopupPledge])
            ->getResult();

        return $result;
    }

    /**
     * Check for balance increase and apply any in a high-volume-safe way.
     * Note that a balance DECREASE after campaign open time is unsupported and would be error
     * logged below, as this risks invalidating in-progress donation matches.
     *
     * @param numeric-string $amountForCampaign
     *
     * @return bool Whether anything changed substantively. Use to decide about e.g. stats regeneration.
     */
    private function applyFundBalanceChange(string $amountForCampaign, CampaignFunding $campaignFunding, Campaign $campaign, DateTimeImmutable $at, string $fundId, string $campaignSFId): bool
    {
        $increaseInAmount = bcsub($amountForCampaign, $campaignFunding->getAmount(), 2);
        if ($this->matchingAdapter === null) {
            throw new \Exception("Matching Adapter not set");
        }

        // No change
        if (bccomp($increaseInAmount, '0.00', 2) === 0) {
            $this->getLogger()->info(
                "Campaign Funding ID {$campaignFunding->getId()} balance was already £{$amountForCampaign} " .
                "for campaign {$campaignSFId} and fund SF ID {$fundId}"
            );

            return false;
        }

        // Increase
        if (bccomp($increaseInAmount, '0.00', 2) === 1) {
            // This sets CampaignFunding::$amountAvailable as a side effect.
            $newTotal = $this->matchingAdapter->addAmount(
                funding: $campaignFunding,
                amount: $increaseInAmount,
                donationId: null,
                extraComment: 'applyFundBalanceChange'
            );

            $this->getLogger()->info(
                "Campaign Funding ID {$campaignFunding->getId()} balance increased " .
                "£{$increaseInAmount} to £{$newTotal}"
            );

            $campaignFunding->setAmount($amountForCampaign);

            return true;
        }

        // By process of elimination, we're considering a decrease, so
        \assert(bccomp($increaseInAmount, '0.00', 2) === -1); // @phpstan-ignore function.alreadyNarrowedType, identical.alwaysTrue
        $decreaseInAmount = bcmul($increaseInAmount, '-1', 2);

        if (!self::reductionsAreAllowed($campaign, $campaignFunding, $at)) {
            $this->getLogger()->error(
                "Campaign Funding ID {$campaignFunding->getId()} balance could not be decreased by " .
                "£{$decreaseInAmount}. Salesforce Fund ID {$fundId} as campaign {$campaignSFId} opened in past"
            );

            return false;
        }

        // This sets CampaignFunding::$amountAvailable as a side effect.
        $newTotal = $this->matchingAdapter->subtractAmount(
            funding: $campaignFunding,
            amount: $decreaseInAmount,
            donationId: null,
            extraComment: 'applyFundBalanceChange',
        );

        $this->getLogger()->info(
            "Campaign Funding ID {$campaignFunding->getId()} balance decreased " .
            "£" . bcmul($decreaseInAmount, '-1', 2) . " to £{$newTotal}"
        );

        $campaignFunding->setAmount($amountForCampaign);

        return true;
    }

    /**
     * To avoid tricky scaling & race condition problems in big campaigns, the default position during
     * a campaign is to allow top-ups but not reductions.
     *
     * Reductions are *only* allowed in 3 scenarios:
     * 1. Campaign has yet to start
     * 2. Campaign is a never-proceeding (Rejected) app campaign *and* all funds are unused
     * 3. Campaign is closed *and* all funds are unused. This is likely to be useful only if a database
     *    migration was run *before* a Salesforce data change. Follow the process at {@link https://youneedawiki.com/app/page/1aktyZ90uoX-nuAYW7mxPhlDLWb902FLV?p=1AR_eRWSQCFYUnvPWxf_uBW6Yz0yePCo0}
     *    to avoid creating data inconsistencies.
     */
    public static function reductionsAreAllowed(Campaign $campaign, CampaignFunding $campaignFunding, DateTimeImmutable $at): bool
    {
        if ($campaign->getStartDate() > $at) {
            return true;
        }

        $fundsUnused = $campaignFunding->getAmountAvailable() === $campaignFunding->getAmount();

        if (!$fundsUnused) {
            // Never-proceeding app and closed campaign post-DB-migration cases both
            // require all funds unused.
            return false;
        }

        if ($campaign->isNeverProceedingAppCampaign()) {
            // Campaign abandoned & no funds used; OK to zero even mid/post campaign.
            return true;
        }

        if ($campaign->getEndDate() < $at) {
            // Campaign closed & no funds used, maybe due to a DB migration moving allocations.
            return true;
        }

        return false;
    }
}