refactor(core): enhance SDK structure and documentation

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

src/Data/Statement/AmountData.php

@@ -0,0 +1,28 @@
+<?php
+/*
+// MODULE_CONTRACT: Defines the data structure for an amount with its currency.
+// RESPONSIBILITY: To hold and type-safely represent a monetary value and its corresponding currency.
+// INPUTS: Raw JSON object or internal input.
+// OUTPUTS: A structured object containing amount and currency details.
+// LINKS: TransactionData.php
+*/
+
+namespace Apoloz\AlfaBank\Data\Statement;
+
+// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
+// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from JSON and provides other DTO benefits.">
+use Spatie\LaravelData\Data;
+// </SECTION>
+
+// <SECTION name="class_definition" intent="Define a DTO for monetary amount data.">
+// <BELIEF_STATE "This DTO provides a clear, type-safe contract for representing financial amounts, ensuring that both the numerical value and its currency context are always explicit.">
+class AmountData extends Data
+{
+    // <SECTION name="constructor_properties" intent="Define the properties of a monetary amount.">
+    // <BELIEF_STATE "The constructor includes the `amount` (as a float, assuming precision is handled upstream or by casting) and the `currencyName` (e.g., 'RUB', 'USD'). Both are mandatory to fully describe a monetary value.">
+    public function __construct(
+        public float $amount,
+        public string $currencyName,
+    ) {}
+    // </SECTION>
+}

src/Data/Statement/RurTransferData.php

@@ -0,0 +1,44 @@
+<?php
+/*
+// MODULE_CONTRACT: Defines the data structure for detailed Russian Ruble (RUR) transfer information within a transaction.
+// RESPONSIBILITY: To hold and type-safely represent comprehensive details about the payer and payee in an RUR transfer.
+// INPUTS: Raw JSON object from the API response.
+// OUTPUTS: A structured object containing RUR transfer details.
+// LINKS: TransactionData.php
+*/
+
+namespace Apoloz\AlfaBank\Data\Statement;
+
+// <SECTION name="module_imports" intent="Import the base Spatie Laravel Data class.">
+// <BELIEF_STATE "Extending `Spatie\LaravelData\Data` enables automatic casting from JSON and provides other DTO benefits.">
+use Spatie\LaravelData\Data;
+// </SECTION>
+
+// <SECTION name="class_definition" intent="Define a DTO for Russian Ruble transfer details.">
+// <BELIEF_STATE "This DTO provides a clear, type-safe contract for highly detailed RUR transfer information, which is critical for financial reconciliation and compliance with Russian banking standards.">
+class RurTransferData extends Data
+{
+    // <SECTION name="constructor_properties" intent="Define the comprehensive properties of an RUR transfer.">
+    // <BELIEF_STATE "The constructor includes a wide array of optional fields covering full payee and payer details (account, bank BIC, correspondent account, INN, KPP, name), as well as specific payment attributes like `paymentKind110`, `priority`, `receiptDate`, and `valueDate`. All are optional as not all fields may be present or relevant in every transaction record.">
+    public function __construct(
+        public ?string $payeeAccount = null,
+        public ?string $payeeBankBic = null,
+        public ?string $payeeBankCorrAccount = null,
+        public ?string $payeeBankName = null,
+        public ?string $payeeInn = null,
+        public ?string $payeeKpp = null,
+        public ?string $payeeName = null,
+        public ?string $payerAccount = null,
+        public ?string $payerBankBic = null,
+        public ?string $payerBankCorrAccount = null,
+        public ?string $payerBankName = null,
+        public ?string $payerInn = null,
+        public ?string $payerKpp = null,
+        public ?string $payerName = null,
+        public ?string $paymentKind110 = null,
+        public ?string $priority = null,
+        public ?string $receiptDate = null,
+        public ?string $valueDate = null,
+    ) {}
+    // </SECTION>
+}

src/Data/Statement/TransactionCollectionData.php

@@ -0,0 +1,32 @@
+<?php
+/*
+// MODULE_CONTRACT: Defines the data structure for a paginated collection of TransactionData objects.
+// RESPONSIBILITY: To provide a structured, type-safe container for lists of account transactions returned by the API, including pagination metadata.
+// INPUTS: Raw JSON array from the API response.
+// OUTPUTS: An object containing pagination details and a collection of `TransactionData`.
+// LINKS: Requests/Statement/GetTransactionsRequest.php
+*/
+
+namespace Apoloz\AlfaBank\Data\Statement;
+
+// <SECTION name="module_imports" intent="Import necessary DTOs and Spatie Laravel Data components.">
+// <BELIEF_STATE "This collection DTO relies on `PaginationData` for metadata and `TransactionData` for the individual items. `DataCollection` and `DataCollectionOf` are Spatie Data features for handling typed arrays of DTOs.">
+use Apoloz\AlfaBank\Data\PaginationData;
+use Spatie\LaravelData\Attributes\DataCollectionOf;
+use Spatie\LaravelData\Data;
+use Spatie\LaravelData\DataCollection;
+// </SECTION>
+
+// <SECTION name="class_definition" intent="Define a DTO for a collection of account transactions.">
+// <BELIEF_STATE "A dedicated DTO for a collection ensures that the structure of paginated lists is consistent and type-safe, providing a reliable contract for consumers to manage financial statements.">
+class TransactionCollectionData extends Data
+{
+    // <SECTION name="constructor_properties" intent="Define the properties of the transaction collection.">
+    // <BELIEF_STATE "The collection structure includes pagination metadata (`pagination`) and the actual list of transactions (`transactions`). The `#[DataCollectionOf(TransactionData::class)]` attribute is crucial for ensuring that each item in the `transactions` array is automatically cast to a `TransactionData` DTO.">
+    public function __construct(
+        public PaginationData $pagination,
+        #[DataCollectionOf(TransactionData::class)]
+        public DataCollection $transactions
+    ) {}
+    // </SECTION>
+}

src/Data/Statement/TransactionData.php

@@ -0,0 +1,36 @@
+<?php
+/*
+// MODULE_CONTRACT: Defines the data structure for a single transaction record.
+// RESPONSIBILITY: To hold and type-safely represent the details of an individual account transaction.
+// INPUTS: Raw JSON object from the API response.
+// OUTPUTS: A structured object containing transaction details.
+// LINKS: TransactionCollectionData.php
+*/
+
+namespace Apoloz\AlfaBank\Data\Statement;
+
+// <SECTION name="module_imports" intent="Import necessary DTOs and Spatie Laravel Data components.">
+// <BELIEF_STATE "This DTO includes nested `AmountData` for monetary values and `RurTransferData` for detailed transfer information.">
+use Spatie\LaravelData\Data;
+// </SECTION>
+
+// <SECTION name="class_definition" intent="Define a DTO for a single account transaction.">
+// <BELIEF_STATE "This DTO provides a comprehensive, type-safe representation of a transaction, essential for consistent data handling and financial reporting.">
+class TransactionData extends Data
+{
+    // <SECTION name="constructor_properties" intent="Define all properties that describe an account transaction.">
+    // <BELIEF_STATE "The constructor includes key identifiers like `uuid`, `transactionId`, `operationDate`, `number`, and `direction` (DEBIT/CREDIT). Crucially, `amount` and `amountRub` use the nested `AmountData` DTO to ensure monetary values are correctly associated with their currencies. `paymentPurpose` and `rurTransfer` provide additional context, with `rurTransfer` being another nested DTO for specific RUR details.">
+    public function __construct(
+        public string $uuid,
+        public string $transactionId,
+        public string $operationDate,
+        public string $number,
+        public string $direction, // DEBIT, CREDIT
+        public AmountData $amount, // Nested DTO for amount
+        public AmountData $amountRub, // Nested DTO for amount in RUB
+        public ?string $paymentPurpose = null,
+        public ?RurTransferData $rurTransfer = null, // Nested DTO for RUR specific transfer details
+        public ?string $correspondingAccount = null,
+    ) {}
+    // </SECTION>
+}