Custom Plugin Development with SDD Methodology and Clean Architecture

<?php
declare(strict_types=1);

/**
* Author: Artur Yusupov (Fullstack Agentic Lab)
* Package: @agentic-lab/enterprise-commerce
* Module: OrderRefund
* Standard: Clean Architecture / DDD / PHP 8.4 Strict / WC HPOS
*/

namespace AgenticLab\Commerce\Domain\Model;

use InvalidArgumentException;

// ==========================================
// 1. DOMAIN LAYER: Value Objects & Contracts
// ==========================================

final readonly class CurrencyAmount
{
  public function __construct(
      public float $amount,
      public string $currencyCode = 'EUR'
  ) {
      if ($amount < 0.0) {
          throw new InvalidArgumentException('Сумма не может быть отрицательной.');
      }
      if (strlen($currencyCode) !== 3) {
          throw new InvalidArgumentException('Код валюты должен соответствовать ISO 4217.');
      }
  }

  public function subtract(CurrencyAmount $other): self
  {
      if ($this->currencyCode !== $other->currencyCode) {
          throw new InvalidArgumentException('Невозможно вычесть суммы в разных валютах.');
      }
      return new self($this->amount - $other->amount, $this->currencyCode);
  }
}

interface OrderRepositoryInterface
{
  public function findOrderTotal(int $orderId): ?CurrencyAmount;
  public function applyRefund(int $orderId, CurrencyAmount $refundAmount, string $reason): bool;
}

// ==========================================
// 2. APPLICATION LAYER: Use Case & DTO
// ==========================================

namespace AgenticLab\Commerce\Application\UseCase;

use AgenticLab\Commerce\Domain\Model\CurrencyAmount;
use AgenticLab\Commerce\Domain\Model\OrderRepositoryInterface;
use DomainException;

final readonly class RefundOrderRequest
{
  public function __construct(
      public int $orderId,
      public float $amount,
      public string $currency,
      public string $reason
  ) {}
}

final readonly class ProcessOrderRefundUseCase
{
  public function __construct(
      private OrderRepositoryInterface $orderRepository
  ) {}

  public function execute(RefundOrderRequest $request): bool
  {
      $currentTotal = $this->orderRepository->findOrderTotal($request->orderId);

      if ($currentTotal === null) {
          throw new DomainException("Заказ #{$request->orderId} не найден в системе.");
      }

      $refundAmount = new CurrencyAmount($request->amount, $request->currency);

      if ($refundAmount->amount > $currentTotal->amount) {
          throw new DomainException('Сумма возврата превышает остаточную стоимость заказа.');
      }

      return $this->orderRepository->applyRefund(
          $request->orderId,
          $refundAmount,
          $request->reason
      );
  }
}

// ==========================================
// 3. INFRASTRUCTURE LAYER: WooCommerce HPOS
// ==========================================

namespace AgenticLab\Commerce\Infrastructure\Persistence;

use AgenticLab\Commerce\Domain\Model\CurrencyAmount;
use AgenticLab\Commerce\Domain\Model\OrderRepositoryInterface;
use Automattic\WooCommerce\Utilities\OrderUtil;
use WC_Order;
use Exception;

final readonly class WooCommerceHposOrderRepository implements OrderRepositoryInterface
{
  public function findOrderTotal(int $orderId): ?CurrencyAmount
  {
      $order = wc_get_order($orderId);
      if (!$order instanceof WC_Order) {
          return null;
      }

      return new CurrencyAmount(
          (float) $order->get_total(),
          $order->get_currency()
      );
  }

  public function applyRefund(int $orderId, CurrencyAmount $refundAmount, string $reason): bool
  {
      $order = wc_get_order($orderId);
      if (!$order instanceof WC_Order) {
          return false;
      }

      try {
          $refund = wc_create_refund([
              'amount'     => $refundAmount->amount,
              'reason'     => sanitize_text_field($reason),
              'order_id'   => $orderId,
              'refund_id'  => 0,
              'restock_items' => true
          ]);

          return !is_wp_error($refund);
      } catch (Exception $e) {
          error_log("[AgenticLab Refund] HPOS Error: " . $e->getMessage());
          return false;
      }
  }
}

// ==========================================
// 4. INFRASTRUCTURE: Service Provider & Hook
// ==========================================

namespace AgenticLab\Commerce\Infrastructure\Bootstrap;

use AgenticLab\Commerce\Application\UseCase\ProcessOrderRefundUseCase;
use AgenticLab\Commerce\Application\UseCase\RefundOrderRequest;
use AgenticLab\Commerce\Infrastructure\Persistence\WooCommerceHposOrderRepository;
use WP_REST_Request;
use WP_REST_Response;

final class CommerceModulePlugin
{
  private ProcessOrderRefundUseCase $refundUseCase;

  public function __construct()
  {
      // Инициализация слоя внедрения зависимостей
      $repository = new WooCommerceHposOrderRepository();
      $this->refundUseCase = new ProcessOrderRefundUseCase($repository);
  }

  public function init(): void
  {
      add_action('rest_api_init', [$this, 'registerRestRoutes']);
  }

  public function registerRestRoutes(): void
  {
      register_rest_route('agentic-lab/v1', '/orders/(?P<id>\d+)/refund', [
          'methods'             => 'POST',
          'callback'            => [$this, 'handleRefundRestApi'],
          'permission_callback' => static fn(): bool => current_user_can('manage_woocommerce'),
          'args'                => [
              'amount' => ['required' => true, 'type' => 'number'],
              'reason' => ['required' => true, 'type' => 'string', 'sanitize_callback' => 'sanitize_text_field'],
          ],
      ]);
  }

  public function handleRefundRestApi(WP_REST_Request $request): WP_REST_Response
  {
      $orderId = (int) $request->get_param('id');
      $amount  = (float) $request->get_param('amount');
      $reason  = (string) $request->get_param('reason');

      try {
          $dto = new RefundOrderRequest($orderId, $amount, get_woocommerce_currency(), $reason);
          $success = $this->refundUseCase->execute($dto);

          return new WP_REST_Response([
              'success' => $success,
              'message' => 'Возврат успешно оформлен через HPOS.',
          ], $success ? 200 : 400);
      } catch (\Throwable $e) {
          return new WP_REST_Response([
              'success' => false,
              'error'   => $e->getMessage(),
          ], 422);
      }
  }
}