refactor(core): enhance SDK structure and documentation

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

src/Requests/Statement/GetTransactionsRequest.php

@@ -0,0 +1,59 @@
+<?php
+/*
+// MODULE_CONTRACT: Represents the API call to retrieve a list of account transactions.
+// RESPONSIBILITY: To define the HTTP method, endpoint, and query parameters for fetching statement data, and to map the response to a structured collection DTO.
+// INPUTS: Account number, date range, and pagination parameters.
+// OUTPUTS: TransactionCollectionData (a DTO containing a list of transactions).
+// LINKS: AlfaBankConnector.php#paginate
+*/
+
+namespace Apoloz\AlfaBank\Requests\Statement;
+
+// <SECTION name="module_imports" intent="Import the response DTO and Saloon framework components.">
+// <BELIEF_STATE "This request requires the `TransactionCollectionData` DTO to structure its response. It's a GET request, so it doesn't need body-related traits.">
+use Apoloz\AlfaBank\Data\Statement\TransactionCollectionData;
+use Apoloz\AlfaBank\Traits\HasAlfaPagination;
+use Saloon\Enums\Method;
+use Saloon\Http\Request;
+use Saloon\Http\Response;
+
+class GetTransactionsRequest extends Request
+{
+    use HasAlfaPagination;
+
+    protected Method $method = Method::GET;
+
+    public function __construct(
+        protected string $accountNumber,
+        protected string $executeDateFrom,
+        protected string $executeDateTo,
+        ?int $limit = 1000,
+        ?int $offset = 0
+    ) {
+        $this->limit = $limit;
+        $this->offset = $offset;
+    }
+
+    public function resolveEndpoint(): string
+    {
+        return '/api/jp/v1/statement/transactions';
+    }
+
+    protected function defaultQuery(): array
+    {
+        return array_merge([
+            'accountNumber' => $this->accountNumber,
+            'executeDateFrom' => $this->executeDateFrom,
+            'executeDateTo' => $this->executeDateTo,
+        ], $this->getPaginationQuery());
+    }
+    // </SECTION>
+
+    // <SECTION name="response_dto_caster" intent="Transform the raw API JSON response into a structured collection DTO.">
+    // <BELIEF_STATE "The API returns a list of transactions. Casting this directly to a `TransactionCollectionData` DTO provides a type-safe, iterable object for the end-user, which is a significant improvement over dealing with raw arrays.">
+    public function createDtoFromResponse(Response $response): TransactionCollectionData
+    {
+        return TransactionCollectionData::from($response->json());
+    }
+    // </SECTION>
+}