<?xml version="1.0"?>
<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Setup/Declaration/Schema/etc/schema.xsd">
    <table name="quote" resource="checkout" engine="innodb" comment="Sales Flat Quote">
        <column xsi:type="int" name="loyalty_points_to_redeem" unsigned="true" nullable="true"
                default="0" comment="Loyalty points the customer wants to redeem as a checkout discount"/>
    </table>
</schema>

<?php

declare(strict_types=1);

namespace Mironsoft\Loyalty\Controller\Ajax;

use Magento\Checkout\Model\Session as CheckoutSession;
use Magento\Customer\Model\Session as CustomerSession;
use Magento\Framework\App\Action\HttpPostActionInterface;
use Magento\Framework\App\CsrfAwareActionInterface;
use Magento\Framework\App\Request\InvalidRequestException;
use Magento\Framework\App\RequestInterface;
use Magento\Framework\Controller\Result\JsonFactory;
use Magento\Framework\Controller\ResultInterface;
use Magento\Quote\Api\CartRepositoryInterface;
use Mironsoft\Loyalty\Model\Config\LoyaltyConfig;
use Psr\Log\LoggerInterface;

/**
 * Persists how many loyalty points a logged-in customer wants to redeem as a
 * checkout discount on the currently active quote. Chapter 39's totals plugin
 * then turns this stored value into the actual grand total reduction.
 */
class ApplyPoints implements HttpPostActionInterface, CsrfAwareActionInterface
{
    /**
     * @param RequestInterface $request Current HTTP request
     * @param JsonFactory $resultJsonFactory Factory for JSON responses
     * @param CustomerSession $customerSession Frontend customer session
     * @param CheckoutSession $checkoutSession Checkout session holding the active quote
     * @param CartRepositoryInterface $cartRepository Quote repository, needed to persist the change
     * @param LoyaltyConfig $loyaltyConfig Loyalty module configuration reader
     * @param LoggerInterface $logger Loyalty-specific error logger
     */
    public function __construct(
        private readonly RequestInterface $request,
        private readonly JsonFactory $resultJsonFactory,
        private readonly CustomerSession $customerSession,
        private readonly CheckoutSession $checkoutSession,
        private readonly CartRepositoryInterface $cartRepository,
        private readonly LoyaltyConfig $loyaltyConfig,
        private readonly LoggerInterface $logger,
    ) {
    }

    /**
     * Validates the requested points amount and stores it on the active quote.
     *
     * @return ResultInterface
     */
    public function execute(): ResultInterface
    {
        $result = $this->resultJsonFactory->create();

        if (!$this->customerSession->isLoggedIn()) {
            return $result->setHttpResponseCode(401)
                ->setData(['success' => false, 'message' => 'Login erforderlich.']);
        }

        $requestedPoints = (int) $this->request->getParam('points', 0);
        $balance = (int) $this->customerSession->getCustomer()->getData('loyalty_points_balance');

        if ($requestedPoints < 0 || $requestedPoints > $balance) {
            return $result->setData(['success' => false, 'message' => 'Ungültige Punktzahl.']);
        }

        try {
            $quote = $this->checkoutSession->getQuote();
            $quote->setData('loyalty_points_to_redeem', $requestedPoints);
            $this->cartRepository->save($quote);
        } catch (\Throwable $exception) {
            $this->logger->error(
                'Punkte konnten nicht auf den Warenkorb angewendet werden.',
                ['exception' => $exception]
            );
            return $result->setData(['success' => false, 'message' => 'Technischer Fehler.']);
        }

        return $result->setData([
            'success' => true,
            'points_applied' => $requestedPoints,
            'discount_amount' => round($requestedPoints / $this->loyaltyConfig->getPointsPerEuro(), 2),
        ]);
    }

    /**
     * Declines to build a dedicated CSRF exception - Magento's default form-key
     * validation, shared with the rest of this module's POST controllers (chapter
     * 50), is sufficient here.
     *
     * @param RequestInterface $request Current HTTP request
     * @return InvalidRequestException|null
     */
    public function createCsrfValidationException(RequestInterface $request): ?InvalidRequestException
    {
        return null;
    }

    /**
     * Confirms that standard CSRF validation should run for this action.
     *
     * @param RequestInterface $request Current HTTP request
     * @return bool|null
     */
    public function validateForCsrf(RequestInterface $request): ?bool
    {
        return null;
    }
}

<?php

declare(strict_types=1);

namespace Mironsoft\Loyalty\Setup\Patch\Data;

use Magento\Framework\Setup\ModuleDataSetupInterface;
use Magento\Framework\Setup\Patch\DataPatchInterface;
use Magento\Sales\Setup\SalesSetupFactory;

/**
 * Adds the loyalty_points_redeemed attribute to sales_order - the redemption-side
 * counterpart to loyalty_points_earned from chapter 23 (order/order_item).
 * Order-level only, since redemption is decided once per order, not per line.
 */
class InstallSalesLoyaltyRedeemedAttribute implements DataPatchInterface
{
    /**
     * @param ModuleDataSetupInterface $moduleDataSetup Data setup instance
     * @param SalesSetupFactory $salesSetupFactory Factory for the Sales module's setup helper
     */
    public function __construct(
        private readonly ModuleDataSetupInterface $moduleDataSetup,
        private readonly SalesSetupFactory $salesSetupFactory,
    ) {
    }

    /**
     * Registers the order-level attribute for redeemed loyalty points.
     *
     * @return void
     */
    public function apply(): void
    {
        $this->moduleDataSetup->getConnection()->startSetup();

        $salesSetup = $this->salesSetupFactory->create(['setup' => $this->moduleDataSetup]);
        $salesSetup->addAttribute('order', 'loyalty_points_redeemed', [
            'type' => 'int',
            'visible' => false,
            'default' => 0,
        ]);

        $this->moduleDataSetup->getConnection()->endSetup();
    }

    /**
     * Declares this patch depends on chapter 23's sales attribute installer.
     *
     * @return string[]
     */
    public static function getDependencies(): array
    {
        return [InstallSalesLoyaltyAttributes::class];
    }

    /**
     * Declares no aliases for this patch.
     *
     * @return string[]
     */
    public function getAliases(): array
    {
        return [];
    }
}

<?php

declare(strict_types=1);

namespace Mironsoft\Loyalty\Observer;

use Magento\Customer\Api\CustomerRepositoryInterface;
use Magento\Framework\Event\Observer as EventObserver;
use Magento\Framework\Event\ObserverInterface;
use Magento\Quote\Api\CartRepositoryInterface;
use Magento\Sales\Api\Data\OrderInterface;
use Mironsoft\Loyalty\Api\Data\PointsLedgerInterface;
use Mironsoft\Loyalty\Api\Data\PointsLedgerInterfaceFactory;
use Mironsoft\Loyalty\Api\PointsLedgerRepositoryInterface;
use Psr\Log\LoggerInterface;

/**
 * Books the loyalty points a customer redeemed as a checkout payment discount
 * once the resulting order has actually been placed - not earlier, for the same
 * idempotency reason ReversePointsOnCreditmemoSave (chapter 31) and ExpirePoints
 * (chapter 33) only book at a well-defined, single-fire point in time.
 */
class RedeemPointsOnOrderPlaced implements ObserverInterface
{
    /**
     * @param CartRepositoryInterface $cartRepository Quote repository, needed to read the redeemed points amount
     * @param CustomerRepositoryInterface $customerRepository Customer repository for balance updates
     * @param PointsLedgerRepositoryInterface $ledgerRepository Points ledger repository
     * @param PointsLedgerInterfaceFactory $ledgerFactory Factory for new ledger entries
     * @param LoggerInterface $logger Loyalty-specific error logger
     */
    public function __construct(
        private readonly CartRepositoryInterface $cartRepository,
        private readonly CustomerRepositoryInterface $customerRepository,
        private readonly PointsLedgerRepositoryInterface $ledgerRepository,
        private readonly PointsLedgerInterfaceFactory $ledgerFactory,
        private readonly LoggerInterface $logger,
    ) {
    }

    /**
     * Reads the redeemed points amount from the order's quote and books it.
     * Wrapped in try/catch for the same reason AwardPointsOnOrderPlaced (chapter
     * 30) is: events.xml observers run synchronously, and an unhandled exception
     * here would abort the checkout request after the order already exists.
     *
     * @param EventObserver $observer Event observer carrying the placed order
     * @return void
     */
    public function execute(EventObserver $observer): void
    {
        /** @var OrderInterface $order */
        $order = $observer->getEvent()->getData('order');

        if (!$order->getCustomerId()) {
            return;
        }

        try {
            $this->redeemForPayment($order);
        } catch (\Throwable $exception) {
            $this->logger->error(
                'Einlösung von Treuepunkten fehlgeschlagen.',
                ['exception' => $exception, 'order_id' => $order->getEntityId()]
            );
        }
    }

    /**
     * Books the points that were applied as a payment discount during checkout
     * (chapter 63's ApplyPoints controller).
     *
     * @param OrderInterface $order Placed order
     * @return void
     */
    private function redeemForPayment(OrderInterface $order): void
    {
        $quote = $this->cartRepository->get((int) $order->getQuoteId());
        $pointsToRedeem = (int) $quote->getData('loyalty_points_to_redeem');

        if ($pointsToRedeem <= 0) {
            return;
        }

        $order->setData('loyalty_points_redeemed', $pointsToRedeem);
        $this->bookRedemption((int) $order->getCustomerId(), (int) $order->getEntityId(), $pointsToRedeem);
    }

    /**
     * Writes a TYPE_REDEEM ledger entry and decrements the customer's points
     * balance, using the same CustomerRepositoryInterface custom-attribute
     * technique as AwardPointsOnOrderPlaced (chapter 30) - LoyaltyTierBackend
     * (chapter 26) recalculates the tier automatically on save.
     *
     * @param int $customerId Customer entity ID
     * @param int $orderId Order entity ID
     * @param int $points Points to deduct
     * @return void
     */
    private function bookRedemption(int $customerId, int $orderId, int $points): void
    {
        $customer = $this->customerRepository->getById($customerId);
        $currentBalance = (int) $customer->getCustomAttribute('loyalty_points_balance')?->getValue();
        $newBalance = max(0, $currentBalance - $points);

        /** @var PointsLedgerInterface $ledgerEntry */
        $ledgerEntry = $this->ledgerFactory->create();
        $ledgerEntry->setCustomerId($customerId);
        $ledgerEntry->setOrderId($orderId);
        $ledgerEntry->setPoints(-$points);
        $ledgerEntry->setType(PointsLedgerInterface::TYPE_REDEEM);
        $ledgerEntry->setBalanceAfter($newBalance);
        $this->ledgerRepository->save($ledgerEntry);

        $customer->setCustomAttribute('loyalty_points_balance', $newBalance);
        $this->customerRepository->save($customer);
    }
}

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Event/etc/events.xsd">
    <event name="sales_order_place_after">
        <observer name="mironsoft_loyalty_award_points_on_order_placed"
                  instance="Mironsoft\Loyalty\Observer\AwardPointsOnOrderPlaced"/>
        <observer name="mironsoft_loyalty_redeem_points_on_order_placed"
                  instance="Mironsoft\Loyalty\Observer\RedeemPointsOnOrderPlaced"/>
    </event>
    <!-- sales_order_creditmemo_save_commit_after (chapter 31) unchanged, omitted here for brevity -->
</config>